Skip to content

feat: install.sh that installs or updates pullgate from a checked release #7

Open

Description

@groupsky

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 starts main, so a download cut in the middle of curl … | sh runs 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 fixed PATH.
  • Check that only root can change the bin directory, the old binary, the temporary directory and the gh given 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 verify with the release's pullgate_<version>.sigstore.json bundle, --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 version prints the version asked for (the attestation proves the workflow, not the version).
  • When --gh is not given, download a pinned gh release 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-listen service and timers, see contrib/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.Z for --version; the tag is v<version>. Check that the tag of the chosen release matches.
  • SHA256SUMS must have exactly one line for the tarball.
  • The target DIR/pullgate must be a regular file or missing: refuse a symlink or anything else.
  • Make the temporary directory with mktemp -d and check who owns it and its parent (TMPDIR).
  • Run pullgate version on 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 --version asks 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.sh in the repository root does every point above; shellcheck passes on it in CI.
  • Tests run in CI against a fake release (a local HTTPS or file server with tarballs, SHA256SUMS and 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; SHA256SUMS has 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.md has an entry for the install path (what the script trusts: GitHub, the release workflow identity, the pinned gh), 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

  1. groupsky commented on Nov 12, 2026

    @groupsky
    ContributorAuthor

    install.sh is in main (#10, dd7638d). Evidence for the ticked boxes:

    • install.sh in the root does every point; CI runs ShellCheck v0.11.0 on it (job lint).
    • Tests in install_linux_test.go against 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).
    • THREAT-MODEL.md T17 (what the script trusts: GitHub, the release workflow identity, the pinned gh); DESIGN.md section 16.
    • README "Install": download, read, run; the manual check stays as the other way.
    • Security reviewer and a correctness review on feat: install.sh that installs or updates pullgate from a checked release #10; findings fixed or listed in the PR.

    Only the last box is left: a real run against the first release. The release waits for the owner's OK (release PR #11).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions