GitHub Integration

Connect GitHub to enable the AI agent to access code context, pull requests, and deployment information during investigations.

Capabilities

Once connected, the AI agent can:

Capability	Description
Browse Code	View repository files and code
Search Code	Search across repositories
Pull Requests	Review recent PRs and changes
Commits	View commit history and diffs
Deployments	Check deployment status
Actions	Review workflow runs

Prerequisites

• A GitHub account or organization
• A Personal Access Token (PAT) or GitHub App
• Read access to the repositories you want to query

Setup

1

Create a Personal Access Token

You can use either a classic token or a fine-grained token. Classic tokens are required if your organization uses SAML SSO.

Classic token (GitHub docs):

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click Generate new token → Generate new token (classic)
3. Give it a descriptive name
4. Set an expiration date
5. Select the repo scope (grants read access to repositories)
6. Click Generate token and copy it

Fine-grained token (GitHub docs):

1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Click Generate new token
3. Set an expiration date
4. Select the repositories to grant access
5. Set permissions (see Required Permissions below)
6. Click Generate token and copy it

2

Configure SSO (if applicable)

If your GitHub organization uses SAML single sign-on (SSO), you must authorize the token for SSO access after creating it (GitHub docs):

1. Go to Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Next to your token, click Configure SSO
3. Click Authorize next to the organization you want to grant access to

warning

Without SSO authorization, the token will return 403 errors when accessing organization resources, even with the correct scopes.

3

Add Integration in Autoheal

1. Go to Integrations in Autoheal
2. Click GitHub
3. Enter a name (e.g., "Production GitHub")

4

Configure Credentials

Enter the following:

• Token: Your GitHub Personal Access Token
• Organization (optional): Limit to a specific org

5

Test and Save

Click Test Connection to verify, then Save.

Required Permissions

For fine-grained tokens, grant these permissions:

Permission	Access Level	Why It's Needed
Contents	Read	View repository files
Metadata	Read	Access repository information
Pull requests	Read	View PR details
Commit statuses	Read	Check CI/CD status
Actions	Read	View workflow runs
Deployments	Read	Check deployment status

tip

Use fine-grained tokens when possible - they provide more granular control than classic tokens.

GitHub Enterprise

For GitHub Enterprise Server, provide the API URL:

https://github.your-company.com/api/v3

Configure GitHub App for BYOC deployments

Self-hosted (BYOC) deployments of Autoheal use a GitHub App you create under your own GitHub organization. End users then connect via the standard Connect with GitHub OAuth flow — the same flow that Autoheal SaaS uses — so there are no credentials to paste in the UI and no extra auth mode to pick.

You configure the App once, at deploy time, via Helm values (or the equivalent env vars on Docker Compose).

1

Create the GitHub App

Go to https://github.com/organizations/{ORG}/settings/apps/new and create a new App with:

• Homepage URL: https://{autoheal-host}
• Callback URL: https://{autoheal-host}/api/v1/oauth/github_app/callback
• Webhook URL: https://{autoheal-host}/api/v1/webhooks/github
• Webhook secret: a random string you generate. This becomes GITHUB_APP_WEBHOOK_SECRET below.
• Uncheck "Expire user authorization tokens" — Autoheal uses only installation-scoped tokens, not user tokens.
• Under Where can this GitHub App be installed? pick whichever scope suits your org (typically "Only on this account").

2

Set repository permissions

Grant the App read on the resources Autoheal agents need:

Permission	Access	Why it's needed
Contents	Read	Browse repository files
Metadata	Read	Mandatory; repo information
Pull requests	Read	Review PR details
Commit statuses	Read	Check CI/CD status
Actions	Read	View workflow runs
Deployments	Read	Check deployment status

3

Subscribe to webhook events

Under Subscribe to events, enable:

• Installation target (delivered as installation) — Autoheal uses installation.deleted to auto-clean integrations when a user uninstalls the App from their org.
• Repository (delivered as installation_repositories) — keeps the repository list in sync when a user adds/removes repos from the install.

4

Generate and download the private key

