Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runaegis.co/llms.txt

Use this file to discover all available pages before exploring further.

Aegis acts as a governance layer between your AI agents and GitHub. To inspect repository state, evaluate branch policies, and route pull request actions on your behalf, Aegis needs your GitHub identity and a personal access token (PAT) with the right scopes. You provide these once during onboarding and can update them at any time from Settings.

​
What you need before you start

Before connecting GitHub, collect the following:
  • GitHub username, your GitHub login name (e.g. octocat).
  • GitHub user ID, the numeric ID for your account, not the username.
  • Personal access token, a classic or fine-grained PAT with the required scopes listed below.
Your GitHub user ID is a number, not your username. Look it up by visiting https://api.github.com/users/YOUR_USERNAME in a browser and reading the id field in the JSON response.

​
Required PAT scopes

Your PAT must have all three of the following scopes. Aegis will not function correctly if any are missing.
ScopeWhy Aegis needs it
repoRead repository contents, branches, and pull request state. Required for policy evaluation on any private or public repo.
read:userVerify your GitHub identity and confirm the user ID you provide matches your token.
workflowInspect and interact with GitHub Actions workflows. Required for CI-status checks used by policies like CI Required Before Merge.
Treat your PAT like a password. Anyone with access to it can perform GitHub operations under your identity. Never share it or commit it to a repository.

​
Create a personal access token

1

Open GitHub token settings

Go to github.com/settings/tokens. Sign in if prompted.
2

Choose a token type

Click Generate new token and select Generate new token (classic). Fine-grained tokens are supported, but classic tokens are the simplest way to grant the three required scopes in one step.
3

Set a name and expiration

Give the token a descriptive name such as Aegis governance and choose an expiration that fits your rotation policy. Tokens with no expiration are convenient but are not recommended for production use.
4

Select the required scopes

Check the boxes for repo, read:user, and workflow. You do not need any other scopes.
5

Generate and copy

Click Generate token. Copy the token value, GitHub only shows it once. Paste it somewhere secure before closing the page.
If your organization enforces SSO, you may need to click Authorize next to the token after generating it so it can access organization repositories.

​
Add your credentials in Aegis

During initial setup, the onboarding flow collects your GitHub credentials in step 1. If you have already completed onboarding, navigate to Settings → GitHub to view your current connection or go to Settings → Profile to update your PAT.
1

Open the GitHub settings section

In the Aegis dashboard, click Settings in the sidebar, then select GitHub under the Integrations group. You will see your current username, numeric user ID, and the scopes your token requires.
2

Update your credentials if needed

If you need to change your PAT, go to Settings → Profile, scroll to the Personal access token card, paste your new token into the field, and click Update token.

​
Sync your repositories after connecting

Providing your credentials does not automatically import your repositories. You must trigger a sync so Aegis can discover the repos your PAT can access. After saving your GitHub credentials, navigate to Settings → Repositories and click Sync. Aegis uses your GitHub user ID and PAT to discover the repositories your token can access. New repositories added to your account will not appear in Aegis until you sync again. For details on setting read and write permissions for each repository after syncing, see Repository permissions.

​
Rotate your PAT

When you generate a new PAT to replace an expiring or compromised one:
  1. Create the new token on GitHub with the same three scopes.
  2. In Aegis, go to Settings → Profile and paste the new token into the GitHub PAT field.
  3. Click Update token.
  4. Revoke the old token on GitHub at github.com/settings/tokens.
If you revoke your PAT before updating it in Aegis, all agent governance and repository syncing will stop working until you provide a valid replacement token.