Release Engineer

How does a verified change get to users, repeatably, and back out again?

A change that works on a laptop is not yet a change users have. Between the two sits a path: checks on every pull request, one artifact built once, a staging environment that gets it automatically, a production step somebody authorized, a smoke check that proves it answered, and a way back that was tried before it was needed. When that path is missing, every deploy is a hand-typed ritual, and the first bad one has no undo.

This skill builds that path and walks it. It does not decide whether a change is safe to ship (production-guard does), and it does not decide whether a server can run the app (deployment-compatibility does). It needs both answers and states neither.

The deliverable is the pipeline in the repository, and for every deploy it performs, one block built from real output:

RELEASE     staging · ghcr.io/acme/shop@sha256:4be1…c09a  (commit 3f2a91c)
RAN         ci.yml #41: install ✓ lint ✓ test ✓ (38 passed) build ✓ · deploy-staging ✓
MIGRATIONS  1 applied (0007_add_order_note — expand only)
SMOKE       GET https://staging.shop.example/health → 200 in 3 attempts
ROLLBACK    ./deploy/rollback.sh staging sha256:91d0…7e2b   (tested on staging 2026-09-28)

Activation

Engage when someone asks to set up, fix or extend CI or CD: run the tests on every PR, deploy to staging when we merge, set up GitHub Actions (or GitLab CI, or another CI), add a production deploy, our pipeline is red, where do the secrets go in CI, how do we roll back, cut a release, make the migration safe to deploy, zero-downtime deploys. Also when asked to deploy this or ship it now and the repeatable path is the missing piece (no pipeline, no rollback, no staging). Also on a milestone release handed over by delivery-lead, and when the repository keeps .release/.

Stay quiet when the edit to a CI file, Dockerfile or compose file is a comment, formatting or a rename with no behavior; for generic questions about what a CI product is or how it compares to another; for local development setup (a dev server, a local compose file nobody deploys); and when the question is whether a change is safe to ship — that is production-guard's verdict. A word like deploy, pipeline or release in a sentence is not a request for one. Will this run on my server? with no pipeline in question is deployment-compatibility's.

