GitHub Integration

Connect your AI agents to GitHub repositories for automated issue management, pull request workflows, CI/CD monitoring, and autonomous code development tasks.

Overview

The GitHub Integration provides two complementary capabilities that enable AI agents to interact with GitHub repositories:

1. GitHub API Tools - 25 synchronous operations for querying and modifying issues, pull requests, GitHub Actions workflows, and repository information
2. Claude Code Launcher - Asynchronous development tasks where Claude Code CLI clones a repository, makes changes, runs tests, and creates pull requests autonomously

The integration supports multiple connections with different authentication methods, letting you scope repository access and permissions precisely for each use case.

info

GitHub API Tools require the custom.github feature code (Pro Plus+ tier). Claude Code Launcher additionally requires the custom.claude_code feature code (Enterprise tier only).

Use Cases

• Issue Triage from Email - Agent receives a bug report email, searches existing issues for duplicates, creates a new GitHub issue with labels and assignee, and replies to the reporter with the issue link
• PR Review Notifications - Webhook triggers when a review is requested, agent fetches the PR details and changed files, then sends a summary notification to the reviewer
• CI/CD Failure Monitoring - Webhook triggers on workflow failure, agent retrieves job logs, identifies the error, and posts a diagnostic comment on the associated PR
• Autonomous Code Changes - Agent receives a feature request, triggers Claude Code to clone the repo, implement the change, run tests, and create a pull request with a detailed description

How It Works

GitHub Connection          GitHub Tools           Agent Execution
      |                        |                       |
      v                        v                       v
+-----------------+     +-----------------+     +-----------------+
| PAT or GitHub   | --> | 25 API          | --> | Agents use      |
| App credentials |     | operations +    |     | tools for issue |
| (encrypted)     |     | Claude Code     |     | mgmt, PRs, CI,  |
|                 |     | launcher        |     | and code tasks  |
+-----------------+     +-----------------+     +-----------------+

When you create a connection, you provide authentication credentials (Personal Access Token or GitHub App). You then configure individual tools for the specific GitHub operations your agents need, or use the setup wizard to auto-create all 25 tools at once. Agents execute these tools during their workflows to read and write GitHub data.

Getting Started

Prerequisites

Before connecting GitHub:

1. Pro Plus+ Subscription - GitHub Integration requires the custom.github feature code on your subscription
2. GitHub Account - You need a GitHub account with access to the repositories your agents will use
3. Authentication Credentials - Either a Personal Access Token (PAT) or a GitHub App installation (see Authentication section below)
4. Control Bridge Admin Access - You must be a Control Bridge administrator to configure the integration

Step 1: Navigate to GitHub Settings

1. Navigate to Build > Connections > GitHub
2. Click Add Connection to start the setup wizard

Step 2: Choose Authentication Method

Select one of two authentication methods:

Method	Best For	Rate Limit
Personal Access Token	Single-repo access, personal projects, quick setup	5,000 requests/hour
GitHub App	Organization-wide access, multi-repo, team usage	15,000 requests/hour

Personal Access Token (PAT)

Generate a fine-grained PAT from GitHub:

1. Go to GitHub Settings > Developer Settings > Personal Access Tokens > Fine-grained tokens
2. Click Generate new token
3. Set a descriptive name and expiration date
4. Select the repositories to grant access to
5. Grant the required permissions (see Required Permissions section)
6. Copy the generated token

tip

Fine-grained PATs are recommended over classic PATs because they allow per-repository access and granular permission scoping.

GitHub App

For organization-level access:

1. Go to your GitHub organization Settings > Developer Settings > GitHub Apps
2. Create a new GitHub App with the required permissions
3. Install the app on the repositories you want agents to access
4. Note the App ID, generate a Private Key, and record the Installation ID

Step 3: Configure Connection Details

Enter the following information in the setup wizard:

Field	Description
Connection Name	A unique identifier (lowercase, no spaces) used internally
Display Name	Human-readable name shown in the UI
Description	Optional description of this connection's purpose
Auth Type	Personal Access Token or GitHub App

For Personal Access Token:

Field	Description
Personal Access Token	Your GitHub PAT (stored encrypted with AES-256-CBC)
Token Expiration	Optional expiration date for tracking and rotation reminders

For GitHub App:

Field	Description
App ID	Your GitHub App's numeric ID
Private Key	The PEM private key (stored encrypted with AES-256-CBC)
Installation ID	The installation ID for your organization

Step 4: Set Repository Scope

Field	Description
Default Owner	Default GitHub organization or username for operations
Default Repository	Default repository for operations when not specified per-tool
Allowed Repositories	Optional allow-list restricting which repositories agents can access

warning

If you leave the Allowed Repositories field empty, agents can access any repository the token has permissions for. Use an allow-list for production environments to limit scope.

Step 5: Configure Write Protection

