Getting started

Install the tools#

Each tool is a single static Go binary (the plugins add a small adapter). Install what you need — they compose, but each works on its own.

zegit (zg)#

Binaries ship as GitHub Releases on the public, releases-only repository zegit-zoo/zg (the source stays private). Download the archive for your platform — zegit_<version>_{linux,darwin}_{amd64,arm64}.tar.gz, containing zg, z-backend and z-gateway — verify it, and put zg on your PATH. Every release's checksums file is signed once by the Control Plane's artifact key:

curl -fsSO https://zegit.io/signing/artifact-key
cosign verify-blob --key artifact-key --insecure-ignore-tlog \
  --signature zegit_<v>_checksums.txt.sig zegit_<v>_checksums.txt
sha256sum -c zegit_<v>_checksums.txt --ignore-missing

zg version
export ZEGIT_CP_URL=https://zegit.io   # omit for local IAM mode

From then on zg update fetches the latest release and runs the same verification before it installs anything (zg update --check only reports). The --insecure-ignore-tlog flag is required because a key-based signature is not logged in Rekor.

meerkat (mk)#

The repo is public and Apache-2.0, so this works anonymously — no login or token required:

PLATFORM=darwin_arm64          # darwin_amd64 / linux_amd64 / linux_arm64
mkdir -p ~/.local/bin
gh release download --repo zegit-zoo/meerkat \
  -p "meerkat_*_${PLATFORM}.tar.gz" --output - \
  | tar -xz -C ~/.local/bin meerkat
ln -sf meerkat ~/.local/bin/mk
meerkat version

No tag is pinned — gh release download with no tag argument fetches the latest release. If you hit the anonymous API rate limit, gh auth login raises it.

mongoose#

mongoose has no tagged release yet — build from the source repository and export a provider key:

export ANTHROPIC_API_KEY=sk-ant-...
go build -o mongoose ./cmd/mongoose
./mongoose run "list the Go files here and summarise each"

Your first governed push#

This is the core loop: validate locally, which signs an Attestation of Validation (AoV) for the exact commit, then push — the gateway verifies the signed evidence instead of re-running CI.

1. Authenticate

   A passkey ceremony issues a short-lived signing certificate. In Control-Plane mode the login also fetches a gateway SSH certificate and pins the gateway host key under ZEGIT_HOME/ssh/known_hosts. Headless? ZEGIT_NO_BROWSER=1 prints the URL instead of opening a browser.

   terminalbash

   Copy

   zg auth login
   zg auth status        # identity, role, expiry

2. Initialize the repo

   Writes .zegit/config.yaml, a ZEGITFILE, and a pre-push hook, and wires the clone to the gateway (a gateway remote plus core.sshCommand = zg ssh, both in the clone's own .git/config). Working alone? zg init --solo writes a ZEGITFILE in which your own attestation counts as the one approval.

   terminalbash

   Copy

   cd my-repo
   zg init

3. Validate

   Runs your pipeline, evaluates policy, and unless blocked signs an AoV into refs/zegit/aov/<commit>. The first run in a repository prints a NOTICE: the pipeline's shell steps run with your privileges, so only validate repositories you trust.

   terminalbash

   Copy

   git add -A && git commit -m "feature"
   zg validate

4. Push

   The pre-push hook pushes the AoV ref alongside your branch; the gateway accepts or rejects. zg push does the same with before/after verification of the remote ref, and refuses up front (exit 7) when the tip has no AoV.

   terminalbash

   Copy

   git push gateway main      # or: zg push gateway main

Your first governed release#

Releases go through a Tag Request — a quorum gate. The creator's own approval never counts toward quorum (unless the repo opts into AoV self-approval), so you need a second authorized identity. Before the first tag, the repository also needs an activated release policy: the gateway refuses tag pushes on a repository whose policy has never been activated.

# once per repository: turn the ZEGITFILE into the active policy
zg policy propose               # signs HEAD's ZEGITFILE as a proposal
zg policy approve <blob>        # an owner (the first activation needs one; later ones two)
zg policy activate <blob> --push gateway

zg tr create v0.1.0 --commit HEAD
# a second owner/maintainer approves — zg tr approve, or the Control Plane's
# Tag Requests page — with a fresh passkey touch:
zg tr approve v0.1.0
zg tr finalize v0.1.0           # writes the signed tag once quorum is met
zg push gateway refs/tags/v0.1.0
# or wait for quorum and push in one go:
zg tr watch v0.1.0 --push gateway

Produce a CRA Evidence Bundle#

Every release tag can be turned into a signed, offline-verifiable bundle:

zg evidence bundle --tag v0.1.0 --prev v0.0.9 --out v0.1.0-bundle.zip
zg evidence verify-bundle v0.1.0-bundle.zip --trust-root root.crt

The manifest is signed with your login certificate. If a commit in the range has no valid AoV the zip is still written but the command exits 20 (ZG_ERR_EVIDENCE_INCOMPLETE) — --allow-incomplete accepts the gap knowingly. Archive the zip and the Root CA certificate together — that pair verifies with no network access, years later. See CRA & compliance.

Where to go next#