Skip to content

feat: a pullgate recipe in contrib/pullgate, to change the broker config from git - #204

Merged
groupsky merged 1 commit into
mainfrom
feat/102-pullgate-recipe
Nov 17, 2026
Merged

groupsky merged 1 commit into
mainfrom
feat/102-pullgate-recipe

Conversation

@groupsky

Copy link
Copy Markdown
Contributor

The broker host can now pull its config from a private git repo with pullgate. The owner taps Apply on Telegram for each commit, and a config that fails goes back to the last good one by itself. No SSH login to the broker host is needed for a config change.

What is in it

  • contrib/pullgate/:
    • nodkey-broker.toml: the pullgate instance config (mode = "ask", on_failure = "rollback", refuse_symlinks = true, max_files, max_tree_bytes).
    • check.sh (check user): both files are plain files, not symlinks; a commit may not change the path of known_hosts or audit_log (compared with the live config by nodkey broker config-diff); then nodkey broker check --files "$PULLGATE_TREE".
    • summary.sh (check user): nodkey broker config-diff --short --max-chars 2000 from the applied commit, or from the live config on the first apply. ⚠ needs a broker restart: all grants end comes first when a reload cannot take the change. A ⚠ line also shows when the live config is not the applied commit (a change by hand).
    • apply.sh (root): checks the files again with the credential names, installs both with the owner and mode of the live files, then nodkey broker reload or systemctl restart nodkey. On a failure it puts the old files back, reloads or restarts again, and exits 1.
    • health.sh (root): waits up to 60 s until the broker's own status file names the unit's main process, a result of started or loaded, and the SHA-256 of the live broker.toml.
    • lib.sh: the one rule for "reload or restart": a reload only when every line of the full config-diff is about a client, secret, project, SSH key (not a new key or key file) or a host key of known_hosts. Anything else, or a failed compare, is a restart.
  • The release packs these files as nodkey_VERSION_pullgate.tar.gz. It is in SHA256SUMS and covered by the attestation, as the binaries are (release.yml, docs/releasing.md).
  • CI runs shellcheck on the scripts.
  • docs/setup.md, section 10, "Change the config from git with pullgate": the repo layout, what stays a step on the host, the install steps (with the checks of the release file), and how to read the question.
  • THREAT-MODEL.md T52, DESIGN.md section 18, AGENTS.md.

Tests

contrib_pullgate_linux_test.go runs the scripts with /bin/sh and the environment that pullgate gives, against a fake broker: a fake systemctl and a fake nodkey broker reload that write the status file as the broker does, and the real nodkey (built from this tree) for the check and the diff.

  • TestPullgateCheck: a good commit; a missing file; a symlink; a config that is not valid; a moved audit_log; a moved known_hosts.
  • TestPullgateSummary: a reload-safe change (no restart line); a restart-type change (the restart line first); a new SSH key (restart); the first apply (against the live config); a hand edit.
  • TestPullgateApply: a reload-safe change (reload), a restart-type change (restart), a refused reload (old files back, reload again, exit 1), a failed restart (old files back, restart again, exit 1), a broker that does not run (restart). After each, health.sh must pass.
  • TestPullgateApplyRefusesBadFiles: nothing is installed for a config that is not valid, or a symlink.
  • TestPullgateHealth: a status file of another process, of another config, of a refused reload, and a broker that does not run: each fails after the timeout.

Reviews

A security review and a correctness review ran on the change. Fixed here:

  • A commit cannot change the gate. check.sh, and apply.sh again as root (also in a rollback), refuse a change of listen, tls_key, the paths of known_hosts and audit_log, [telegram], [ntfy], and a new or changed [store.*]. Else a commit could point the channel at its own server, or a token file at another credential, and approve its own requests. These stay steps on the host.
  • The summary can be cut by pullgate, which puts it after the commits and the changed files. So the summary uses --max-chars 1200, not 2000 as the issue says (HTML escaping makes it longer), max_files = 20, and the guide says: tap Skip when the summary is not complete. pullgate itself could put the summary first; that is a change for pullgate.
  • In a rollback, a failed reload does not put the failed files back; it tries a restart.
  • A new order of a list in [logins.*] means a restart (the reload compares it exactly).
  • A failure before the files move removes the stage and the copy; a copy left by a failed restore blocks the next apply until a person looks at it.
  • check.sh says early when the live known_hosts path is not the one the recipe needs.

Not changed: health.sh uses the wall clock (pullgate's apply_timeout still limits it), and its timeout is fixed at 60 s (pullgate gives an empty environment).

Fixes #102

🤖 Generated with Claude Code

…fig from git

The broker host pulls broker.toml and known_hosts from a private git
repo with pullgate. The owner taps Apply on each commit; a config that
fails goes back to the last good one. The release packs the recipe as
nodkey_VERSION_pullgate.tar.gz, in SHA256SUMS and the attestation.

Fixes #102

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@groupsky
groupsky merged commit 22f8965 into main Nov 17, 2026
22 of 25 checks passed
@groupsky
groupsky deleted the feat/102-pullgate-recipe branch November 17, 2026 12:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Change the broker config from git without SSH: a pullgate recipe in contrib/

1 participant