> ## 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.

# GitHub setup

> Provide your GitHub credentials and personal access token so Aegis can inspect your repositories, evaluate agent actions, and manage pull requests.

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.

<Note>
  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.
</Note>

## Required PAT scopes

Your PAT must have all three of the following scopes. Aegis will not function correctly if any are missing.

| Scope       | Why Aegis needs it                                                                                                                |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `repo`      | Read repository contents, branches, and pull request state. Required for policy evaluation on any private or public repo.         |
| `read:user` | Verify your GitHub identity and confirm the user ID you provide matches your token.                                               |
| `workflow`  | Inspect and interact with GitHub Actions workflows. Required for CI-status checks used by policies like CI Required Before Merge. |

<Warning>
  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.
</Warning>

## Create a personal access token

<Steps>
  <Step title="Open GitHub token settings">
    Go to [github.com/settings/tokens](https://github.com/settings/tokens). Sign in if prompted.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Select the required scopes">
    Check the boxes for `repo`, `read:user`, and `workflow`. You do not need any other scopes.
  </Step>

  <Step title="Generate and copy">
    Click **Generate token**. Copy the token value, GitHub only shows it once. Paste it somewhere secure before closing the page.
  </Step>
</Steps>

<Tip>
  If your organization enforces SSO, you may need to click **Authorize** next to the token after generating it so it can access organization repositories.
</Tip>

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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**.
  </Step>
</Steps>

## 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](/configuration/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](https://github.com/settings/tokens).

<Warning>
  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.
</Warning>