Setting	Description
Allow Write Operations	Master toggle enabling create, update, delete, merge, trigger, cancel, and rerun operations

When disabled, all write operations are blocked at the connection level regardless of individual tool settings. Read operations (list, get, compare) always work.

Step 6: Test and Save

1. Click Test Connection to verify credentials and check granted permissions
2. Review the rate limit status and granted scopes shown in the test results
3. Click Save to create the connection

After saving, the setup wizard offers to auto-create all 25 API tools for the connection.

Step 7: Assign Tools to Agents

1. Navigate to Build > AI Agents > Agents
2. Edit the agent that should use GitHub tools
3. In the Tools section, find your GitHub tools
4. Enable the specific tools the agent needs
5. Save the agent

Available Operations (25 Tools)

When you create tools for a GitHub connection, you choose from 25 operations across four categories. Each operation becomes an individual tool that can be assigned to agents independently.

Issues (6 operations)

Operation	Type	Description
list_issues	Read	Query issues with filters for state, labels, assignees, milestone, and date range
get_issue	Read	Get a single issue with full details including body, labels, and comment count
create_issue	Write	Create a new issue with title, body, labels, assignees, and milestone
update_issue	Write	Update issue title, body, state, labels, or assignees
add_issue_comment	Write	Add a comment to an existing issue
list_issue_comments	Read	Get all comments on an issue with author and timestamp

Pull Requests (8 operations)

Operation	Type	Description
list_pull_requests	Read	Query PRs with filters for state, base branch, head branch, and sort order
get_pull_request	Read	Get a single PR with details including review status, mergeable state, and diff stats
create_pull_request	Write	Create a new PR with title, body, base branch, and head branch
update_pull_request	Write	Update PR title, body, or state (open/closed)
add_pr_comment	Write	Add a review comment to a PR
list_pr_comments	Read	Get all comments on a PR
list_pr_files	Read	Get the list of files changed in a PR with additions, deletions, and patch data
merge_pull_request	Write	Merge a PR using merge, squash, or rebase strategy

GitHub Actions (8 operations)

Operation	Type	Description
list_workflows	Read	List all workflow definitions in a repository
list_workflow_runs	Read	Query workflow runs with filters for status, branch, actor, and event
get_workflow_run	Read	Get details of a specific workflow run including timing and conclusion
list_workflow_jobs	Read	Get all jobs for a workflow run with step-level status
get_job_logs	Read	Download the full log output for a job, useful for debugging failures
trigger_workflow	Write	Trigger a workflow_dispatch event with optional input parameters
cancel_workflow_run	Write	Cancel a workflow run that is in progress
rerun_workflow	Write	Re-run a failed or cancelled workflow

Repository (5 operations)

Operation	Type	Description
get_repository	Read	Get repository metadata including visibility, default branch, and language
list_branches	Read	List all branches with protection status
list_commits	Read	Query commits with filters for author, path, and date range
get_commit	Read	Get a single commit with full diff, author, and file changes
compare_commits	Read	Compare two commits or branches showing ahead/behind counts and file changes

Configuring Individual Tools

After creating a connection, you can fine-tune each tool's behavior.

Tool Settings

Field	Description
Tool Name	Unique identifier for this tool
Display Name	Name shown to agents during tool selection
Description	Helps the agent understand when to use this tool (critical for good tool selection)
Default Owner/Repo	Override the connection-level defaults for this specific tool
Max Results	Limit results for list operations (reduces token usage)
Result Format	JSON (raw data), Markdown (formatted tables), or Summary (brief counts and titles)

Security Settings

Setting	Description
Require Confirmation	When enabled, the agent must get human approval before executing this tool

Testing Tools

1. Navigate to Build > Connections > GitHub
2. Click on your connection, then go to the Tools tab
3. Click Test on any tool
4. Enter sample parameters in the test dialog
5. Execute and verify the results match expectations

Webhooks

Receive real-time notifications from GitHub to trigger agent workflows automatically.

Supported Events

Event	Actions	Description
issues	opened, closed, edited, labeled, unlabeled, assigned	Issue lifecycle events
pull_request	opened, closed, merged, review_requested, ready_for_review	PR lifecycle events
workflow_run	completed, requested	GitHub Actions workflow events
push	-	Code pushed to any branch
issue_comment	created, edited, deleted	Comments on issues or PRs

Creating a Webhook Subscription

1. Navigate to Build > Connections > GitHub
2. Click on your connection
3. Go to the Webhooks tab
4. Click Add Webhook

Field	Description
Repository	Owner/repo to subscribe to events from
Events	Which event types to receive
Trigger Agent	The agent to trigger when events are received
Filter Expression	Optional filter to narrow which events trigger the agent

When you save the subscription, the system automatically registers the webhook in the GitHub repository. A webhook secret is generated and used for HMAC-SHA256 signature validation on incoming payloads.

