repo-keeper

A lightweight, local-first background agent that keeps every repository you can access on GitHub, GitLab, Bitbucket, Azure DevOps and Gitea/Forgejo cloned and up to date, safely.

Status: beta. GitHub and GitLab are verified end to end; Gitea/Forgejo, Bitbucket Cloud, Azure DevOps and plain git remotes are implemented and fixture-tested but not yet verified against live servers. The sync engine, safe cleanup, rate limiting, daemon, web UI, tray, packaging, hardening and fuzzing are done and measured; the beta soak is next. See docs/, installation, security review and the roadmap.

What it does

• Discovers all remotes you can access per configured account (via official APIs).
• Syncs them on a schedule: fetch, prune, fast-forward the default branch (main/master/anything, auto-detected).
• Cleans up local branches that are already merged (including squash/rebase merges), with safety rails and undo.
• Respects provider rate limits and terms of service (back-off, conditional requests, polite minimum intervals).
• Shows state in a small local web UI (and CLI): last sync, errors, rate-limit budget, pending cleanups, configuration.

Principles

1. Never lose work. Fast-forward only, never touch dirty trees, never force, every deletion recoverable.
2. Least privilege. Read-only tokens by default; secrets live in the OS keychain only.
3. Lightweight. One static binary, no runtime, idle ≈ 0% CPU, <50 MB RSS.
4. Polite. Official APIs only, identifiable User-Agent, honors Retry-After and rate-limit headers.
5. Boring to install. Reproducible releases with cosign-signed checksums, SBOMs and build provenance; user-level autostart, no admin rights.

How this is built (AI assistance)

Much of this code is written with AI coding assistants. That is a reason to check the work, so the project is set up to make it checkable rather than taken on trust:

• Rules for the assistants are in AGENTS.md and are enforced, not just requested: git runs only through one hardened package, every outbound call goes through one rate-limited client, secrets never touch logs, argv or config, and nothing may update or download-and-execute code on its own (a test fails the build if the update code is imported from anywhere else).
• Safety-critical logic fails closed and is tested exhaustively: the cleanup safety invariant is checked over every combination of branch facts (100% coverage required on it), and the config parser, ref-name sanitiser and rate-limit header parsers are fuzzed.
• Every change must pass make test lint security: race-detector tests with a coverage gate (85% overall), golangci-lint, gosec, govulncheck, CodeQL and OpenSSF Scorecard in CI.
• The design is written down before the code: requirements, architecture, a threat model and ADRs, plus a security self-review that lists what was and was not verified.
• Releases are verifiable: reproducible builds, an SPDX SBOM per archive, cosign keyless signatures on the checksums and GitHub build-provenance attestations. The installers check these before installing anything.
• Tests never touch your home directory, keychain or the network.

None of this makes the code correct by itself. Read the source, start with cleanup in dry-run (the default), and report anything wrong through SECURITY.md or an issue.

Documentation

License

Apache-2.0. Contributions: see CONTRIBUTING.md.

Installing as a service (NixOS, Home Manager, deb, rpm, tarball): see docs/INSTALL.md.

Quick start (development builds)

nix develop            # or install Go ≥ 1.26 and git ≥ 2.34
make build
./bin/repo-keeper init                      # writes a starter config
# GitHub: a fine-grained read-only token is recommended
./bin/repo-keeper accounts add personal --token-stdin --include 'me/*,my-org/*' < token.txt
# GitLab (nested groups welcome): a group/project access token with read_api + read_repository
./bin/repo-keeper accounts add work --provider gitlab --base-url https://gitlab.example.com --token-stdin --include 'acme/**' < token.txt
$EDITOR ~/.config/repo-keeper/config.toml   # set [general] root = "/home/you/code"   # or open `repo-keeper ui` → Settings
./bin/repo-keeper discover                  # preview what would be cloned
./bin/repo-keeper daemon                    # sync in the background (see packaging/systemd)
./bin/repo-keeper status
./bin/repo-keeper ui                        # opens the web interface (one-time sign-in link; --print-url for SSH)
./bin/repo-keeper-tray &                    # optional status icon (KDE, waybar/sway, GNOME with AppIndicator)

No keychain (headless server, container)? Use --token-file /run/secrets/gh-token (mode 600) or --token-env GH_TOKEN instead of --token-stdin.

Topics

• InstallNix, Home Manager, packages and the tarball.
• Beta guideTest it safely: look first, sync one thing, clean last.
• Command lineEvery command and flag, generated from the binary.
• ConfigurationThe starter configuration, generated from the binary.
• ProvidersGitHub, GitLab, Gitea/Forgejo, Bitbucket, Azure DevOps and plain git.
• Release notesWhat changed in each release.
• ReleasingHow a release is cut and verified.
• RequirementsScope and acceptance criteria.
• ArchitectureHow the pieces fit together.
• Threat modelWhat can go wrong and what stops it.
• Security reviewFindings and their status.
• Security policyReport a vulnerability.
• DistributionPackaging, signing and supply chain.
• Decisions (ADRs)Why things are the way they are.
• TestingHow it is tested.
• PerformanceBudgets and measurements.
• ContributingHow to propose and land a change.
• Code of conductHow we treat each other.
• Agent instructionsThe hard rules for AI coding agents working on this repository.
• RoadmapMilestones and what is next.
• Implementation planHow the work was phased.
• Open questionsDecisions and verifications still pending.
• StatisticsSize, tests, coverage and releases, generated on every build.