shipmill

The open-source AI software factory for GitHub. Agents triage your issues, fix them, and land the pull requests; release lanes cut, publish, deploy, and roll back by a policy you write. Everything runs on GitHub, and you stay in charge.

issue ─▶ triage ─▶ fix ─▶ review & land ─▶ release ─▶ deploy ─▶ watch
          agent     agent      agent         policy     policy    agent

Why shipmill

Coding agents can write a fix. Getting that fix to users is the rest of the work: deciding which issues deserve one, reviewing the pull request, waiting for green CI, cutting a release, publishing it, telling the reporter, and noticing when production breaks. shipmill does that rest, end to end, on any GitHub repository.

• Issue to release, not just issue to PR. One pipeline from a new issue to a published, deployed, and announced release
• Policy, not prompts, decides what ships. A single file, .github/shipmill.toml, says which lanes release and when (dev, rc, stable, hotfix), what gates hold them, and how far automation may go
• You stay in control. Each stage runs at observe, propose, or act; the decision policy ([decisions]) says which of the agents' decisions they take, tell you about, ask you, or leave to your hand (Who decides); one shipmill-hold issue, opened from your phone, stops everything
• No server, no state of its own. GitHub is the database: issues, labels, pull requests, tags, deployments; nothing lives outside your repository
• Releases you can trust. CI runs on the exact release commit before it is tagged; a breaking change reaches a stable release only after your decision; a failing deploy rolls back and opens an incident

How it works

The skills run in Claude Code, on demand or unattended on a schedule. The release side is plain GitHub Actions plus the shipmill CLI, and works without the agents.

Quickstart

You need a GitHub repository with a CHANGELOG.md that has an ## [Unreleased] section, the gh CLI signed in, uv, and Claude Code. From the root of your repository:

claude plugin marketplace add shipmill/shipmill && claude plugin install shipmill@shipmill && claude "/shipmill:shipmill-setup"

The shipmill-setup skill inspects the repository, asks which lanes to run, and wires everything on a branch, ending with a pull request. Releases start in dry-run mode until you switch them on.

Then ask what needs you:

uv tool install shipmill  # once; `uv tool upgrade shipmill` after each plugin update
shipmill status

uv tool install shipmill is the one way to put the CLI on your PATH. The plugin runs its own pinned release, so run uv tool upgrade shipmill after each plugin update to keep the two the same; shipmill doctor and shipmill status report a shipmill on PATH whose version differs from the plugin's. Without the install, uvx shipmill status runs the latest release from PyPI.

It answers STUCK, WAITS ON YOU, WORKING, or IDLE, with a link to each item that waits on you. One factory line sums up the machinery on this machine; shipmill factory prints it a line per check: the gate's launchd job, its sessions, the GitHub App, the shipmill installs, the checkout, and the worktrees.

Prefer to set it up by hand, or want only the release lanes without agents? Follow docs/install.md.

Release lanes at a glance

Every pull request adds its own CHANGELOG entry, as a fragment file by default so pull requests don't conflict on it; the entries decide the next version. Installers skip dev and rc unless asked, so a user who wants to try a change first pins the pre-release while everyone else gets each stable release; a breaking change waits for you.

Who the work is credited to

Agents write to GitHub through the repo's GitHub App, so by default the App's bot authors the issues, pull requests, and merges they make. [agents] author in .github/shipmill.toml picks one of three modes:

• Autonomous ([agents] author = "app"): the App authors them, and each merge commit names its decider in a Co-authored-by trailer
• Assisted ([agents] author = "decider"): an agent's issue, pull request, and merge commit go out as their decider, through the App, once that person has run shipmill app-login; for anyone else, the App writes them. Comments, labels, and reviews stay the App's
• Operator (no App, [agents] identity = "host"): the host's gh login writes, as before

Each person opts in by running shipmill app-login themselves; the owner turning assisted mode on authorizes no one. The decider is who assigned or approved the work, never an outside author of a request, and a record an agent wrote keeps its agent marker whoever authors it. Flow has the details.

Documentation

Status

shipmill is alpha and releases itself with its own workflows, so every release you see on PyPI went through the pipeline described above. Expect the policy keys to change between minor versions; the CHANGELOG says how.

Contributing

Issues and pull requests are welcome. A new feature starts as a spec in docs/specs/; every pull request adds its own changelog entry as a new file in changelog.d/. The checks CI runs are listed in CLAUDE.md.

License

MIT