tip

You do not need to manually configure webhooks in GitHub. The system registers and manages them automatically. If you delete a subscription, the corresponding GitHub webhook is also removed.

Viewing Webhook Logs

Monitor incoming webhook deliveries:

1. Navigate to Build > Connections > GitHub
2. Select your connection
3. Go to the Webhooks tab
4. Click View Logs on a subscription
5. Each log entry shows the event type, action, processing status, and whether an agent was triggered

Claude Code Launcher

For complex development tasks, the Claude Code Launcher executes Claude Code CLI in an isolated environment to clone repositories, make code changes, run tests, and create pull requests.

info

Claude Code Launcher requires the custom.claude_code feature code (Enterprise tier only) and a container environment capable of running the Claude Code CLI. Contact support for infrastructure setup assistance.

How It Works

Agent Request         Task Queued          Claude Code Runs       Result
     |                    |                     |                   |
     v                    v                     v                   v
+-----------+       +-----------+        +---------------+    +----------+
| Agent     | ----> | Task      | ----> | Clone repo    | -> | PR       |
| requests  |       | queued as |        | Create branch |    | created  |
| code      |       | 'pending' |        | Run Claude    |    | Agent    |
| changes   |       |           |        | Run tests     |    | resumes  |
|           |       |           |        | Push + PR     |    | with URL |
+-----------+       +-----------+        +---------------+    +----------+

1. An agent identifies a code task and invokes the Claude Code tool
2. The tool creates a task record in pending state and pauses the agent's execution
3. A timer processor (runs every 30 seconds) picks up pending tasks respecting per-connection concurrency limits
4. The launcher clones the repository, creates a branch, executes Claude Code with the instructions, optionally runs tests, and creates a pull request
5. The agent resumes with the task result (PR link, branch name, or error details)

Registering a Repository

Before agents can use Claude Code, register the repository:

1. Navigate to Build > Connections > GitHub
2. Click on your connection
3. Go to the Repos tab
4. Click Add Repository

Field	Description
Owner	GitHub organization or username
Repository	Repository name
Base Branch	Default branch to start from (e.g., main)
Run Tests	Whether to execute tests before pushing changes
Test Command	The test command to run (e.g., npm test, pytest)
Create PR	Automatically create a pull request on completion
Max Concurrent Tasks	How many Claude Code tasks can run simultaneously for this connection (default: 2)
Max Execution Minutes	Timeout for individual tasks (default: 30 minutes)

Task Monitoring

View Claude Code task history and status:

1. Navigate to Build > Connections > GitHub
2. Click on your connection
3. Go to the Tasks tab
4. Filter by status: Pending, Running, Completed, Failed, or Timed Out

Each task shows the instructions given, branch created, test results, PR link (if created), and execution duration.

You can Cancel pending or running tasks, or Retry failed tasks from this page.

Required GitHub Permissions

Fine-Grained PAT Permissions

Permission	Access Level	Required For
Issues	Read and Write	All issue operations
Pull Requests	Read and Write	All PR operations
Actions	Read and Write	Workflow operations
Contents	Read (Write for Claude Code)	Repository operations, code changes
Metadata	Read	Required for all operations
Projects	Read and Write	Assigning issues to Projects v2 boards

Classic PAT Scopes

Scope	Description
repo	Full repository access (issues, PRs, contents)
workflow	GitHub Actions read/write
project	Projects v2 board access (required for assigning issues to projects)

GitHub App Permissions

If using a GitHub App, grant these repository permissions:

Permission	Access Level	Required For
Issues	Read and Write	All issue operations
Pull Requests	Read and Write	All PR operations
Actions	Read and Write	Workflow operations
Contents	Read (Write for Claude Code)	Repository operations, code changes
Metadata	Read	Required for all operations

And these organization permissions:

Permission	Access Level	Required For
Projects	Read and Write	Assigning issues to Projects v2 boards

tip

Fine-grained PATs are strongly recommended. They provide per-repository scoping and can be restricted to only the permissions each connection needs.

Rate Limiting

GitHub API enforces rate limits that the integration handles automatically:

Auth Type	Rate Limit	Search Limit
Personal Access Token	5,000 requests/hour	30 requests/minute
GitHub App	15,000 requests/hour	30 requests/minute

The integration automatically:

• Tracks remaining requests per connection using GitHub's rate limit headers
• Backs off when approaching limits
• Logs rate limit warnings in the audit log
• Displays current rate limit status on the connection details page

Security

Token Encryption

All authentication credentials are encrypted using AES-256-CBC:

• Tokens and private keys are encrypted immediately on save
• Decrypted only at execution time, never stored in memory longer than needed
• Never included in logs or API responses
• Uses GITHUB_ENCRYPTION_KEY if set, otherwise falls back to DB_ENCRYPTION_KEY

Write Protection

