Release Engineer

---
name: release-engineer
description: Use when asked to set up or fix CI/CD, a pipeline (GitHub Actions, GitLab CI or another), automated deploys, staging or production environments, secrets in CI, a release or versioning, rollback, or a zero-downtime or migration-safe deploy, or to deploy or ship now when no repeatable path exists. Builds PR checks, a build-once artifact, staging on merge, gated production promotion, smoke checks and a tested rollback, and reports only what actually ran. Not for comments or formatting in CI files, generic CI product questions, local setup, or deciding whether a change is safe to ship.
---

# 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).

<!-- skills-hub:protocol -->
### 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.
<!-- /skills-hub:protocol -->

## 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

| Situation | Action |
| --- | --- |
| Target named and a fit record or a past successful deploy exists | Use it |
| Target named, fit unknown | `HANDOFF → deployment-compatibility: <target>, fit unknown` before the first deploy. The pipeline can still be written |
| No target named, app has a `Dockerfile` | Ask one question: which host. Offer the beginner choices in `references/deploy-targets.md` |
| Kubernetes | Only if manifests or a cluster already exist. Never introduce it |

### 3. Build the pipeline minimum

| Stage | Trigger | Runs | Gate |
| --- | --- | --- | --- |
| PR checks | every pull request (and push to main) | install from lockfile · lint · test · build | required status check on main |
| Artifact | push to main, after checks | build image or bundle once, tag with commit SHA, push, record digest | checks green |
| Staging | automatically after the artifact | migrations · deploy the digest · smoke check · auto-rollback on failure | `autonomy.deploy_staging` (default `auto`) |
| Production | explicit promotion of a digest staging verified | same steps as staging, same artifact | rule 1, plus the CI's environment protection where available |

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:

| Condition | Result |
| --- | --- |
| No tested rollback (rule 5) | `BLOCKED` — test rollback on staging first |
| The digest was not deployed and smoke-checked on staging | `BLOCKED` — promote only what staging verified |
| `production-guard` said DO NOT SHIP for this commit, no explicit override | `BLOCKED` — name the verdict and its blockers, ask nothing else |
| No verdict for this commit | `HANDOFF → production-guard`, and deploy only on the verdict or the human's explicit "deploy without it" |
| CONDITIONAL SHIP with a condition not shown met | `BLOCKED` — list the unmet conditions |
| First production deploy and `observability-baseline` has not run | `HANDOFF → observability-baseline`, then continue unless the human pauses |
| `autonomy.deploy_production` is not `auto` and no yes in this session | Ask once: `Deploy <digest> to production? (rollback: <cmd>)` |
| Otherwise | Deploy |

### 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.