Runbook: onboard 2 engineers on 1 repo, then 6 engineers on 3 repos¶

One ordered checklist for putting a team on hangar. Weeks 1–2 end with 2 engineers merging agent PRs on 1 repo, and weeks 3–4 with all 6 on 3 repos. Every step names the command and the page it comes from, and every command is on main. It ends, for each repo, with hangar repo check green.

Read it with team setup (people and credentials), landing (the App and branch protection), intake (Jira) and the security model (the gateway).

Three hard stops. If any of these is true, the repo isn't onboarded, whatever else is green:

• CI isn't required on the default branch. With no required status checks GitHub merges as soon as hangar arms auto-merge (how a PR lands). hangar repo check fails required checks.
• The GitHub App is on a bypass list. Never add it to "Allow specified actors to bypass required pull requests" or to a ruleset's bypass list. Branch protection is what makes a merge wait for a person (creating the App).
• The repo's environment is credential_mode: direct, or the gateway is off. A direct-mode job's sandbox holds a GitHub token, and hangar never lands such a job: landing is off for it (what landing doesn't cover).

Two limits on GKE today¶

Tell each engineer these on day one:

• Approvals are auto only. GKE sets HANGAR_UID_SPLIT=required, so a job or session with approvals: ask (or deny-risky, governed) has its turns refused. Interactive approvals wait for the driver sidecar (KAN-186, the driver sidecar).
• No jobs run 01:00–10:00 ET. The sandbox pools power down at 01:00 and are ready at 10:00 (deploy/terraform/gke/power.tf). A job sent in that window queues until 10:00, and a session resumes on its next message after it (infra states). The overnight lane, off by default, is the only exception.

Engineer-hours¶

The product lead's question: how long does one repo take to onboard? Record it here when the per-repo checklist is run, from the first command to hangar repo check green. Count each person's hands-on time, not waiting for a GitHub admin or for CI.

Open item: these hours are the one thing this runbook doesn't have yet. They are measured on the first real run of the per-repo checklist (#154).

Phase 1: 2 engineers, 1 repo (weeks 1–2)¶

1. Control-plane prerequisites¶

The safe release (#120–#132) is deployed: secure defaults for intake jobs, API keys for automated work, one approval rule (the safe release). It changes every environment's image, so deploy it by hand in the power-down window, 01:00–09:50 ET. Then the sandbox pools are down and the control plane is up (applying it).

Later routine deploys go through deploy.yml while the pools are on, 10:00–01:00 ET (when to deploy). Then comes the adopt & capture upgrade (#133–#189), which deploys by day.

hangar doctor                          # clean: no failures (it also fails on a removed switch still stored)

2. People¶

Add each engineer and link their accounts elsewhere (add people, linked accounts). Links use ids that don't change hands: GitHub is stored as the account's numeric id, Slack as TEAM/USER, Jira as the Atlassian account id.

hangar person add alice --name "Alice"        # prints her login token once; she runs hangar login, hangar connect
hangar person link alice github alice-gh
hangar person link alice slack T0123ABCD/U012AB3CD
hangar person link alice jira 5b10ac8d82e05b22cc7d4ef5

Two people means approvals work without HANGAR_SELF_APPROVAL=allow_solo: nobody approves their own job.

3. Credentials¶

API keys with a spend cap set in the vendor's console, one per engineer or one for the team (team credentials). Never a subscription login: jobs refuse them (subscription logins).

hangar cred add claude-team --team --harness claude-code --kind api_key --file team-key.txt
#   each engineer, on their machine:
hangar cred add claude-alice --harness claude-code --kind api_key --file anthropic-key.txt
hangar cred ls                         # kind api_key; owner=team or owner=<person>

The per-repo checklist¶

Steps 4–7 for each repo: repo 1 in phase 1, repos 2 and 3 in phase 2. They are on the per-repo checklist: the repo, its policy, its doors, and hangar repo check until green.

8. First day (phase 1)¶

Each engineer:

1. moves 2 tickets to Ready for agent (or labels 2 issues hangar);
2. reviews the agent PRs at the 10:00 triage (hangar inbox), and approves one that is ready. hangar lands it once the required checks pass. That is a teammate's PR as its second reviewer, or their own only when it is low risk with an AI review;
   • past 5 open agent PRs awaiting them, their new jobs wait as awaiting_capacity (review capacity): reviewing is what frees them;
3. answers one agent question in its thread or ticket (/hangar <answer>, a thread reply, a Jira comment).

Moved from this page¶