GitHub CLI — The Deployment That Succeeded via Wrong Workflow

The GitHub web UI is designed for casual use. For daily operations — creating PRs, reviewing code, running workflows, managing issues — the CLI is faster and safer. A single gh pr create --fill creates a PR from your current branch without touching the mouse. gh workflow run deploy.yml --ref main triggers a deployment with a specific ref — no risk of clicking the wrong button. This guide covers the essential gh commands, the incident where web UI clicking triggered the wrong workflow, and how to script common operations.

Why GitHub CLI?

GitHub CLI (gh) replaces context-switching between terminal and browser. For DevOps engineers, staying in the terminal means faster workflows, easier scripting, and fewer distractions. gh supports authentication, repo management, issues, PRs, actions, and more. It's not a toy—it's a production tool. If you're still clicking through the GitHub UI for routine tasks, you're wasting time. Install gh, authenticate, and never open a browser for repo management again.

# macOS
brew install gh

# Linux (Ubuntu/Debian)
sudo apt install gh

# Verify
gh --version

Creating Repositories from the Terminal

Creating a repo via UI is slow. With gh, you can create a repo, initialize it, and push code in seconds. Use gh repo create with flags for visibility, license, and gitignore. For teams, set defaults in ~/.config/gh/config.yml. This is especially useful for bootstrapping microservices or spinning up ephemeral repos for experiments. Avoid the trap of creating repos manually—automate it.

# Create a public repo with README, license, and gitignore
gh repo create my-new-project --public --add-readme --license mit --gitignore Node

# Clone it locally
git clone https://github.com/your-org/my-new-project.git
cd my-new-project

# Add code and push
echo "# My New Project" > README.md
git add . && git commit -m "Initial commit"
git push origin main

Cloning and Forking Repositories

Cloning a repo is basic, but gh adds convenience: gh repo clone uses the authenticated user by default, supports SSH, and can clone from any org. Forking is a one-liner: gh repo fork. This is critical for open-source contributions or internal forks. gh also sets up the upstream remote automatically. Avoid manual git remote add—let gh handle it.

# Clone a repo (defaults to SSH if configured)
gh repo clone cli/cli

# Fork a repo and clone your fork
gh repo fork cli/cli --clone

# Verify remotes
cd cli
git remote -v

Managing Repository Settings

Repository settings like description, homepage, topics, and visibility are configurable via gh. Use gh repo edit to update multiple fields. This is essential for automation: when spinning up repos, enforce naming conventions and metadata. You can also enable/disable issues, wiki, and projects. Avoid manual UI edits—script them.

# Update description and homepage
gh repo edit my-repo --description "A microservice for user auth" --homepage "https://auth.example.com"

# Add topics
github repo edit my-repo --add-topic "go" --add-topic "authentication"

# Change visibility to private
gh repo edit my-repo --visibility private

# Disable wiki
gh repo edit my-repo --enable-wiki=false

Listing and Searching Repositories

Finding repos in large orgs is painful. gh repo list filters by owner, language, topic, and visibility. Use --json for machine-readable output. This is invaluable for audits, reporting, or feeding into other tools. Combine with jq for complex queries. Avoid scrolling through the UI—use the terminal.

# List all repos in your org, public only, with Go language
gh repo list your-org --visibility public --language go --limit 100

# JSON output for scripting
gh repo list your-org --json name,url,description,primaryLanguage

# Filter by topic
gh repo list your-org --topic "production"

Deleting and Archiving Repositories

Cleanup is part of lifecycle management. gh repo delete removes a repo permanently (requires confirmation). gh repo archive marks it read-only. Use these in automation for ephemeral environments or stale projects. Be careful: deletion is irreversible. Always archive before delete in production workflows.

# Archive a repo
gh repo archive your-org/stale-project

# Delete a repo (requires confirmation or --yes flag)
gh repo delete your-org/stale-project --yes

# Verify deletion
gh repo list your-org | grep stale-project

Working with Pull Requests and Issues

gh isn't just for repo management—it handles PRs and issues too. Create, list, review, and merge PRs without leaving the terminal. This speeds up code review workflows. For DevOps, automating PR creation for dependency updates or release branches is a game-changer. Use gh pr create with templates and labels.

# Create a PR with title, body, and labels
gh pr create --title "Update dependencies" --body "Automated dependency update" --label "dependencies"

# List open PRs assigned to you
gh pr list --assignee @me --state open

# Merge a PR with squash
gh pr merge 42 --squash --delete-branch

Automating with GitHub Actions and gh

gh integrates seamlessly with GitHub Actions. Use gh workflow run to trigger workflows, gh run list to check status, and gh run watch to monitor in real-time. This enables complex automation: e.g., trigger a deployment workflow after a PR merge. Avoid polling the API—use gh's built-in commands.

# Trigger a workflow with parameters
gh workflow run deploy.yml --ref main --field environment=staging

# List recent runs
gh run list --workflow=deploy.yml --limit 5

# Watch a specific run
gh run watch 1234567890

Scripting and CI/CD Integration

gh is designed for scripting. Use --json and --jq to parse output in shell scripts. For CI/CD, set GH_TOKEN environment variable for authentication. Common patterns: create release, upload assets, manage environments. Avoid brittle parsing of human-readable output—always use --json.

#!/bin/bash
# Create a release and upload asset
VERSION="v1.0.0"
gh release create $VERSION --title "Release $VERSION" --notes "Changelog..."
gh release upload $VERSION ./dist/app.tar.gz

# Get latest release tag
LATEST=$(gh release list --json tagName --jq '.[0].tagName')
echo "Latest release: $LATEST"

Troubleshooting Common Issues

Even with gh, things go wrong. Common issues: authentication failures, rate limiting, and permission errors. Use gh auth status to verify auth. Check rate limits with gh api rate_limit. For permission issues, verify your token scopes. Always test commands in a dry-run manner first. Avoid assuming everything works—build in error handling.

# Check authentication status
gh auth status

# Check rate limit
gh api rate_limit --jq '.rate.remaining'

# Test a simple command
gh repo view cli/cli --json name

# Debug with verbose flag
gh repo list --verbose