baton

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: Apache-2.0

README

baton

ci OpenSSF Scorecard Contributor-Covenant

baton tracks the follow-up work that a change in one repository owes the others in a multi-repository project.

A release of a library owes a bump in each consumer, then a release of each consumer, then a deploy. A copied schema owes a sync when the source changes. These rules usually live in maintainers' heads, and the work gets missed or arrives late. baton records them in one baton.yml and checks them on a schedule. Each owed action stays open as an issue in the owing repository until baton can verify, from the repositories or the running service, that it's done.

Preview. baton is pre-1.0. apply writes issues only to a sandbox owner given with --redirect-owner, never to the component repositories. Use plan to see what it would do there.

How it works

  • baton.yml lives in a dedicated <project>-baton repository. It lists the components, the rollouts each release triggers (a trigger plus obligations ordered by needs), standing invariants, and waivers.
  • Probes answer "is this done?" as of a date, from go.mod files, releases, file contents, or a live endpoint, so the same file replays against history.
  • Issues. Each rollout gets a parent issue in the baton repository with a checklist. Each pending or overdue obligation gets a child issue in the repository that owes it.

The full design, including states, probes, and the threat model, is in docs/design.md. A complete example for OpenSSF Scorecard is in examples/scorecard/baton.yml.

Usage

go install github.com/uwu-tools/baton/cmd/baton@latest

baton validate baton.yml                        # offline checks, for PRs
baton plan baton.yml                            # states and issue changes; read-only
baton plan --as-of 2026-07-01 baton.yml         # the same, as of a past date
baton apply --redirect-owner my-sandbox baton.yml
baton version

plan and apply read GITHUB_TOKEN. Exit status is 0 on success, 1 for bad usage or config, and 2 when an obligation, API call, or inventory check failed.

Adopting baton

  1. Create a <project>-baton repository and add a baton.yml.
  2. Copy templates/workflows/ into its .github/workflows/. The comments in baton.yml cover the GitHub App and environment it needs.
  3. Run baton plan and review the result before enabling the schedule.

Contributing

See CONTRIBUTING.md. Please report security issues as described in SECURITY.md.

License

Distributed under the Apache License 2.0. See LICENSE.

Directories

Path Synopsis
cmd
baton command
Command baton tracks the work one component owes another.
Command baton tracks the work one component owes another.
baton/cmd
Package cmd holds baton's command tree.
Package cmd holds baton's command tree.
internal
batontest
Package batontest holds shared fixtures for baton's tests.
Package batontest holds shared fixtures for baton's tests.
github
Package github implements baton's source and issue APIs on GitHub.
Package github implements baton's source and issue APIs on GitHub.
pkg
config
Package config loads and validates a baton file.
Package config loads and validates a baton file.
plan
Package plan maps a reconcile report to issue changes.
Package plan maps a reconcile report to issue changes.
probe
Package probe checks whether an owed action is done, as of a date.
Package probe checks whether an owed action is done, as of a date.
reconcile
Package reconcile evaluates every obligation in a baton file.
Package reconcile evaluates every obligation in a baton file.
source
Package source defines what baton reads about components.
Package source defines what baton reads about components.
source/sourcefakes
Code generated by counterfeiter.
Code generated by counterfeiter.
writer
Package writer carries out an issue plan on GitHub.
Package writer carries out an issue plan on GitHub.
writer/writerfakes
Code generated by counterfeiter.
Code generated by counterfeiter.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL