GitHub CLI: A Beginner’s Guide to Command-Line Repo Management

Migrating from Git to GitHub CLI — Best Practices and PitfallsMigrating from using Git (the distributed version-control system) primarily via raw git commands or GUI clients to incorporating the GitHub CLI (gh) can streamline workflows, reduce context switching, and provide first-class GitHub features directly in your terminal. This article covers why you might migrate, how to plan and execute the transition, recommended practices, automation tips, and common pitfalls to avoid.

Why migrate to GitHub CLI?

• Unified tooling: gh combines many GitHub actions (issues, pull requests, releases, workflows) with local git operations.
• Faster workflows: create PRs, view diffs, and manage issues without opening a browser.
• Scriptability: gh is designed for automation and integrates well with shell scripts and CI.
• Improved collaboration: standardized commands reduce onboarding friction across teams.

Preparation: audit and planning

1. Inventory current workflows

   • List frequent tasks: branching, PR creation, code reviews, releases, issue triage, CI checks.
   • Identify tools/scripts that call git or use web UI.

2. Map features needed from GitHub

   • Which GitHub features do you require (draft PRs, reviews, checks, repo creation, secrets)?
   • Note API rate limits and permissions for automation.

3. Environment and permissions

   • Decide between user tokens, GitHub Apps, or OAuth for automation. For individual use, gh auth login with an OAuth flow is simplest.
   • Ensure required scopes: repo, workflow, read:org, etc., depending on tasks.

4. Choose a migration approach

   • Gradual: adopt gh for non-destructive tasks first (PR creation, issue browsing), then replace scripts incrementally.
   • Big-bang: swap pipelines and tooling at once—riskier but faster for small teams.

Installation and configuration

• Install gh on supported platforms (macOS, Linux, Windows). Package managers: brew, apt, dnf, winget, scoop.
• Authenticate: run gh auth login (interactive) or use gh auth login –with-token for CI.
• Configure defaults: gh config set editor “code –wait”, gh config set prompt disabled, and set git user.name/email if needed.
• Enable extensions for added features: gh extension install .

Core commands and equivalents

Here are common git + GitHub tasks and their gh equivalents:

• Create a repository
  • git: create repo on GitHub via web or API scripts
  • gh: gh repo create
• Create a branch and push
  • git: git checkout -b feature; git push -u origin feature
  • gh: same git commands for local branch; use gh pr create to open PR
• Create a pull request
  • git: use GitHub web UI or API scripts
  • gh: gh pr create –title “…” –body “…” –base main
• Review and merge
  • gh: gh pr review, gh pr merge
• View issues and PRs
  • gh issue list, gh pr list, gh pr view –web or –comments
• Release management
  • gh release create v1.0.0 –title “v1.0.0” –notes “release notes”

Use gh help for flags and usage.

Best practices

1. Keep git and gh responsibilities clear

   • Use git for local commits, branching, and history manipulation.
   • Use gh for GitHub-specific operations (PRs, issues, repo settings, workflows).

2. Use scripts and aliases

   • Standardize repetitive tasks via shell scripts or gh aliases (gh alias set co ‘pr checkout’).
   • Example gh alias: gh alias set prc ‘pr create –fill’

3. Automate safely in CI

   • Use gh with a machine user or GitHub App and least-privilege tokens.
   • Cache authentication tokens securely (secrets in CI).

4. Adopt preview and dry-run modes

   • Where available, test gh commands with –dry-run or use gh pr create –fill in a sandbox repo.

5. Teach team conventions

   • Document command patterns, branching strategies, and PR templates.
   • Include gh usage in developer onboarding.

6. Use extensions when necessary

   • Extensions can add missing features or convenience commands (search community extensions first).

7. Handle repository visibility and defaults

   • Configure default branch names and repo visibility when creating repos via gh (gh repo create –public –default-branch main).

Automation & scripting examples

Create a PR, assign reviewer, and open in browser:

git checkout -b feature/awesome git push -u origin feature/awesome gh pr create --title "Add awesome feature" --body "Implements X" --reviewer alice --web 

Bulk-close stale issues (use with care):

gh issue list --state open --label stale --json number -q '.[].number' | xargs -I{} gh issue close {} 

Create a release from latest tag:

TAG=$(git describe --tags --abbrev=0) gh release create "$TAG" --notes-file CHANGELOG.md 

Pitfalls and how to avoid them

1. Overreliance on gh for local git operations

   • Pitfall: assuming gh substitutes git—some local-only tasks still require git.
   • Avoid by keeping git fluency and scripts using git where appropriate.

2. Permission and token scope mistakes

   • Pitfall: using tokens with excessive scopes or exposing tokens in CI logs.
   • Avoid by generating least-privilege tokens and storing them securely.

3. Breaking existing automation

   • Pitfall: replacing scripts without compatibility checks.
   • Avoid by running migrations in parallel and keeping old scripts until verified.

4. Different behaviors across versions

   • Pitfall: team members on different gh versions encounter differing flags or features.
   • Avoid by standardizing gh version in docs or CI containers.

5. Ambiguous default behaviors

   • Pitfall: gh commands sometimes assume defaults (current branch, repo), leading to actions on unintended targets.
   • Avoid by explicitly passing –repo, –base, or branch names in scripts.

6. Performance and rate limits

   • Pitfall: hit GitHub API rate limits when scripting aggressively.
   • Avoid by batching operations, caching, and obeying rate limit headers.

Migration checklist

• [ ] Inventory workflows and scripts
• [ ] Install gh for all developers and CI
• [ ] Decide authentication method and rotate/generate tokens
• [ ] Create gh aliases and shared scripts for common tasks
• [ ] Update CI pipelines incrementally
• [ ] Run tests and dry-runs in a sandbox org
• [ ] Document new workflows and train team
• [ ] Deprecate old scripts after verification

Conclusion

Migrating to GitHub CLI can modernize developer workflows, reduce context switching, and unlock automation capabilities tied directly to GitHub. Proceed incrementally, enforce least-privilege authentication, standardize versions, and keep git skills strong to avoid common pitfalls. With careful planning and clear team conventions, gh becomes a powerful extension of local git, not a replacement.