GitHub Token Setup
Configure a GitHub personal access token to enable commit enrichment, PR metadata, and changed file tracking for your services.
A GitHub personal access token allows BlameTrail to fetch commit metadata, pull request details, and changed files for your deploys. This data powers commit enrichment, suspect scoring context, AI-generated incident summaries, and fix proposal PR creation.
Creating a token
- Go to GitHub Settings > Developer settings > Personal access tokens.
- Click Generate new token (classic).
- Give it a descriptive name (e.g.,
BlameTrail - Acme Corp). - Select the required scope:
| Repository visibility | Required scope |
|---|---|
| Private repositories | repo |
| Public repositories only | public_repo |
- Set an expiration. If your token expires, enrichment will stop working until you replace it.
- Click Generate token and copy it immediately. GitHub only shows the token once.
Adding the token to BlameTrail
Organization-wide token
An organization-wide token applies to all services in your organization:
- Navigate to Organization > Settings.
- In the GitHub section, paste your personal access token.
- Click Save.
All services linked to a GitHub repository will use this token for enrichment.
Per-service token
You can override the organization-wide token for individual services:
- Open the service you want to configure.
- In the service settings, add a GitHub token in the repository section.
- Click Save.
This token takes priority over the organization-wide token for that specific service.
Security
- Tokens are encrypted at rest. They are never stored in plaintext.
- The API never returns a saved token. You can replace or delete a token, but you cannot retrieve it.
- Tokens are only used server-side for GitHub API calls. They are never sent to the browser.
What the token enables
Once a token is configured and a service is linked to a repository (in owner/repo format), BlameTrail automatically enriches deploys with:
- Full commit messages for all commits in a deploy
- Linked pull request titles, numbers, and authors
- Changed files ranked by relevance
This enrichment data appears on deploy detail pages, in suspect scoring results, and in AI-generated incident summaries.
When fix proposals are enabled (Starter/Pro plans), the same token is used to create branches, commit fixes, and open pull requests on your repository.
Updating or revoking a token
To update a token, paste a new token in the same location (organization settings or service settings) and save. The old token is replaced immediately.
If you revoke a token on GitHub, BlameTrail will log authentication failures when attempting enrichment. Deploys will still be recorded, but without enrichment data. Replace the token in BlameTrail to restore enrichment.
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
| No enrichment data on deploys | Token not configured or service not linked to a repository | Verify both the token and the repository field are set |
| 401 errors in logs | Token revoked or expired on GitHub | Generate a new token and update it in BlameTrail |
| 404 on private repos | Token has public_repo scope but not repo | Regenerate with the repo scope |
| Enrichment works for some services but not others | Per-service token override missing for certain repos | Add a per-service token or ensure the org-wide token has access to all relevant repos |