pipeline-worker

Automate the last mile of your local changes: pipeline-worker takes the uncommitted diff in your repo and drives it — unattended — all the way to a merged, locally-synced result.

1. Captures your staged + unstaged changes (your working tree is only read, not modified, up through this point).
2. Replays them in a disposable git worktree.
3. Asks a coding agent (Claude Code, Pi, or GitHub Copilot CLI) to infer the intent: change type, branch slug, commit message, summary.
4. Runs your build / lint / test commands, fail-fast.
5. Commits, pushes, and opens a GitLab MR or GitHub PR — the branch name is composed from the configurable branchPattern.
6. Polls the CI pipeline; on failure it hands the pipeline URL to the agent, which pulls the failed jobs and logs itself via whatever GitLab/GitHub MCP tooling is available (pipeline-worker's own forge MCP server, or an external one the agent already has configured), commits the fix, pushes, and re-polls — capped at maxFixAttempts before escalating to a human with an MR comment.
7. Once the MR/PR is ready to merge (or, with PIPELINE_WORKER_CLEANUP_EARLY, as soon as the MR/PR is opened), resets your repo's current branch back to HEAD (see PIPELINE_WORKER_CLEANUP below) — your changes now live safely on the feature branch instead of sitting uncommitted locally too.
8. By default (PIPELINE_WORKER_AUTO_MERGE_ON_GREEN), waits for the forge to confirm the auto-merge actually landed, then (after a few seconds' grace for the ref to settle) fast-forwards your local target branch from origin — so your local main already contains the merged result when the run ends. Best-effort: if the merge is held up (e.g. by required approvals), you switched branches mid-run, or your local target branch diverged, it leaves everything untouched and tells you to git pull instead. Set PIPELINE_WORKER_AUTO_MERGE_ON_GREEN=false to go back to opening the MR/PR and merging it yourself.

While attached to a real terminal, the run renders as a live step tree — header line, then one row per step (capture, worktree, checks, ci-watch, merge, ...) with a status glyph, duration, and best-effort token count, updated in place. CI logs and piped output fall back to the previous append-only narration (or force it yourself with PIPELINE_WORKER_PLAIN_OUTPUT=true).

Polling is plain REST and costs zero agent tokens; the agent is invoked only when a pipeline actually fails, and fetches whatever pipeline/job detail it needs through pipeline-worker's token-efficient TOON-encoded MCP server (or an external forge MCP server, if the agent has one available).

Requirements

• Node.js >= 20.12 and git
• One coding agent CLI on your PATH: Claude Code (claude), Pi (pi), or GitHub Copilot CLI (copilot)
• A GitLab or GitHub token with API access to the repo

Agents

| CLI | PIPELINE_WORKER_AGENT | Setup | Per-invocation model selection | | --- | ----------------------- | ----- | ------------------------------ | | Claude Code | claude | npm install -g @anthropic-ai/claude-code | ✅ (--model) | | Pi | pi | npm install -g @earendil-works/pi-coding-agent | ✅ (--model) — any provider/model | | GitHub Copilot CLI | copilot | Install via GitHub's docs | ❌ (uses its own configured model) |

Pi supports models from any provider — Anthropic, OpenAI, Google Gemini, DeepSeek, Groq, OpenRouter, etc. Configure your provider/api-key via pi's own setup (/login), env vars, or --provider in the adapter.

Install

npm install -g pipeline-worker

This installs two equivalent commands, pipeline-worker and the shorter pw — use whichever you prefer (e.g. pw run --ticket PROJ-123).

Quick start

Set these once in your shell profile (~/.zshrc / ~/.bashrc) and every repo on the machine picks them up — no per-repo setup needed:

export PIPELINE_WORKER_AGENT=claude     # or pi, or copilot
export PIPELINE_WORKER_FORGE=gitlab
export PIPELINE_WORKER_GITLAB_HOST=https://gitlab.example.com
export PIPELINE_WORKER_GITLAB_TOKEN=glpat-xxxxx
export PIPELINE_WORKER_GITLAB_REPO_BASE=$HOME/REPO   # local dir that mirrors the GitLab namespace root — enables auto-detected projectId in any repo underneath it

Then, in any repo:

cd your-repo
# hack, hack, hack — leave the changes uncommitted, then:
pipeline-worker

Configuration

pipeline-worker is configured entirely through real environment variables — set them in your shell profile once, and every repo picks them up.

| Env var | Default | Meaning | | --------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------- | | PIPELINE_WORKER_AGENT | claude | claude, pi, or copilot | | PIPELINE_WORKER_FORGE | gitlab | gitlab or github | | PIPELINE_WORKER_GITLAB_HOST | — | e.g. https://gitlab.example.com | | PIPELINE_WORKER_GITLAB_PROJECT_ID | — | numeric project id | | PIPELINE_WORKER_GITLAB_REPO_BASE | — | local dir mirroring the GitLab namespace root, for auto-detecting projectId | | PIPELINE_WORKER_GITLAB_TOKEN | — | GitLab API token | | PIPELINE_WORKER_GITHUB_REPO | auto-detected from origin | owner/name slug — only needed when origin isn't a GitHub remote | | PIPELINE_WORKER_GITHUB_TOKEN | falls back to GITHUB_TOKEN | GitHub token | | PIPELINE_WORKER_POLL_INTERVAL_SECONDS | 15 | pipeline poll cadence; use 60 for slow pipelines | | PIPELINE_WORKER_BRANCH_PATTERN | pipeline-worker/{name} | feature branch naming template — see below | | PIPELINE_WORKER_CLEANUP | true | reset repoRoot to HEAD once cleanup fires (see PIPELINE_WORKER_CLEANUP_EARLY for when) (false to keep your local uncommitted changes as-is) | | PIPELINE_WORKER_CLEANUP_EARLY | false | true resets repoRoot as soon as the MR/PR is opened (diff committed + pushed), instead of waiting for CI to go green — frees the repo (and the run lock) for a new pipeline-worker run while this run's CI-watch/fix loop keeps going in the background | | PIPELINE_WORKER_INTENT_MODEL | haiku | model used for the intent-capture step (branch/commit/summary); claude and pi support per-invocation model selection — copilot ignores it | | PIPELINE_WORKER_BUILD | auto-detected from toolchain | build command override; set to an empty string to skip the stage | | PIPELINE_WORKER_LINT | auto-detected from toolchain | lint command override; set to an empty string to skip the stage | | PIPELINE_WORKER_TEST | auto-detected from toolchain | test command override; set to an empty string to skip the stage | | PIPELINE_WORKER_MAX_FIX_ATTEMPTS | 5 | how many CI-fix attempts before escalating to a human — tracked independently from merge-conflict-resolution attempts, so a long-lived PR needing several rebases can't exhaust the budget meant for real bug-fixing | | PIPELINE_WORKER_RUN_LINT_AND_TEST | true | run the local lint and test stages (false to run only build — for repos where an earlier workflow, e.g. upstream CI, already verified lint/test) | | PIPELINE_WORKER_UPDATE_CHANGELOG | false | once checks pass, add a bullet (from the captured intent's summary) under CHANGELOG.md's [Unreleased] section — feature/bugfix/chore map to the Added/Fixed/Changed categories — creating the file, Keep a Changelog-style, if the repo has none — and include it in the same commit | | PIPELINE_WORKER_AUTO_MERGE_ON_GREEN | true | once the MR/PR opens, ask the forge to merge it automatically as soon as CI (and any required approvals) allow — best-effort; if the forge rejects it (auto-merge not enabled for the repo, pending approvals, ...) the run continues normally and you merge manually. Once the forge confirms the merge landed, the run also fast-forwards your local target branch from origin (waiting a few seconds for the ref to settle first), so your local main is already up to date when the run ends. Set to false to go back to opening the MR/PR and merging it yourself | | PIPELINE_WORKER_MERGE_METHOD | squash | merge, squash, or rebase — passed to auto-merge. GitLab has no per-request rebase option; rebase there falls back to the project's own default merge method | | PIPELINE_WORKER_SQUASH_ON_MERGE | false | once CI is green, collapse every commit this run made on the branch into one (titled from the captured intent) and force-push — keeps history clean regardless of the repo's merge-strategy setting. Off by default: rewrites published history (force-push), a materially different risk from everything else this tool does. Only reliable with auto-merge off — the forge may already have merged (and deleted) the branch before this step runs | | PIPELINE_WORKER_PLAIN_OUTPUT | false | force the append-only, non-redrawing narration even on a real terminal (the same output CI/piped runs always get) — useful when pasting output into a bug report or feeding it to another tool |

Branch naming

PIPELINE_WORKER_BRANCH_PATTERN controls the feature branch name, built from three placeholders:

| Placeholder | Filled by | | ----------- | ------------------------------------------------------------------- | | {type} | feature, bugfix, or chore — inferred from the diff by the agent | | {ticket} | the --ticket <id> flag passed to pipeline-worker run | | {name} | a short kebab-case slug describing the change — inferred by the agent |

For example, a team using GitLab issue-linked branches would set:

export PIPELINE_WORKER_BRANCH_PATTERN='{type}/{ticket}/{name}'

pipeline-worker run --ticket PROJ-123
# -> bugfix/PROJ-123/fix-login-redirect

A pattern that includes {ticket} requires --ticket to be passed; the run fails fast at the naming step otherwise.

Check command auto-detection

build / lint / test are picked from the repo's toolchain (first marker found wins; mixed-language repos should set PIPELINE_WORKER_BUILD / PIPELINE_WORKER_LINT / PIPELINE_WORKER_TEST explicitly):

| Toolchain | Marker | build | lint | test | | ----------------- | ------------------------------------------------------ | ---------------- | ----------------------------------- | ------------------------------------------------ | | Node / TypeScript | package.json | npm run build | npm run lint | npm test — each only if the script is declared | | .NET | *.sln / *.csproj / *.fsproj / *.vbproj at root | dotnet build | dotnet format --verify-no-changes | dotnet test | | Go | go.mod | go build ./... | go vet ./... | go test ./... | | Python | pyproject.toml / setup.py / requirements.txt | — | — | pytest |

A stage with no command (—) is skipped. If no toolchain is detected and no commands are configured, all local checks are skipped with a warning.

Commands

| Command | What it does | | -------------------------------------------- | ------------------------------------------------------------------------- | | pipeline-worker (or pipeline-worker run) [--ticket <id>] | Capture the current diff and drive it to a green MR/PR | | pipeline-worker serve | Start the forge MCP server over stdio (used by the agent during fix runs) | | pipeline-worker resume --branch <name> [--target <branch>] | Resume watching/fixing a run after a crash, or adopt a branch pipeline-worker has no record of | | pipeline-worker status --branch <name> | Print the persisted state of a run | | pipeline-worker sessions [--branch <name>] | List every persisted run in this repo, or show one run's full step-by-step timeline | | pipeline-worker update | Install the latest release from npm (npm install -g pipeline-worker@latest) |

Before doing any work, pipeline-worker run checks npm for a newer published version and installs it automatically if the locally installed one is out of date (the update takes effect on the next run). This check is best-effort: if npm is unreachable or the install fails, the run proceeds anyway on whatever version is already installed.

Adopting a branch pipeline-worker never ran on

pipeline-worker resume --branch <name> also works for a branch pipeline-worker has no persisted state for at all — e.g. one you committed and pushed by hand. It checks out the branch and checks the forge for an open PR/MR for it:

• No PR/MR yet: runs it like a fresh pipeline-worker run from this point on — build/lint/test checks (aborting the same way a normal run does on failure), intent capture, then opens the MR/PR — targeting --target <branch> if given, or origin's auto-detected default branch otherwise.
• PR/MR already open: re-captures intent from the branch's actual diff, overwrites the PR/MR's description with it (using the PR/MR's own target branch — no guessing needed), and resumes the normal watch/fix loop: poll CI, and on failure pull the failed jobs' logs, hand them to the agent to fix, commit, push, and repoll.

Every time a run hands a turn to the agent (resolving a conflict, capturing intent, fixing a failed pipeline), the output includes that turn's duration and an agent session: <id> line — claude --resume <id>, pi --session <id>, or copilot --resume <id> opens the same session later to see exactly what it did and why. Copilot CLI has no way to report the session id it picked for itself, so pipeline-worker assigns one via --name instead and reports that.

How the fix loop stays bounded

Every retry path has a cap: local checks abort the run before an MR is ever opened; if no CI pipeline shows up for the MR/PR within 60s, the run ends there instead of polling; otherwise pipeline polling gives up after a 2-hour safety window; fix attempts stop at maxFixAttempts; a fix attempt that changes no files, or a pipeline that ends canceled/skipped, escalates immediately instead of spending agent tokens. Escalation always leaves a comment on the MR/PR so a human knows to take over.

License

MIT