@crvouga/dev-fleet 0.4.0 → 0.6.0

package/ansible/ubuntu/tasks/install.yml

@@ -0,0 +1,38 @@
+---
+# The one way a pinned Ubuntu package is installed: from the snapshot,
+# waiting for the APT lock, and never downgrading. A pin is a minimum: a
+# package Ubuntu's security updates moved past its pin is left as it is and
+# reported as a warning (docs/worker-contract.md). `install_pins` maps each
+# package to its pinned version.
+- ansible.builtin.import_tasks: snapshot.yml
+- name: Read the installed package versions
+  ansible.builtin.package_facts:
+    manager: apt
+- name: Compare each installed pinned package with its pin
+  ansible.builtin.command:
+    argv:
+      - dpkg
+      - --compare-versions
+      - '{{ ansible_facts.packages[item][0].version }}'
+      - ge
+      - '{{ install_pins[item] }}'
+  loop: "{{ install_pins.keys() | select('in', ansible_facts.packages) | list }}"
+  register: pin_comparison
+  changed_when: false
+  failed_when: pin_comparison.rc not in [0, 1]
+  check_mode: false
+- name: Select the pinned packages that are absent or older than their pin
+  ansible.builtin.set_fact:
+    below_pin: "{{ (install_pins.keys() | reject('in', ansible_facts.packages) | list) + (pin_comparison.results | selectattr('rc', 'equalto', 1) | map(attribute='item') | list) }}"
+- name: Install the pinned version of each package below its pin, without restarting services
+  ansible.builtin.apt:
+    name: '{{ item }}={{ install_pins[item] }}'
+    state: present
+    lock_timeout: '{{ aptLockTimeoutSeconds }}'
+    allow_downgrade: false
+    allow_unauthenticated: false
+    fail_on_autoremove: true
+    policy_rc_d: 101
+  environment:
+    APT_CONFIG: /etc/personal-fleet/apt.conf
+  loop: '{{ below_pin }}'

package/ansible/ubuntu/tasks/packages.yml

@@ -1,56 +1,5 @@
 ---
-- name: Create owned APT configuration directory
-  ansible.builtin.file:
-    path: /etc/personal-fleet
-    state: directory
-    owner: root
-    group: root
-    mode: '0755'
-- name: Declare snapshot sources used only for managed package transactions
-  ansible.builtin.copy:
-    dest: /etc/personal-fleet/ubuntu.sources
-    owner: root
-    group: root
-    mode: '0644'
-    backup: true
-    content: |
-      Types: deb
-      URIs: https://snapshot.ubuntu.com/ubuntu/{{ snapshot }}/
-      Suites: resolute resolute-updates resolute-security
-      Components: main universe restricted multiverse
-      Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
-  register: snapshot_sources
-- name: Isolate snapshot selection from unrelated APT operations
-  ansible.builtin.copy:
-    dest: /etc/personal-fleet/apt.conf
-    owner: root
-    group: root
-    mode: '0644'
-    content: |
-      Dir::Etc::sourcelist "/etc/personal-fleet/ubuntu.sources";
-      Dir::Etc::sourceparts "-";
-      DPkg::Lock::Timeout "{{ aptLockTimeoutSeconds }}";
-- name: Inspect immutable snapshot package index
-  ansible.builtin.stat:
-    path: '/var/lib/apt/lists/snapshot.ubuntu.com_ubuntu_{{ snapshot }}_dists_resolute_InRelease'
-  register: snapshot_index
-- name: Fetch signed snapshot indexes after source change or interrupted setup
-  ansible.builtin.apt:
-    update_cache: true
-    cache_valid_time: 0
-    lock_timeout: '{{ aptLockTimeoutSeconds }}'
-  environment:
-    APT_CONFIG: /etc/personal-fleet/apt.conf
-  when: snapshot_sources.changed or not snapshot_index.stat.exists
-- name: Install exact managed packages without downgrading or restarting services
-  ansible.builtin.apt:
-    name: '{{ item.key }}={{ item.value }}'
-    state: present
-    lock_timeout: '{{ aptLockTimeoutSeconds }}'
-    allow_downgrade: false
-    allow_unauthenticated: false
-    fail_on_autoremove: true
-    policy_rc_d: 101
-  environment:
-    APT_CONFIG: /etc/personal-fleet/apt.conf
-  loop: '{{ packages | dict2items }}'
+- ansible.builtin.include_tasks: install.yml
+  vars:
+    install_pins: '{{ packages }}'
+- ansible.builtin.import_tasks: unattended-upgrades.yml

