Skip to content
code6xPublic

About

Pull a git repo, ask one person on Telegram to apply one exact commit, then apply it. Small Go tool for plain Linux hosts.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

pullgate

pullgate lets a Linux host change only through its own updates. The host pulls a git repo by itself. It applies a new commit only after its owner taps Apply on a Telegram question that names that exact commit. Then root applies it, with a health check and a rollback or a hold.

  • The gate lives on the host. What runs, who may approve and which paths get a warning come from /etc/pullgate, never from the repo. A commit cannot change the gate.
  • One exact commit. The question shows a short SHA at the top and the full SHA once, on its last line. Apply applies only that full SHA, even when a newer commit arrives in between.
  • No code from the new commit runs before Apply. Optional check and summary commands read the commit as data, as an unprivileged user.
  • Only the listener holds the bot token. It runs as its own user and opens no port.
  • Forward only by default. A force push or an older commit is refused.
  • Root never runs git in a directory another user can write.

It is a small Go program for plain Linux with systemd. It needs git and ssh. No server, no web UI.

Read DESIGN.md for how it works and THREAT-MODEL.md for what it protects and where it stops.

How it works

timer ──> pullgate run NAME (root)
            fetch ─> read the commit ─> check, summary (check_user)
            ─> question into the outbox
                     │
pullgate listen (own user, holds the token) ─> Telegram ─> owner taps Apply
                     │
            approval (only a one-time code) into the inbox
                     │
path unit ─> pullgate apply NAME (root)
            looks the code up in its own state ─> apply ─> health
            ─> success: report; failure: rollback or hold, and report

Install

pullgate runs on Linux, on amd64 or arm64. There are three ways to get the binary.

With the install script (as root, on the host itself). Download the script, read it, then run it:

curl --proto '=https' --tlsv1.2 -fsSL -o /root/install.sh https://raw.githubusercontent.com/code6x/pullgate/main/install.sh
less /root/install.sh
sh /root/install.sh [--version X.Y.Z] [--bin-dir DIR] [--gh PATH] [--reinstall]

It installs the newest release, or the one of --version, as /usr/local/bin/pullgate (or DIR/pullgate). It installs nothing unless every check passes: the SHA-256 in SHA256SUMS, the build attestation of the release (with gh attestation verify), and the version that the new binary prints. It needs curl, tar, gzip, sed and GNU coreutils. Without --gh, it downloads a pinned gh and checks its SHA-256. It replaces the old binary only in the last step, and restarts nothing: it prints what to restart. Run it again to update. --reinstall installs the same version again, or replaces a build of unknown version. Exit codes: 0 done or nothing to do, 1 failure (nothing was installed), 64 wrong usage. To get the script of one release, put its tag (vX.Y.Z) in the URL instead of main. To start it with a clean environment, run it as env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin sh /root/install.sh. What it does and what it trusts: DESIGN.md section 16 and THREAT-MODEL.md T17.

By hand. Download a release and check it as docs/releasing.md says (section "Verify a download"). Then, as root:

install -m 0755 pullgate /usr/local/bin/pullgate

From the source, with Go 1.26 or newer. Then install it as above:

CGO_ENABLED=0 go build -trimpath -o pullgate ./cmd/pullgate

Then, as root, make the users and the directories, and copy the units from contrib/systemd/:

useradd --system --no-create-home --shell /usr/sbin/nologin pullgate
# One check user per instance, never the listener user:
useradd --system --no-create-home --shell /usr/sbin/nologin pullgate-check-config-repo
install -d -m 0755 /etc/pullgate /var/spool/pullgate
install -d -m 0711 /var/lib/pullgate
cp contrib/systemd/* /etc/systemd/system/
  1. Make a Telegram bot with BotFather. Put its token in /etc/pullgate/bot-token (owner root, mode 0600).
  2. Find your Telegram user ID and the chat ID of your private chat with the bot. Write /etc/pullgate/listener.toml from contrib/examples/listener.toml.
  3. Make a read-only deploy key for the repo: ssh-keygen -t ed25519 -N '' -f /etc/pullgate/NAME.key. Add the public key to the repo as a read-only deploy key.
  4. Pin the host key of the git server in /etc/pullgate/NAME.known_hosts. Check the fingerprint against the one your git host publishes.
  5. Write /etc/pullgate/NAME.toml (owner root, mode 0600). Start from one of the examples below.
  6. Start it:
systemctl daemon-reload
systemctl enable --now pullgate-listen.service
systemctl enable --now pullgate-apply@NAME.path pullgate-run@NAME.timer
systemctl enable --now pullgate-check@NAME.path   # optional: /check

Every step logs to the journal: journalctl -t pullgate.

To see the version of a binary, run pullgate --version or pullgate version. Both print pullgate X.Y.Z and exit 0. A build from the source without -ldflags "-X main.version=..." prints pullgate dev.

Commands: /help

Send the bot /help to get the list of commands, the instances of this listener, what Apply and Skip do, and the pullgate status commands for the host. Any other text from you (not a command) gets one short reply: "Not a command. Send /help for the list.", at most once a minute. Messages from other users, or in other chats, get no answer.

Check now: /check

The timer runs every 5 minutes. After a push you do not have to wait: send the bot /check (all instances) or /check NAME (one instance). The listener answers "Checking NAME…" and writes a check request. pullgate-check@NAME.path then starts the normal run at once. You get the usual Apply question, or "No new commit (the applied commit is …)", or "NAME is paused" / "NAME is off" (then nothing is fetched).

  • Only your user ID in your chat counts. The text must be exactly /check or /check NAME. Other messages get no request. Edited messages do not count.
  • /check never applies anything in ask mode: it only fetches and asks. In auto mode, /check applies a new commit at once, without a tap, as the timer would a few minutes later.
  • Root allows at most one run per minute from /check. More requests in that minute are dropped, with one reply. The listener also takes at most one /check per instance in 10 seconds.
  • pullgate-check@NAME.path stops after 10 starts in a minute. Then /check waits for the timer until you run systemctl reset-failed pullgate-check@NAME.path and systemctl start pullgate-check@NAME.path.
  • Without pullgate-check@NAME.path, the request waits for the next timer run.

Config

The instance config /etc/pullgate/NAME.toml:

mode = "ask"              # "ask" (default), "auto" (no question; for development hosts) or "off"
on_failure = "rollback"   # "rollback" or "pause"; the default is "pause"
host = "example-host"     # shown in each message

[repo]
url = "ssh://git@git.example.com/owner/config-repo.git"
branch = "main"
deploy_key = "/etc/pullgate/NAME.key"
known_hosts = "/etc/pullgate/NAME.known_hosts"

[commands]
check = ["/path/to/check"]       # optional; runs as check_user; a failure means no question
summary = ["/path/to/summary"]   # optional; runs as check_user; its output is in the question
apply = ["/path/to/apply"]       # required; runs as root after Apply
health = ["/path/to/health"]     # optional; runs as root after apply
check_user = "pullgate-check"

[watch]
paths = ["policy/**", "*.toml"]  # a warning for each changed path that matches

[limits]
questions_per_day = 10
approval_ttl = "12h"
max_failed_tries = 1
allow_older = false

The commands get these environment variables: PULLGATE_SHA, PULLGATE_OLD_SHA, PULLGATE_TREE (a clean, read-only copy of the commit), PULLGATE_OLD_TREE (the same for the applied commit), PULLGATE_CHANGED_FILES (a file with the changed paths, each ended by a NUL byte), PULLGATE_FAILED_SHA, PULLGATE_ROLLBACK and PULLGATE_INSTANCE. The full list of keys and what they do is in DESIGN.md, sections 5 and 11.

What happens when an apply fails is your choice per instance:

  • on_failure = "rollback": pullgate runs apply again with the last good commit, then health. So apply must be safe to run again on an older tree. If the rollback fails too, the instance is paused.
  • on_failure = "pause": no rollback. The failed commit is held and not tried again. A newer commit is still asked, with a warning at the top, so you can fix it forward.

pullgate status NAME shows the state. As root: pullgate status NAME --pause stops the instance, pullgate status NAME --resume starts it again, and pullgate status NAME --ask-again asks about the tip again. If a question for the tip is still open (for example its Telegram message was lost), it closes that question too: the next run sends a new question, and the Apply button of the old one no longer works.

Example 1: a config file and a service reload

A service reads one policy file from a private repo. pullgate checks the file, shows a diff of it in the question, copies it into place and reloads the service. A failed health check rolls back to the last good file.

Files: contrib/examples/config-file/

  • config-repo.toml: on_failure = "rollback", a watch on policy.toml.
  • check.sh: the file must exist, be small and be plain text.
  • summary.sh: diff -u of the old and the new tree.
  • apply.sh: install the file and systemctl reload.
  • health.sh: systemctl is-active.

Example 2: ansible-playbook on the tree

A server runs ansible-playbook locally on the approved commit. Running an older playbook again can do more harm than good, so this example holds a failed commit instead of rolling back.

Files: contrib/examples/ansible/

  • playbooks.toml: on_failure = "pause", watches on ansible.cfg, site.yml and sudoers files.
  • apply.sh: ansible-playbook --connection local site.yml in the tree.

There is no check here: ansible-playbook --syntax-check loads ansible.cfg and plugins from the tree, and that is code from the commit before Apply.

The systemd units

contrib/systemd/ has the units. Their systemd-analyze security scores (systemd 255, 2026-11-11; lower is better):

unit score why
pullgate-listen.service 1.2 OK own user, no capabilities, read-only system
pullgate-run@.service 2.4 OK root, but only the capabilities it needs to run check as check_user, to stop it on a timeout, and to fix the spool; read-only system
pullgate-apply@.service 7.9 EXPOSED it runs your apply command as root, which must change the system. Add a drop-in for what your apply needs (systemctl edit pullgate-apply@NAME.service)

The run unit sets MemoryDenyWriteExecute=yes, which also holds for check and summary. A command that needs a JIT (for example Node.js) does not work there.

Update from 0.1.0

To update a host from 0.1.0: update the binary, and copy the units of contrib/systemd/ of the new version to /etc/systemd/system/ again. The copy replaces the unit files, so keep your own changes in drop-ins (systemctl edit UNIT); systemctl cat UNIT shows them. Then do the two steps below.

The run unit (issue #19). In 0.1.0 the first pullgate run failed under pullgate-run@.service with chmod .../outbox: operation not permitted. A host may have a drop-in with RestrictSUIDSGID=no for the run unit. Newer versions do not need it.

  1. Find the drop-in: systemctl cat pullgate-run@NAME.service shows each file and its path. It is in /etc/systemd/system/pullgate-run@.service.d/ or in /etc/systemd/system/pullgate-run@NAME.service.d/.
  2. Remove the line RestrictSUIDSGID=no, or the whole file when that is all it holds.
  3. Run systemctl daemon-reload.

The next run takes the setgid bit off the outbox by itself.

The listener at boot (issue #20). In 0.1.0, pullgate-listen.service had no [Install] section, so systemctl enable did nothing and the listener did not start after a reboot. Every host updated from 0.1.0 must enable it again. A host may have the workaround systemctl add-wants multi-user.target pullgate-listen.service. That made the same link that systemctl enable makes now (/etc/systemd/system/multi-user.target.wants/pullgate-listen.service), so there is nothing to remove first (systemd has no remove-wants). With or without the workaround, run:

systemctl daemon-reload
systemctl reenable pullgate-listen.service
ls -l /etc/systemd/system/multi-user.target.wants/pullgate-listen.service

reenable removes the old link, if there is one, and makes it again from the new [Install] section. The ls shows the link.

Development

go test -race ./...
go vet ./...
golangci-lint run --build-tags e2e
go test -race -tags e2e ./test/e2e/...

CI runs the install commands of this README as written: each install block above has an <!-- install-test:… --> comment before it, and test/units/full-loop.sh runs those blocks as root, then a full loop under the units. Keep that comment when you change a block.

The rules for changes are in AGENTS.md.

License

Apache-2.0. See LICENSE.

About

Pull a git repo, ask one person on Telegram to apply one exact commit, then apply it. Small Go tool for plain Linux hosts.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages