GitHub CLI Integration

GitHub CLI (gh) is often the simplest way to connect Claude Code to GitHub without adding a full MCP server. It gives Claude Code a terminal interface for issues, pull requests, checks, releases, repository metadata, and API calls while keeping the actual authentication inside your local GitHub CLI setup.

Quick Answer

Install gh, authenticate it once, verify it works outside Claude Code, then let Claude Code use narrow gh commands only for the GitHub workflow you actually need.

For many projects, this is enough. Add GitHub MCP only when you need structured tool discovery, repeated GitHub workflows inside Claude Code, or team-managed MCP configuration.

Install GitHub CLI

Choose the official path for your operating system:

After installation, verify the binary before involving Claude Code:

gh --version
which gh
gh help

If gh works in your normal terminal but not inside Claude Code, you probably have a shell, PATH, or login-shell mismatch. Fix the terminal environment first; do not compensate by giving Claude broader shell permissions.

Authenticate Safely

Start with interactive login on a developer workstation:

gh auth login
gh auth status
gh api user --jq .login

The default gh auth login flow uses a browser-based login for github.com. GitHub CLI stores the resulting token in the system credential store when available. If a credential store is unavailable, gh can fall back to a plain text file, so gh auth status is worth checking on shared machines.

For automation, prefer environment tokens:

GH_TOKEN="$GITHUB_TOKEN" gh issue list --repo OWNER/REPO --limit 10

Do not paste personal access tokens into Claude Code prompts, issue comments, screenshots, or documentation. If a token is accidentally exposed, rotate it before continuing.

Give Claude Code A Narrow Job

The safest pattern is to ask Claude Code for one GitHub task, not broad repository control.

Good prompt:

Use GitHub CLI to read issue #123 only. Summarize the problem, acceptance
criteria, linked files, and unanswered questions. Do not create branches,
comments, commits, or pull requests.

Riskier prompt:

Handle all my GitHub issues and make PRs.

Claude Code works best when the gh command has a clear target: one issue, one PR, one release range, one label, one branch, or one repository.

Recommended First Commands

Use these as starting points for Claude Code prompts and project documentation:

Use --repo OWNER/REPO when Claude Code is running outside the repository or when the current directory could be ambiguous.

Issue-Driven Development Workflow

This is the most useful GitHub CLI workflow for Claude Code:

1. Read the issue with gh issue view <number> --comments.
2. Ask Claude Code to extract the acceptance criteria.
3. Inspect the local codebase before editing.
4. Create a focused implementation plan.
5. Implement and test locally.
6. Draft a PR that links back to the issue.

Example prompt:

Use gh to read issue #123. Then inspect the local codebase and propose a plan.
After I approve the plan, implement only the smallest change that satisfies the
issue. Do not create a PR until tests pass.

Helpful commands:

gh issue view 123 --comments
git checkout -b fix/issue-123
gh pr create --fill --base main

Keep the issue number in the branch name or PR body so future readers can connect the implementation back to the original request.

Pull Request Review Workflow

Claude Code can use gh to understand review context before changing code:

gh pr view 456 --comments --json title,body,comments,reviews,files
gh pr checks 456
gh pr diff 456

Ask for a structured summary before edits:

Read PR #456 with gh. List reviewer concerns, failing checks, files involved,
and the smallest safe response. Do not push or comment yet.

Good review response output should include:

• what the reviewer asked for;
• which files need changes;
• which comments are already resolved by the current diff;
• what tests or checks should run;
• what should be written in the reply comment.

If Claude Code needs to post a comment, keep that as a separate explicit approval step:

gh pr comment 456 --body "Thanks. I updated the validation path and added a regression test."

Release Notes Workflow

GitHub CLI is also useful for changelogs and release notes:

gh release list --limit 10
gh pr list --state merged --base main --limit 30
git log --oneline --decorate --max-count=30

Prompt Claude Code to produce release notes from a bounded range:

Use gh and git to summarize changes since v1.4.0. Group them into Features,
Fixes, Docs, and Internal. Do not publish a release. Prepare draft notes only.

Publish only after a human checks the version, target branch, notes, and assets:

gh release create v1.5.0 --notes-file RELEASE_NOTES.md

Permission Configuration

Do not start with Bash(gh:*) or broad Bash(*). Start with read-heavy commands and add write commands only when a workflow proves useful.

Example narrow rules:

{
  "permissions": {
    "allow": [
      "Bash(gh auth status)",
      "Bash(gh repo view:*)",
      "Bash(gh issue list:*)",
      "Bash(gh issue view:*)",
      "Bash(gh pr status)",
      "Bash(gh pr view:*)",
      "Bash(gh pr checks:*)"
    ],
    "ask": [
      "Bash(gh pr create:*)",
      "Bash(gh pr comment:*)",
      "Bash(gh issue create:*)",
      "Bash(gh release create:*)"
    ],
    "deny": [
      "Bash(gh repo delete:*)",
      "Bash(gh auth token:*)"
    ]
  }
}

Treat this as a starting policy. Claude Code permission matching can change, and shell patterns are not a complete security boundary. Use plan mode for the first pass and keep destructive or publishing actions behind human approval.

GitHub CLI vs GitHub MCP

For most users, start with GitHub CLI because it is easy to audit: you can see the exact command Claude Code wants to run. Move to MCP when the workflow becomes repetitive enough to justify another integration surface.

Troubleshooting

Project Checklist

• Add GitHub CLI setup notes to CLAUDE.md.
• Document which gh commands Claude Code may run without asking.
• Keep PR creation, comments, release publishing, and merge actions behind explicit approval.
• Prefer gh issue view <id> and gh pr view <id> over broad lists.
• Use --json when you need stable structured output.
• Use --repo OWNER/REPO in automation or multi-repo workspaces.
• Rotate tokens used in demos, CI, or temporary experiments.

Related Pages

• Tools allowlist
• Bash tools
• GitHub MCP
• MCP security checklist

Official Sources

• GitHub CLI manual
• gh auth login
• gh issue commands
• GitHub CLI installation
• Claude Code permissions
• Claude Code settings

Next: Bash Tools - Learn how to work with command-line tools safely.