Multiple layers prevent unintended modifications:

1. Connection-level - AllowWriteOperations master toggle blocks all write operations when disabled
2. Tool-level - RequireConfirmation flag on individual tools requires human approval before execution
3. Repository allow-lists - Restrict which repositories agents can access

Webhook Security

• Webhook secrets are auto-generated and stored encrypted
• Incoming payloads are validated using HMAC-SHA256 with constant-time comparison to prevent timing attacks
• Webhook secrets are never returned in API responses

Audit Logging

Every GitHub operation is recorded in the audit log:

• Operation type and parameters
• Success or failure status with error details
• Response duration
• Rate limit usage after each call
• Associated agent and execution ID

Tenant Isolation

• All database queries include TenantId scoping
• Tool cache keys include tenant ID to prevent cross-tenant access
• Each connection's credentials are isolated to the owning tenant

Troubleshooting

Authentication Errors (401)

Problem: API returns 401 Unauthorized

Solutions:

1. Verify the PAT has not expired (check the Token Expiration field on the connection)
2. Confirm the token has the required permissions for the operation being attempted
3. For GitHub App connections, verify the App ID, Private Key, and Installation ID are correct
4. Regenerate the token in GitHub and update the connection
5. Click Test Connection to validate credentials

Rate Limit Exceeded (403)

Problem: API returns 403 with rate limit exceeded message

Solutions:

1. Check current rate limit status on the connection details page
2. Wait for the rate limit reset window (shown in the UI)
3. Consider switching from PAT to GitHub App for 3x higher rate limits
4. Reduce the number of agents querying the same connection simultaneously
5. Use the Summary result format to reduce follow-up queries

Repository Not Found (404)

Problem: Cannot access repository

Solutions:

1. Verify the repository owner and name are spelled correctly
2. For private repositories, ensure the token grants access to that specific repository
3. For organization repositories, confirm the token owner has membership in the organization
4. Check the Allowed Repositories list on the connection - the repo may be excluded

Webhook Not Receiving Events

Problem: Webhook logs show no deliveries

Solutions:

1. The system auto-registers webhooks in GitHub. Verify it appears in your repository's Settings > Webhooks
2. In GitHub's webhook settings, click Recent Deliveries to check if GitHub is sending events
3. If GitHub shows deliveries but they are failing, check the response code for clues
4. Verify the webhook subscription is Active (not paused or deleted)

Claude Code Task Stuck in Pending

Problem: A Claude Code task remains in pending state

Solutions:

1. Check the per-connection concurrency limit (Max Concurrent Tasks). If other tasks are running, the pending task waits for capacity
2. Verify the container environment is running and the task processor timer is active
3. Check the Tasks tab for any running tasks that may be blocking
4. If a task is stuck, use the Cancel button and retry

Tool Not Appearing in Agent Configuration

Problem: GitHub tools do not appear when editing an agent

Solutions:

1. Verify the tool status is Active (not disabled) on the Tools tab
2. Confirm the connection status is Active
3. Refresh the page
4. Verify you have settings:write permission in Control Bridge

Best Practices

Token Management

• Use fine-grained PATs with the minimum permissions required
• Set expiration dates and rotate tokens regularly
• Use separate connections for different permission levels (e.g., read-only for monitoring, read-write for operations)
• Consider GitHub App authentication for production use with higher rate limits

Repository Scoping

• Always configure Allowed Repositories on production connections to limit blast radius
• Set default owner and repository on connections to reduce per-tool configuration
• Override defaults at the tool level only when a tool needs access to a different repository

Agent Instructions

Include clear guidance in your agent's system prompt for using GitHub tools effectively:

When handling bug reports:
1. First search existing issues using list_issues with label and keyword filters
2. If no duplicate exists, create a new issue with:
   - Clear title describing the problem
   - Labels based on severity and component
   - Assignee based on component ownership
3. Reply to the reporter with the issue link

When monitoring CI/CD:
1. Use get_workflow_run to check the run status
2. If failed, use list_workflow_jobs then get_job_logs to identify the error
3. Post a diagnostic summary as a comment on the associated PR

Write Operation Safety

• Start with AllowWriteOperations disabled to verify read operations work correctly
• Enable write operations only after testing and confirming agent behavior
• Use RequireConfirmation on high-impact operations like merge_pull_request and trigger_workflow
• Review audit logs regularly to verify agents are using write operations appropriately

Claude Code Tasks

• Start with conservative concurrency limits (1-2 concurrent tasks) and increase as you gain confidence
• Always enable test execution for production repositories
• Set reasonable timeout limits to prevent runaway tasks
• Monitor the Tasks tab regularly for failed or timed-out tasks

Related Topics

• Tools Overview - All available agent tools
• Agents - Configure agents to use tools
• HTTP API Tools - Connect other REST APIs
• Agent Executions - View tool execution logs