GitHub Integration

Connecting a GitHub repository lets Pilot interact with your codebase directly — cloning repos, creating branches, writing code, and opening pull requests.

Setting up GitHub

OAuth authentication

Agent HQ uses GitHub’s device flow for authentication:

1. Go to Settings > Integrations or create a new project
2. Click Connect GitHub
3. You’ll receive a device code — enter it at GitHub’s verification page
4. Authorize the Agent HQ application
5. Once approved, your GitHub account is linked

Repository access

After connecting, you can link any repository you have access to with a project. Pilot inherits your permissions — it can only access repos that your GitHub account can access.

How Pilot uses GitHub

When a task executes

1. Pilot clones the linked repository into an isolated sandbox
2. A new branch is created for the task (e.g., taskyou/fix-login-bug-abc123)
3. Pilot writes code changes on this branch
4. Tests are run if applicable
5. Changes are committed and pushed
6. A pull request is created with a clear description

Pull request workflow

Pull requests created by Pilot include:

• A descriptive title summarizing the change
• A body explaining what was changed and why
• A link back to the task in Agent HQ

You review the PR on GitHub as you would any other. Merge it, request changes, or close it.

Branch management

Each task creates its own branch from the project’s default branch. This ensures:

• Tasks don’t interfere with each other
• Your main branch is never modified directly
• You can review each change independently

Troubleshooting

”Repository not found” errors

Make sure your GitHub account has access to the repository. If the repo belongs to an organization, you may need to grant the Agent HQ OAuth app access in your organization settings.

Authentication expired

GitHub tokens can expire. Go to Settings > Integrations and reconnect GitHub if you see authentication errors.