Getting Started

Getting Started

This page takes you from nothing to a prepared proposal on a fixture repository, then to your own repository.

Requirements

Requirement	Why	Notes
Go 1.27 or later	builds the tool; os.Root is used for file containment	the host compiler is separate from the toolchain image used to validate a target repository
Git	the tool drives Git with fixed arguments	any recent version
A Docker-compatible engine over a unix socket	every command that runs repository code runs in a container	Docker Desktop, OrbStack, Colima, or Rancher Desktop
For model mode: an Ollama server with a tool-calling model	the local model is the development provider	qwen3:30b-a3b and gpt-oss:20b have been benchmarked
For vulns and -select vulnerable	build the pinned scanner, fetch the vulnerability database	network access to proxy.golang.org and sum.golang.org the first time each toolchain image is used, and to https://vuln.go.dev on every run unless -vulndb names a directory
For publication: a fine-grained GitHub token	API calls and the push	contents and pull requests permissions on the target repository only

Nothing in the default paths calls a paid model. Nothing reaches GitHub unless you pass -publish and approve.

A note for macOS users of VM-backed engines

Colima, and engines like it, share only certain host paths with their virtual machine, typically your home directory. Repo Steward keeps its data directory under your home directory for this reason, and every run probes that the engine can actually see the directories it mounts. If you point -data-dir at an unshared path, the probe fails with a clear message rather than validating an empty directory.

One-time bootstrap

The toolchain image used to validate a repository is pinned by digest and selected from the repository's go directive. Pull it once with network access, either with docker pull or by passing -pull on the first run:

docker pull golang@sha256:3d699e4d15d0f8f13c9195c0632a16702b8cbdece2955af1c23b37ae5d55a253   # Go 1.22

The pinned table covers Go 1.22 through 1.27; see Configuration.

First run on a fixture

Fixtures are small Go repositories embedded in the tool, with a matching offline module proxy, so you can exercise the whole path with the network disabled.

git clone https://github.com/joeylking/repo-steward.git
cd repo-steward
go test ./...                                             # no engine needed

go run ./cmd/repo-steward fixture list
go run ./cmd/repo-steward fixture setup patch-safe -dest ~/tmp/patch-safe
go run ./cmd/repo-steward fixture proxy -dest ~/tmp/proxy

# Profile, discover candidates, validate the baseline. No model.
go run ./cmd/repo-steward inspect ~/tmp/patch-safe -fixture-proxy ~/tmp/proxy

# Deterministic upgrade pipeline, ends with a frozen proposal commit.
go run ./cmd/repo-steward maintain ~/tmp/patch-safe -mode baseline \
  -author "Your Name <you@example.com>" -fixture-proxy ~/tmp/proxy

inspect prints a JSON report: the repository profile, the baseline validation with each check's status and whether it was conclusive, and every outdated direct dependency with each newer version marked eligible or not. maintain -mode baseline selects the smallest eligible upgrade, applies it, validates, and freezes a proposal; the output names the proposal commit and the files it changes.

Vulnerability report

Build the binary first, because go run hides exit codes. The synthetic database plants advisories in the fixture modules, so this needs no network beyond building the scanner once per toolchain image:

go build -o ~/tmp/repo-steward ./cmd/repo-steward
~/tmp/repo-steward fixture vulndb -dest ~/tmp/vulndb
~/tmp/repo-steward vulns ~/tmp/patch-safe -fixture-proxy ~/tmp/proxy -vulndb ~/tmp/vulndb
~/tmp/repo-steward maintain ~/tmp/patch-safe -mode baseline -select vulnerable \
  -vulndb ~/tmp/vulndb -author "Your Name <you@example.com>" -fixture-proxy ~/tmp/proxy

The first reports the fixture's advisory and exits 4; the second picks the lowest version that clears it and proposes it only if a second scan confirms. See Vulnerabilities: Reporting and Fixing.

Your own repository

Your repository must be a single Go module with go.mod at the root, committed (a dirty checkout is refused), without vendoring, workspaces, submodules, cgo, or local replace directives. inspect tells you if it is unsupported and why.

For a repository with real dependencies, note that inspect and maintain apply a 72-hour version cooldown by default: a version published more recently, or with no publish time from the proxy, is listed as ineligible with the reason. -min-age 0 turns it off.

go run ./cmd/repo-steward inspect ~/src/myrepo
go run ./cmd/repo-steward maintain ~/src/myrepo -mode baseline -author "Your Name <you@example.com>"

Without -fixture-proxy, dependency acquisition reaches the public module proxy and checksum database. Everything that executes repository code still runs with no network.

With a local model

ollama serve &
ollama pull qwen3:30b-a3b
go run ./cmd/repo-steward maintain ~/src/myrepo -mode model -model ollama:qwen3:30b-a3b \
  -author "Your Name <you@example.com>" -trace

-trace prints every runtime event as it happens: each decision, policy verdict, tool call, and model call with usage and latency.

Publishing

See Publication. In short: add -publish, set GITHUB_TOKEN, approve the pause with approve, and continue with resume.