@crvouga/dev-fleet 0.5.0 → 0.6.0

package/ansible/ubuntu/baseline.yml

@@ -65,3 +65,5 @@
     - ansible.builtin.import_tasks: tasks/ssh.yml
     - ansible.builtin.import_tasks: tasks/credentials.yml
       when: development_source is defined
+    - ansible.builtin.import_tasks: tasks/github.yml
+      when: development_source is defined

package/ansible/ubuntu/tasks/github.yml

@@ -0,0 +1,50 @@
+---
+# This worker's GitHub sign-in, apart from its Vault renewal: a failure of one
+# never hides or stops the other. The job signs in from the stored credential
+# and adopts a rotated token while the old one still works.
+- name: Declare the GitHub sign-in job
+  vars:
+    # Every step the job runs (the secret read and four gh calls) may take
+    # its full timeout (GITHUB_STEP_TIMEOUT_MS), plus the runtime's start.
+    github_step_timeout_seconds: 30
+    github_job_steps: 5
+    github_job_start_seconds: 30
+  ansible.builtin.copy:
+    dest: '{{ development_home }}/.config/systemd/user/personal-worker-github.service'
+    owner: '{{ development_user }}'
+    mode: '0600'
+    content: |
+      [Unit]
+      Description=Sign this worker in to GitHub from its stored credential
+      [Service]
+      Type=oneshot
+      WorkingDirectory={{ development_source }}
+      ExecStart={{ development_home }}/.local/bin/mise exec -- bun bootstrap/worker-github.ts
+      Environment="PATH={{ development_home }}/.local/share/mise/shims:{{ development_home }}/.local/bin:/usr/local/bin:/usr/bin:/bin"
+      UMask=0077
+      TimeoutStartSec={{ github_step_timeout_seconds * github_job_steps + github_job_start_seconds }}
+- name: Declare the GitHub sign-in schedule
+  ansible.builtin.copy:
+    dest: '{{ development_home }}/.config/systemd/user/personal-worker-github.timer'
+    owner: '{{ development_user }}'
+    mode: '0600'
+    content: |
+      [Unit]
+      Description=Keep this worker signed in to GitHub with the stored credential
+      [Timer]
+      OnBootSec=2min
+      OnUnitActiveSec=10min
+      Persistent=true
+      [Install]
+      WantedBy=timers.target
+- name: Enable this user's GitHub sign-in timer
+  become: true
+  become_user: '{{ development_user }}'
+  environment:
+    XDG_RUNTIME_DIR: '/run/user/{{ development_uid }}'
+  ansible.builtin.systemd_service:
+    scope: user
+    name: personal-worker-github.timer
+    daemon_reload: true
+    enabled: true
+    state: started

package/bootstrap/worker-auth.ts

@@ -1,5 +1,7 @@
-import { syncWorkerGithub } from './worker-github';
-/** Private scheduled job. The worker retains its own token; raw auth output is never logged. */
+/** Private scheduled job: renews this worker's own Vault token, and nothing
+ * else. GitHub sign-in is its own job (worker-github.ts), so a failure of
+ * one never stops or hides the other. Raw auth output is never logged.
+ */
 import { spawnSync } from 'node:child_process';
 import { resolveVaultConfig, usesVault } from '../src/vault-config';
 
@@ -49,14 +51,11 @@ if (import.meta.main) {
     jobId: 'vault-self-renewal',
     operation: 'vault.token.renew',
   });
