Claude Code is Anthropic's official AI coding agent, used by developers at companies from startups to Fortune 500. Learn more →

How to Use Claude Code with GitHub

Connect Claude Code to GitHub using MCP servers. Automate pull requests, manage issues, and build CI/CD workflows without leaving your terminal.

Claude Code connects to GitHub through the gh CLI, the GitHub MCP server, and the official GitHub Action — letting you create PRs, manage issues, review CI failures, and even tag @claude on pull requests, all without leaving the terminal. Set up takes about five minutes and works with any GitHub repo.

This guide walks through the full setup: authenticating the gh CLI, configuring the GitHub MCP server for deeper access, installing the Claude Code GitHub Action for automated PR workflows, and practical examples for everyday use.

What Is Claude Code GitHub Integration?

Claude Code connects to GitHub through three methods:

• The gh CLI — GitHub's official command-line tool, already available in Claude Code for basic operations
• GitHub MCP Server — A Model Context Protocol server that gives Claude deeper, structured access to GitHub's API (repos, PRs, issues, code search)
• Claude Code GitHub Actions — An official GitHub Action that lets Claude respond to @claude mentions in PRs and issues, implementing changes and creating pull requests automatically

The gh CLI handles basic operations. The MCP server enables more sophisticated workflows like reading entire repositories, managing multiple PRs, and integrating with GitHub Actions. The GitHub Action brings Claude directly into your CI/CD pipeline.

New to Claude Code? Get the Free Blueprint to see what it can do, then come back for GitHub setup.

1 Set Up GitHub CLI Authentication

First, ensure the GitHub CLI is authenticated. In your terminal (outside Claude Code):

gh auth login

Follow the prompts to authenticate with your GitHub account. Choose HTTPS and authenticate via browser.

Verify it works:

gh auth status

You should see your username and authentication status.

2 Add the GitHub MCP Server

For deeper GitHub integration, add the official GitHub MCP server. The recommended method uses the HTTP transport:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

After adding, authenticate using the /mcp command inside Claude Code. Select "Authenticate" for GitHub and follow the browser login flow. Claude Code handles OAuth 2.0 authentication automatically.

Alternatively, you can use a personal access token. Create one at github.com/settings/tokens with these scopes:

• repo — Full repository access
• workflow — GitHub Actions access
• read:org — Organization read access (if needed)

Then add the server with the token:

claude mcp add --transport stdio --env GITHUB_TOKEN=your_token_here github -- npx -y @modelcontextprotocol/server-github

3 Basic GitHub Operations

With GitHub connected, Claude can handle common operations directly:

Check Repository Status

Show me the open issues in this repository

Claude reads your issues and presents them with titles, labels, and assignees.

Read a Specific Issue

Read issue #42 and summarize what needs to be done

Claude fetches the issue, reads comments, and extracts actionable requirements.

View Pull Requests

List open PRs and show which ones are ready for review

Claude checks PR status, review states, and CI results.

Working with Pull Requests

This is where Claude Code shines. Instead of manually writing PR descriptions, let Claude do it based on actual changes.

If you want to see my complete GitHub and Claude Code setup — branches, reviews, and deployment — I documented it all in a free guide.

Create a Pull Request

After making changes and committing:

Create a pull request for my changes. Include:
- A clear title
- Summary of what changed and why
- Testing instructions
- Link to issue #42 if related

Claude analyzes your commits, generates a comprehensive PR description, and creates the PR.

Review a Pull Request

Review PR #15. Check for:
- Security issues
- Performance problems
- Missing tests
- Code style violations

Claude reads the diff, analyzes the changes, and provides structured feedback.

Update PR Based on Feedback

Read the review comments on PR #15 and make the requested changes

Claude reads reviewer comments, implements fixes, and commits the changes.

Managing GitHub Issues

Claude can help you work through issues systematically.

Triage Issues

Show me all open issues without labels. For each one, suggest appropriate labels based on the content.

Plan Issue Implementation

Read issue #23. Create a plan for implementing it:
1. What files need to change
2. Step-by-step implementation approach
3. What tests to add
4. Estimated complexity

Work Through an Issue

I want to fix issue #23. Read it, implement the fix, write tests, and create a PR.

This single command triggers a complete workflow: Claude reads the issue, understands requirements, implements changes, tests them, and opens a PR.

Claude Code GitHub Actions (@claude in PRs and Issues)

This is one of the most powerful integrations. Claude Code GitHub Actions lets you tag @claude in any PR or issue comment, and Claude will analyze your code, implement changes, and create pull requests — all within GitHub.

