@crvouga/dev-fleet 0.4.0 → 0.6.0

package/docs/declared.md

@@ -47,11 +47,10 @@ stays in the playbook: the playbook is its declaration.
   launchd job from TypeScript and has never worked from the published package.
   It should become a playbook.
 - **The rest of a worker's packages.** Only the packages in `policy.json` are
-  exact. `systemd-oomd` and the T3 desktop libraries are installed at whatever
-  version the machine's own archive holds, and the machine's own updates move
-  everything else. Pinning them needs every worker on the snapshot with its
-  own updates off, so security fixes arrive only when the snapshot moves. That
-  is a policy choice, not a missing line.
+  pinned. The T3 desktop libraries are installed at whatever version the
+  machine's own archive holds, and Ubuntu's security updates move everything
+  else, pinned packages included: a pin is a minimum
+  ([worker contract](worker-contract.md#package-pins-and-security-updates)).
 - **What a worker needs before Ansible exists.** `fleet-remote-bootstrap.sh`
   installs Git, curl, CA certificates, Python and `ansible-core` from the
   machine's own archive (the snapshot is HTTPS, and a new machine has no CA

package/docs/github.md

@@ -0,0 +1,107 @@
+# GitHub on every node
+
+Every node, the manager and each worker, signs in to GitHub from a stored
+credential. Nobody runs `gh auth login` on a node, and no login directory is
+copied between machines.
+
+## Where the token is
+
+The token is the declared secret `github-token`, read through the secrets
+provider your `fleet.json` names, like every other secret:
+
+| Provider | Shared token                                                              | Per-node token (`"credential": "per-node"`) |
+| -------- | ------------------------------------------------------------------------- | ------------------------------------------- |
+| `env`    | `DEVFLEET_SECRET_GITHUB_TOKEN`                                            | `DEVFLEET_SECRET_GITHUB_TOKEN_<NODE>`       |
+| `file`   | `github-token`                                                            | `github-token-<node>`                       |
+| `sops`   | key `github-token`                                                        | key `github-token-<node>`                   |
+| `vault`  | `locations["github-token"]`, or field `GITHUB_TOKEN` beside the proxy key | the same location, field `<FIELD>_<NODE>`   |
+
+The login it must belong to is `worker.githubLogin`.
+
+## The `github` block
+
+All of it is optional:
+
+```json
+"github": {
+  "manager": "fleet",
+  "credential": "shared",
+  "scopes": ["repo", "workflow"],
+  "repositories": ["example-org/app"],
+  "organizations": ["example-org"],
+  "sandbox": "example-org/sandbox"
+}
+```
+
+- `manager`: `"fleet"` (the default) signs the manager in as the fleet login,
+  like a worker. `{ "login": "…" }` names a person's own login: it is checked
+  and never replaced.
+- `credential`: `"shared"` (one token) or `"per-node"` (one per node, so one
+  can be revoked alone and nodes do not share a rate limit).
+- `scopes`, `repositories`, `organizations`: what `github:permissions` and
+  `github:org-access` hold the token to.
+- `sandbox`: the repository `fleet-github-verify` may use.
+
+## How a node is signed in
+
+`bootstrap/worker-github.ts` runs at every `fleet-sync` and, on a worker, every
+ten minutes from the user timer `personal-worker-github`. It is apart from the
+Vault renewal (`personal-worker-auth`): one failing never stops or hides the
+other. It signs gh in with the stored token when the node is not signed in, or
+when the stored token differs from the one gh holds and is valid for the
+declared login. git asks gh for the token at every use
+(`credential.https://github.com…helper = !gh auth git-credential`, set by
+`ansible/github/git.yml` with the identity of the `git` block on every node),
+so a replaced token reaches git with no change and no second copy on disk.
+
+A `fleet-sync` fails with `github:sync` when the node cannot be signed in.
+
+## Rotating the token
+
+1. Issue a new token for the fleet login and put it in the store as
+   `github-token`.
+2. Run `fleet-sync` (the canary worker first, as always), or wait up to ten
+   minutes for every node's timer. Each node adopts the new token while the old
+   one still works.
+3. When `github:token-current` passes on every node, revoke the old token.
+
+## Checks
+
+| Check                   | What it says                                                                                                                                                            |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auth:github`           | gh answers `auth status` in this context.                                                                                                                               |
+| `github:principal`      | The node is signed in as its declared login (the fleet login, or the manager's personal one).                                                                           |
+| `github:token-current`  | The node uses the token the store holds now (`GITHUB_TOKEN_STALE` otherwise). Not reported for a personal login.                                                        |
+| `github:permissions`    | The token has every declared scope and can push to every declared repository (`GITHUB_PERMISSION_MISSING: …`). Warns for a fine-grained token, which reports no scopes. |
+| `github:expiry`         | Warns 14 days before the token expires, fails 3 days before.                                                                                                            |
+| `github:rate-limit`     | Warns below 20 % of the rate limit left, with the reset time.                                                                                                           |
+| `github:org-access`     | Single sign-on has authorised the token for each declared organisation.                                                                                                 |
+| `github:git-credential` | git asks gh for its GitHub credential.                                                                                                                                  |
+| `worker:github-sync`    | Why a worker is not signed in: `GITHUB_TOKEN_MISSING`, `GITHUB_TOKEN_REJECTED`, `GITHUB_LOGIN_MISMATCH`, `GITHUB_UNREACHABLE`.                                          |
+| `auth:copilot`          | Copilot CLI uses the node's GitHub sign-in; fails `not-signed-in` without one and `COPILOT_TOKEN_UNSUPPORTED` for a classic token.                                      |
+| `github:workflow`       | From `fleet-github-verify`: the first step of clone, branch, commit, push, pull request, checks and comment that failed.                                                |
+
+## Copilot CLI
+
+Copilot CLI takes the token gh holds when it has none of its own, so the
+node's GitHub sign-in is its sign-in. It accepts OAuth, GitHub App user and
+fine-grained tokens with the Copilot Requests permission, not classic
+personal access tokens. Whether the account is entitled to Copilot is not
+measured; no prompt is sent.
+
+## Verifying the whole workflow
+
+`devfleet fleet-github-verify` runs, from the machine it is started on, what an
+agent does on the sandbox repository: clone, a uniquely named branch, an empty
+commit with the configured identity, push, a draft pull request, a read of its
+checks, a comment. It then closes the pull request and deletes the branch,
+whatever failed, and reports anything it could not remove.
+
+## Not yet
+
+- Short-lived GitHub App installation tokens minted by the manager.
+- A container registry, package registry and tool installer adapter: today
+  only git takes its credential from gh.
+- A launchd timer for the manager: it is signed in at every `fleet-sync`.
+- `fleet-github-verify` runs on the machine it is started on; `--node` and a
+  scheduled run are not there yet.

package/docs/operations.md

@@ -107,7 +107,7 @@ remote nodes' required lists. Run `fleet-nodes --schema` for editor/agent valida
 | `ssh:agent`                                                                        | Manager agent exposes an identity; missing agent warns because IdentityFile keys may still work.                                                                      |
 | `ssh:session`                                                                      | Fresh batch SSH session actually runs the Node/Bun probe. No reused multiplexed connection or agent forwarding.                                                       |
 | `ssh:host-key`, `ssh:dns`, `ssh:auth`, `ssh:network`, `ssh:runtime`, `ssh:timeout` | Classified failure and targeted remedy, without raw logs.                                                                                                             |
-| `auth:github`                                                                      | gh auth status --active succeeds on this machine; not proof of Git SSH or every repository permission.                                                                |
+| `auth:github`                                                                      | gh auth status --active succeeds; the `github:*` checks ([GitHub](github.md)) say which login, token, permissions and expiry.                                         |
 | `auth:vault`                                                                       | Server-side vault token lookup succeeds in this context; not proof of access to every secret path.                                                                    |
 | `auth:vscode`                                                                      | code CLI finds the local Remote-SSH extension. Other profiles/Cursor/GUI PATH/agents can differ.                                                                      |
 | `t3:settings`                                                                      | Connect explicitly enabled and not revoked in t3 status --json; settings are not connectivity.                                                                        |

package/docs/runbooks.md

@@ -8,29 +8,26 @@ person (a login, an approval, a choice) is marked **needs a person**.
 `features/rules/runbooks.feature` fails when a code in the source has no
 entry here, or a `devfleet` command quoted in the documents does not exist.
 
-There are 241 codes; 31 need a person.
+There are 244 codes; 31 need a person.
 
 ## Bootstrap of a new or returning worker
 
 - **Meaning:** The remote bootstrap (`bootstrap/fleet-remote-bootstrap.sh`) stopped before node convergence. It reports the phase and the code, never its output.
 - **Confirm:** Run `devfleet fleet-sync --dry-run` and read the `bootstrap:*` check of the worker; `ssh WORKER` and look under `~/.local/share/personal/fleet`.
 - **Fix:** Follow the remedy the check prints, then run `devfleet fleet-sync`. The bootstrap resumes where it stopped.
-- **Escalate:** A platform or architecture code means the machine must be reinstalled: Ubuntu 26.04 on x86_64 or aarch64.
+- **Escalate:** A platform or architecture code means the machine must be reinstalled with a release [the support matrix](support-matrix.md) lists, on a machine of its own.
 
 - `BOOTSTRAP_CAPACITY_UNVERIFIED`: bootstrap capacity unverified.
 - `BOOTSTRAP_DISK_CAPACITY_REQUIRED`: bootstrap disk capacity required.
-- `BOOTSTRAP_LOCK_TOOL_REQUIRED`: bootstrap lock tool required.
 - `CONFIGURATION_INSTALL_FAILED`: configuration install failed.
 - `FLEET_APPROVED_BOOTSTRAP_UNAVAILABLE`: fleet approved bootstrap unavailable.
 - `FLEET_STATE_PATH_UNSAFE`: fleet state path unsafe.
-- `MACOS_ARCHITECTURE_UNSUPPORTED`: macos architecture unsupported. **Needs a person.**
-- `MACOS_BASELINE_MISMATCH`: macos baseline mismatch. **Needs a person.**
 - `PLATFORM_UNSUPPORTED`: platform unsupported. **Needs a person.**
 - `REMOTE_BOOTSTRAP_EVIDENCE_INVALID`: remote bootstrap evidence invalid.
 - `REMOTE_BOOTSTRAP_EXIT_FAILED`: remote bootstrap exit failed.
 - `ROOT_DEVELOPMENT_USER_REJECTED`: root development user rejected.
 - `UBUNTU_ARCHITECTURE_UNSUPPORTED`: ubuntu architecture unsupported. **Needs a person.**
-- `XCODE_COMMAND_LINE_TOOLS_REQUIRED`: xcode command line tools required. **Needs a person.**
+- `WORKER_ENVIRONMENT_UNSUPPORTED`: worker environment unsupported: a container or WSL2. **Needs a person.**
 
 ## Ubuntu packages
 
@@ -150,6 +147,20 @@ There are 241 codes; 31 need a person.
 - `GIT_REMOTE_REFUSED`: git remote refused. **Needs a person.**
 - `GIT_REMOTE_UNREACHABLE`: git remote unreachable.
 
+## GitHub sign-in
+
+- **Meaning:** A node is not signed in to GitHub from the stored `github-token`, or the token belongs to another login. See [GitHub on every node](github.md).
+- **Confirm:** The `worker:github-sync` and `github:*` checks of `devfleet fleet-status --workers`; on the node, `gh auth status`.
+- **Fix:** Put a valid token for `worker.githubLogin` in the store as `github-token`, then run `devfleet fleet-sync` (a worker also retries every ten minutes).
+- **Escalate:** A missing login or a token issued for another account needs a person to declare the login or issue a new token.
+
+- `GITHUB_LOGIN_MISMATCH`: github login mismatch. **Needs a person.**
+- `GITHUB_LOGIN_UNDECLARED`: github login undeclared. **Needs a person.**
+- `GITHUB_SIGN_IN_FAILED`: github sign in failed.
+- `GITHUB_TOKEN_MISSING`: github token missing.
+- `GITHUB_TOKEN_REJECTED`: github token rejected.
+- `GITHUB_UNREACHABLE`: github unreachable.
+
 ## Tailscale
 
 - **Meaning:** A machine is not on the tailnet as the fleet declares it.

package/docs/support-matrix.md

@@ -0,0 +1,36 @@
+# Support matrix
+
+Which platforms dev-fleet runs on, in which role, and what happens to the
+rest. The default is one macOS manager and Ubuntu workers treated as cattle.
+
+- **supported**: converged, measured and tested on every pull request.
+- **best effort**: works and is not tested as a fleet role.
+- **refused**: stopped with the named reason before anything is installed.
+
+<!-- Generated by `bun src/machine/support-matrix.ts` from ansible/macos/policy.json, ansible/ubuntu/policy.json and ansible/platforms.json; features/rules/support-matrix.feature fails when it differs. -->
+
+| Role           | Platform  | Versions            | Architectures   | Status      | Note                                                                                      |
+| -------------- | --------- | ------------------- | --------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| manager        | macOS     | 14 or newer         | arm64, x86_64   | supported   | ansible/macos/policy.json                                                                 |
+| worker         | Ubuntu    | 26.04 (resolute)    | amd64, arm64    | supported   | ansible/ubuntu/policy.json; a machine of its own, physical or virtual                     |
+| manager        | any other | any                 | any             | refused     | The fleet configuration accepts only a macOS manager.                                     |
+| worker         | Ubuntu    | any other release   | any             | refused     | UBUNTU_BASELINE_MISMATCH                                                                  |
+| worker         | Ubuntu    | an accepted release | any other       | refused     | UBUNTU_BASELINE_MISMATCH                                                                  |
+| worker         | Debian    | any                 | any             | refused     | UBUNTU_BASELINE_MISMATCH                                                                  |
+| worker         | macOS     | any                 | any             | refused     | The fleet configuration accepts only Linux workers.                                       |
+| worker         | Windows   | any                 | any             | refused     | The fleet configuration accepts only Linux workers.                                       |
+| worker         | WSL2      | any                 | any             | refused     | WORKER_ENVIRONMENT_UNSUPPORTED                                                            |
+| worker         | container | any                 | any             | refused     | WORKER_ENVIRONMENT_UNSUPPORTED                                                            |
+| toolchain only | macOS     | any                 | arm64, x86_64   | best effort | No fleet role: devfleet bootstrap installs the pinned tools (docs/machine-setup.md).      |
+| toolchain only | Linux     | any                 | x86_64, aarch64 | best effort | No fleet role: devfleet bootstrap installs the pinned tools (docs/machine-setup.md).      |
+| toolchain only | WSL2      | any                 | x86_64          | best effort | Treated as Linux: devfleet bootstrap installs the pinned tools (docs/machine-setup.md).   |
+| toolchain only | Windows   | any                 | x64             | best effort | No fleet role: bootstrap/bootstrap.ps1 installs the pinned tools (docs/machine-setup.md). |
+| toolchain only | Alpine    | any                 | any             | refused     | musl: the pinned mise build needs glibc.                                                  |
+
+A worker is refused by the first check that can tell: the fleet configuration
+refuses a worker that is not Linux, the platform probe refuses another
+release, CPU or environment (`ubuntu:release`, `platform:environment`), and
+the bootstrap and the Ubuntu baseline refuse them again on the machine.
+
+Supporting another platform means adding it to the policy that names it, with
+its package pins, a fresh-box job and its row here.

package/docs/ubuntu-sync.md

@@ -61,10 +61,9 @@ resolve enrolled fleet
 
 Bare invocation selects every canonical Linux and macOS node. It does not mean
 “this computer,” and the manager is not implicitly a deployment target. Its own
-node is targeted only if explicitly declared in Fleet membership. Ubuntu 26.04 is
-the accepted worker platform; a node declared `"os": "macOS"` runs the same phases
-best effort through `ansible/macos` (see the platform matrix below).
-Windows machines stay declared for diagnostics and are never converged.
+node is targeted only if explicitly declared in Fleet membership. Workers are the
+Ubuntu releases the [support matrix](support-matrix.md) lists; it also says what
+is refused (macOS and Windows workers, WSL2, containers) and why.
 `--node ID` filters troubleshooting/rollout. `--all` is an explicit spelling of the
 default. Neither flag authorizes managing arbitrary Tailscale peers.
 
@@ -188,7 +187,7 @@ verification and the CLIProxy singleton.
 | Disk safety                 | `personal-fleet-disk-guard` kills only the top user-cgroup writer below 3 GiB free, never deletes files; hourly `personal-fleet-disk-gc.timer` deletes git-ignored build output (`node_modules`, `.cache`, `dist`, ...) in checkouts idle 7d (12h under 15 GiB free) with no process inside, plus unused Docker images and build cache, never source, worktrees or volumes; journal 1G; `/tmp` 25% of RAM, aged 2d hourly, a measured write probe (`TMP_QUOTA_EXHAUSTED`), and T3 agents use disk-backed `/var/tmp` (`TMPDIR`, aged 14d); Docker log rotation                                                                                                                                                                       | not managed                                                                                                                                                                                                                                                                                                                                                                                               |
 | Tailscale                   | pinned APT package, `tailscaled` enabled, native login required                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Tailscale app, human login                                                                                                                                                                                                                                                                                                                                                                                |
 | Dashboard agent             | pinned native binary, hardened `beszel-agent` systemd unit as user `beszel`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | not installed                                                                                                                                                                                                                                                                                                                                                                                             |
-| Credential renewal          | user timer `personal-worker-auth` renews the node's own Vault token and GitHub login every 10min                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | the human's own Vault and GitHub sessions                                                                                                                                                                                                                                                                                                                                                                 |
+| Credential renewal          | user timer `personal-worker-auth` renews the node's own Vault token every 10min; `personal-worker-github` signs it in to GitHub from the stored token ([GitHub](github.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | the human's own Vault and GitHub sessions                                                                                                                                                                                                                                                                                                                                                                 |
 | Noninteractive sudo         | validated `/etc/sudoers.d/personal-fleet-USER`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | never; the human runs `manager.yml` once with `-K`                                                                                                                                                                                                                                                                                                                                                        |
 | T3 worker app               | pinned desktop `.deb` is the only T3 process (UI plus embedded server); GDM auto-login, user unit `t3code-desktop.service` bound to the graphical session with `Restart=always`; `personal-worker-recovery` runs a copy of `t3-health.sh` installed in `/usr/local/lib/personal-fleet` every minute: it stops and disables a still-running headless `t3code.service`, reports `T3_NO_GRAPHICAL_SESSION` and restarts the display manager (three times at most) when there is no session, starts a stopped app after `reset-failed`, restarts one whose local API missed three checks, and restarts one on another release than the installed one or with a deferred policy restart once it runs no agent turn; administrator policy | not a worker                                                                                                                                                                                                                                                                                                                                                                                              |
 | T3 providers                | the same managed instances (`fleet/agents/t3.json`) through locked T3 administrator policy                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | reconciled into the human's T3 settings by `fleet-sync` (`t3:providers`) with the ownership-safe `t3-apply` engine, so every T3 offers the identical set; unrelated and unmanaged instances are preserved. `fleet-sync` also applies the same proxy agent profiles (`configuration:apply`) and verifies the shared Vault gateway credential end to end with `provider:*:inference`, exactly as on workers |
@@ -210,16 +209,19 @@ vault kv get -field=FLEET_WORKER_TOKEN_WORKER_ONE secret/personal/prd \
   | ssh worker-one 'vault login -address=https://vault.example.com -no-print -'
 ```
 
-From then on the node's `personal-worker-auth` timer renews that token and
-restores its GitHub login from it (`bootstrap/worker-auth.ts`). It renders no
-provider configuration: agent profiles are applied by `fleet-sync`. See
-[Authentication and accounts](authentication.md).
+From then on the node's `personal-worker-auth` timer renews that token and its
+`personal-worker-github` timer keeps its GitHub sign-in current
+([GitHub](github.md)). It renders no provider configuration: agent profiles
+are applied by `fleet-sync`. See [Authentication and accounts](authentication.md).
 
 ## Ubuntu and remote-work safety
 
-The declared common baseline is Ubuntu **26.04 LTS**, amd64/arm64. Other releases
-receive `UBUNTU_BASELINE_MISMATCH`; there is no automatic release upgrade or
-package downgrade. Fleet audits release, packages, service state and dpkg
+The accepted releases are named once, in `ansible/ubuntu/policy.json`, and
+listed in the [support matrix](support-matrix.md). Other releases receive
+`UBUNTU_BASELINE_MISMATCH`, and WSL2 and containers
+`WORKER_ENVIRONMENT_UNSUPPORTED`; there is no automatic release upgrade or
+package downgrade. Package pins are minimums: see the
+[worker contract](worker-contract.md#package-pins-and-security-updates). Fleet audits release, packages, service state and dpkg
 consistency, declares snapshot sources for managed transactions, and pins its
 selected APT packages. Unrelated applications and package sources are preserved.
 

package/docs/worker-contract.md

@@ -12,7 +12,8 @@ devfleet fleet-status --workers
 ```
 
 The manager needs Node/npm, Git, SSH, Tailscale, and its own authorized T3 link.
-Initially each Ubuntu 26.04 worker (or best-effort macOS 14+ node) needs a
+Initially each worker (an Ubuntu release the [support matrix](support-matrix.md)
+lists) needs a
 designated non-root account, trusted SSH access and administrator authorization. Standard Ubuntu cloud-image users
 already commonly have noninteractive sudo; otherwise establish the repository's
 `authorize-sudo.sh` policy once during administrator enrollment. Routine commands
@@ -39,6 +40,32 @@ HEAD. Private rosters contain connection paths and identities, not weaker policy
 | No routine password prompts        | Verified BatchMode SSH, `sudo -n`, source-owned NOPASSWD policy; missing initial authorization is a failure                                                                                                |
 | Keep service authorization alive   | Native service credentials stay per-node; Vault self-renewal timer and GitHub recovery from authorized Vault credentials; expiring T3 links are reported before expiry                                     |
 
+## Package pins and security updates
+
+A pin in `ansible/ubuntu/policy.json` is a **minimum**, never a hold. Ubuntu
+keeps installing security updates by itself, and a worker is not turned red by
+one:
+
+- The Ubuntu baseline installs a pinned package from the snapshot only when it
+  is absent or older than its pin, and never downgrades
+  (`ansible/ubuntu/tasks/install.yml`; every pinned package, `systemd-oomd`
+  included, goes through it).
+- What Ubuntu installs unattended is declared in
+  `/etc/apt/apt.conf.d/52personal-fleet-unattended-upgrades`: security updates
+  only, no automatic reboot, no removals.
+- `worker:package:NAME` passes at the pin, **warns** with
+  `PACKAGE_NEWER_THAN_PIN` above it, and fails with `PACKAGE_BELOW_PIN` below
+  it or when the package is missing. A warning does not block convergence or
+  readiness; it says the pin can be raised when the snapshot moves.
+- Tailscale follows the same rule: a newer Tailscale is kept; an older one
+  stops with `TAILSCALE_UPGRADE_PENDING`, because upgrading an active VPN can
+  drop SSH.
+
+A package run cut off by a power loss is finished by the next sync: the
+baseline waits for the APT lock, runs `dpkg --configure -a` once (bounded to
+ten minutes) and audits again; only a database still inconsistent stops with
+`APT_STATE_BROKEN`.
+
 Health does not mutate configuration, renew tokens, log in, install software, or
 make billable inference requests. It audits the immutable desired worker deployment,
 not an unrelated developer branch. Every declared worker must be enrolled and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/dev-fleet",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Keeps a set of development machines in sync: one manager and many workers",
   "license": "MIT",
   "repository": "github:crvouga/dev-fleet",
@@ -72,5 +72,5 @@
   "engines": {
     "node": ">=22"
   },
-  "gitHead": "f2813f818b062ed53335afbeee8f67de3b3ac4d4"
+  "gitHead": "9f9718f2853ed7840c846c8dfc8750903c782b87"
 }

package/schema/check-ids.json

@@ -50,6 +50,14 @@
       "id": "auth:*",
       "meaning": "A required login or capability works in this process context."
     },
+    {
+      "id": "auth:copilot",
+      "meaning": "Copilot CLI uses the node's GitHub sign-in with a token it accepts."
+    },
+    {
+      "id": "auth:github",
+      "meaning": "gh answers auth status in this context."
+    },
     {
       "id": "auth:toolchain",
       "meaning": "The pinned toolchain, dependencies and Docker could be checked."
@@ -168,15 +176,47 @@
     },
     {
       "id": "git:configuration",
-      "meaning": "The fleet's Git identity and credential helper were written on this node."
+      "meaning": "The declared Git identity and the GitHub credential helper are written in the node's global Git configuration."
     },
     {
-      "id": "login:*",
-      "meaning": "A native per-machine login is in place."
+      "id": "github:expiry",
+      "meaning": "The GitHub token does not expire within the warning window."
+    },
+    {
+      "id": "github:git-credential",
+      "meaning": "git asks gh for its GitHub credential."
+    },
+    {
+      "id": "github:org-access",
+      "meaning": "Single sign-on has authorised the GitHub token for each declared organisation."
+    },
+    {
+      "id": "github:permissions",
+      "meaning": "The GitHub token has every declared scope and can push to every declared repository."
+    },
+    {
+      "id": "github:principal",
+      "meaning": "The node is signed in to GitHub as its declared login."
     },
     {
-      "id": "macos:release",
-      "meaning": "The manager runs a supported macOS release."
+      "id": "github:rate-limit",
+      "meaning": "The GitHub rate limit left is above the warning floor."
+    },
+    {
+      "id": "github:sync",
+      "meaning": "fleet-sync signed this node in to GitHub from the stored credential."
+    },
+    {
+      "id": "github:token-current",
+      "meaning": "The node uses the GitHub token the store holds now."
+    },
+    {
+      "id": "github:workflow",
+      "meaning": "fleet-github-verify completed clone, branch, commit, push, pull request, checks and comment on the sandbox repository."
+    },
+    {
+      "id": "login:*",
+      "meaning": "A native per-machine login is in place."
     },
     {
       "id": "manager:docker",
@@ -202,6 +242,10 @@
       "id": "notify:configured",
       "meaning": "Every notification target fleet.json names has its address available as a secret."
     },
+    {
+      "id": "platform:environment",
+      "meaning": "The worker runs on a physical or virtual machine of its own, not in a container or WSL2."
+    },
     {
       "id": "platform:unsupported",
       "meaning": "The machine runs a supported operating system."
@@ -483,8 +527,12 @@
       "meaning": "The worker runs the declared revision."
     },
     {
-      "id": "worker:github-principal",
-      "meaning": "The worker's GitHub login is the declared account."
+      "id": "worker:github-sync",
+      "meaning": "The worker is signed in to GitHub from the stored credential as the declared login."
+    },
+    {
+      "id": "worker:package:*",
+      "meaning": "The pinned Ubuntu package is installed at or past its pin."
     },
     {
       "id": "worker:power-loss-recovery",

package/schema/fleet.schema.json

@@ -253,13 +253,17 @@
       "required": ["release", "architectures"],
       "properties": {
         "release": {
-          "const": "26.04"
+          "type": "string",
+          "pattern": "^[0-9]{2}\\.[0-9]{2}$",
+          "description": "An Ubuntu release ansible/ubuntu/policy.json accepts (docs/support-matrix.md)."
         },
         "architectures": {
-          "const": ["amd64", "arm64"]
+          "type": "array",
+          "items": { "enum": ["amd64", "arm64"] },
+          "description": "Exactly the architectures the policy names for that release."
         }
       },
-      "description": "The supported worker release and architectures (fixed)."
+      "description": "The worker release and its architectures, as the Ubuntu policy of the pinned dev-fleet names them."
     },
     "worker": {
       "type": "object",
@@ -607,8 +611,24 @@
                     }
                   },
                   "description": "Only with the ntfy notify target: the ntfy topic URL fleet-watch publishes to."
+                },
+                "github-token": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["path", "field"],
+                  "properties": {
+                    "path": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z0-9._/-]+$"
+                    },
+                    "field": {
+                      "type": "string",
+                      "pattern": "^[A-Za-z0-9_]+$"
+                    }
+                  }
                 }
-              }
+              },
+              "description": "Required for every secret except github-token, which defaults to the field GITHUB_TOKEN beside proxy-client-key."
             }
           }
         }
@@ -658,6 +678,68 @@
           "maximum": 720
         }
       }
+    },
+    "github": {
+      "description": "How every node signs in to GitHub. The fleet login is worker.githubLogin.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "manager": {
+          "description": "fleet: the manager signs in as the fleet login. {login}: a person's own login, checked and never replaced.",
+          "oneOf": [
+            {
+              "const": "fleet"
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["login"],
+              "properties": {
+                "login": {
+                  "type": "string",
+                  "pattern": "^[a-zA-Z0-9-]{1,39}$"
+                }
+              }
+            }
+          ]
+        },
+        "credential": {
+          "description": "shared: one github-token for every node. per-node: github-token-<node> for each node.",
+          "enum": ["shared", "per-node"]
+        },
+        "scopes": {
+          "description": "Token scopes every node must have, such as repo and workflow.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z:_]{1,40}$"
+          }
+        },
+        "repositories": {
+          "description": "owner/name of repositories every node must be able to push to.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9-]{1,39}/[A-Za-z0-9._-]{1,100}$"
+          }
+        },
+        "organizations": {
+          "description": "Organisations whose single sign-on must have authorised the token.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9-]{1,39}$"
+          }
+        },
+        "sandbox": {
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9-]{1,39}/[A-Za-z0-9._-]{1,100}$",
+          "description": "owner/name of a repository fleet-github-verify branches, pushes to and opens pull requests on, then cleans up."
+        }
+      }
     }
   }
 }

package/src/auth-checks.ts

@@ -6,6 +6,8 @@ import { codingAuth, serviceAuth } from './service-auth';
 import { workstationChecks } from './workstation-checks';
 import { toolchainChecks } from './toolchain-checks';
 import { workerSelection } from '../bootstrap/worker-tools';
+import { githubChecks } from './github/checks';
+import { secretsProvider } from './secrets';
 import type { Capability, Check, Runner, CommandResult } from './types';
 
 export async function authCheck(
@@ -20,6 +22,17 @@ export async function authCheck(
     return codingAuth(capability, run);
   if (capability === 'services') return serviceAuth(run);
   if (capability === 'workstation') return workstationChecks(root, run);
+  if (capability === 'github')
+    return githubChecks(run, {
+      definition,
+      ...(nodeId === undefined ? {} : { node: nodeId }),
+      secret: secretsProvider(definition.secrets, {
+        run: async (argv) => {
+          const result = await run(argv, { timeoutMs: 20_000 });
+          return result.ok ? result.stdout : null;
+        },
+      }),
+    });
   if (capability === 'toolchain')
     return toolchainChecks(
       root,
@@ -32,16 +45,11 @@ export async function authCheck(
 }
 
 async function basicAuth(
-  capability: 'github' | 'vault' | 'vscode',
+  capability: 'vault' | 'vscode',
   run: Runner,
   root: string
 ): Promise<Check[]> {
   const spec = {
-    github: {
-      command: ['gh', 'auth', 'status', '--active'],
-      action:
-        'Authenticate on this node with gh auth login, then gh auth setup-git.',
-    },
     vault: {
       command: [
         'vault',

package/src/cli/fleet-sync-manager.ts

@@ -16,6 +16,7 @@ import { idesOf } from '../ide/definition';
 import { convergeGitIdentity, gitChecks } from '../git-identity';
 import macos from '../../ansible/macos/policy.json';
 import { ansibleCommand } from '../platform/ansible';
+import { convergeGithub } from '../github/converge';
 import { PACKAGE_ROOT } from '../package-info';
 import { managerHealth } from '../manager-health';
 import { readFileSync } from 'node:fs';
@@ -70,6 +71,14 @@ export async function convergeManager(
       );
       if (definition.git)
         checks.push(...(await gitChecks(definition.git, run)));
+      // The same GitHub sign-in as every worker, or only a check of a
+      // person's own login when the configuration names one. git asks gh
+      // for the token through the helper git.yml declared above.
+      checks.push(
+        ...(await attempt('github:sync', async () => [
+          await convergeGithub(input.workspace, run),
+        ]))
+      );
       const providers = await attempt('provider:verification', () =>
         verifyFleetProviders(id)
       );