Connect GitHub

Forge uses a GitHub App grant to read source for deploys. Use the setup link for the customer account so the GitHub App installation is bound to the same production account context that will fetch source and serve the app.

Connecting GitHub is a deploy-time step. It is not required to sign in or to run an agent through Aegis; Aegis requests GitHub authority reactively when a deploy or push actually needs it.

The GitHub App grant is product authorization for connector and deploy flows. It is not a personal access token and it is not host gh authority.

What the grant does

The GitHub App grant answers one question: can Forge read this repository for the customer account context established by setup?

That grant is necessary, but not sufficient, for deploys. A repo also needs Forge onboarding:

Control	Owner	Why it matters
GitHub App installation	GitHub org or repo admin	Allows the Forge GitHub App shown by the customer setup link to read selected repos or all repos in the GitHub owner.
Repo grant	GitHub org or repo admin	Decides which repositories are included in the App installation.
map onboard registration	Forge operator or app developer	Records the repo, installation ref, tenant/account refs, and project/app ref in the Forge control plane.
Deploy trigger	App team	Uses the built-in GitHub App webhook path, direct map deploy, or the optional custom-CI workflow.

Do not use a copied workflow file as proof of access. Forge still checks that the repo is granted to the App and onboarded before accepting deploy requests.

Before onboarding

Confirm these before a developer runs map onboard:

Check	Evidence
The developer is using the customer setup context.	aegis doctor --json from the developer machine.
The target repo is covered by the GitHub App grant.	aegis github status --project-repo <owner/repo> --require --json.
The app identity is agreed.	Served app ref, usually app:<repo-name> or the value the operator gives for map onboard --app-ref.
The account boundary is agreed when used.	Tenant and account refs from the customer account operator.

Developer Flow

Start with local setup:

aegis setup

Plain setup signs you in and prepares local profile state. When GitHub App access is required, setup opens the Forge setup link for the customer account. That link carries the Mithran setup session context Forge needs to associate the GitHub installation with your profile.

Use the setup link even if you already know the GitHub App's page. A direct GitHub installation can leave the App installed in GitHub without giving Forge the setup context it needs to finish the account installation handoff.

Make the target repo explicit when checking grant status:

aegis github status --project-repo <owner/repo> --require --json

--require makes the command fail when the repo grant is missing, revoked, expired, mismatched, or waiting for reauthorization. Use the JSON output when you need evidence for admin review or an escalation packet.

Admin Flow

If GitHub asks for an organization owner, have the owner continue from the same Forge setup link. In GitHub, choose one of:

• Selected repositories for the smallest deploy surface.
• All repositories when your org wants one broad grant for current and additional Forge apps.

The setup status records exact-repository grants and owner-wide grants differently. Owner-wide grants are treated as broader authority than a single target repository.

Change repository selection from the GitHub App installation page for the App shown by the customer setup link.

See Account context and app environments for the distinction between setup context and app environments.

If you administer the GitHub organization, review Administer Forge before choosing all repositories versus selected repositories.

Grant Scope

Forge records the selected scope in the GitHub grant status:

Scope	Status evidence	Operational meaning
Exact repository	selected_grant_ref like scm-grant://github/<owner>/<repo>, scope_kind: repository, and authority_breadth: exact_repository.	Only that repo is covered by the grant.
Owner-wide	selected_grant_ref like scm-grant://github/<owner>/*, scope_kind: organization, and authority_breadth: broader_than_target.	Repos under that GitHub owner can be covered. Treat this as broader source authority.

For owner-wide grants, repo-scoped status can require live proof before the execution target reports ready. If the selected grant does not cover the checked repo, status reports a repository-grant mismatch.

Check the grant

aegis doctor --json

Run this from a Git repository you plan to use with Forge. The GitHub App grant is workspace-scoped; from a directory with no GitHub repository in scope, doctor reports the GitHub App grant as not applicable.

You can also inspect the GitHub grant directly:

aegis github status --project-repo <owner/repo> --require --json

Check these fields in the JSON:

Field	Expected value
state or validation_status	valid.
identity_link.status	linked.
github_app.status	installed.
repository_grant.status	selected.
selected_grant_ref	The exact repo or approved owner-wide scope that covers the repo.
execution_target.ready	true.
raw_credential_material_present	false.

aegis github status --json can infer the repo when you run it from a GitHub checkout. Use --project-repo in evidence packets so the checked repo is unambiguous.

Change Or Revoke Access

Changing the GitHub App grant affects source fetches and deploy starts after the grant change. It does not change app-route exposure, protected sharing policy, or the version served by a published public hostname.

Goal	Action
Add a repo	Add the repo to the GitHub App installation, then run map onboard for that repo.
Remove a repo	Remove it from the GitHub App installation. Also disable the optional custom-CI workflow if that repo uses one.
Move from selected repos to all repos	Revisit the admin review in Administer Forge; this broadens source access for the GitHub owner.

GitHub App grant changes affect new source fetches. They do not remove an already served route or move the clean public URL.

After any grant change, run:

aegis github status --project-repo <owner/repo> --require --json
map doctor --app <owner/repo>

Next

Configure your app with a mithran.yaml, or jump to Onboard a repo.