Connect GitHub¶
Forge reads one repository only when a deployment needs it. Connecting GitHub is several separate facts, not one switch: a success in one does not establish another.
The four facts¶
| Fact | What establishes it |
|---|---|
| Aegis identity | aegis auth login binds the profile to your account. |
| GitHub App installed | The Forge GitHub App is installed on the GitHub account or organization that owns the repository. An organization may require an administrator to approve it. |
| Repository grant | That installation grants access to exactly OWNER/REPOSITORY. All-repositories access is broader, but it is not the same as selecting the one repository. |
| Deployment association | The App is associated with the profile, agent and repository that request this deployment. |
The last fact is the one that is easiest to miss. Forge resolves the deployment for one context tuple: profile, agent and repository. A grant made for another profile, another agent or another repository does not cover this deployment, even though GitHub reports the App and its installation as healthy.
One next action per state¶
Work out which fact is missing, then take the single action that establishes it. Do not repeat an earlier action because a later state is still missing.
| What you see | Missing fact or state | Next action |
|---|---|---|
aegis auth status reports the profile as signed out, or a journey exits 66 with no bound account for this profile |
Aegis identity | Run aegis auth login. |
| The setup or GitHub App page offers to install the App | GitHub App installed | Install or authorize the Forge App on the owning account or organization. An administrator may need to approve it. |
The App is installed, but the repository list does not include OWNER/REPOSITORY |
Repository grant | Update the App installation's repository access to include exactly that repository. |
| The setup page reports a missing association for the exact profile, agent and repository | Deployment association | Associate the existing App for that context. Do not reinstall the App or change permissions again. |
| App installation, repository access and association are valid, but the setup page reports an expired deploy grant | Deployment authorization has expired | Use Renew deploy authorization. Renewing the grant is distinct from associating the App or changing repository permissions. |
A "repository access updated" confirmation from GitHub proves only the repository grant. It does not prove that the App is associated with this profile, agent and repository, and it does not prove that a deployment will be accepted.
In Aegis 0.9.4¶
aegis forge deploy does not open a browser and does not print a GitHub setup
URL. When the context tuple is not authorized, the command ends with a
value-free preflight refusal, forge_preflight_refused, and exits 1. The
same refusal also covers a service-side refusal, so read it as "the request
was not accepted", then check the four facts and whether deployment
authorization is still current. A generic refusal alone does not identify
a missing association.
The setup page that names the context tuple and offers to associate an existing App is being improved; it is not part of the 0.9.4 CLI. If an association is missing and the page is unavailable to you, ask your Forge administrator to associate the existing App for this exact context. A page opened for a different profile, agent or repository addresses a different deployment context. If the association is valid but the deploy grant has expired, use Renew deploy authorization instead.
After authorization¶
Run aegis forge deploy again from the same repository and commit. The
request keeps its source selection; a successful run prints
aegis: forge deploy accepted <deployment_ref>.
Your own GitHub credentials perform ordinary Git operations, including the push that publishes the commit. Forge adds no workflow to the repository. Read Security and trust for the separation of authorities and Deploy for source selection.
Keep out of reports¶
Record the repository, commit, profile and agent, and the outcome of each state. Do not include tokens, App private keys, installation secrets or raw authorization material.