The organisation owner makes one GitHub App. It gives Factorial a credential for every agent run, with its own identity in the audit log and no dependence on one person's account. It takes about 10 minutes.
Before you start
- You must be an owner of the GitHub organisation that holds the repositories.
- You need a machine that runs Docker. Run the factory gives the steps for it.
- Decide which repository Factorial manages first. You select it when you install the App.
Create the App
Go to the settings of your organisation, then Developer settings, then GitHub Apps. Make the App at the organisation level. Do not make it on a personal account. A personal App stops work when that person leaves.
| Field | Value |
|---|---|
| Name | A name for your factory, for example acme-software-factory |
| Homepage URL | Any URL your organisation chooses. GitHub needs one |
| Webhook, Active | Remove the tick. This App gives credentials. It does not receive events |
| Where can this be installed | Only on this account |
Set the permissions
Set these repository permissions. Do not set more.
| Permission | Level |
|---|---|
| Contents | Read & write |
| Issues | Read & write |
| Pull requests | Read & write |
| Webhooks | Read & write |
| Checks | Read-only |
| Artifact metadata | Read-only |
| Metadata | Read-only (GitHub adds this) |
| Administration | Read-only, optional |
| Workflows | Do not set this permission |
The App never has workflows: write. CI runs agent-written code with your repository secrets, and a token that could edit workflows could change the CI that examines it.
Checks Read-only lets Factorial read check runs for its ci_green condition. Keep write off: a check that an agent can forge would let agent output vouch for itself.
Administration Read-only is optional. With it, the branch-protection row on the Configuration page reports what protection the default branch has. Without it, the row says "not checked" and everything else works.
Do not set Administration to Read & write. Branch protection stops agent-written code from reaching the default branch without a person. An App that can write protection can remove it. The dashboard therefore has no button for this: it prints a gh command for you to run under your own credentials.
Install the App
- Open the App and choose Install App.
- Select Only select repositories.
- Select the repository that Factorial manages.
- Do not select All repositories.
- Install the App. The installation ID is the number at the end of the URL after you install.
The list of installed repositories is the limit of what the factory can touch. A project's Configuration page has a GitHub App access row. It shows the account, whether the installation covers all repositories or selected ones, and whether this project's repository is among them. The row links to the installation settings on GitHub. Only an owner of the account can open that page.
Make the private key
On the General page of the App, make a private key. GitHub gives you the .pem file one time only.
A person who has this file can act as the App. Keep it in your secret store. Do not send it in chat or in email.
On the machine that runs Factorial, keep the file at ~/.config/factorial/app.pem with mode 0600. Never put the key in .env, and never commit it.
On an E2B runtime, the key stays out of the sandbox of the agent. In the container, an agent on a host runtime runs as the same user as Factorial. That agent can read the copy of the key, the .env file and the database. Use an E2B runtime for containment. See Security.
Note these two numbers. Run the factory asks for them:
- the App ID, from the General page of the App
- the Installation ID, from the installation URL
Two requests to refuse
People ask for these two changes. Say no to both.
- "Do we set Workflows also?"
- No. Agents write code, and CI examines that code with repository secrets. Write access to
.github/workflows/lets an agent change the CI that examines it. Because the App does not have this permission, no token can get it later. - "Is All repositories more simple?"
- No. "All repositories" makes the limit the full organisation. The factory needs only the repositories it manages today.
A permission that you add later needs a second approval. The App declares it, and each installation must accept it on the organisation's Settings, GitHub Apps, Configure page. Before that, a token request for the new permission fails.
What the team does next
The team runs Factorial with the App ID, the installation ID and the key. Run the factory gives the steps. Then Connect a repository adds the first project.
How Factorial uses the App
For each agent run, Factorial signs a short request with the private key and gets a token from GitHub. The token is valid for one hour. It gives access to the named repository only, and to the named permissions only. Factorial fails the request unless GitHub grants exactly the permissions it asked for. The token is the only GitHub credential that Factorial gives an agent. See Security.
Rotate or revoke
| Event | Action |
|---|---|
| You think the key leaked | On the General page of the App, revoke the private key. Make a new one, and replace the file at ~/.config/factorial/app.pem |
| Someone leaves | Nothing. The organisation owns the App |
| You want to narrow access | Change the list of repositories in the installation |
| You shut the factory down | Uninstall the App. Every token that is still out dies within the hour |
Uninstalling is the fastest way to stop everything. It ends every token from that installation. You do not touch any repository or any running container.
Check a token
A token from the App must give these two results against the installed repository:
- A read of the repository returns
200. - A write to a file under
.github/workflows/returns403, with the message "Resource not accessible by integration".
To check the permissions without a token, open the organisation's Settings, GitHub Apps, Configure page for the App. If Workflows is in the list, remove that permission at once.