package/ansible/ubuntu/tasks/release.yml

@@ -0,0 +1,25 @@
+---
+# The accepted releases are named once, in policy.json. This selects the
+# entry of the running release and refuses everything else.
+- name: Select the accepted release this machine runs
+  ansible.builtin.set_fact:
+    ubuntu_release: "{{ releases | selectattr('release', 'equalto', ansible_facts.distribution_version) | first | default({}) }}"
+- name: Require an accepted release, its codename and one of its architectures
+  ansible.builtin.assert:
+    that:
+      - ansible_facts.distribution == 'Ubuntu'
+      - ubuntu_release.release is defined
+      - ansible_facts.distribution_release == ubuntu_release.codename
+      - "(ansible_facts.architecture | replace('x86_64', 'amd64') | replace('aarch64', 'arm64')) in ubuntu_release.architectures"
+    fail_msg: UBUNTU_BASELINE_MISMATCH; workers run a release docs/support-matrix.md lists. No distribution upgrade is permitted.
+- name: Pin the packages of this release, its own pins over the common ones
+  ansible.builtin.set_fact:
+    packages: '{{ packages | combine(ubuntu_release.packages | default({})) }}'
+- name: Read the kernel release to tell WSL2 apart from a machine of its own
+  ansible.builtin.slurp:
+    src: /proc/sys/kernel/osrelease
+  register: kernel_release
+- name: Refuse WSL2 by name
+  ansible.builtin.assert:
+    that: not (kernel_release.content | b64decode | lower is search('microsoft|wsl'))
+    fail_msg: WORKER_ENVIRONMENT_UNSUPPORTED; WSL2 is not a worker. Run the worker on a physical or virtual machine of its own (docs/support-matrix.md).

package/ansible/ubuntu/tasks/resources.yml

@@ -49,10 +49,11 @@
     line: /swap.fleet none swap sw 0 0
   when: active_swap.stdout | trim == ''
 
-- name: Install the systemd userspace OOM killer
-  ansible.builtin.apt:
-    name: systemd-oomd
-    state: present
+- name: Install the systemd userspace OOM killer at its pin
+  ansible.builtin.include_tasks: install.yml
+  vars:
+    install_pins:
+      systemd-oomd: "{{ packages['systemd-oomd'] }}"
 - name: Create memory and disk policy directories
   ansible.builtin.file:
     path: '{{ item }}'
@@ -276,7 +277,7 @@
         After=docker.service
         [Service]
         Type=oneshot
-        ExecStart=/usr/bin/python3 -I -B {{ disk_gc_source.stat.path }} --home {{ development_home }} --path / --path {{ development_home }} --idle-days {{ resourceSafety.diskGcIdleDays }} --pressure-mib {{ resourceSafety.diskGcPressureMiB }} --pressure-inode-percent {{ resourceSafety.inodeWarnFreePercent }} --pressure-idle-hours {{ resourceSafety.diskGcPressureIdleHours }} --docker-age-hours {{ resourceSafety.diskGcDockerAgeHours }} --pressure-docker-age-hours {{ resourceSafety.diskGcPressureDockerAgeHours }}{% for cache in resourceSafety.diskGcPressureCaches %} --pressure-cache {{ cache }}{% endfor %}
+        ExecStart=/usr/bin/python3 -I -B {{ disk_gc_source.stat.path }} --home {{ development_home }} --path / --path {{ development_home }} --idle-days {{ resourceSafety.diskGcIdleDays }} --pressure-mib {{ resourceSafety.diskGcPressureMiB }} --pressure-inode-percent {{ resourceSafety.inodeWarnFreePercent }} --pressure-idle-hours {{ resourceSafety.diskGcPressureIdleHours }} --docker-age-hours {{ resourceSafety.diskGcDockerAgeHours }} --pressure-docker-age-hours {{ resourceSafety.diskGcPressureDockerAgeHours }}{% for cache in resourceSafety.diskGcPressureCaches %} --pressure-cache {{ cache }}{% endfor %}{% for root in resourceSafety.diskGcWorktreeRoots %} --worktree-root {{ root }}{% endfor %} --worktree-idle-days {{ resourceSafety.diskGcWorktreeIdleDays }}{% for cache, mib in resourceSafety.diskGcCacheCapsMiB.items() %} --cache-cap {{ cache }}={{ mib }}{% endfor %} --keep-newest /var/cache/personal-fleet={{ resourceSafety.diskGcPackagesKept }} --mise {{ development_home }}/.local/bin/mise --user {{ development_user }}
 
         TimeoutStartSec=2h
         Nice=19

