Skip to content
Agent HQ

GitHub

GitHub is the primary integration for Agent HQ. It enables Pilot to work directly with your repositories — cloning code, creating branches, making changes, and opening pull requests.

Setup

Section titled “Setup”

Connecting your account

Section titled “Connecting your account”
  1. Go to Integrations in the sidebar
  2. Click Connect next to GitHub
  3. You’ll see a device code — copy it
  4. Click the link to go to GitHub’s verification page
  5. Paste the device code and authorize the Agent HQ application
  6. Return to Agent HQ — your GitHub account is now connected

Organization access

Section titled “Organization access”

If your repositories belong to a GitHub organization, you may need to grant the Agent HQ OAuth application access:

  1. Go to your GitHub organization settings
  2. Navigate to Third-party access or OAuth App policy
  3. Approve the Agent HQ application

What Pilot can do with GitHub

Section titled “What Pilot can do with GitHub”

Repository operations

Section titled “Repository operations”
  • Clone — pull down your repo into an isolated sandbox
  • Branch — create task-specific branches (e.g., taskyou/fix-auth-bug-abc123)
  • Commit — commit code changes with clear messages
  • Push — push branches to your remote
  • Pull Request — open PRs with descriptive titles and bodies

When a task runs

Section titled “When a task runs”
  1. The linked repo is cloned into the task’s sandbox
  2. A new branch is created from the project’s default branch
  3. Pilot makes code changes on this branch
  4. Changes are committed and pushed
  5. A pull request is created linking back to the task

Pull request format

Section titled “Pull request format”

PRs created by Agent HQ include:

  • Title — a concise summary of the change
  • Body — what was changed, why, and any relevant context
  • Link — a reference back to the task in Agent HQ

Linking repos to projects

Section titled “Linking repos to projects”

When creating or editing a project:

  1. Click Connect Repository
  2. Select a repo from the list of your accessible repositories
  3. Choose the default branch (main, master, develop, etc.)
  4. Save

The repo is now linked. All tasks in this project will use this repo as their starting point.

Troubleshooting

Section titled “Troubleshooting”

Cannot see a repository

Section titled “Cannot see a repository”
  • Ensure your GitHub account has access to the repo
  • For organization repos, verify the OAuth app is authorized
  • Try disconnecting and reconnecting GitHub

Push failed

Section titled “Push failed”
  • Check that your GitHub account has write access to the repo
  • Verify the branch isn’t protected in a way that blocks pushes
  • Check that the GitHub integration is still connected (token not expired)

Authentication errors

Section titled “Authentication errors”

GitHub tokens can expire. Go to Integrations and click Reconnect next to GitHub to refresh your credentials.