The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
Swarm GitHub App
When a Swarm agent works on another person's project, it pushes commits and opens pull requests with the Harness GitHub App, not the GitHub login of the computer it runs on. Each token is for the project's one repository and lasts at most an hour. Harness revokes it as soon as the agent's task ends.
The agent's commits name the person whose project it is as co-author, along with the agent and the computer. This is step 4 of the Swarm team account plan.
Set it up
An owner of the GitHub organization does this once. A Harness server administrator then adds three settings.
1. Create the app
On GitHub, open the organization, then Settings → Developer settings → GitHub Apps → New GitHub App, and fill in:
| Field | Value |
|---|---|
| GitHub App name | Harness where it is free (GitHub needs it to be unique). Its address and its bot account follow it (github.com/apps/harness, harness[bot]): renaming the app later changes both, so set GITHUB_APP_SLUG again. |
| Homepage URL | https://harness.autonomous.ai |
| Callback URL, Setup URL | Leave empty. |
| Webhook → Active | Clear it. Harness subscribes to no events. |
| Repository permissions | Contents: Read and write. Pull requests: Read and write. Checks: Read-only. Actions: Read-only. Metadata: Read-only (GitHub sets this one). Workflows: Read and write, and Issues: Read and write, if agents should push changes to .github/workflows and write issues (see Workflows and issues). Leave every other permission at No access. |
| Organization and account permissions | No access. |
| Where can this GitHub App be installed? | Only on this account |
Click Create GitHub App. These settings match this manifest, if you prefer to register with GitHub's manifest flow:
{
"name": "Harness for Acme",
"url": "https://harness.autonomous.ai",
"public": false,
"hook_attributes": { "active": false },
"default_permissions": {
"contents": "write",
"pull_requests": "write",
"checks": "read",
"actions": "read",
"metadata": "read",
"workflows": "write",
"issues": "write"
},
"default_events": []
}
On the app's page:
- Note the App ID near the top.
- Under Private keys, click Generate a private key. GitHub downloads a
.pemfile. It is the app's only credential: keep it in your secret store. - Note the app's name in its public address,
https://github.com/apps/NAME. This is the slug.
2. Install it
On the app's page, click Install App and choose the organization. Select Only select repositories and pick the repositories your Swarm projects use, or choose All repositories. Click Install. You can add repositories later from the organization's Settings → GitHub Apps → Configure.
If a project uses a repository the app is not installed on, its agents cannot push. They receive the install link to pass on to an organization owner.
Workflows and issues
An agent's token also asks for Workflows and Issues where the repository's
installation has granted them, at no more than the granted level. Without
Workflows, GitHub refuses a push that changes .github/workflows, and on a large
repository it can refuse a push it could not finish checking for workflow changes in
time. Harness reads what each installation has granted and asks only for that, so an
installation that has not granted them keeps getting today's tokens. A grant is
remembered ten minutes, and read again at once when GitHub refuses a token for its
permissions.
To grant them on an app already installed:
- On the app's settings page (Settings → Developer settings → GitHub Apps → the app → Permissions & events), set Workflows and Issues to Read and write and click Save changes.
- An owner of each organization the app is installed on opens Settings → GitHub Apps → Configure for the app, reviews the request and clicks Accept new permissions. Until then, that installation's tokens leave the new permissions out.
Every agent that gets its token from the app, for a repository whose installation granted these, gets them, Harness Team account agents included. A workflow change runs in CI with the repository's secrets, so a branch an agent pushes can run code with them; the default branch's pull request rule (below) still keeps such a change from reaching the default branch unreviewed.
New repositories from New Project
New Project's New repository creates a project's repository in an organization
(docs/plans/2026-11-05-new-repository-design.md). It needs one more repository
permission on the app: Repository creation: Read and write. Never grant
Administration: it also lets a token delete or transfer repositories.
- On the app's settings page (Permissions & events), set Repository creation
to Read and write and click Save changes. The server's sign-in settings
(
GITHUB_APP_CLIENT_IDandGITHUB_APP_CLIENT_SECRET, step 4) must be set. - An owner of each organization accepts it: Settings → GitHub Apps → Configure → Accept new permissions. Until then, New Project says so for that organization.
The repository is created with the person's own sign-in token through the app, never an
installation token. So GitHub decides whether they may create repositories in that
organization, and they become the repository's admin. Harness refuses to mint any
installation token that asks for administration, repository_creation or
installation_repositories (NEVER_ON_INSTALLATION_TOKENS in
backend/src/github/app.ts). GitHub gives the app access to repositories it creates, on
either kind of install. If an installation also grants GitHub App installation
repository access, Harness adds a new repository that the installation doesn't cover
yet. Otherwise the person is told that an owner of the organization adds it under
Configure. The new repository is allowed for the project in the same step.
The endpoints:
GET /api/super-tabs/:tabId/github/owners/:owneranswersready,not-installed(withinstallUrl),not-acceptedornot-configured. Organization checks are limited to 30 a minute per person, on both routes (RATE_LIMITED, 429).POST /api/super-tabs/:tabId/projects/:projectId/github/repositorytakes{ owner, name, private }. Only the project's owner may call it, while the project has no repository. It answers{ authorizeUrl, at }.- GitHub sends the person back to
/api/github/callback. The callback creates the repository and writes the outcome on the project asrepositoryCreation. While it runs, the state iscreating, and a replay of the same link changes nothing. The outcome iscreated(withrepositoryUrlandreachable),taken,refused(with GitHub'sreason),failedorcancelled. The apps then start the Product Manager with today'slead.start.
3. Require pull requests on the default branch
A token that can write contents can push straight to any branch that nothing protects. On each repository, or once for the organization, open Settings → Rules → Rulesets → New branch ruleset. Target the default branch, turn on Require a pull request before merging, set Enforcement status to Active and save. Leave the app off the bypass list.
Harness checks this when it hands out a token. It still gives the token when the
default branch is unprotected, but it reports defaultBranchProtected: false. Each
time git uses that token, harness git-credential warns the agent, so the agent can
tell its Lead and the Lead can warn people. Harness reads rulesets with the app's metadata
permission. It cannot read classic branch protection rules without administration
access, which it does not request. A branch protected only by a classic rule
therefore reports defaultBranchProtection: "classic" and
defaultBranchProtected: false. A ruleset removes that false warning.
4. Configure the Harness server
Set these on the backend and deploy it:
| Variable | Value |
|---|---|
GITHUB_APP_ID |
The App ID (the app's Client ID also works). |
GITHUB_APP_PRIVATE_KEY |
The .pem file's contents. You can paste them as they are, with line breaks written as \n, or as base64: base64 < key.pem | tr -d '\n'. |
GITHUB_APP_SLUG |
The app's name from https://github.com/apps/NAME. Optional; it adds the install link to refusals. |
| GITHUB_APP_CLIENT_ID | The app's Client ID (Iv23…), for its sign-in. |
| GITHUB_APP_CLIENT_SECRET | A client secret: the app's page, Client secrets → Generate a new client secret. Keep it with the private key. |
The last two let a person approve a repository for a Swarm project (below). Set both or neither: one alone stops the backend at startup. Without them, no repository can be approved, so the app gives no tokens.
On the app's settings page on GitHub, so that GitHub sends people back to Harness:
- Callback URL and Setup URL:
https://harness-api.autonomous.ai/api/github/callback(your server's address). - Request user authorization (OAuth) during installation: on. Installing then also approves the repository.
- Redirect on update: on.
If both of the first two are empty, the feature is off and nothing changes. If only one of them is set, or the key cannot be read, the backend stops at startup with a message that never shows the key. Once the key is configured, delete the downloaded copy.
To try it, start an agent from a Lead on someone else's computer, for a project
whose repository has the app installed. When it has a task, git push and
gh pr create work in its terminal. git log -1 shows the trailers, and on GitHub
the push and pull request appear as the app.
Approving a repository for a project
A project's repository address is text its owner types, and the app is installed on other people's repositories too.
So the app gives a project tokens only once someone GitHub says can push to the repository approved it, for that
project or for every project of the Swarm (backend/src/github/approvals.ts). In Harness: Project details, GitHub
access, Approve for this project (or for every project here). The person signs in to GitHub through the app;
their own short-lived token reads whether they can push, is revoked at once and is never stored. Install on GitHub
in the same place approves too, once installed. A project without an approval gets
GITHUB_REPOSITORY_NOT_APPROVED.
Which agents use it
Harness wires the app into an agent when the start meets all of these conditions:
- The agent is a Claude Code or Codex agent started by a Swarm Lead.
- The project's owner is not the owner of the computer the agent runs on.
- The server has the app configured.
A person's own agents, starts on a server without the app, and computers whose Harness
is too old to understand the request keep using the computer's own git and gh
configuration. The decision is recorded with the session, so a relaunch keeps it.
In a team account (a Mac's Harness Team account, or a computer after harness team on),
every Swarm agent qualifies, because the owner's login is not there. Windows works the
same way, through Git for Windows.
Preparing the folder before the agent starts
Before a contributed computer creates the agent, it clones the project into its Swarm folder and fetches the default branch the worktree starts from. For another person's project it does this with the app too, never with its owner's git login:
- The host asks
POST /api/super-tabs/hosts/:machineId/starts/:tabId/:startId/github-token. For another person's project the answer is a token that can only read the project's repository (contents: read,metadata: read), and whom the work is for. For the machine owner's own project the answer is{ "github": false }and the owner's login prepares it as before. A team account sends{ "always": true }, because it has no login of its own. - The clone and the fetch run with that token alone: the owner's global and system git
config are not read,
[email protected]:addresses go over HTTPS, and nothing prompts. The token is in the git process's environment only. - The agent is created with
swarmGitHub, and the daemon does not fetch again. - The read-only token is revoked as soon as the clone and the fetch are done, or have failed. The agent gets a token of its own for its task.
If the token cannot be had (the app is not installed on the repository, the project has
no GitHub address, or a team account's server has no app), the start fails with that
reason. It is never prepared with the owner's login instead. A server's host rows say
githubApp: true when it has the app; a server without the app, or one from before this
endpoint, leaves an owner's computer preparing as before.
How git and gh get the token
Everything reaches the agent through environment variables, because those survive
what its shells do. Codex runs every command in a login shell, and Claude Code
replays the person's startup files. On a Mac, both put Homebrew's folders back at
the front of PATH. A gh wrapper placed first on PATH would be skipped, so
Harness does not use one.
- git reads
GIT_CONFIG_PARAMETERS, the variablegit -cuses, which overrides every config file:- For
https://github.com, it clears the credential helpers git has read so far and setsharness git-credentialas the only one. It also setsuseHttpPath, so the helper sees which repository git wants. [email protected]:andssh://[email protected]/remotes are fetched and pushed over HTTPS, so no SSH key of the owner is used.core.hooksPathpoints to Harness's hooks. Each one runs the repository's own hook first, from the repository's owncore.hooksPathor.git/hooks.GIT_TERMINAL_PROMPT=0makes a missing credential fail at once instead of waiting for input that never comes.
- For
harness git-credential getfinds the calling agent from its tmux pane, the wayharness super-tabdoes. It asks the local daemon for the token of that agent's task and answersusername=x-access-tokenandpassword=<token>, but only forhttps://github.comand only for the task's repository. A request for another host or another repository gets no answer. It ignoresstoreanderase.- gh reads
GH_CONFIG_DIR, a folder belonging to the session. The daemon writes the token into that folder'shosts.yml: when the task starts, again before the token expires, and every time git asks for it. When the task ends, the daemon empties the file. gh reads the file each time it runs, so it never holds a stale token.GH_TOKENandGITHUB_TOKENare cleared from what the agent inherits. gh never reads the owner's configuration.
The daemon checks its sessions' tasks once a minute, and only while such a session is running. The backend returns the same token until ten minutes before it expires.
Attribution
Each commit message gets these trailers, added by the prepare-commit-msg hook after
the repository's own hook has run:
Co-authored-by: Ada Lovelace <[email protected]>
Harness-Agent: Atlas
Harness-Machine: Studio Mac
The co-author is the project's owner, under their Harness account name and email
address. The commit-msg hook adds any missing trailers to a message written in an
editor. Trailers already in the message are not added again, so an amend keeps one
of each. An empty message still aborts the commit.
Every such commit also carries Co-authored-by: Harness by Autonomous <[email protected]>.
In a Harness Team account, the commits themselves are by Harness by Autonomous <[email protected]>. No GitHub
account owns that address, so GitHub links them to nobody; a Team agent's branch is told apart by who pushed it, from
GitHub's activity log, which names the app's bot account. The
account has no git identity of its own, and its commits read Harness Team <harnessteam@<host>.local> before. The token response names it as commitAs for a
team account only; the daemon writes it to the session's gitconfig, which the
session's git includes. A person's machine keeps its owner's git identity.
The prepare-commit-msg hook runs even with --no-verify. Two things leave a commit
without trailers: plumbing such as git commit-tree, and a command that sets its own
-c core.hooksPath.
Each task's message ends with Start each pull request body with: Requested by <email> through Harness., naming the person whose ask the task is: its group's requester while
they can still read the project, otherwise the project's owner (requestedByLine in
backend/src/superTabs/projects.ts). It comes with every task, so an agent reused for
another person's task names that person; the start prompt names nobody. It is given
for another person's project (its owner is not the machine's), not for a review. Who asked
changes no token and no trailer: the token response's pullRequestLine and the
co-author still name the project's owner, so members' emails do not enter git history. This line depends on the agent following its instructions. Harness does not
assign the pull request, because it does not know the person's GitHub login.
The token endpoint
POST /api/super-tabs/:tabId/github-token?asAgentId=AGENT with body
{ "machineId": "MACHINE" }.
The caller must be the account that hosts the agent, sending from the computer that runs it. The agent must have a task in progress: working, waiting on a person, stuck, or out for review. The response is:
{
"token": "ghs_…",
"expiresAt": "2026-10-24T13:00:00Z",
"repository": "acme/app",
"defaultBranch": "main",
"defaultBranchProtected": true,
"defaultBranchProtection": "pull_request",
"requestedBy": { "name": "Ada Lovelace", "email": "[email protected]" },
"agent": "Atlas",
"machine": "Studio Mac",
"trailers": ["Co-authored-by: Ada Lovelace <[email protected]>", "Harness-Agent: Atlas", "Harness-Machine: Studio Mac"],
"pullRequestLine": "Requested by Ada Lovelace ([email protected]) through Harness."
}
defaultBranchProtection takes one of these values:
pull_request: a ruleset requires a pull request.classic: classic protection is on, but its settings cannot be read.none: nothing protects the branch.unknown: GitHub could not say.
The endpoint refuses with these codes:
| Code | Status | When |
|---|---|---|
GITHUB_APP_NOT_CONFIGURED |
503 | The server has no app. |
AGENT_REQUIRED |
400 | No asAgentId. |
FORBIDDEN |
403 | Another account's agent, or the agent runs on another computer. |
NO_ASSIGNMENT |
409 | The agent has no task in progress. |
REPOSITORY_NOT_GITHUB |
409 | The project has no repository address, or one outside github.com. |
GITHUB_APP_NOT_INSTALLED |
409 | The app does not cover the repository. When the slug is set, the response includes installUrl. |
GITHUB_APP_PERMISSIONS |
409 | The installation has not accepted the permissions above. |
GITHUB_APP_MISCONFIGURED, GITHUB_UNAVAILABLE |
503/502 | GitHub refused the app's credentials, or did not answer. |
Each token is cached per agent and task, sealed with a key derived from the app's
private key, in the backend's shared Redis. The backend serves the cached token until
ten minutes before it expires. Then it mints a new one and leaves the old one to its
last ten minutes, so a push that took the old token before the renewal is not broken.
That token is for the one repository and the task's own session. When the task is
done, cancelled or stopped, goes to another agent or attempt, or its agent is removed,
every token minted for the task is revoked (DELETE /installation/token) and dropped,
replaced ones included, whichever backend instance minted them. A request only ever
ends its own task: one that waited across its task's end leaves the agent's next task
alone. If a revocation fails, Harness logs it without
the token and the task's change goes ahead. The token then expires within the hour.
The server never logs a token.
Known limits
- A Lead that starts an agent on its own computer for another person's project starts the worktree from what that computer's checkout has: nothing fetches it first.
- On a personal computer, startup files that export
GITHUB_TOKENreach Claude Code's and Codex's commands again. gh then uses that token. The team account has no such files. - The team account has gh of its own: a Homebrew it cannot read leaves it none, so its
daemon installs GitHub's release of gh (pinned by checksum in
cli/src/team/gh.ts) in its home and links it from~/.local/bin. - If Redis is unavailable, Harness still issues tokens but cannot revoke them when the task ends. They expire within the hour.
- In the first minute of a task, gh can be without a token until the daemon's next check or the agent's first git command that needs credentials.