package/ansible/ubuntu/tasks/snapshot.yml

@@ -0,0 +1,50 @@
+---
+# The snapshot every managed package comes from, separate from the system's
+# own sources. Included before any pinned package is installed; a second
+# inclusion in one run changes nothing.
+- name: Create owned APT configuration directory
+  ansible.builtin.file:
+    path: /etc/personal-fleet
+    state: directory
+    owner: root
+    group: root
+    mode: '0755'
+- name: Declare snapshot sources used only for managed package transactions
+  ansible.builtin.copy:
+    dest: /etc/personal-fleet/ubuntu.sources
+    owner: root
+    group: root
+    mode: '0644'
+    backup: true
+    content: |
+      Types: deb
+      URIs: https://snapshot.ubuntu.com/ubuntu/{{ snapshot }}/
+      Suites: {{ ubuntu_release.codename }} {{ ubuntu_release.codename }}-updates {{ ubuntu_release.codename }}-security
+      Components: main universe restricted multiverse
+      Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
+  register: snapshot_sources
+# Fetching the snapshot indexes must leave the indexes of the system's own
+# sources in place: the system's APT and unattended upgrades still use them.
+- name: Isolate snapshot selection from unrelated APT operations
+  ansible.builtin.copy:
+    dest: /etc/personal-fleet/apt.conf
+    owner: root
+    group: root
+    mode: '0644'
+    content: |
+      Dir::Etc::sourcelist "/etc/personal-fleet/ubuntu.sources";
+      Dir::Etc::sourceparts "-";
+      APT::Get::List-Cleanup "false";
+      DPkg::Lock::Timeout "{{ aptLockTimeoutSeconds }}";
+- name: Inspect immutable snapshot package index
+  ansible.builtin.stat:
+    path: '/var/lib/apt/lists/snapshot.ubuntu.com_ubuntu_{{ snapshot }}_dists_{{ ubuntu_release.codename }}_InRelease'
+  register: snapshot_index
+- name: Fetch signed snapshot indexes after source change or interrupted setup
+  ansible.builtin.apt:
+    update_cache: true
+    cache_valid_time: 0
+    lock_timeout: '{{ aptLockTimeoutSeconds }}'
+  environment:
+    APT_CONFIG: /etc/personal-fleet/apt.conf
+  when: snapshot_sources.changed or not snapshot_index.stat.exists

package/ansible/ubuntu/tasks/unattended-upgrades.yml

@@ -0,0 +1,24 @@
+---
+# Ubuntu installs security updates by itself, and they keep flowing: a pin is
+# a minimum, never a hold. What runs unattended is declared here so it is
+# known: security updates only, never a reboot, never a removal. The fleet's
+# own file sorts after the package's 50unattended-upgrades and replaces its
+# origins.
+- name: Declare which updates Ubuntu installs unattended
+  ansible.builtin.copy:
+    dest: /etc/apt/apt.conf.d/52personal-fleet-unattended-upgrades
+    owner: root
+    group: root
+    mode: '0644'
+    content: |
+      // Managed by personal Fleet: unattended upgrades
+      APT::Periodic::Update-Package-Lists "1";
+      APT::Periodic::Unattended-Upgrade "1";
+      #clear Unattended-Upgrade::Allowed-Origins;
+      #clear Unattended-Upgrade::Origins-Pattern;
+      Unattended-Upgrade::Allowed-Origins {
+        "${distro_id}:${distro_codename}-security";
+      };
+      Unattended-Upgrade::Automatic-Reboot "false";
+      Unattended-Upgrade::Remove-Unused-Dependencies "false";
+      Unattended-Upgrade::Remove-New-Unused-Dependencies "false";

package/bootstrap/fleet-remote-bootstrap.sh

@@ -2,14 +2,17 @@
 # Executed over strict SSH from the selected verified Git revision. stdin is
 # one line holding the base64 fleet configuration (empty when there is none),
 # then the base64 Git bundle (nothing in cached mode). All executable content
