Skip to content

GITHUB.md

Latest commit

 

History

History
103 lines (71 loc) · 3.31 KB

GITHUB.md

File metadata and controls

103 lines (71 loc) · 3.31 KB

Integrating Claude Code with GitHub

Claude Code offers an official GitHub integration that lets Claude run inside GitHub Actions. This integration provides two main workflows: mention support for issues and pull requests, and automatic pull request reviews.

Setting Up the Integration

To get started, run /install-github-app in Claude. This command walks you through the setup process:

  1. Install the Claude Code app on GitHub
  2. Add your API key
  3. Automatically generate a pull request with the workflow files

The generated pull request adds two GitHub Actions to your repository. Once merged, you'll have the workflow files in your .github/workflows directory.

Default GitHub Actions

The integration provides two main workflows:

Mention Action

You can mention Claude in any issue or pull request using @claude. When mentioned, Claude will:

  • Analyze the request and create a task plan
  • Execute the task with full access to your codebase
  • Respond with results directly in the issue or PR

Pull Request Action

Whenever you create a pull request, Claude automatically:

  • Reviews the proposed changes
  • Analyzes the impact of modifications
  • Posts a detailed report on the pull request

Customizing the Workflows

After merging the initial pull request, you can customize the workflow files to fit your project's needs. Here's how to enhance the mention workflow:

Adding Project Setup

Before Claude runs, you can add steps to prepare your environment:

- name: Project Setup
  run: |
    npm run setup
    npm run dev:daemon

Custom Instructions

Provide Claude with context about your project setup:

custom_instructions: |
  The project is already set up with all dependencies installed.
  The server is already running at localhost:3000. Logs from it
  are being written to logs.txt. If needed, you can query the
  db with the 'sqlite3' cli. If needed, use the mcp__playwright
  set of tools to launch a browser and interact with the app.

MCP Server Configuration

You can configure MCP servers to give Claude additional capabilities:

mcp_config: |
  {
    "mcpServers": {
      "playwright": {
        "command": "npx",
        "args": [
          "@playwright/mcp@latest",
          "--allowed-origins",
          "localhost:3000;cdn.tailwindcss.com;esm.sh"
        ]
      }
    }
  }

Tool Permissions

When running Claude in GitHub Actions, you must explicitly list all allowed tools. This is especially important when using MCP servers.

allowed_tools: "Bash(npm:*),Bash(sqlite3:*),mcp__playwright__browser_snapshot,mcp__playwright__browser_click,..."

Unlike local development, there's no shortcut for permissions in GitHub Actions. Each tool from each MCP server must be individually listed.

Best Practices

When setting up Claude's GitHub integration:

  • Start with the default workflows and customize gradually
  • Use custom instructions to provide project-specific context
  • Be explicit about tool permissions when using MCP servers
  • Test your workflows with simple tasks before complex ones
  • Consider your project's specific needs when configuring additional steps

The GitHub integration transforms Claude from a development assistant into an automated team member that can handle tasks, review code, and provide insights directly within your GitHub workflow.