Linux

One static binary, CGO_ENABLED=0, so there is no C library to install and no distribution to match. A release archive and a PATH entry is the whole install; everything below that is about doing it deliberately.

The one-line install

curl -fsSL https://raw.githubusercontent.com/jmrplens/ghchronicle/main/install.sh | bash

It works out the architecture, takes the newest release, checks the archive against the checksum that release published, and puts the binary in /usr/local/bin when that is writable. When it is not, it takes the first of ~/.local/bin and ~/bin that exists and is already on your PATH, and falls back to ~/.local/bin when neither is. A checksum that does not match stops it without installing anything, and there is no flag to skip that step. When cosign 2.4.2 or newer is already on the machine it also verifies that the checksum file itself came from the release workflow, and a signature cosign does not confirm stops it, with what cosign said. An older cosign cannot read the signature bundle, so then, as with no cosign at all, it says that only the checksum was verified. It ends by running what it installed, so the version you see is the file it just wrote, and it says so when another ghchronicle earlier in your PATH still wins the name.

Pin a version, or choose where it goes:

curl -fsSL https://raw.githubusercontent.com/jmrplens/ghchronicle/main/install.sh | VERSION=2.6.5 BIN_DIR=~/bin bash

Reading it first is the whole point of a short script

Piping anything into a shell means running whatever that URL answers with today. curl -fsSL <url> -o install.sh, read it, then bash install.sh: it is the same script, and it is short enough to read.

The rest of this page is that same install done by hand, which is what to follow when you want to know exactly what landed where, or when you would rather not run a script you did not write.

Pick the archive

Release archives are named ghchronicle_<version>_linux_<arch>.tar.gz, with <arch> either amd64 or arm64. uname -m answers which.

uname -m reports	The archive to take
x86_64	linux_amd64
aarch64	linux_arm64

VERSION=2.6.5
arch=$(uname -m); case "$arch" in x86_64) arch=amd64 ;; aarch64) arch=arm64 ;; esac
base=https://github.com/jmrplens/ghchronicle/releases/download/v$VERSION
curl -fsSLO "$base/ghchronicle_${VERSION}_linux_${arch}.tar.gz"

Name the version rather than asking for the newest

The repository publishes a moving major tag beside the numbered releases, because the Action is listed on the Marketplace and that listing needs one. That tag’s release carries no files at all, so never build a download URL from the major tag: there is nothing behind it to download. Take the version from the releases page and write it down, as above.

Check what you downloaded

Two files are published beside the archives: checksums.txt, which holds the SHA-256 of every archive, and checksums.txt.sigstore.json, which is a signature over that file. So the chain is one signature and a digest: verify the file, then verify the archive against the file.

1. Take the checksum file and its signature.

   curl -fsSLO "$base/checksums.txt"
   curl -fsSLO "$base/checksums.txt.sigstore.json"

2. Check the archive against it. --ignore-missing is what lets one line of a twelve-line file be checked without the other eleven archives being present.

   sha256sum --ignore-missing -c checksums.txt

   ghchronicle_2.6.5_linux_amd64.tar.gz: OK

3. Check the checksum file itself, if you have cosign 2.4.2 or newer. An older one cannot read the bundle and fails whatever the file says.

   cosign verify-blob \
     --certificate-identity-regexp 'https://github.com/jmrplens/ghchronicle/.github/workflows/release.yml@refs/tags/.*' \
     --certificate-oidc-issuer https://token.actions.githubusercontent.com \
     --bundle checksums.txt.sigstore.json \
     checksums.txt

   Verified OK

The signing is keyless: there is no public key to fetch and no private key for anyone to lose, because the identity being verified is the workflow that ran, recorded in a public transparency log. That is what the two --certificate flags say, and why they are not optional: without them cosign would confirm that somebody signed the file, which is not the question.

Then let it write the configuration:

ghchronicle -setup

It asks for a token and where the numbers go, checks each answer against the thing it names, and writes a config.yaml and, if you want one, a systemd unit. The installer above offers to run it as its last step.

Put it on the PATH

The archive holds three files and no directory, so extract it somewhere you meant to.

• Directoryghchronicle_VERSION_linux_ARCH.tar.gz

  • ghchronicle the binary
  • LICENSE
  • README.md

For everyone

tar -xzf "ghchronicle_${VERSION}_linux_${arch}.tar.gz" ghchronicle
sudo install -m 755 ghchronicle /usr/local/bin/
ghchronicle -version

For one account

mkdir -p ~/.local/bin
tar -xzf "ghchronicle_${VERSION}_linux_${arch}.tar.gz" -C ~/.local/bin ghchronicle
chmod 755 ~/.local/bin/ghchronicle
ghchronicle -version

~/.local/bin is on the PATH of most distributions already. If ghchronicle -version answers “command not found”, it is not on yours.

-version answers with one line: the release number, then the commit and the build date of that release.

ghchronicle 2.6.5 (commit <commit>, built <date>)

Run it once

The binary needs a configuration file and a token, and the quickstart writes both in six steps. With those in place:

ghchronicle -config config.yaml -list   # what would be collected
ghchronicle -config config.yaml -once   # one sweep, then exit

Keep it running

systemd is the arrangement this documentation treats as the default on Linux, and the unit there is hardened rather than minimal, because this is very likely the only process on the host holding a GitHub token with read access to every repository of an account. A service started on a state file nothing has written yet brings its eleven families of six hours or more into the store over its first two and a half hours, one a sweep, and only that once; the systemd page says why.

A scheduler works too: cron with -once is a single line, at the cost of giving every family the same cadence.

Build it from source

Go 1.27.1 or newer is what the module declares. Nothing else is needed: the build sets CGO_ENABLED=0, so there is no compiler and no header package to find.

go install

go install github.com/jmrplens/ghchronicle/v2/cmd/ghchronicle@latest

Lands in $(go env GOPATH)/bin, which is ~/go/bin unless you moved it, and that directory has to be on your PATH.

A binary built this way has no commit or build date to report: those two are stamped by the release build and by nothing else, and a module downloaded through the proxy carries no checkout to read them from. -version names what the build does record instead, the module version the go command fetched and the Go release that compiled it:

ghchronicle 2.6.5 (module v2.6.5, built with <go version>)

The first version comes from the VERSION file the module embeds.

make

git clone https://github.com/jmrplens/ghchronicle
cd ghchronicle
make build      # into bin/ghchronicle
make install    # into GOBIN, stamped like a release build

make build stamps the version, the short commit and the commit date, so -version says exactly which tree it came from. make with no target lists every target there is.

Where the files go

The collector looks for a configuration file in no particular place: -config defaults to config.yaml relative to the working directory, and there is no search path behind it. So the path is a decision you make once and then pass on every invocation. What the rest of this documentation assumes:

File	Path	Mode
Configuration	/etc/ghchronicle/config.yaml	world readable, no secrets
Tokens	/etc/ghchronicle/ghchronicle.env	600
State, ledger, cache	/var/lib/ghchronicle/	written by the service user

state_file has a default of its own, ghchronicle-state.json in the working directory, with the write ledger beside it as ghchronicle-state-written.bin and the cache as ghchronicle-state-cache.bin. That default is fine for a first run in a directory you made, and wrong for a service, whose working directory is not something to rely on. Set it.