GitHub App installation
Delta AI writes into your GitHub organisation, so it needs an installation there. This page explains what the App is, why it asks for the permissions it does, and what to do when an installation is missing or has lost a permission.
Why an App and not a personal token
Section titled “Why an App and not a personal token”A GitHub App is installed on an organisation, not on a person. That means:
- The work does not stop when an individual leaves or revokes a token
- Access is scoped to the repositories you choose
- Permissions are visible to your organisation admins and revocable by them
- Delta AI never holds a credential that can act as a human
A personal access token would tie every generated pull request to one person’s account. An App keeps the audit trail honest.
What the App does
Section titled “What the App does”During a run, the App:
- Creates a repository for each service in your organisation
- Pushes a branch containing the specification and implementation
- Opens a pull request against your default branch
- Merges the pull requests once every one in the change set is approved
It does not read repositories you have not granted, and it does not act outside the organisation it is installed on.
Why it needs broad permissions
Section titled “Why it needs broad permissions”The App requests full access to the repositories it manages. That is a deliberate choice, and it is broader than a typical integration, so it is worth being explicit about why.
Repository creation requires organisation-level administration. Creating a repository is not a repository-scoped permission — it is an organisation permission. An App that can only read and write existing repositories cannot create the ones your services need.
Each service is its own repository. A six-service project creates six repositories plus the system design repository. The App has to be able to create all of them, which means it needs the organisation-level grant.
Contents, pull requests and workflows are all written. The App pushes source, opens pull requests, and in some cases adds workflow files. Each of those is a separate permission, and all of them are needed for a run to complete.
Installing
Section titled “Installing”Installation happens once per organisation, from the workspace when you first connect GitHub. The flow is:
- Choose the organisation
- Grant access — all repositories, or a selection
- Approve the requested permissions
- You are returned to the workspace
If you are not an organisation owner, GitHub will ask an owner to approve the installation. The workspace shows the installation as pending until they do.
When permissions have drifted
Section titled “When permissions have drifted”An installation can stop working without anyone changing it. Common causes:
- An organisation owner narrowed the App’s repository access
- An owner revoked a permission during a security review
- The App was uninstalled and reinstalled with different settings
- A repository was transferred out of the organisation
The symptom is a run that fails with a permission error, or a change set that moves to Needs action with a message naming the missing permission.
Checking the installation
Section titled “Checking the installation”In GitHub, go to Settings → Applications → Installed GitHub Apps, find the Delta AI App, and open Configure. Check two things:
| Setting | What it should be |
|---|---|
| Repository access | All repositories, if you want new services created |
| Permissions | Unchanged from what the App requested |
Re-consenting
Section titled “Re-consenting”If a permission was revoked, GitHub marks the installation as requiring review. An organisation owner has to approve the new permissions before the App can act again. Until they do, runs that need the revoked permission fail.
After re-consenting, retry the failed run from the change set panel. It continues from where it stopped rather than starting over.
When the App is not installed at all
Section titled “When the App is not installed at all”A workspace with no installation can still be opened, but no run can create anything. The composer will accept a prompt and the workflow will fail at the first step that needs GitHub.
Install the App from the workspace, then retry.
Removing access
Section titled “Removing access”Uninstalling the App stops all future runs. It does not delete anything already created: your repositories, branches and pull requests stay where they are, under your organisation’s control.