Open source: Upgrade and uninstall

Open source

Upgrade and uninstall

Check for a newer release, upgrade the agent in place with signature verification, and remove HookCI from a host completely.

Check for a new release

hookci upgrade --check compares the installed version with the latest release and changes nothing. It needs no root.

build-host
build-host recording
$ hookci upgrade --check
current: v0.4.0
latest:  v0.5.0
$ echo $?
10

Illustration. Exit code 10 means a newer release exists.

The exit code is built for scripts and monitoring: 0 means you are current, 10 means an upgrade is available, and 4 means the check itself failed, for example because the network was unreachable. The versions above are illustrative.

hookci upgrade --check; [ $? -eq 10 ] && echo "hookci upgrade available"

hookci --version prints the installed version on its own. Upgrades are only supported on Linux.

Upgrade

Run the upgrade as root, since it replaces the binary:

build-host
build-host recording
$ sudo hookci upgrade
upgraded v0.4.0 -> v0.5.0
$ hookci --version
v0.5.0

Illustration. The binary is verified before it replaces the old one.

What it does, in order:

  1. Downloads SHA256SUMS and its sigstore bundle from the release and verifies the signature against the pinned release identity, using the trusted root at /var/lib/hookci/trusted_root.json. If that file does not exist, the root embedded in the binary is used.
  2. Downloads the archive for your architecture and checks its digest against the signed SHA256SUMS.
  3. Writes the new binary next to the old one, syncs it, and renames it into place, so the path never holds a half-written file.
  4. Runs systemctl try-restart on every running hookci-agent@ unit so they pick up the new binary.

A failure at any step exits with code 4 and leaves the old binary untouched. Downloads are capped at 256 MiB for the archive and 1 MiB for the small files.

Pin or move between versions

sudo hookci upgrade --version v0.5.0

--version installs that exact release instead of the latest. Installing an older release than the current one is refused with refusing downgrade without --allow-downgrade. If you really mean it, say so:

sudo hookci upgrade --version v0.4.0 --allow-downgrade

The installer can also lay down a specific version on a fresh host: see Install the agent.

Refresh the trust root

Signatures are checked against a sigstore trusted root. A copy ships inside the binary, and releases carry a current trusted_root.json. If sigstore rotates its keys and an old binary can no longer verify new releases, refresh the root first:

sudo hookci upgrade --refresh-trust-root

It downloads trusted_root.json from the release, checks it against the signed SHA256SUMS, verifies it and writes it to /var/lib/hookci/trusted_root.json. It prints trusted root updated from <version> and does not upgrade the binary. Run a normal sudo hookci upgrade afterwards.

A hub that refuses an agent version as too old makes the agent exit with code 4, and the fix is the same upgrade. See The agent service.

Uninstall

HookCI has no uninstall command. Removing it is a short list, because the installer only wrote a few files. Replace 48213907 with your installation ID. If the host has several agents, repeat step 1 for each. systemctl list-units 'hookci-agent@*' lists them.

  1. Stop and disable the agent:

    sudo systemctl disable --now hookci-agent@48213907

  2. Remove the unit files:

    sudo rm /etc/systemd/system/hookci-agent@.service /etc/systemd/system/hookci.slice

  3. Reload systemd:

    sudo systemctl daemon-reload

  4. Remove the binary:

    sudo rm /usr/local/bin/hookci

  5. Remove the state directory. This deletes the agent credential, run history, logs and caches, and the trusted root if you refreshed it:

    sudo rm -rf /var/lib/hookci

  6. Remove the job user:

    sudo userdel hookci-run

If you installed with HOOKCI_PREFIX, the binary is at $HOOKCI_PREFIX/bin/hookci instead. If you installed from a .deb or .rpm package, remove it with your package manager instead of step 4 and the unit files in step 2.

Remove the hub side

Uninstalling on the host does not tell the hub. Do these as well so nothing is left behind:

  • In Slack, open the HookCI App Home and revoke the agent, so its credential stops working even if a copy of agent.json survives somewhere.
  • To stop HookCI from seeing your repositories at all, uninstall the GitHub App from your GitHub account or organization settings.

Hub data for an uninstalled installation is purged within 30 days. What is stored and for how long is in Security and data. If you run your own hub, the data is in your Cloudflare account: see Operations.