-# remains in this tracked source.
+# remains in this tracked source. The Ubuntu releases workers may run are
+# named once, in ansible/ubuntu/policy.json; the manager passes them in.
 set -eu
 umask 077
 revision=$1
 bundle_sha=$2
 node=$3
 source_mode=${4:-transfer}
+releases=${5:-}
 case "$source_mode" in cached|transfer) ;; *) exit 2;; esac
+case "$releases" in *[!0-9.\ ]*|'') exit 2;; esac
 case "$revision" in *[!a-f0-9]*|'') exit 2;; esac
 [ "${#revision}" = 40 ] || exit 2
 case "$bundle_sha" in *[!a-f0-9]*|'') exit 2;; esac
@@ -26,7 +29,8 @@ remedy() {
   case "$1" in
     FLEET_REMOTE_LOCKED) echo 'Another fleet operation holds this machine. Wait for it to finish; rerun fleet-sync afterwards. Never remove the lock while its holder runs.';;
     ROOT_DEVELOPMENT_USER_REJECTED) echo 'Connect as the non-root developer account the fleet configuration names.';;
-    UBUNTU_BASELINE_MISMATCH|UBUNTU_ARCHITECTURE_UNSUPPORTED|MACOS_BASELINE_MISMATCH|MACOS_ARCHITECTURE_UNSUPPORTED|PLATFORM_UNSUPPORTED) echo 'Workers run Ubuntu 26.04 on x86_64 or aarch64. Reinstall the machine; fleet-sync never upgrades an operating system.';;
+    UBUNTU_BASELINE_MISMATCH|UBUNTU_ARCHITECTURE_UNSUPPORTED|PLATFORM_UNSUPPORTED) echo 'Workers run an Ubuntu release docs/support-matrix.md lists, on x86_64 or aarch64. Reinstall the machine; fleet-sync never upgrades an operating system.';;
+    WORKER_ENVIRONMENT_UNSUPPORTED) echo 'WSL2 is not a worker. Run the worker on a physical or virtual machine of its own (docs/support-matrix.md).';;
     FLEET_STATE_PATH_UNSAFE) echo 'A fleet state directory under ~/.local/share/personal is a symbolic link. Replace it with a real directory.';;
     BOOTSTRAP_CAPACITY_UNVERIFIED|BOOTSTRAP_DISK_CAPACITY_REQUIRED) echo 'Free at least 2 GiB and 50000 inodes on the home file system, then rerun fleet-sync.';;
     SOURCE_DIGEST_MISMATCH) echo 'The bundle changed in transit. Rerun fleet-sync; if it repeats, check the SSH route.';;
@@ -37,8 +41,6 @@ remedy() {
     APT_DISK_FULL) echo 'Package installation ran out of disk space. Free space under /var and /usr, then rerun fleet-sync.';;
     DPKG_INTERRUPTED) echo 'An earlier package installation that fleet-sync did not start was interrupted. Run sudo dpkg --configure -a once no package process is running, then rerun fleet-sync.';;
     APT_UPDATE_FAILED|APT_INSTALL_FAILED) echo 'Run sudo apt-get update and install the bootstrap packages by hand to see the error, then rerun fleet-sync.';;
-    XCODE_COMMAND_LINE_TOOLS_REQUIRED) echo 'Install the Xcode Command Line Tools (xcode-select --install), then rerun fleet-sync.';;
-    BOOTSTRAP_LOCK_TOOL_REQUIRED) echo 'Install python3 so the operation lock can be taken, then rerun fleet-sync.';;
     SOURCE_CACHE_CHANGED|SOURCE_STATUS_FAILED|SOURCE_CHECKOUT_CONFLICT) echo 'The fleet-owned checkout of this revision holds changes fleet-sync did not make. Inspect and remove that revisions directory, then rerun fleet-sync.';;
     CONFIGURATION_INSTALL_FAILED) echo 'The fleet configuration could not be written under ~/.config/dev-fleet. Check that directory, then rerun fleet-sync.';;
     TOOLCHAIN_*) echo 'The pinned toolchain did not converge. Rerun fleet-sync; it resumes where it stopped. If it repeats, run devfleet fleet-status --node for this worker.';;
@@ -64,22 +66,14 @@ trap '' HUP
 trap 'exit 1' INT TERM
 # No shell startup assumptions, and no implicit root development user.
 [ "$(id -u)" != 0 ] || die ROOT_DEVELOPMENT_USER_REJECTED
-# Ubuntu 26.04 is the accepted worker platform; macOS 14+ follows the same
-# phases best effort with launchd instead of systemd.
-platform=$(uname -s)
-case "$platform" in
-  Linux)
-    # shellcheck source=/dev/null
-    . /etc/os-release
-    [ "$ID" = ubuntu ] && [ "$VERSION_ID" = 26.04 ] || die UBUNTU_BASELINE_MISMATCH
-    case "$(uname -m)" in x86_64|aarch64) ;; *) die UBUNTU_ARCHITECTURE_UNSUPPORTED;; esac ;;
-  Darwin)
-    major=$(sw_vers -productVersion | cut -d. -f1)
-    case "$major" in ''|*[!0-9]*) die MACOS_BASELINE_MISMATCH;; esac
-    [ "$major" -ge 14 ] || die MACOS_BASELINE_MISMATCH
-    case "$(uname -m)" in arm64|x86_64) ;; *) die MACOS_ARCHITECTURE_UNSUPPORTED;; esac ;;
-  *) die PLATFORM_UNSUPPORTED;;
-esac
+# Workers are the Ubuntu releases the policy accepts (docs/support-matrix.md).
+[ "$(uname -s)" = Linux ] || die PLATFORM_UNSUPPORTED
+# shellcheck source=/dev/null
+. /etc/os-release
+[ "$ID" = ubuntu ] || die UBUNTU_BASELINE_MISMATCH
+case " $releases " in *" $VERSION_ID "*) ;; *) die UBUNTU_BASELINE_MISMATCH;; esac
+case "$(uname -m)" in x86_64|aarch64) ;; *) die UBUNTU_ARCHITECTURE_UNSUPPORTED;; esac
+! grep -qiE 'microsoft|wsl' /proc/sys/kernel/osrelease 2>/dev/null || die WORKER_ENVIRONMENT_UNSUPPORTED
 root="$HOME/.local/share/personal/fleet"
 # Refuse symlinked state roots rather than allowing writes through them.
 for path in "$HOME/.local" "$HOME/.local/share" "$HOME/.local/share/personal" "$root"; do
@@ -89,14 +83,8 @@ mkdir -p "$root"
 phase=lock
 [ ! -L "$root/remote-operation.lock" ] || exit 1
 exec 9>"$root/remote-operation.lock"
-# macOS has no flock(1); lock the same descriptor through fcntl. The lock
-# follows this shell's open descriptor and is released when it exits.
-if command -v flock >/dev/null 2>&1; then
-  flock -n 9 || die FLEET_REMOTE_LOCKED
-else
-  command -v python3 >/dev/null 2>&1 || die BOOTSTRAP_LOCK_TOOL_REQUIRED
-  python3 -c 'import fcntl; fcntl.flock(9, fcntl.LOCK_EX | fcntl.LOCK_NB)' 9>&9 || die FLEET_REMOTE_LOCKED
-fi
+# The lock follows this shell's open descriptor and is released when it exits.
+flock -n 9 || die FLEET_REMOTE_LOCKED
 # The operation record: a manager that lost its session reads it to follow
 # this operation to its end instead of starting another (see
 # src/remote-operation.ts). The result of the last operation is beside it.
@@ -132,14 +120,9 @@ if [ "$source_mode" = transfer ]; then
 bundle=$(mktemp "$root/source.XXXXXX")
 # Leave no executable payload copies; this temporary file is only Git data.
 base64 -d >"$bundle"
-if command -v sha256sum >/dev/null 2>&1; then
-  printf '%s  %s\n' "$bundle_sha" "$bundle" | sha256sum -c - >/dev/null 2>&1 || die SOURCE_DIGEST_MISMATCH
-else
-  [ "$(shasum -a 256 "$bundle" | cut -d' ' -f1)" = "$bundle_sha" ] || die SOURCE_DIGEST_MISMATCH
-fi
+printf '%s  %s\n' "$bundle_sha" "$bundle" | sha256sum -c - >/dev/null 2>&1 || die SOURCE_DIGEST_MISMATCH
 fi
 phase=prerequisites
-if [ "$platform" = Linux ]; then
 missing=''
 for package in git curl ca-certificates unzip xz-utils build-essential python3 ansible-core; do
   dpkg-query -W -f='${db:Status-Status}' "$package" 2>/dev/null | grep -qx installed || missing="$missing $package"
@@ -171,12 +154,6 @@ if [ -n "$missing" ]; then
   rm -f -- "$pending" "$apt_log"
   apt_log=''
 fi
-else
-  # Apple Command Line Tools provide git and python3; Ansible runs through the
-  # pinned uv tool runner installed by the shared mise toolchain below.
-  xcode-select -p >/dev/null 2>&1 || die XCODE_COMMAND_LINE_TOOLS_REQUIRED
-  command -v git >/dev/null 2>&1 || die XCODE_COMMAND_LINE_TOOLS_REQUIRED
-fi
 phase=source-verification
 deployment="$root/revisions/$revision"
 [ ! -L "$root/revisions" ] && [ ! -L "$deployment" ] || exit 1
@@ -235,7 +212,7 @@ else
   toolchain_warm=''
   rm -f -- "$status_file" "$ready_file"
 fi
-if command -v timeout >/dev/null 2>&1; then bounded='timeout 1800'; else bounded=''; fi
+bounded='timeout 1800'
 # shellcheck disable=SC2086
 if [ -z "$toolchain_warm" ] && ! $bounded bash bootstrap/bootstrap.sh --worker --node "$node" --non-interactive --status-file "$status_file" >/dev/null 2>&1; then
   tool_phase=$(sed -n 's/.*"phase":"\([a-z0-9-]*\)".*/\1/p' "$status_file" 2>/dev/null) || tool_phase=''

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

@@ -153,35 +153,36 @@ npx devfleet fleet-state --example > fleet.json
 Then replace every placeholder. Each field, from
 [`schema/fleet.schema.json`](../schema/fleet.schema.json):
 
