release-agent

release-agent

Deterministic, non-blocking release preparation across a fleet of GitLab repositories —a reconciler engine over a declarative manifest, exposed as a CLI (release) and anMCP server (release-mcp) so you can drive releases from GitHub Copilot Chat, Claude,or any other MCP client in plain language.

Built for the reality of multi-repo products: libraries that must publish before servicescan pin them, release branches with iterated tags (v1.0.0-1, -2, ...), a QA gate, adeploy repo that pins the final versions — and CI pipelines that take 40–50 minutes.The engine never waits: every command returns in seconds, pipelines run on their own time,and an idempotent reconcile advances whatever is ready whenever you come back.

How it works

• Manifest (release-manifest.yaml) — declares your repos, their dependency DAG,which files to edit (maven properties, python dependencies, yaml keys), and whatvariables each pipeline needs. See examples/release-manifest.yaml.The engine hard-codes zero product knowledge — adoption is pure configuration.
• Run state — one JSON per release, stored in a small dedicated GitLab project.Shared visibility, full history, optimistic locking; any teammate can resume any release.
• Reconciler — walks the DAG; per node: create branch → commit version pins → cut tag →trigger pipeline (via the API, so per-release variables travel with the build) → poll →record produced versions → unblock dependents. Nothing is ever created twice.
• Gates — a manual checkpoint (e.g. qa-signoff) the engine will not pass withoutan explicit release approve.
• Captures & report — manifest-declared regexes grep job logs for values of interest(Sonar URLs, image digests); release report assembles the whole release — tags,pipelines, versions, captured values — into markdown, optionally published to thestate repo (reports/<coordinate>.md).
• No LLM in the engine — ever. release explain deterministically fetches a failedjob's log tail; the model on the client side (Copilot, Claude, ...) interprets it inthe same chat. ports.LogExplainer stays as an extension point if you want a hostedmodel, but nothing requires one.

Install

Requires Python 3.13+ and uv.

git clone <this repo> && cd release_agent
uv sync
uv run release --help

Configure

Everything is environment variables (per-developer PAT model):

* one of STATE_PROJECT / STATE_DIR is required.

Use — CLI

release start 1.0.0 --env sit \
  -i jar_bundle_1_version=1.0.1 -i pydantic_version=10.0.0 -i jar_bundle_2_version=2.3.0

release status 1.0.0        # render the DAG, tags, pipeline URLs
release reconcile 1.0.0     # idempotent tick — run it whenever, it never double-fires
release bump 1.0.0 service-a          # next vX.Y.Z-(N+1) after a QA fix
release approve 1.0.0 qa-signoff      # clear the manual gate
release explain 1.0.0 service-a       # advisory: why did the pipeline fail?

Use — MCP (Copilot Chat, Claude, ...)

Register the stdio server with your client, e.g. VS Code .vscode/mcp.json:

{
  "servers": {
    "release-agent": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/release_agent", "release-mcp"],
      "env": {
        "RELEASE_AGENT_GITLAB_URL": "https://gitlab.example.com",
        "RELEASE_AGENT_GITLAB_TOKEN": "${input:gitlab-token}",
        "RELEASE_AGENT_STATE_PROJECT": "group/release-state"
      }
    }
  }
}

Then just talk: "start release 1.0.0 on sit with jar-bundle-2 2.3.0, jar-bundle-1 jar 1.0.1,pydantic 10.0.0" → the model calls release_start; later, "advance the release" →release_reconcile. Tools exposed: release_start, release_status, release_reconcile,release_approve, release_bump, release_explain, get_manifest.

Prompt cookbook

Habits that keep it reliable: always name the coordinate ("release 1.2.0") so themodel never guesses which release you mean, and ask to "advance" freely — reconcilenever double-fires, so an over-eager prompt costs nothing.

Adapt to your product

1. Copy examples/release-manifest.yaml and describe yourrepos, tiers, edits, and pipeline variables.
2. Create a release-state project in GitLab, commit the manifest there.
3. Gate your CI release/publish jobs to run only from API-triggered tag pipelines($CI_COMMIT_TAG && $CI_PIPELINE_SOURCE == "api" — purely additive, design §9).On GitLab 17.7+ also set each project's "Minimum role to use pipeline variables"to developer, or API-triggered pipelines with variables are rejected with HTTP 400.
4. Need a new file mutation? Add one function to EDIT_KINDS insrc/release_agent/core/edits.py.
5. Have an LLM endpoint? Implement ports.LogExplainer and wire it insrc/release_agent/bootstrap.py.

Development

uv run pytest          # unit + engine tests against an in-memory fake GitLab
uv run ruff check .

License

MIT