-  const vault = renewWorkerVault();
-  const github = vault && syncWorkerGithub();
-  const ok = vault && github;
+  const ok = renewWorkerVault();
   log.info('job_finished', {
     jobId: 'vault-self-renewal',
     operation: 'vault.token.renew',
-    vaultAuthenticated: vault,
-    githubAuthenticated: github,
+    vaultAuthenticated: ok,
     outcome: ok ? 'success' : 'authentication_required',
     durationMs: Date.now() - started,
     retryDelayMs: 600000,

package/bootstrap/worker-github.ts

@@ -1,47 +1,58 @@
-/** Acquire declared service credentials from this worker's Vault session; never copy a login directory. */
-import { spawnSync } from 'node:child_process';
-import { resolveVaultConfig, usesVault } from '../src/vault-config';
-import { fleet as definition } from '../src/fleet-config';
+/** GitHub sign-in of this node from the stored credential; never copies a
+ * login directory. Runs from the timer (`personal-worker-github`) and from
+ * every sync. One JSON line, never a token or raw output.
+ */
+import { hostname } from 'node:os';
+import { fleet } from '../src/fleet-config';
+import { secretsProvider } from '../src/secrets';
+import { runCommand } from '../src/runner';
+import { hostId } from '../src/topology';
+import { githubCredential } from '../src/github/credential';
+import { githubNode } from '../src/github/policy';
+import { syncGithub, type GithubSyncResult } from '../src/github/sync';
 
-export type AuthRunner = (
-  args: string[],
-  options?: { input?: string; env?: NodeJS.ProcessEnv }
-) => { status: number | null; stdout: string | null };
-const execute: AuthRunner = (args, options = {}) =>
-  spawnSync(args[0]!, args.slice(1), {
-    encoding: 'utf8',
-    timeout: 30_000,
-    ...options,
-  });
-export function syncWorkerGithub(run: AuthRunner = execute): boolean {
-  const expected = definition.worker!.githubLogin;
-  const current = run(['gh', 'api', 'user', '--jq', '.login']);
-  if (current.status === 0 && current.stdout?.trim() === expected) return true;
-  // The service token is kept in the shared Vault document only.
-  if (!usesVault()) return false;
-  const { addr, mount, project, config } = resolveVaultConfig();
-  const secret = run([
-    'vault',
-    'kv',
-    'get',
-    `-address=${addr}`,
-    '-field=GITHUB_TOKEN',
-    `${mount}/${project}/${config}`,
-  ]);
-  const token = secret.stdout?.trim() ?? '';
-  if (secret.status !== 0 || !/^[\x21-\x7e]{16,4096}$/.test(token))
-    return false;
-  const validated = run(['gh', 'api', 'user', '--jq', '.login'], {
-    env: { ...process.env, GH_TOKEN: token, GITHUB_TOKEN: undefined },
-  });
-  if (validated.status !== 0 || validated.stdout?.trim() !== expected)
-    return false;
-  const login = run(
-    ['gh', 'auth', 'login', '--hostname', 'github.com', '--with-token'],
-    {
-      input: token + '\n',
-      env: { ...process.env, GH_TOKEN: undefined, GITHUB_TOKEN: undefined },
-    }
+/** The exit status of each outcome, so the unit's result names it too. */
+export const EXIT_CODES: Record<GithubSyncResult['code'], number> = {
+  GITHUB_OK: 0,
+  GITHUB_TOKEN_MISSING: 10,
+  GITHUB_TOKEN_REJECTED: 11,
+  GITHUB_LOGIN_MISMATCH: 12,
+  GITHUB_UNREACHABLE: 13,
+  GITHUB_SIGN_IN_FAILED: 14,
+};
+
+export const GITHUB_JOB = 'dev-fleet-github';
+
+if (import.meta.main) {
+  const started = Date.now();
+  // The manager is never a declared worker; `--node` names a worker whose
+  // host name is not its id.
+  const flag = process.argv.indexOf('--node');
+  const id = flag > 0 ? process.argv[flag + 1] : hostId(hostname());
+  const target = githubNode(fleet, id);
+  const result: GithubSyncResult =
+    target.login === null
+      ? { code: 'GITHUB_LOGIN_MISMATCH', adopted: false }
+      : await syncGithub({
+          run: runCommand,
+          token: githubCredential(
+            fleet,
+            target.node,
+            secretsProvider(fleet.secrets)
+          ),
+          login: target.login,
+          // A person's own login on the manager is measured, never replaced.
+          apply: target.managed,
+        });
+  process.stdout.write(
+    JSON.stringify({
+      name: GITHUB_JOB,
+      event: 'job_finished',
+      role: target.role,
+      code: result.code,
+      adopted: result.adopted,
+      durationMs: Date.now() - started,
+    }) + '\n'
   );
-  return login.status === 0;
+  process.exitCode = EXIT_CODES[result.code];
 }

package/docs/authentication.md

@@ -54,6 +54,7 @@ Every failure code is in [the runbooks](runbooks.md).
 | `monitoring-account-password`  | yes                          | `DEVFLEET_SECRET_MONITORING_ACCOUNT_PASSWORD`  | `~/.config/dev-fleet/secrets/monitoring-account-password`  |
 | `monitoring-tunnel-token`      | yes                          | `DEVFLEET_SECRET_MONITORING_TUNNEL_TOKEN`      | `~/.config/dev-fleet/secrets/monitoring-tunnel-token`      |
 | `proxy-tunnel-token`           | yes                          | `DEVFLEET_SECRET_PROXY_TUNNEL_TOKEN`           | `~/.config/dev-fleet/secrets/proxy-tunnel-token`           |
+| `github-token`                 | when its feature is declared | `DEVFLEET_SECRET_GITHUB_TOKEN`                 | `~/.config/dev-fleet/secrets/github-token`                 |
 | `monitoring-backup-access-key` | when its feature is declared | `DEVFLEET_SECRET_MONITORING_BACKUP_ACCESS_KEY` | `~/.config/dev-fleet/secrets/monitoring-backup-access-key` |
 | `monitoring-backup-secret-key` | when its feature is declared | `DEVFLEET_SECRET_MONITORING_BACKUP_SECRET_KEY` | `~/.config/dev-fleet/secrets/monitoring-backup-secret-key` |
 | `notify-webhook-url`           | when its feature is declared | `DEVFLEET_SECRET_NOTIFY_WEBHOOK_URL`           | `~/.config/dev-fleet/secrets/notify-webhook-url`           |
@@ -67,10 +68,11 @@ Every failure code is in [the runbooks](runbooks.md).
 
 | Check                         | Measured in                                |
 | ----------------------------- | ------------------------------------------ |
+| `auth:github`                 | `src/github/checks.ts`                     |
 | `auth:vault`                  | `src/cli/fleet-sync-vault.ts`              |
 | `worker:git-identity`         | `src/git-identity.ts`                      |
 | `worker:git-push-auth`        | `src/definition.ts`, `src/git-identity.ts` |
-| `worker:github-principal`     | `src/worker-access-checks.ts`              |
+| `worker:github-sync`          | `src/worker-access-checks.ts`              |
 | `worker:proxy-authentication` | `src/worker-access-checks.ts`              |
 | `worker:vault-renewal`        | `src/worker-access-checks.ts`              |
 
@@ -84,6 +86,7 @@ Every failure code is in [the runbooks](runbooks.md).
 | -------------------------------- | -------------------------------------- | ------------------------------------- |
 | `personal-fleet-disk-gc.timer`   | `ansible/ubuntu/tasks/resources.yml`   | OnBootSec=10min, OnCalendar=hourly    |
 | `personal-worker-auth.timer`     | `ansible/ubuntu/tasks/credentials.yml` | OnBootSec=2min, OnUnitActiveSec=10min |
+| `personal-worker-github.timer`   | `ansible/ubuntu/tasks/github.yml`      | OnBootSec=2min, OnUnitActiveSec=10min |
 | `personal-worker-recovery.timer` | `ansible/ubuntu/tasks/recovery.yml`    | OnBootSec=1min, OnUnitActiveSec=1min  |
 | `personal-worker-recovery.timer` | `ansible/ubuntu/tasks/recovery.yml`    | OnBootSec=5min, OnUnitActiveSec=15min |
 

package/docs/consumer-setup.md

@@ -179,6 +179,7 @@ Then replace every placeholder. Each field, from
 | `ubuntu`                                              | `{ "release": "26.04", "architectures": ["amd64", "arm64"] }`: a release of the [support matrix](support-matrix.md). |
 | `worker.requiredCapabilities`                         | Normally all of `github`, `vault`, `t3`, `toolchain`, `workstation`, `worker`.                                       |
 | `worker.githubLogin`                                  | The GitHub login every worker must be signed in as.                                                                  |
+| `github` (optional)                                   | Who the manager signs in to GitHub as, per-node tokens, required scopes; see [GitHub](github.md).                    |
 | `worker.vaultUser`                                    | The Vault user each worker's token is issued for.                                                                    |
 | `worker.toolchain`, `agentProfile`                    | `"mise.lock"`, `"proxy"` (fixed).                                                                                    |
 | `worker.unattendedSudo`, `persistentT3`, `neverSleep` | `true` (fixed policy).                                                                                               |
@@ -206,6 +207,10 @@ dev-fleet asks for four secrets by purpose: `proxy-client-key`,
 | `file`   | `{ "provider": "file" }` (optional `"directory"`)                                                                                                    | One private file per name, default `~/.config/dev-fleet/secrets/NAME`.  |
 | `env`    | `{ "provider": "env" }`                                                                                                                              | `DEVFLEET_SECRET_PROXY_CLIENT_KEY` and so on (upper case, `_` for `-`). |
 
+A fifth, `github-token`, is the GitHub token of `worker.githubLogin`: every node
+is signed in with it ([GitHub](github.md)). With `vault` it needs no location
+of its own: it defaults to the field `GITHUB_TOKEN` beside `proxy-client-key`.
+
 Only `vault` gives each worker its own login and renewal and gives the CLI
 proxy its encrypted backup; with the other three those two features are not
 available yet. You never write a secret value into the project; the human puts

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,7 +8,7 @@ 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 238 codes; 29 need a person.
+There are 244 codes; 31 need a person.
 
 ## Bootstrap of a new or returning worker
 
@@ -147,6 +147,20 @@ There are 238 codes; 29 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/ubuntu-sync.md

@@ -187,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 |
@@ -209,10 +209,10 @@ 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/dev-fleet",
-  "version": "0.5.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": "620b8de05d662b4dc9072457580ca4b4eab54242"
+  "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,7 +176,43 @@
     },
     {
       "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": "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": "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:*",
@@ -483,8 +527,8 @@
       "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:*",

package/schema/fleet.schema.json

@@ -611,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."
             }
           }
         }
@@ -662,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."
+        }
+      }
     }
   }
 }