Quick Setup with /install-github-app

The fastest way to set this up: open Claude Code in your terminal and run:

/install-github-app

This command guides you through installing the Claude GitHub app and adding the required secrets to your repository. You must be a repository admin.

What Can @claude Do?

Once set up, use these commands in any PR or issue comment:

@claude implement this feature based on the issue description
@claude fix the TypeError in the user dashboard component
@claude review this PR for security issues
@claude how should I implement user authentication for this endpoint?

Claude analyzes the context, makes changes, and pushes commits directly to the PR branch. It follows your CLAUDE.md guidelines and existing code patterns.

Basic Workflow Configuration

If you prefer manual setup, add this workflow to .github/workflows/claude.yml:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

The action defaults to Claude Sonnet 4.5. To use Opus 4.6, add claude_args: "--model claude-opus-4-6". The action also supports AWS Bedrock and Google Vertex AI for enterprise environments.

Creating and Debugging GitHub Actions Workflows

Beyond the @claude integration, Claude Code can also help you create and debug any GitHub Actions workflow.

Create a CI Workflow

Create a GitHub Actions workflow that:
- Runs on push to main and on PRs
- Installs dependencies
- Runs linting
- Runs tests
- Reports coverage

Claude creates .github/workflows/ci.yml with proper syntax and best practices.

Debug Failed Workflows

My CI failed on the latest push. Check the workflow logs and tell me what went wrong.

Claude reads the GitHub Actions logs, identifies the failure, and suggests fixes.

Add Deployment Workflow

Add a deployment workflow that:
- Triggers when a release is published
- Builds the project
- Deploys to production
- Posts to Slack on success or failure

Common GitHub Workflows

Here are complete workflows you can use immediately:

Feature Branch Workflow

# Start working on an issue
Read issue #45 and create a feature branch for it

# After implementation
Create a PR for this branch. Link it to issue #45 and add the "ready for review" label

# After review
Read the review comments and address each one

# After approval
Merge the PR and delete the branch

Release Workflow

# Prepare release
Show me all merged PRs since the last release

# Create release notes
Generate release notes from those PRs, grouped by type (features, fixes, docs)

# Create the release
Create a GitHub release v1.2.0 with those notes

Bug Investigation

# Investigate a bug report
Read issue #67 (the bug report). Then:
1. Find related code
2. Identify the likely cause
3. Create a failing test that demonstrates the bug
4. Implement the fix
5. Verify the test passes
6. Create a PR

Common Mistakes

1. Forgetting to authenticate: Run gh auth status to verify authentication before starting GitHub workflows.
2. Pushing without review: Always check git diff before pushing Claude's changes. Review is essential.
3. Skipping the MCP setup: The gh CLI works for basic tasks, but MCP enables much richer interactions. Take 5 minutes to set it up.
4. Vague PR descriptions: Tell Claude what context to include. "Create a PR" gives worse results than "Create a PR explaining the authentication changes and how to test them."
5. Ignoring CI failures: When CI fails, ask Claude to read the logs. It can usually identify and fix the issue faster than manual debugging.

FAQ

Do I need the MCP server or is gh CLI enough?

The gh CLI handles basic operations like creating PRs and reading issues. The GitHub MCP server provides structured access to the full GitHub API with OAuth authentication and handles complex workflows more gracefully. For serious GitHub work, use both. And for automated PR workflows, add the Claude Code GitHub Action as well.

What is /install-github-app?

It is a slash command you run inside Claude Code that walks you through installing the official Claude GitHub app on your repository and configuring the required secrets. This is the fastest way to set up the @claude GitHub Actions integration. You need to be a repository admin.

Can Claude push directly to my repository?

Yes, if you've authenticated with gh CLI or provided a token with push access. Claude can commit, push, create branches, and merge PRs. Always review changes before allowing pushes to important branches.

How do I restrict what Claude can do on GitHub?

Limit the scopes on your personal access token. For read-only access, use only the read:repo scope. For PR creation without merge ability, exclude write permissions from your token.

Can Claude handle multiple repositories?

Yes. Specify the repository in your request: "Read the issues in owner/other-repo" or navigate to that repository's folder before starting Claude Code.

What if my workflow requires manual approval?

Claude can create PRs and workflows that require manual approval. It cannot bypass branch protection rules or required reviewers. This is a feature, not a limitation.

Related Guides

• Claude Code for Git Commits — automatic commit messages and staging
• Claude Code Slash Commands — all built-in commands including /mcp
• Claude Code Tutorial for Beginners — start here if you're new
• What Is Claude Code? — understand the fundamentals