-| Field                                                 | Value                                                                                                              |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `version`                                             | `3`                                                                                                                |
-| `source.repository`                                   | `https://github.com/crvouga/dev-fleet.git`, or your fork if you publish one. Machines only accept code from it.    |
-| `state`                                               | `{ "bucket", "endpoint"?, "region"?, "prefix"? }` or `{ "directory": "/absolute/path" }`. Never credentials.       |
-| `secrets`                                             | See [secrets](#secrets).                                                                                           |
-| `manager.id`                                          | A short lowercase id, `^[a-z][a-z0-9-]{0,62}$`, e.g. `manager-mac`.                                                |
-| `manager.os`                                          | `"macOS"`                                                                                                          |
-| `manager.network.tailscaleName`                       | The manager's MagicDNS name: `tailscale status --json` → `.Self.DNSName` without the trailing dot.                 |
-| `manager.network.user`                                | The manager's login name (`id -un`).                                                                               |
-| `manager.neverSleepOnPower`                           | `true` (workers depend on the manager's services).                                                                 |
-| `workers[].id`                                        | A short lowercase id. The **first** worker is the canary: a new revision must pass there before the others get it. |
-| `workers[].ssh`                                       | The worker's alias in the manager's `~/.ssh/config`.                                                               |
-| `workers[].os`                                        | `"linux"`                                                                                                          |
-| `workers[].network.tailscaleName`                     | The worker's MagicDNS name (from `tailscale status --json` → `.Peer[].DNSName` on the manager).                    |
-| `workers[].network.sshPort`                           | `22` unless the worker's sshd listens elsewhere.                                                                   |
-| `workers[].network.user`                              | The worker account (`ssh WORKER_ALIAS id -un`).                                                                    |
-| `workers[].network.t3Port`                            | `3773`                                                                                                             |
-| `services.proxy.endpoint`                             | The public HTTPS origin of the CLI proxy, e.g. `https://cli-proxy.example.com`.                                    |
-| `services.monitoring.hubPort`                         | `8443`                                                                                                             |
-| `services.monitoring.publicUrl`                       | The public HTTPS origin of the monitoring dashboard.                                                               |
-| `services.monitoring.managerAccount`                  | The email of the monitoring account the manager enrolls machines with.                                             |
-| `services.monitoring.viewerAccount`                   | The email of the read-only account visitors are signed in as.                                                      |
-| `ubuntu`                                              | `{ "release": "26.04", "architectures": ["amd64", "arm64"] }` (fixed).                                             |
-| `worker.requiredCapabilities`                         | Normally all of `github`, `vault`, `t3`, `toolchain`, `workstation`, `worker`.                                     |
-| `worker.githubLogin`                                  | The GitHub login every worker must be signed in as.                                                                |
-| `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).                                                                                             |
+| Field                                                 | Value                                                                                                                |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `version`                                             | `3`                                                                                                                  |
+| `source.repository`                                   | `https://github.com/crvouga/dev-fleet.git`, or your fork if you publish one. Machines only accept code from it.      |
+| `state`                                               | `{ "bucket", "endpoint"?, "region"?, "prefix"? }` or `{ "directory": "/absolute/path" }`. Never credentials.         |
+| `secrets`                                             | See [secrets](#secrets).                                                                                             |
+| `manager.id`                                          | A short lowercase id, `^[a-z][a-z0-9-]{0,62}$`, e.g. `manager-mac`.                                                  |
+| `manager.os`                                          | `"macOS"`                                                                                                            |
+| `manager.network.tailscaleName`                       | The manager's MagicDNS name: `tailscale status --json` → `.Self.DNSName` without the trailing dot.                   |
+| `manager.network.user`                                | The manager's login name (`id -un`).                                                                                 |
+| `manager.neverSleepOnPower`                           | `true` (workers depend on the manager's services).                                                                   |
+| `workers[].id`                                        | A short lowercase id. The **first** worker is the canary: a new revision must pass there before the others get it.   |
+| `workers[].ssh`                                       | The worker's alias in the manager's `~/.ssh/config`.                                                                 |
+| `workers[].os`                                        | `"linux"`                                                                                                            |
+| `workers[].network.tailscaleName`                     | The worker's MagicDNS name (from `tailscale status --json` → `.Peer[].DNSName` on the manager).                      |
+| `workers[].network.sshPort`                           | `22` unless the worker's sshd listens elsewhere.                                                                     |
+| `workers[].network.user`                              | The worker account (`ssh WORKER_ALIAS id -un`).                                                                      |
+| `workers[].network.t3Port`                            | `3773`                                                                                                               |
+| `services.proxy.endpoint`                             | The public HTTPS origin of the CLI proxy, e.g. `https://cli-proxy.example.com`.                                      |
+| `services.monitoring.hubPort`                         | `8443`                                                                                                               |
+| `services.monitoring.publicUrl`                       | The public HTTPS origin of the monitoring dashboard.                                                                 |
+| `services.monitoring.managerAccount`                  | The email of the monitoring account the manager enrolls machines with.                                               |
+| `services.monitoring.viewerAccount`                   | The email of the read-only account visitors are signed in as.                                                        |
+| `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).                                                                                               |
 
 Use the same values in every place they repeat. Validate before going on:
 
@@ -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
@@ -352,7 +357,9 @@ Read `summary` and `remedy.action` of the failing check. The common ones:
 | `TAILSCALE_NODE_OFFLINE`                  | The worker is off or off the tailnet. It is listed and skipped; others continue.                                              |
 | `TAILSCALE_DEVICE_REPLACED`               | The tailnet device behind a worker changed. Nothing is written to it until the human confirms the replacement.                |
 | `SUDO_AUTHORIZATION_REQUIRED`             | The worker account cannot use sudo without a password. Run the first sync interactively.                                      |
-| `UBUNTU_BASELINE_MISMATCH`                | The worker is not Ubuntu 26.04.                                                                                               |
+| `UBUNTU_BASELINE_MISMATCH`                | The worker is not an Ubuntu release the [support matrix](support-matrix.md) lists.                                            |
+| `WORKER_ENVIRONMENT_UNSUPPORTED`          | The worker is WSL2 or a container. Use a physical or virtual machine of its own.                                              |
+| `PACKAGE_NEWER_THAN_PIN` (warning)        | Ubuntu's security updates moved a pinned package past its pin. It is kept; the pin is a minimum.                              |
 | `ROOT_DEVELOPMENT_USER_REJECTED`          | The worker's SSH user is root. Use a normal account with sudo.                                                                |
 | `BOOTSTRAP_DISK_CAPACITY_REQUIRED`        | Less than 2 GiB free (or too few inodes) where the fleet keeps its files on the worker.                                       |
 | `FLEET_REMOTE_LOCKED`                     | Another operation is running on that worker. Wait and run again.                                                              |