Repository navigation
Open
Labels
Description
Today a host gets pullgate by hand: download the tarball, check SHA256SUMS, run gh attestation verify (README, "Install"). That is easy to get wrong, and every host needs it. Add an install.sh in the repository root, like the one in code6x/nodkey, adapted to pullgate. Copy its design and its checks; the code is the model, the docs of this repo must still stand alone (#6).
Use:
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]What it must do (as nodkey's script does)
- POSIX
sh,set -eu. All work in functions; only the last line startsmain, so a download cut in the middle ofcurl … | shruns nothing. - Run as root on the host itself. Clean the environment first (
TAR_OPTIONS,GZIP,CURL_HOME,SSL_CERT_*,OPENSSL_*,LD_*,GCONV_PATH,CDPATH,IFS, …),LC_ALL=C, and as root a fixedPATH. - Check that only root can change the bin directory, the old binary, the temporary directory and the
ghgiven with--gh. - Linux amd64 and arm64 only; a clear error on anything else.
- Pick the newest release, or
--version. Size limits on every download.curl -q --proto '=https' --tlsv1.2. - Install nothing unless every check passes:
- the SHA-256 of the tarball is the one in the release's
SHA256SUMS; gh attestation verifywith the release'spullgate_<version>.sigstore.jsonbundle,--repo code6x/pullgate,--cert-identity https://github.com/code6x/pullgate/.github/workflows/release.yml@refs/heads/main,--deny-self-hosted-runners;- the new binary's
pullgate versionprints the version asked for (the attestation proves the workflow, not the version).
- the SHA-256 of the tarball is the one in the release's
- When
--ghis not given, download a pinnedghrelease and check it against a pinned SHA-256 per CPU (as nodkey does; a minimum version for--gh). - Replace the old binary only in the last step, with an atomic rename in the same directory. Clean up the temporary files on every exit.
- "Nothing to do" (exit 0) when the version is installed already, unless
--reinstall. - Restart nothing; print what to restart (the
pullgate-listenservice and timers, seecontrib/systemd/). - Exit codes: 0 done or nothing to do, 1 failure, 64 wrong usage. The last line of a failure says that nothing was installed.
Also, as in nodkey's script:
- Accept only
X.Y.Zfor--version; the tag isv<version>. Check that the tag of the chosen release matches. SHA256SUMSmust have exactly one line for the tarball.- The target
DIR/pullgatemust be a regular file or missing: refuse a symlink or anything else. - Make the temporary directory with
mktemp -dand check who owns it and its parent (TMPDIR). - Run
pullgate versionon the new binary from the temporary directory before the rename. - An installed binary with an unknown version (
dev, or no output): say so, and install only with--reinstall. - An older version than the installed one: install only when
--versionasks for it, and say that it is a downgrade.
Out of scope: a pullgate update command that runs a built-in copy of the script (nodkey has one). File it separately if wanted.
Done when
-
install.shin the repository root does every point above;shellcheckpasses on it in CI. - Tests run in CI against a fake release (a local HTTPS or file server with tarballs,
SHA256SUMSand a bundle), and show that it installs nothing when: the SHA-256 is wrong; the attestation fails; the binary reports another version; the bin directory is writable by a non-root user; the target is a symlink;SHA256SUMShas no or two lines for the tarball; the installed version is unknown (without--reinstall); the platform is not supported. And that it installs when all checks pass, and does nothing on the same version. -
THREAT-MODEL.mdhas an entry for the install path (what the script trusts: GitHub, the release workflow identity, the pinnedgh), and DESIGN.md or the README describes the script. - README "Install" shows the download, read, run steps above, and the manual check stays as the other way.
- After the first release exists: a real run on a test machine (or a CI job) installs that release and prints its version. Paste the output in a comment.
- Security review subagent run on the PR, findings fixed.
Activity
groupsky commentedon Nov 12, 2026
install.shis inmain(#10,dd7638d). Evidence for the ticked boxes:install.shin the root does every point; CI runs ShellCheck v0.11.0 on it (joblint).install_linux_test.goagainst a fake release:TestInstallDenies/wrong_sha256,/attestation_fails,/binary_reports_another_version,/bin_directory_writable_by_others,/target_is_a_symlink,/SHA256SUMS_has_no_line_for_the_tarball,/SHA256SUMS_has_two_lines_for_the_tarball,/installed_version_unknown,/platform_not_supported;TestInstall(all checks pass, it installs);TestInstallNothingToDo(same version);TestInstallUsage(exit 64).Only the last box is left: a real run against the first release. The release waits for the owner's OK (release PR #11).