davidsmith3/gh repository overview

⁠GH - GitHub CLI Docker Wrapper

Work seamlessly with GitHub from the command line

⁠Contents

• Quick Start⁠
• Prerequisites⁠
• Installation⁠
• Configuration⁠
  • Authentication Setup⁠
  • Environment Variables⁠
  • Volume Mounts⁠
• Usage⁠
  • Basic Commands⁠
  • Common Use Cases⁠
  • Shell Aliases⁠
• LLM/AI Assistant Usage⁠
• Image Information⁠
• Development⁠
• Contributing⁠
• License⁠

⁠Quick Start

⁠One-Line Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/zero-to-prod/gh/main/install.sh | bash

# Get the LLM Guide
curl https://raw.githubusercontent.com/zero-to-prod/gh/main/LLM_USAGE.md

⁠Manual Setup

# Pull the image
docker pull zero-to-prod/gh:latest

# Authenticate (one-time setup)
docker run -it --rm -v ~/.config/gh:/root/.config/gh zero-to-prod/gh auth login

# Run a command (example - requires a git repository)
docker run --rm -v ~/.config/gh:/root/.config/gh -v $(pwd):/workspace -w /workspace zero-to-prod/gh repo list

⁠Creating Shell Aliases

For convenience, create an alias in your shell configuration (.bashrc, .zshrc):

alias gh='docker run --rm -v ~/.config/gh:/root/.config/gh -v $(pwd):/workspace -w /workspace zero-to-prod/gh'

⁠Prerequisites

Before using this Docker image, ensure you have:

• Docker: Version 20.10+ or Docker Desktop (Windows/Mac)
• Docker Compose (optional): Version 1.29+

⁠Installation

⁠Option 1: Using Docker Run (Recommended)

Pull the latest image from Docker Hub:

docker pull zero-to-prod/gh:latest

⁠Option 2: Using Docker Compose

Create a docker-compose.yml:

services:
  gh:
    image: zero-to-prod/gh:latest
    container_name: gh
    volumes:
      - ~/.config/gh:/root/.config/gh
    environment:
      - TZ=UTC

Run with:

docker-compose run --rm gh --help

⁠Available Tags

• latest - Current stable release (recommended)
• {X.Y.Z} - Specific versions (e.g., 1.1.3)
• {X.Y} - Major.minor versions (e.g., 1.1)

⁠Configuration

⁠Authentication Setup (Required)

GH requires authentication to connect to your instance.

⁠Step 1: Create Local Configuration

Configure GH with your credentials:

docker run -it --rm -v ~/.config/gh:/root/.config/gh zero-to-prod/gh auth login

Follow the interactive prompts to complete authentication.

⁠Environment Variables

Optional environment variables you can set:

docker run --rm \
  -e TZ=UTC \
  -v ~/.config/gh:/root/.config/gh \
  -v $(pwd):/workspace \
  -w /workspace \
  zero-to-prod/gh [COMMAND]

⁠Volume Mounts

Essential volumes:

Example with workspace mount (recommended for most commands):

docker run --rm \
  -v ~/.config/gh:/root/.config/gh \
  -v $(pwd):/workspace \
  -w /workspace \
  zero-to-prod/gh [COMMAND]

Most CLI tools require git repository context and should use the workspace mount pattern above.

⁠Security Considerations

• Configuration files are stored in ~/.config/gh on your host machine
• Never commit .config/gh to version control
• Ensure file permissions are restrictive: chmod 700 ~/.config/gh
• Use API tokens instead of passwords for authentication

⁠Usage

⁠Basic Command Structure

# For commands that need git repository context
docker run --rm \
  -v ~/.config/gh:/root/.config/gh \
  -v $(pwd):/workspace \
  -w /workspace \
  zero-to-prod/gh [COMMAND] [OPTIONS]

docker run -it --rm \
  -v ~/.config/gh:/root/.config/gh \
  zero-to-prod/gh [COMMAND] [OPTIONS]

⁠Quick Reference

Display help:

# General help
docker run --rm zero-to-prod/gh --help

# Command-specific help
docker run --rm zero-to-prod/gh [COMMAND] --help

⁠Common Use Cases

Example commands:

# Example command with full volume mounts
docker run --rm \
  -v ~/.config/gh:/root/.config/gh \
  -v $(pwd):/workspace \
  -w /workspace \
  zero-to-prod/gh repo list

After adding the alias (see Creating Shell Aliases⁠), restart your shell or run source ~/.bashrc. Then you can use:

# Use the alias for simpler commands
gh repo list

# For interactive commands, add -it manually
docker run -it --rm -v ~/.config/gh:/root/.config/gh zero-to-prod/gh auth login

⁠Using Docker Compose

# Run a command
docker-compose run --rm gh repo list

# Interactive mode
docker-compose run --rm gh

⁠LLM/AI Assistant Usage

This Docker wrapper includes comprehensive documentation for Large Language Models and AI assistants to help users interact with GitHub CLI.

⁠For AI Assistants

A complete guide is available in LLM_USAGE.md⁠ which includes:

• Complete command patterns with all required volume mounts
• Common use cases and workflows
• Error troubleshooting guide
• Environment variable usage
• Best practices for suggesting gh commands to users

⁠Quick Access

View the LLM guide:

curl https://raw.githubusercontent.com/zero-to-prod/gh/main/LLM_USAGE.md

⁠Key Points for AI Assistants

When helping users with gh commands, always:

1. Include both volume mounts: config (~/.config/gh) and workspace ($(pwd):/workspace)
2. Verify user is in a git repository before suggesting repository commands
3. Check authentication status before suggesting authenticated operations
4. Suggest setting up the alias for frequent users

Example complete command:

docker run --rm \
  -v ~/.config/gh:/root/.config/gh \
  -v $(pwd):/workspace \
  -w /workspace \
  zero-to-prod/gh repo list

⁠Image Information

⁠Docker Hub

• Repository: zero-to-prod/gh⁠
• Pull Command: docker pull zero-to-prod/gh

⁠Updating the Image

# Pull the latest version
docker pull zero-to-prod/gh:latest

# Verify the update
docker run --rm zero-to-prod/gh --version

⁠Development

For development or custom builds, see Image Development⁠.

⁠Project Links

• Source Repository: zero-to-prod/gh⁠
• Docker Hub: zero-to-prod/gh⁠
• Official Docs: Documentation⁠

⁠Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues⁠ page if you want to contribute.

Please read our:

• Contributing Guide⁠ - Contribution guidelines
• Code of Conduct⁠ - Community standards
• Security Policy⁠ - Vulnerability reporting

⁠How to Contribute

1. Fork the repository
2. Create a new branch (git checkout -b feature-branch)
3. Make your changes
4. Commit changes (git commit -m 'Add some feature')
5. Push to the branch (git push origin feature-branch)
6. Create a Pull Request

⁠License

This project is licensed under the MIT License - see LICENSE.md⁠ for details.

Maintained by: zero-to-prod⁠ Last Updated: 2025-11-16