Manual steps
Every human action, why it cannot be automated, and what breaks if you skip it.
Everything a human has to do, why it cannot be automated, and what it looks like when you skip it. This page exists because every item on it has cost somebody real time.
The portal walks you through most of this now. roster with no arguments opens a setup screen
that deep-links item 1, runs items 2 and 3 for you as far as GitHub allows, and hands you a prompt
for items 5 and 6. This page is still the why: it is what to read when one of them bites, and
what to check when the page says something is not done.
The portal's Health screen checks most of these, per staff member and for the org, with
every finding carrying the sentence that fixes it. roster doctor prints the same from a
terminal. Look after each step.
1. Allow the ops repo's workflow to be called
Do: <org>/roster-ops -> Settings -> Actions -> General -> Access -> Accessible from
repositories in the organisation. The setup screen links straight to that page.
Why not automated: it is an organisation permission on a repository, and the API for it needs admin rights that a token created for a different purpose should not have. roster reads it and tells you, but setting it is one click and it is yours.
If you skip it: every caller fails with "workflow not found". That reads like a typo in a path, or a missing file, or a bad branch reference. You will check all three. It is none of them, it is this.
Check: Health, or roster doctor, reports roster-ops is callable from the whole org.
2. Create the GitHub App
Do: the GitHub App button on a staff card in the portal, or roster app <handle> in a
terminal. Either opens a browser, GitHub asks you to confirm, and you come back. Credentials go
straight into the repository's secrets.
Why not fully automated: there is no API that creates a GitHub App. The only route is the App Manifest flow: POST a manifest to a settings page, a human confirms, GitHub returns a one-time code. roster does everything either side of that confirmation.
If you skip it: the run fails at the token-minting step with a message about the app not existing.
Note: the private key is handed to gh on standard input. It is never written to a file,
never passed on a command line, and never appears in the process table. If the secret write
fails after the App is created, the key is gone: generate a new one from the App's settings
page and set the secret by hand. roster tells you this if it happens.
3. Install the App, and grant it the right repositories
Do: open the URL the portal shows, or that roster app prints. Choose repositories.
Why not automated: installing is a grant of access to specific repositories, and GitHub requires a human to choose them. This is the correct behaviour and should not be worked around.
Grant it on every tracker the staff member writes to, not just their own. The token is
minted organisation-wide, and a peer's board is where a brief lands. Both the portal and
roster app say so.
If you skip it, or under-grant it: this is the trap that costs the most time, because of how it fails.
The API reports an App's declaration separately from an installation's grant.
GET /apps/<slug>will happily tell you the App exists and hascontents: write. That says nothing about whether it has been installed on the repository you care about. Two of our Apps declare permissions they were never granted.
So: do not verify an installation by reading the API. The only thing that proves the whole
chain (App created, installed, granted, secrets right, workflow reachable) is a run that
finished. roster doctor reads a window of recent runs for exactly this reason, and reports a
workflow that has never run as unproven rather than as fine.
Check: that staff member's Health screen, or roster doctor <handle>. Then trigger one run
and look again.
4. Set the agent's credential
Do: put the coding agent's credential on each brain repo as a secret. The name follows the
credential: CLAUDE_CODE_OAUTH_TOKEN, CODEX_API_KEY, and so on. See
choosing a coding agent.
Why not automated: it is your account's credential and roster has no way to obtain one.
If you skip it: the run fails immediately with the caller passed no agent credential.
That check exists so it fails there rather than forty lines later inside the agent, after the
checkouts have already happened.
Check: Health, or roster doctor, lists the secrets each caller references and whether
they exist.
5. Write org/business.md
Do: the setup screen does both halves of this. Copy the prompt puts a brief on your
clipboard with every file it refers to inlined, so a chat window with no filesystem is as useful
as an agent standing in the repo; the box beneath it takes the reply, shows you a diff, and
saves only when you press the button. roster brief discover prints the same brief for a
terminal, and you can always just answer the questions in the file by hand.
Health reports business.stub while it is still the questions.
Why not automated: an agent that does not know the business writes work that is plausible and generic. That is worse than no work, because it takes longer to notice. This file is composed into the top of every prompt, every run.
If you skip it: nothing errors. That is the problem. You get competent-looking output about a business that does not exist.
6. Write each staff member's CHARTER.md
Do: Write the charter on that staff member's card, which is the same copy-a-prompt,
paste-the-answer-back round trip as item 5, aimed at CHARTER.md. The brief it copies carries
the org layer, business.md and the peers' charters, because without those the model writes
a second copy of whoever it was shown. roster brief charter <handle> prints the same brief, and
writing a charter has the shape if you would rather write it yourself.
Why not automated: same reason, one level down. The charter is what makes a staff member different from the others.
If you skip it: charter reports it as present, because the stub is a file. charter.stub
is the finding that says nobody has answered it. The agent has no personality and produces
whatever the shared layer implies.
7. Commit and push what roster wrote into other repos
Do: hiring writes a whole brain repo and pushes it, so this is mostly about roster upgrade, which writes into repos on disk and leaves them for you. Review, commit, push.
Hiring from the Staff screen still edits the other staff members' manifests on disk to wire the peers both ways, and those are yours to commit.
Why not automated: roster does not commit on your behalf into repositories it did not
create in that command. And App tokens cannot push a change under .github/workflows/ in any
repository, which is a GitHub restriction and not a configuration mistake. That is also why
agents can never update their own workflows, and why upgrades are human-run by design.
If you skip it: the change exists locally and nowhere else. roster upgrade will report it
as still pending next time, which is the intended behaviour.
Order
For a new organisation:
In the portal it is the screen you are looking at, in this order:
the setup screen 1 is deep-linked from it, and 5 is on it
Staff -> Hire someone then 7
GitHub App, on the new staff card 2, then 3
Write the charter, on the same card 6
4 is yours: a secret on the brain repo
Health until the ids are goneFrom a terminal:
roster init --org <org> --apply # 1 applies here
roster hire <handle> --apply # then 7
roster app <handle> # 2, then 3
# 4, 5, 6
roster doctor <handle>Then trigger one run by hand before trusting the schedule. A workflow that has never run has proved nothing.