On this page
Full glossary · 17 terms
- org
- A GitHub organisation: the container that owns repositories, members, teams and installed Apps.
- owner of record
- The one human account that owns the org and is the last resort for every setting. It may be the human’s own account, used for other projects too; that does not make it a shared identity.
- agent
- An AI principal that reads and writes repositories through a seat. Never a human’s account.
- seat
- The running process that is an agent: harness + identity + credential + working directory.
- GitHub App
- A non-human identity GitHub issues: it has a private key, is installed on chosen repositories with chosen permissions, and mints short-lived tokens. Shown as <name>[bot].
- installation token
- A token an App mints for one installation; it expires in an hour and is scoped to that installation’s repositories and permissions.
- fine-grained PAT
- A personal access token on a user account, limited to named repositories and permissions. It belongs to the human whose account issued it.
- classic PAT
- The older, broad-scope token type. Not permitted by this standard.
- deploy key
- A read-only (or read-write) SSH key bound to one repository, for a machine job that needs that repository and nothing else.
- authorship
- The name and address stamped into a commit. Answers who wrote this. Set per working tree.
- push identity
- The credential that authenticates a push or a pull request. Answers who was allowed to send this.
- merge class
- A set of paths whose merge is reserved to a named principal (§4).
- CODEOWNERS
- A file GitHub reads to require review from named users or teams before a pull request touching listed paths can merge. Apps cannot be code owners.
- branch protection
- Rules GitHub enforces on a branch: pull request required, reviews required, who may push.
- credential registry
- A password manager’s vault (1Password here) that is the single inventory of secrets: every credential is an item with a reference string, an owner, a rotation step and a kill step.
- running copy
- A file the system actually reads, kept equal to a versioned original and tracked by digest.
- crossing
- A deliberate, reviewed way for something to enter or leave a seat’s container (see Container Seats). An agent’s GitHub identity is a crossing.
Revision r2 · October 2026 · AstralMaris design series This standard applies to every GitHub organisation and repository the operator runs — the fleet’s own, and any project or team stood up beside it. It is written so a new team can adopt it whole without knowing the fleet; a deviation is a finding against it, not a local custom.
1. Principles
- Humans are users; agents are Apps. No agent ever holds a user account, a user’s token, or a user’s session. No human ever pushes through an agent’s credential.
- Authorship and push identity are separate layers and both are required. A commit says who wrote it; the credential says who was allowed to send it. Neither substitutes for the other.
- One credential, one owner, one kill. Every credential that touches GitHub is a registry item with a named revocation step that takes out that credential and nothing else. A credential whose only kill is “log out everywhere” is recorded as such and treated as a defect to retire.
- Merges are the human’s observation point. Agents open pull requests; the owner of record merges anything in an owner-merge class. Branch protection makes that a rule GitHub enforces, not a habit.
- Signatures where they are load-bearing, not everywhere. Agent commits are unsigned; the owner’s merges and tags are signed. A signature a human approves without reading carries no authority.
- Shortest-lived token that does the job. Installation tokens over PATs; a deploy key for a machine job that needs one repository; a PAT only as a transitional credential for a seat that cannot yet hold an App key safely.
- Ownership and reach written down. Every credential’s owner and the exact set of repositories and permissions it reaches are recorded where the credential is; two paths to one credential are a finding, and the answer is one fresh credential with its ownership and reach documented, the old ones retired once the new one is proved.
- Forge-agnostic contracts. Nothing load-bearing is shaped around one forge’s checks or actions. The merge gate reads trailers and receipts that would be the same on any forge; GitHub is where they happen to run.
- Consistency across projects. A new org adopts this document whole, with one registry vault per project, never shared with another project’s.
2. Identity model
2.1 Humans
- Personal GitHub account, two-factor authentication required, org membership by invitation from the owner of record.
- Fine-grained PATs only; each is a registry item, created in the password manager as an API credential, with its reference string recorded exactly; consumers read the recorded string, never compose it.
- No classic PATs. No OAuth tokens left in a keyring outside the registry: the CLI’s stored token must digest-equal the registry item.
2.2 Agents
- One GitHub App per agent, owned by the org, named
<org>-<agent>(shown as<org>-<agent>[bot]). - Created by one reviewed script, not by hand in the browser. The script runs at the owner’s own login (GitHub’s multi-factor check and one click are the human’s part), generates the private key, writes it straight into the registry as an item, prints the App’s id, the bot’s commit address and a readback, and leaves nothing on disk. The key is never seen by a human and never sits in a download folder.
- Installed only on the repositories that agent writes, with the minimum permissions (typically Contents: read/write, Pull requests: read/write, Metadata: read). No Administration, no Members, no Secrets. Choosing the repositories is a separate, deliberate step after creation.
- The private key is provisioned into the seat’s secrets store — for a container seat, a daemon-managed named volume at mode 0400 — never a file on host disk at a shared uid. The seat mints an installation token at wake through a helper that reads the key and emits the token; the key and the token never enter the seat’s environment.
- Authorship is the agent’s name and its bot address
<app-id>+<org>-<agent>[bot]@users.noreply.github.com, set per working tree (not per repository — a repository-level setting is inherited by every worktree and stamps every agent as one). GitHub then attributes the commit to the bot. - Revocation: rotate the App’s key (invalidates every token minted from the old key within the hour) or uninstall the App. Both are per agent. Both are registry kill steps.
- For a container seat, the App is the seat’s first crossing: the first thing that lets work leave the container under the seat’s own name, with a driving row for every refusal (§5.2, step 3) and a line on the fleet’s reach ledger.
2.3 Machine jobs
- A job on a host that only needs to keep a running copy of one repository current uses a read-only deploy key on that repository, and nothing else. Deploy keys are an org-level setting that is off by default; turning it on is the owner’s act, recorded.
2.4 Transitional: host seats before migration
- A seat that cannot hold an App key safely (a host seat at a shared uid) pushes through the org’s one transitional fine-grained PAT on the owner’s account, scoped to the repositories the fleet writes, with per-worktree authorship telling the record who wrote what.
- This is attribution, not authority, and is recorded as such. It ends for each seat when that seat moves into a container and receives its App; the PAT is retired when the last host seat has moved.
3. Credentials — what may exist
| credential | who | where it lives | lifetime | kill |
|---|---|---|---|---|
| App private key | one per agent | registry item → the seat’s secrets volume, 0400 | until rotated | rotate key / uninstall App |
| installation token | minted per wake | seat memory only, via the helper | one hour | expires; key rotation |
| read-only deploy key | one per machine job | registry item → the job’s key file, root-owned | until rotated | delete from the repository |
| transitional fine-grained PAT | the owner, for host seats | registry item; the CLI’s stored copy must digest-equal the item | rotate quarterly or on any finding | revoke on the account’s token page + registry step |
| owner’s own fine-grained PAT | the owner | registry item | as above | as above |
| SSH keys | humans only | the password manager’s SSH agent, approval-gated | — | remove from account |
Not permitted: classic PATs; tokens in shell functions, rc files, environment exports or session snapshots; a user account for an agent; any credential without a registry item; two stores holding one credential without a digest check.
4. Repository rules
4.1 Merge classes (encoded, not remembered)
| class | paths | merge by |
|---|---|---|
| Owner-merge | designs, scripts, operations, anything carrying a ruling’s text, every code repository | the owner of record only |
| Agent-merge | continuity (handoffs, journals), reports, issue-file appends, an agent’s own namespace | the agent, still by pull request |
| Library structure | directory layout and index files of a documentation repository | the owner of record |
4.2 Branch protection on main of every repository
- Pull request required; no direct push, no force-push, no branch deletion.
- Required review from code owners for paths listed in
CODEOWNERS;CODEOWNERSnames the owner of record on every owner-merge path. - Status checks required where a gate exists (recipe lint, provenance gate, build receipt).
- Signed commits not required (§1.5); signed merges and tags by the owner are the signature of record.
- Apps may push branches and open pull requests; they cannot merge protected paths because they are not code owners — by construction.
4.3 Commit gate (hooks)
- A pre-commit gate refuses a wrong author in the ordinary path and refuses file-count or ownership-zone breaches without an explicit override trailer.
- The gate’s home is a running copy tracked by a digest row in the host’s inventory; a root-owned copy is the target.
- The gate is attribution, not authority: it does not survive
--no-verifyor a command-line author override. Authority is §4.2.
4.4 Trailers
Ruling:on any commit that lands a ruling’s text;Reviewed-by:on any commit that passed a review; a build-receipt citation on any pull request that carries built output. Read by the provenance and merge gates, which are forge-agnostic by design (§1.8).
5. Onboarding checklists
5.1 A new org or project (the owner’s hand, once)
- Create the org; the owner of record is the owner’s own account with two-factor authentication.
- Create the registry vault for the project — one vault per project, never shared.
- Create
CODEOWNERSand branch protection onmainper §4 before the first agent pushes. - If host seats exist, create one transitional fine-grained PAT; register it; install it into the CLI; digest-compare keyring and item.
- If a machine job needs a running copy, turn deploy keys on for the org and add one read-only key per job.
- Adopt this document into the repository beside the project’s designs; deviations are findings.
5.2 A new agent (the owner’s hand + the agent’s packet)
- Owner: run the reviewed creation script at his own login (the multi-factor check and one click); the App
<org>-<agent>exists, its key is in the registry, the readback printed “nothing was written” to disk. - Owner: install the App on exactly the agent’s repositories with minimum permissions.
- Agent packet: provision the key into the seat’s secrets volume; the token-minting helper; per-worktree authorship with the bot address; a start row that asserts the token was minted and no key or token is in the environment.
- Reviewer, driven: a pull request opened as
<org>-<agent>[bot], a commit authored by the bot, a third repository refused, an owner-merge path refused for the App. - Registry: key item, rotation step, kill step, reference recorded. Reach ledger: one line.
5.3 Offboarding an agent
- Uninstall the App; rotate or delete its key; delete the registry item; record the date.
- The agent’s branches stay; its commits are history and are not rewritten.
6. Monitoring rows (printed, zero included)
- commits on
mainauthored by a name that is not the pushing identity — zero; - tokens present in any seat environment (
*_TOKEN,*_KEY,GH_TOKEN) — zero; - CLI auth entries not matching a registry item — zero;
- App installations with permissions beyond §2.2 — zero;
- keyring-vs-registry digest mismatch for any PAT — zero;
- Apps installed with no registry item, or registry items with no App — zero;
- deploy keys with write permission, or on more than one repository — zero.
7. Known limits
- On a host where seats share one uid, authorship is not authority; only the container seat closes that (Container Seats, §12).
- Apps cannot be code owners; human review of owner-merge classes is the control, and it is the owner’s time.
- An App key held in a container volume is readable by whoever can address the daemon socket; the socket’s ownership is the outer wall.
- GitHub-side settings are not versioned by GitHub; the registry and the monitor rows are the record. A change to branch protection without a ruling is a finding.
- A fleet that cannot put a credential’s bytes on the hub (by design) moves code between seats by bundle and by the outbox crossing until each seat holds its own App; the App is what lets a contained seat build and push without a human’s hands.
AstralMaris is one operator and a small fleet of AI agents on Apple-silicon hardware. This series records designs the fleet runs, with the measurements that shaped them. Companion paper: Container Seats.