Intermediate 3 min · July 07, 2026

GitHub CLI: Manage Repositories from the Terminal

GitHub CLI — The Deployment That Succeeded via Wrong Workflow

A developer used the GitHub web UI to trigger a workflow.

Naren Founder & Principal Engineer

20+ years shipping production infrastructure and CI/CD at scale. Notes here come from systems that actually shipped.

✓ Production

production tested

July 07, 2026

last updated

214

articles · all by Naren

Before you start⏱ 15 min

✓Solid grasp of devops fundamentals
✓Comfortable reading and writing code examples independently
✓Basic understanding of production deployment concepts

● Production Incident

⚡Quick Answer

Install: brew install gh or apt install gh. Authenticate: gh auth login. Key commands: gh pr create, gh pr review, gh run list, gh issue create, gh repo clone.

✦ Definition~90s read

What is GitHub CLI?

GitHub CLI (gh) lets you manage GitHub from the terminal: create PRs, review code, run workflows, manage issues, and more without leaving your editor.

★

GitHub CLI is the remote control for GitHub.

Plain-English First

GitHub CLI is the remote control for GitHub. Instead of clicking buttons on a website, you type commands in your terminal. Create a PR without opening a browser. Merge without leaving the editor. Run a deploy workflow with a single command. It's faster, scriptable, and harder to misclick than the web UI.

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.

Essential GitHub CLI Commands

Authentication: gh auth login (supports SSH, HTTPS, GitHub App tokens). Once authenticated, all commands work without tokens in environment variables.

PR workflow: gh pr create --fill (auto-fills from commits), gh pr view --web (open in browser), gh pr checkout <number> (fetch PR locally), gh pr merge --squash (merge without web UI).

Actions: gh run list --limit 5, gh run watch <id> (watch in terminal), gh run cancel <id>, gh workflow run deploy.yml --ref main -f env=production.

Issues: gh issue create --label bug, gh issue list --assignee @me, gh issue close <number>.

Releases: gh release create v1.0.0 --notes-from-tag, gh release list --limit 5.

01_gh_basics.shBASH

# Authenticate
eval "$(gh auth login -s repo,workflow -w)"

# Create a PR
git checkout -b feat/email-validation
echo 'validate() { return true }' > email.js
git add . && git commit -m 'feat: add email validation'
git push -u origin HEAD
gh pr create --fill --assignee @me

# Review a PR
gh pr review 42 --approve --body 'LGTM'

# Run a workflow
gh workflow run deploy.yml --ref main -f env=staging

# Watch a run in real-time
gh run watch

# Create a release
gh release create v1.2.0 --title 'v1.2.0' --notes 'Bug fixes and improvements'

Output

✓ Authentication complete.

Creating pull request for feat/email-validation into main

https://github.com/owner/repo/pull/42

✓ Approved pull request #42

✓ Created workflow run #1234

✓ Release v1.2.0 created

Use `gh` Aliases for Frequent Commands

gh alias set prd 'pr create --fill --assignee @me' creates a shortcut. Now gh prd creates a PR with auto-filled content. Share aliases via a .gh_aliases file in your repo's .github directory.

Production Insight

For production deployments, add a CI check that rejects non-CLI triggers for production workflows: check github.event.triggering_actor == 'CLI' or validate that github.event.inputs.confirm == 'PRODUCTION'. Use GitHub Actions environment protection rules that require a specific number of approvals for production. CLI-based deploys reduce UI misclicks and leave an audit trail.

Key Takeaway

GitHub CLI (gh) manages GitHub from the terminal. Safer than web UI for critical operations. Use gh pr create --fill for fast PR creation. Use gh workflow run with explicit parameters for deploys. Add confirmation inputs to production workflows.

● Production incidentPOST-MORTEMseverity: high

The 'Run Workflow' Button That Deployed Staging to Production

Symptom

A developer navigated to the GitHub Actions page to trigger a staging deploy. The 'Run workflow' button was scrolled to show the production workflow. They clicked without checking the dropdown. The production deploy ran with staging's configuration.

Assumption

The developer assumed the 'Run workflow' button would default to the workflow they were currently viewing. GitHub's UI shows the most recently used workflow, not the page context.

Root cause

1. Developer opened the GitHub Actions tab to trigger a staging deploy. 2. They clicked 'Run workflow' without checking the workflow dropdown. 3. GitHub's UI had the production workflow selected (from a previous deployment). 4. The production workflow ran with staging's branch and environment variables. 5. The production site briefly served staging's content before monitoring caught it. 6. The developer couldn't stop the workflow quickly — the 'Cancel' button is small and easy to miss.

Fix

1. Reverted the production deployment: gh run list --workflow=deploy.yml then gh run cancel <id>. 2. Updated the deploy workflow to require a confirmation input: workflow_dispatch: inputs: confirm: description: 'Type PRODUCTION to confirm'. 3. Switched team to CLI-only deploys: gh workflow run deploy.yml --ref main -f env=production. 4. Added environment protection rules on GitHub requiring manual approval for production deployments.

Key lesson

GitHub web UI makes it easy to click the wrong workflow.
Use CLI for critical operations — it forces explicit parameters.
Add confirmation inputs to workflow_dispatch workflows.
Require environment protection rules for production deployments.

Production debug guideUse this when production is on fire4 entries

Symptom · 01

Create a PR from the current branch

→

Fix

Run gh pr create --fill — auto-fills title and body from commits

Symptom · 02

Review a PR without opening browser

→

Fix

Run gh pr review <number> --approve or --request-changes

Symptom · 03

Run a deploy workflow

→

Fix

Run gh workflow run deploy.yml --ref main — specify exact branch

Symptom · 04

Clone a repo without finding the URL

→

Fix

Run gh repo clone owner/repo

Key takeaways

GitHub CLI is faster and safer than the web UI for daily operations

Use gh pr create --fill for auto-filled PRs

Use gh workflow run with explicit parameters for production deploys

Add confirmation inputs and environment protection rules for production

Naren Founder & Principal Engineer

20+ years shipping production infrastructure and CI/CD at scale. Notes here come from systems that actually shipped.

✓ Verified

production tested

July 07, 2026

last updated

214

articles · all by Naren

🔥

That's Git. Mark it forged?

3 min read · try the examples if you haven't