v0.1: pull a repo, ask the owner on Telegram, apply one exact commit #1

Why

A host should change only through its own updates. It pulls a git repo
by itself, and it applies a new commit only after its owner taps
Apply on a Telegram question that names that exact commit.

No existing tool does this on plain Linux (checked 2026-11-11):

• ansible-pull has no approval step and no hook.
• comin has a "manual" confirm, but it runs only on NixOS.
• Komodo, AWX, Semaphore and Rudder need a central server. Some cannot pin
  one commit.
• omen-cd keeps its gate in the repo, so a commit can remove the gate.

Two first users:

• a secrets broker that applies its policy file from a private repo, and
  then reloads;
• servers that run ansible-playbook locally on the approved commit.

Rules

1. The gate lives on the host, never in the repo. What runs, who may
   approve, and which paths get a warning: all of it comes from the host
   config (/etc/pullgate/NAME.toml). A commit cannot change the gate.
2. One exact commit. The question shows the full SHA. The apply step
   applies only that SHA, even when a newer commit arrives in between.
3. No code from the new commit runs before Apply. Before the tap,
   pullgate only fetches the commit and reads it with git (log, diff,
   files). The check and summary commands from the host config may
   read the commit's files as data (for example, they parse a config
   file). They run as an unprivileged, sandboxed user on a read-only copy
   of the tree, never as root.
4. Only one process holds the bot token and talks to Telegram: the
   listener. It runs as its own unprivileged user, and it connects
   outbound only (getUpdates long-poll, no inbound port). The run and
   the apply give their messages to the listener through a spool
   directory. It accepts a tap only from the configured owner user ID, in
   the configured chat, on an open question. All it can do is write an
   approval for that open question. The approval carries only the
   one-time code; root looks up the SHA in its own state.
5. Root does the apply. It acts only on an approval that matches the
   open question it recorded itself, and only within the approval's time
   limit. By default it moves forward only (the new SHA must descend from
   the applied SHA). A rollback to an older commit is a separate,
   explicit setting.
6. Root never runs git in a directory another user can write. A
   .git/config that someone else can write is code execution as root
   (core.fsmonitor, hooks, and others). So pullgate run runs as root
   and owns the clone. git runs with hooks off and without system or
   global config. The tree is exported by SHA with no filters, no
   submodules and no LFS.

What one run does

1. A timer starts the run. A lock allows one run per instance. If a pause
   file exists, the run logs "paused" and exits.
2. Fetch the branch with a read-only deploy key and a pinned SSH host
   key.
3. If the branch tip is the applied SHA, or a SHA that was already asked,
   skipped or failed its check, stop. An unanswered question that expired
   is not asked again; a new commit, or pullgate status --ask-again,
   asks again.
   At most one question is open per instance. When the tip moves while a
   question is open, the run closes the old question (it edits it to say
   so) and asks about the new tip. A tap that arrives before the close
   still applies the old SHA (rule 2).
   On the first run there is no applied SHA. The question says so and
   lists every file. The forward-only rule starts after the first apply.
4. Build the summary:
   • the commit subjects since the applied SHA;
   • the changed files;
   • a clear warning for each changed path that matches the host's
     watch list;
   • the output of an optional summary command from the host config
     (for example, a semantic diff of a config file).
     It must fit one Telegram message. If it is longer, cut it and say how
     much was left out.
5. Run the optional check command (rule 3). If the check fails, send a
   notice and do not ask. check and summary get the same env
   variables as apply (step 7), with PULLGATE_TREE read-only.
6. Ask: host name, instance, full SHA, summary, and two buttons, Apply and
   Skip. The buttons carry a random one-time code (it fits Telegram's
   64-byte callback_data), not the SHA. A second tap does nothing.
7. After Apply, root runs the apply command with these env variables:
   PULLGATE_SHA, PULLGATE_OLD_SHA, PULLGATE_TREE (a clean copy of
   that commit) and PULLGATE_CHANGED_FILES. Then it runs the optional
   health command. If apply or health fails, it runs apply again with the
   last good SHA and reports. So apply must be safe to run again on an
   older tree. If that rollback fails too, the instance writes its pause
   file and reports. State moves forward only after success.
8. Report the result in the same chat (edit the question, or send a
   reply). Log each step to journald (SYSLOG_IDENTIFIER=pullgate).

Modes

• ask: the default.
• auto: no question. For development hosts.
• off.

Several instances can run on one host. Each has its own config, state and
lock. They may share one bot; then one listener serves them all (two
getUpdates loops on one token conflict).

Limits

These limits are in the host config, with safe defaults:

• the most questions per day;
• how long an approval stays valid;
• the most failed tries per SHA, after which that SHA waits for a new
  commit.

Done when

• DESIGN.md and THREAT-MODEL.md cover the rules above. The threat
  model covers at least:
  - a stolen bot token;
  - a compromised listener;
  - a hostile commit (its content, file names, symlinks, large
  trees, .gitattributes filters, submodules);
  - an approved apply that changes the gate itself (the host config,
  the units or the binary), and a rollback after such an apply;
  - a rollback that fails;
  - a force-push or a rewritten branch;
  - an old commit offered again;
  - a lost or stale approval;
  - a crash between apply and the state write;
  - a wrong clock.
• The commands exist: pullgate run (the timer step), pullgate listen (the bot), pullgate apply (root, started by a path unit
  when an approval appears), and pullgate status.
• Example systemd units with hardening (systemd-analyze security
  score in the docs), and an example config for each of the two first
  users: a config file followed by a service reload, and
  ansible-playbook on the tree.
• Tests for every rule:
  - a tap from another user or chat is ignored;
  - a tap on an old or closed question is ignored;
  - an expired approval is ignored;
  - root takes the SHA from its own state, never from the approval;
  - a newer commit after the question does not change what is applied;
  - an older SHA is refused;
  - a failing check sends no question, and the same SHA is not
  checked again on the next run;
  - check and summary run without root;
  - root refuses to run git in a directory another user can write;
  - a failing apply or health check rolls back and reports;
  - a failing rollback pauses the instance;
  - the pause file, the lock, the limits and the auto mode work;
  - the summary is cut to fit one message;
  - the watch warnings appear.
  The tests use a fake Telegram server and a local git remote.
• An end-to-end test in CI: a local bare repo, two commits, an
  approval, then the second commit applied.
• A release with a static Linux amd64/arm64 binary and checksums.
• README: what it is, install, config, the two examples. It contains
  no hosts, IPs or names from any real deployment.
• It gets a security review before the first release, as nodkey does.

Not in this issue

• Self-update of pullgate.
• Signed commits (git verify-commit): an option for later.
• Any web UI.