On the App's General page, click Generate a private key and download the PEM file. Keep it somewhere secure — you only see the full key once.

Also note the App ID (numeric) and slug (the URL-safe name, visible in github.com/apps/{slug}) from the same page.

5

Configure Autoheal

Encode the private key once. The _BASE64 suffix is the contract — the api-server rejects anything that isn't valid base64 at boot. Run:

base64 -w0 < autoheal-github-app.private-key.pem

Use that single-line blob everywhere below.

Helm: set these values on the api-server-go chart. Supply privateKeyBase64 via --set-file or a CI-rendered Secret so the blob never ends up in committed values history.

githubApp:
  appId: "<app id>"
  slug: "<app slug>"
  hostname: "github.com"
  privateKeyBase64: "<base64 blob>"
  webhookSecret: "<the webhook secret from Step 1>"

Docker Compose: set the equivalent env vars in the environment that starts api-server-go:

GITHUB_APP_ID=<app id>
GITHUB_APP_SLUG=<app slug>
GITHUB_APP_HOSTNAME=github.com
GITHUB_APP_PRIVATE_KEY_BASE64=<base64 blob>
GITHUB_APP_WEBHOOK_SECRET=<the webhook secret>

6

Redeploy and verify

Redeploy Autoheal so the api-server picks up the new values.

In the UI, open Integrations → GitHub → Connect with GitHub. You'll be redirected to github.com/apps/{slug}/installations/new to install the App on an org. After installing, you land back in Autoheal with a new integration row populated for that org.

Rotating the private key

Generate a new private key on the App's General page, update githubApp.privateKeyBase64 (or GITHUB_APP_PRIVATE_KEY_BASE64), and redeploy. Existing integration rows don't need re-linking — GitHub installation IDs are stable across key rotations.

Troubleshooting BYOC setup

'GitHub App is not configured on this deployment' on Connect

The api-server started without GITHUB_APP_ID / GITHUB_APP_PRIVATE_KEY_BASE64. Check the api-server logs on boot — you'll see GitHub App platform credentials not configured when the env vars are missing. Supply both and redeploy.

Webhook not firing on install / uninstall

The App's Webhook URL must be https://{autoheal-host}/api/v1/webhooks/github (plural /webhooks/), and the secret configured on the App must exactly match GITHUB_APP_WEBHOOK_SECRET. Inspect recent deliveries on the App's Advanced page — a signature mismatch returns 401.

Webhooks stop after renaming the GitHub organization

Lifecycle events (suspend / unsuspend / uninstall) are resolved to the Autoheal tenant by the org's login slug, which is what GitHub also rewrites on rename. After a rename, future webhooks arrive with the new slug and are silently ignored because no integration matches. Workaround: recreate the integration in Autoheal after the rename so the new slug is stored.

Cross-org tool calls only use credentials from the first integration

Sandbox executions that explicitly attach multiple GitHub App integration IDs (required_integration_ids) currently inject credentials for the first ID only; additional IDs are reserved for future per-command credential selection. The knowledge service's cross-org cloning is unaffected because it issues one sandbox-execute per integration.

Example Queries

Once connected, you can ask the AI agent:

What changed in the last deployment to production?

Show me recent commits to the payment service

Were there any PRs merged today that touched the database code?

What's the status of the CI pipeline?

Troubleshooting

401 Unauthorized

• Verify the token is correct and hasn't expired
• Check that the token has access to the requested repositories
• For fine-grained tokens, ensure the correct organization is selected

403 Forbidden (SSO)

• If your organization uses SAML SSO, ensure you have authorized the token for SSO
• Go to Settings → Developer settings → Personal access tokens → Tokens (classic), click Configure SSO next to your token, and authorize it for the organization

404 Not Found

• Verify the repository exists and the token has access
• Check the organization/owner name is correct
• Ensure the repository isn't private without proper token access

Rate Limited

• GitHub has API rate limits (5,000 requests/hour for authenticated requests)
• Consider using a GitHub App for higher limits
• Wait for the rate limit to reset