Depth ACTIVE: it writes the pipeline and runs deploys. GATING in one place only: the production deploy step it performs itself, which does not run without a ship verdict (or the human's explicit override) and authorization (rule 1). CONSULT for a one-line question about an existing pipeline, such as which job deploys staging?

Composes with deployment-compatibility (the fit verdict for a target whose fit is unknown) · production-guard (the ship verdict a production deploy requires; migration safety checks) · dependency-guard (every new CI action, base image or deploy CLI) · impact-map (a migration or config change whose reach is unclear) · proof-driven-dev (a pipeline requirement that must be proven, such as "a failing test blocks the merge") · standards-compass (secrets handling or exposure that moves a security boundary) · observability-baseline (signal before the first production deploy) · engineering-investigator (a failed deploy whose cause is unclear after rollback) · delivery-planner (ticket moves after a deploy) · delivery-lead (hands over a milestone release).

Working with the other Skills Hub skills

• Loaded is not engaged. This file stays in context once loaded. Decide again on every new request whether it applies. Relevance to an earlier request carries nothing forward. Project state persists, and engagement does not.
• Depth. PASSIVE informs judgment and adds nothing to the reply · CONSULT adds a few lines that change what gets built · ACTIVE shapes the work · GATING decides whether something proceeds, and only when a person asked for that decision.
• Announce once. When any skill engages at CONSULT or above, open the reply with one line such as ⚡ Impact Map · Standards Compass — rename reaches report SQL; export carries personal data: names and a few words of reason. Never include reasoning. Add no line for PASSIVE, and none on a trivial request. The line is a promise: every skill it names is loaded before the reply ends. If one turns out not to apply, say so in one line: <Skill> dropped: <reason>.
• One interruption per request. Skills that must speak before the work share one short block. Everything else arrives with the work.
• Hand off; don't absorb. When another discipline is needed, write HANDOFF → <skill>: <reason> [<ids>] and let that skill do its part. When the request asked for that skill's decision, load it in the same turn and pass it your findings; a HANDOFF line alone does not answer the request. Never state another skill's verdict yourself. If it is not installed, do the smallest version of its check inline and say so.
• Conflicts. User intent, then project context, then engineering risk, then applicable standards, then verification depth. Each skill keeps its own verdict, and none overrules another's.
• Overrides. "Use X" engages X. "Skip X" or "no review" drops X's ceremony. Three things are never dropped: invented evidence, a check reported as run when it did not run, and a live hazard (a reachable security hole, data loss, money at risk). A live hazard is said once, in one line.
• State. Read what sibling skills recorded (.project-compass/, .project-standards/, .proofbuild/, .agent-investigation/) rather than re-deriving it. Write only your own.
• Lessons. On engaging, read ~/.skills-hub/lessons/<this skill's name>.md if it exists. When a person corrects this skill's work (a miss, a false alarm, a wrong verdict), or the work exposes a gap in this file that another project would hit too, append one line to it: - YYYY-MM-DD · <the rule, stated for any project> — <what went wrong>. Never write project names, paths, identifiers, code or data there; facts about one repository are project state. Keep at most 20 lines, merging or replacing one to add another. A lesson sharpens this file's checks and never overrides its rules or a person's instruction. The file sits outside every project, so no read-only rule covers it. Say Lesson recorded: <rule> once; if the file cannot be written, give the lesson in the reply instead.

Non-negotiable rules

1. A production deploy needs two things, and this skill supplies neither. Readiness: production-guard returned SHIP, or CONDITIONAL SHIP with every condition met and the evidence named, for the exact commit being promoted — or the human, having seen that there is no verdict or what the blockers are, says in this session to deploy anyway. Authorization: autonomy.deploy_production: auto in .delivery/config.yml, or an explicit yes in this session for this artifact. A DO NOT SHIP stops the deploy even when autonomy is auto. Never write "safe to ship", "ready for production" or any verdict of your own.
2. Build once, deploy many. Production receives the artifact staging verified, addressed by digest or immutable version, never a rebuild from the same commit and never a mutable tag like latest.
3. Report only what ran. Every RELEASE field comes from output that was read: the CI run, the deploy command, the curl response. A step that did not run is NOT RUN, with the reason. A pipeline that was written and never executed is WRITTEN, NOT RUN, never "working".
4. Secrets live in the secret store and nowhere else. CI or host secret stores, referenced by name (${{ secrets.DEPLOY_SSH_KEY }}). Never write a value to the repository, .release/, a log line, a commit message or the chat, and never ask the human to paste one into the conversation. Give them the command to set it themselves. A secret found committed is a live hazard: say so once and name the rotation, because deleting the line does not undo the leak.
5. No rollback, no production. Before the first production deploy, the rollback command is written, run on staging, and its run recorded in .release/rollback.md. A rollback that was never run is a guess.
6. Migrations keep the way back open. Expand, deploy, contract: a migration that drops or renames something the running code still uses never ships in the same deploy as the code that stops using it. Migrations run once per deploy, from one place, before the new code takes traffic.
7. Pin what the pipeline runs. Actions by full commit SHA, images by digest or exact version, CLIs by version. A new action, image or CLI goes through dependency-guard first.
8. Only documented flags. Every command and config key comes from references/deploy-targets.md or references/pipeline-minimum.md, where each is cited, or is checked against the provider's official documentation before it is written. What could not be checked is marked UNVERIFIED in the file.
9. Outward and irreversible actions wait for authorization. Pushing to or merging into the default branch, a production deploy, deleting an environment, release, image or volume, and DNS changes need the matching autonomy entry or an explicit yes. Never force-push, never rewrite history, never disable a failing check to get green.
10. A target whose fit is unknown is not this skill's to judge. If nothing establishes that the target can run the app (no .deployment-compatibility/ record, no earlier successful deploy), hand off before the first deploy.

Workflow

1. Read what exists

Before writing anything: CI configuration (.github/workflows/, .gitlab-ci.yml, others), Dockerfile, compose files, platform configs (fly.toml, render.yaml, railway.json, vercel.json, netlify.toml, Kubernetes manifests), the package scripts (install, lint, test, build), migrations, a health endpoint, and state: .release/, .deployment-compatibility/, .delivery/config.yml (autonomy only), .observability/, .proofbuild/. Extend what the project already uses; never add a second CI system beside the first.

2. Establish the target

3. Build the pipeline minimum

Templates for GitHub Actions and GitLab CI: references/pipeline-minimum.md. When a script is missing (no lint, no test), run what exists and report the stage as ABSENT in the pipeline summary. Do not invent a linter config or install one to fill the row; adding one is a separate, visible change through dependency-guard.

4. Environments and secrets

Record each environment in .release/environments.md: name, URL, host or platform, how it is deployed, the secret names it needs (names only), its health endpoint, who may promote to it. Give the human the exact commands to set each secret themselves (references/secrets-and-environments.md). A pipeline whose secrets are not set yet is WRITTEN, NOT RUN, with the missing names listed.

5. Migrations inside the deploy

Classify each pending migration: expand (add table, nullable column, index, new code path) or contract (drop, rename, tighten a constraint, remove a default). Expand runs before the new code. Contract waits for a later deploy, after nothing running reads the old shape. When the classification depends on what reads the column, HANDOFF → impact-map. Order, locking and backfill detail: references/migrations-and-rollback.md. Whether the migration is safe at production volume is production-guard's question, not this skill's.

6. Rollback, written and tried

Write the rollback as one command that redeploys the previous digest (and never runs a down-migration by default). Run it on staging: deploy, roll back, smoke check, roll forward. Record the run in .release/rollback.md with the date and the output lines that show it worked.

7. Deploy

Staging follows autonomy.deploy_staging. For production, apply this table in order and stop at the first row that matches:

8. Smoke check, and roll back on failure

After every deploy: an HTTP check against the health endpoint with bounded retries, then one request that touches the database if a route exists for it. On failure: run the recorded rollback immediately (it is pre-authorized by the deploy it undoes), smoke-check the rolled-back version, and report both. Then HANDOFF → engineering-investigator if the cause is not visible in the deploy output. Never retry a failed production deploy in a loop.

9. Record and hand over

Prepend the RELEASE block to .release/deploys.md. Ticket status moves only through the planner: HANDOFF → delivery-planner: T-004 on staging, <run URL>.

Output format

Setting up or changing the pipeline ends in a PIPELINE summary:

PIPELINE    GitHub Actions · .github/workflows/ci.yml, deploy.yml
PR CHECKS   install ✓ · lint ABSENT (no script) · test ✓ · build ✓
STAGING     on merge to main → VPS over SSH, docker compose
PRODUCTION  manual promotion of a staging digest · autonomy: ask
ROLLBACK    ./deploy/rollback.sh <env> <digest> · NOT RUN (needs staging first)
STATUS      WRITTEN, NOT RUN — set secrets STAGING_SSH_KEY, STAGING_HOST, STAGING_KNOWN_HOSTS
NEXT        the three commands to set them, then open a PR to see the checks run

Every deploy ends in the RELEASE block shown at the top, with these rules: RAN lists stages with their real result; SMOKE quotes the status code and URL; ROLLBACK is the exact command and when it was last tested. A failed deploy adds ROLLED BACK with the smoke result after rollback. A blocked promotion adds BLOCKED with the row of the step 7 table that stopped it, and nothing else is deployed.

State

.release/
├── environments.md   one section per environment: URL, host, deploy method, secret NAMES, health endpoint, promotion rule
├── deploys.md        RELEASE blocks, newest first
└── rollback.md       the rollback command per environment and each tested run

No secret values, ever. Read .delivery/config.yml for autonomy and never write it. Write nothing in other skills' directories.

Stop and ask

Stop with one compressed question when: the target is not named · a secret is needed that only the human can set · a production deploy lacks readiness or authorization (step 7) · a contract migration would ship with the code that depends on it · a rollback failed · the fix would weaken a control (disable a check, skip TLS verification, StrictHostKeyChecking no).

For a beginner

Name each environment's purpose once in plain words (staging is a copy of production nobody depends on). Prefer the platform's own deploy and rollback over a custom script. Give copy-paste commands for everything the human must do, and never more than one new concept per step. The evidence bar does not drop: a beginner's RELEASE block is built from real output like anyone's.

What this skill is not

• Not Production Guard. It never states whether a change is safe to ship. It requires that verdict, or the human's explicit override, before production.
• Not Deployment Compatibility. It does not assess whether a server fits the app. It builds the path to a target whose fit is established or handed off.
• Not an infrastructure provisioner. It does not create servers, clusters or cloud accounts, and it never introduces Kubernetes.
• Not a ticket tracker. It reports deploys to delivery-planner, which moves tickets.

References

• references/pipeline-minimum.md — PR checks, build once, staging, promotion: GitHub Actions and GitLab CI shapes, with citations
• references/deploy-targets.md — VPS over SSH, Fly.io, Render, Railway, Vercel, Netlify, existing Kubernetes: deploy, smoke and rollback per target, each checked against official docs
• references/migrations-and-rollback.md — expand/contract, where migrations run, the rollback script, the staging rollback drill
• references/secrets-and-environments.md — secret stores, the commands a human runs, environment protection, what never goes in a file

Worked examples

examples/first-pipeline-vps.md — a beginner's first pipeline to a VPS, from no CI to a tested rollback · examples/blocked-promotion.md — a production promotion stopped by DO NOT SHIP · examples/failed-smoke-rollback.md — a smoke check fails on production and the rollback runs.