Ways to install

One static binary with no runtime dependencies. How it gets onto the machine is the only decision, and it follows from where you want it to run.

Your system, from download to service

Releases carry binaries for Linux, macOS and Windows, on amd64 and arm64. The three pages below are the same walk for each system, taken all the way: which archive, how to check it, where the binary goes, how to run it once, and how to keep it running once you are done watching it.

LinuxA tar.gz, /usr/local/bin, and a hardened systemd unit.

macOSThe darwin archive, the quarantine attribute, and a launchd agent or daemon.

WindowsA zip, PowerShell and cmd, a scheduled task, and what is genuinely different there.

Getting the binary

Script

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

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/jmrplens/ghchronicle/main/install.ps1 | iex

Either one works out the platform, takes the newest release, and refuses to install anything whose checksum is not the one the release published.

Release

Take the archive for your platform from the releases page. Archives are built for Linux, macOS and Windows, on amd64 and arm64, and ship as tar.gz (zip on Windows).

tar -xzf ghchronicle_2.6.5_linux_amd64.tar.gz
sudo install -m 755 ghchronicle /usr/local/bin/

Go

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

Needs a Go toolchain, and builds from source at whatever the newest tag is. The /v2 is part of the path: without it Go settles on 1.0.0, the last release whose module path it accepts, and says nothing.

Container

docker run -v $PWD/config.yaml:/config.yaml:ro \
  -v ghchronicle-state:/var/lib/ghchronicle -e GITHUB_TOKEN \
  ghcr.io/jmrplens/ghchronicle -config /config.yaml

Distroless, static, and running as uid 65532. With state_file under /var/lib/ghchronicle the volume keeps the state, and it belongs to that user from the start, since the image’s own directory does: what has to be writable.

Action

- uses: jmrplens/ghchronicle@v2
  with:
    token: ${{ secrets.GHCHRONICLE_TOKEN }}
    mode: once
    config: .github/ghchronicle.yaml

A composite Action that downloads a release binary, so the runner needs no Go toolchain.

Choosing where it runs

The collector pushes to every store it supports, so it does not need to be reachable from anywhere. It needs to reach GitHub and to reach its databases. That is the only constraint, and it is what makes all four of these viable. Three of the four want a host you own: systemd, Docker and cron. GitHub Actions is the one that does not. The system pages above are where the scheduler lives, one per system: systemd or cron on Linux, launchd on macOS, a scheduled task on Windows.

systemdA long-running service on a host you own. The default choice: the state file persists, the schedule is the tool's own, and the unit can be locked down hard.

DockerThe same thing in a container. Mount a writable volume for the state file and any file sink.

GitHub ActionsNo host at all. Good for the card and for a scheduled sweep; the state file does not survive between runs unless you cache it.

cron`-once` runs a single sweep and exits, which is all a scheduler needs. Keep the state file on a persistent path.

The three run modes

Command	Does
ghchronicle -config config.yaml	Runs forever, each family on its own cadence
ghchronicle -config config.yaml -once	One sweep, then exits
ghchronicle -config config.yaml -backfill	Walks every surface to its end, waiting for the rate limit

Plus two that write nothing: -list prints the repositories in scope, and -card ... -card-only renders the SVG without touching a database.

The state file is the one thing that must persist

Whichever way it runs, keep state_file on a path that survives a restart, in a directory the collector can write, since the cache file and the write ledger live beside it. Without it every run collects every family whatever its cadence says, and walks the stargazer list, the whole star history and the co-authored pull requests again.

Upgrading

A new release goes over the old one the way the old one was installed, and the configuration and the state carry over. What the first hours after it look like, from 2.5.x to 2.6.x and to 2.6.1, is on upgrading.