Connect a Repository with the GitHub App

A GitHub repository can be connected to a Studio in two ways: with tokens you paste, or through the Productivity Workbench GitHub App. The app is the Studio's own identity on GitHub: it reads with short-lived tokens that reach one repository, and it posts the Definition of Done hold and the reviewer agents' verdicts under its own name rather than under a person's. Tokens keep working exactly as before, and nothing requires the app.

What changes when you connect the app

No token to paste or renew — the Studio asks GitHub for a token each time it needs one. Each token reaches the one repository of the connection, carries only the permissions that call needs, expires within the hour and is never stored.

The system posts as the app — the merge hold and each reviewer agent's verdict appear on the pull request as checks and comments by the app's bot account, not by whoever owned a pasted token.

The repository's owner stays in control — the app is installed on GitHub by someone who administers the account, on the repositories they choose, and they can remove it at any time.

People still act as themselves. Approving, merging, updating a branch, tagging, publishing a coding run's code, opening a pull request and dispatching to a cloud coding agent all use the person's own GitHub account, connected under My Account → Source control. The app never stands in for a person, and it never approves or merges a pull request.

What the app can and cannot do

These are the permissions the app asks for when it is installed. Each is used by a feature that exists today.

Permission	Level	What it is for
Metadata	Read	Repository facts: its name, default branch and visibility
Contents	Read	Scanning, browsing files and commits, release ranges, reading agent definitions. Never write: every commit, branch and tag is made as a person
Pull requests	Read and write	Reading a pull request and its changes; posting and updating the agents' verdict comments. The app does not approve, dismiss a review, merge, retarget or close a pull request
Issues	Read	Following a cloud coding agent's issue to its pull request
Checks	Read and write	Posting the Definition of Done hold and the agents' verdicts as checks; reading other checks for ship readiness
Commit statuses	Read	Reading other tools' statuses for ship readiness
Actions	Read	The DevOps runs panel and the release pipeline view

The app does not ask for Administration or Workflows. Applying branch protection stays a one-off action with an administrator's own token, and adding a pipeline is done as you. An installation that has not granted one of the optional permissions still browses, scans and refreshes; the feature that needs the missing one says it cannot tell.

Connecting

On Code Repositories, the studio's owner chooses Connect with the GitHub App on a GitHub connection. GitHub asks you to approve, and to install the app on the repository if it is not installed yet; you come back to the Studio with the connection made. If someone else administers the GitHub account, they install the app and you then press Connect again.

You need write access to the repository on GitHub. The Studio proves it with your own GitHub sign-in at the moment you connect; a read-only collaborator is refused. Nothing you type is trusted: the installation and the repository must both be visible to your own GitHub account.

Your access is checked again. Each time the connection is used and the last check is more than a day old, and before every check the app posts, the Studio asks GitHub whether you still have write access. If you have lost it, the connection stops and says Connector lost access. It starts again when your access is back and someone presses Verify, or when someone who has access connects it again.

The connection belongs to the studio's owner. If the studio's owner changes, the new owner connects it again.

Stored tokens are kept, and are not used for reading. While the app is connected, a stored read token is not used. A stored write token is used for one thing only: relaying a coding action or an answer to a cloud coding agent, which may ignore a comment made by an app. You can remove the stored tokens from the same page. Disconnecting the app puts the connection back on its tokens.

The app is never a fallback, and neither are tokens. If the app cannot be used — it was suspended or uninstalled, the repository was taken out of it, or the connector lost access — the connection stops and says why. It does not quietly switch to a stored token.

One studio per repository posts the checks

Several studios can connect the same repository for reading, each with its own proof. Only one of them posts the merge hold and the agents' verdicts through the app: the studio that holds the repository's check authority. That is what makes the check mean "this studio's gate passed" rather than "some studio's did".

Who can claim it — the studio's owner, when the person who connected the repository administers it on GitHub. It is claimed for you when you connect as an administrator and nobody holds it. A developer on their own repository is its administrator, so one person can connect, claim and ship alone.

Moving it — another studio can take it over only with a fresh proof, at that moment, that its connector administers the repository. Both studios see the move in their audit log.

Every other studio — reads through the app and posts nothing. Its page says another studio posts the checks; it never names that studio.

If you connect with write access but are not an administrator, the connection reads through the app and posts no hold. To have a hold on your pull requests, either have an administrator connect and claim the authority, or stay on tokens.

Requiring the check in branch protection

The Branch protection dialog can require the Definition of Done check before a pull request merges. For the studio that holds the check authority, it also pins the check to the app. A commit status of the same name posted with a personal token then does not make the check pass. A failing status of that name can still hold a merge back, so the pin stops a forged pass, not every way of blocking a merge. Applying branch protection needs a repository administrator's token, pasted once and not kept.

A pinned check holds merges while the app cannot post it. If the app is disconnected, suspended or uninstalled, the connector loses access, or the check authority is released, a new commit on a pull request gets no check from the app and so cannot be merged while the check is pinned. A pull request whose last check passed stays mergeable — except after a release of the check authority, which sets your studio’s passing checks back to in progress first (below). The Code Repositories page and the work package say which of these has happened and what to do: reconnect, restore the access, or claim the authority again; after a disconnect, with a write token stored, re-applying branch protection without the pin lets the hold be posted as a commit status instead. A repository administrator can always change the protection.

When the check authority changes hands. When your studio claims or takes over the authority, its merge hold and reviewer checks are posted again on its open pull requests on that repository straight away, so that the newest check of each name there is your studio’s (in our tests, with classic branch protection and the check pinned to the app, the newest check of a name was the one GitHub went by); if some could not be posted, the page says how many and asks you to press Check progress on those work packages. When you release the authority, connect the app again as someone who does not administer the repository, or remove the connection, your studio’s checks that had passed on open pull requests are set back to in progress first, so a pass you can no longer take back does not stay; you are told if any could not be. While branch protection requires the check, those pull requests then wait until a studio claims the authority again. Disconnecting the app sets nothing back. If another studio takes the authority over, a pull request that only your studio records keeps your last check: merge or close such pull requests before the authority moves. A check that was already on its way when the authority moved can arrive after your studio’s own; so the first time a work package with an open pull request is refreshed two minutes or more after a claim, the Studio looks at its check on GitHub once more and posts it again if it is not the newest.

What you see when something changes on GitHub

The page says	What happened	What to do
Suspended on GitHub	The installation was suspended on GitHub	Unsuspend it on GitHub, then press Verify
Uninstalled on GitHub	The app was removed from the account	Install it again and connect, or disconnect to use tokens
Repository not in the installation	The repository was taken out of the installation	Add it back on GitHub, then press Verify
Permissions not accepted	The app asks for a permission the account has not accepted yet	An account owner accepts it on GitHub
Connector lost access	The person who connected no longer has write access	Verify once access is back, or connect again as someone who has it
Connect again	The studio's owner changed	The new owner connects
Repository renamed or moved	The repository has a new name or owner on GitHub	Disconnect, correct the connection's address, connect again

With the app connected, GitHub tells the Studio when one of these happens, and when a coding run's pull request gets a new commit or is merged, so the pages catch up without anyone pressing Check progress. The Studio asks GitHub again before it records anything. A pull request merged on GitHub is recorded as merged at once; the product manual update that follows it starts when the studio's owner or a reviewer opens the work package or presses Check progress — never by itself, and not when another member presses Check progress. Any member can still record a delivery by hand from the Product manual card.

Revoking access

There are two ends to a connection, and either can end it.

From the Studio — the studio's owner chooses Disconnect. The connection goes back to its stored tokens, if any.

From GitHub — whoever administers the account uninstalls the app, or removes the repository from the installation, under the account's Settings → Applications. GitHub issues the app no new token for that repository, so within ten minutes — the longest the Studio reuses a token — no studio connected to it through the app can start a new read of it; a read already under way, such as a scan, ends when its token does, within the hour. This is the way to revoke a studio you do not belong to.

GitHub does not show an account's administrators which studios are connected to their repositories, and the Studio does not yet offer them a page that does. Until it does, uninstalling the app or removing the repository is the revoke, and it revokes every studio at once.

Sharing one installation across an organisation's studios

On an Enterprise plan, an Organisation's owner can link an installation once under Organisation → Integrations → GitHub App link, choose which repositories to share, and accept studios one repository at a time. The owner of an accepted studio then chooses the button that names the organisation's GitHub App on the connection, without repeating the GitHub proof.

Reading only — a connection made this way never posts the merge hold or verdicts. A studio that needs to post them connects the app itself, with an administrator.

It rests on the Organisation owner's own access — the owner must have write access to each repository they share, and that is checked again whenever the link is used and the last check is more than a day old. An owner without write access to a repository cannot share it, and cannot hand that to an administrator.

Accepting a studio accepts its owner — everyone that owner adds to the studio reads through the link. If the studio's owner changes, or the studio leaves the Organisation, the connection is revoked and says so.

Revoking — the Organisation's owner can withdraw a studio, stop sharing a repository or remove the link. Each studio affected sees why in its own audit log, and its stored tokens are not used in the link's place.

A studio with no Organisation never needs any of this: connecting at studio level is complete on its own.

All AI Product Studio documentation

Build v0.3.2 · deployed 2026-10-19T23:52:31Z