designing-cicd

Files (6)

• SKILL.md
• evals.json · evals/
• ci.yml · evals/fixtures/phasewave/cicd-migrate/.github/workflows/
• AGENTS.md · evals/fixtures/phasewave/cicd-migrate/
• verify-cicd.cjs · evals/fixtures/phasewave/cicd-migrate/scripts/
• gh-actions-topology.md · references/

SKILL.md (first lines)

# Designing CI/CD

Turn a release/operate pipeline into a verifiable GitHub Actions topology
that a separate build session can implement cold. A design pass is **done**
when the workflow topology exists (as a plan artifact and/or a drafted
workflow file), every gate is an observable, checkable rule, and the user
has approved it. The skill is **design-only** — it does not commit, edit
source, or run deployments. It stops at approval; implementation routes to
`implementing-features`.

This skill closes the library's release/operate gap: no other skill
covers CI topology, job DAGs, `concurrency`, `environment` protection, or
deploy-vs-migrate ordering.

## The design pass

Copy this checklist and check off items as you complete them.

```
CI/CD Design Progress:
- [ ] 1. Identify the pipeline's purpose + which triggers fire it
- [ ] 2. Select triggers (push / pull_request / workflow_run / workflow_dispatch)
- [ ] 3. Build the job DAG via `needs`
- [ ] 4. Add `concurrency` (one deploy at a time; queue, don't cancel prod)
- [ ] 5. Add `environment` + protection rules (reviewers / wait timer / deploy branches)
- [ ] 6. Separate secrets from vars
- [ ] 7. Choose matrix dimensions (only where it speeds feedback)
- [ ] 8. Wire caching + artifacts (reuse, don't rebuild)
- [ ] 9. Mark required checks + branch protection
- [ ] 10. Apply the migrate-before-deploy golden path
- [ ] 11. Present topology + approval question; STOP
```

### Step 1 — Identify purpose + trigger set

Name what the pipeline delivers (test gate, preview deploy, prod release,
migration). Pick triggers deliberately — each has a distinct failure mode:

- `push` to `main` — fires on every merge; the usual prod/release trigger.
- `pull_request` — the validation gate (test + build) before merge; never
  the deploy trigger for prod (PR refs can't see protected secrets).
- `workflow_run` — chain a downstream workflow (e.g. deploy) after an
  upstream one (e.g. CI) completes; the correct way to "deploy after CI
  passed" without polluting the PR trigger.
- `workflow_dispatch` — manual promotion / rollback; pairs with an
  `environment` and protection rules.

Do **not** deploy from `pull_request` with production secrets — PRs from
forks/branches must not hold deploy power. Route deploy through
`workflow_run` or `workflow_dispatch`.

### Step 2 — Select triggers

Map each chosen trigger to a job group (see
[references/gh-actions-topology.md](references/gh-actions-topology.md) for
the event/context matrix). A pipeline usually needs: a `pull_request`
validation job, a `push`/`workflow_run` deploy job, and an optional
`workflow_dispatch` promotion job. List the triggers in the plan so an
implementer doesn't guess.

### Step 3 — Build the job DAG via `needs`

Jobs run in parallel by default; `needs:` makes them a DAG. Common shape:

```
test  ─┐
build ─┼─▶ deploy          (deploy waits for both)
migrate─┘
```

Every job a later gate depends on must be named in `needs`. A deploy that
does not `needs:` the migrate job can race it — the cardinal ordering bug.

### Step 4 — Add `concurrency`

Prevent overlapping runs from clobbering the same environment:

```yaml
concurrency:
  group: deploy-prod-${{ github.ref }}
  cancel-in-progress: false   # queue, don't cancel an in-flight prod deploy
```

- **Non-prod / PR validation**: `cancel-in-progress: true` is fine (drop
  stale runs on new pushes).
- **Prod deploy**: `cancel-in-progress: false` — queue new runs behind the
  in-flight one. Cancelling a prod deploy mid-flight leaves a half-shipped
  environment. Use a per-environment `group` so staging and prod don't
  serialize each other.

A topology with no `concurrency` on deploy is a finding (two merges can
ship concurrently and corrupt state).

### Step 5 — Add `environment` + protection rules

Gate prod with a named `environment` so GitHub enforces protection rules:

```yaml
deploy:
  environment:
    name: production
    url: ${{ steps.deploy.outputs.url }}
  needs: [test, build, migrate]
```

Protection rules (set in repo Settings → Environments, referenced here by
name): required reviewers, wait timer, and restricted deployment branches.
The plan should name the environment and which rules apply — an
ungated `production` environment is a finding.

### Step 6 — Separate secrets from vars

- **Secrets** (`${{ secrets.X }}`) — never logged, never echoable. Deploy
  tokens, `SUPABASE_ACCESS_TOKEN`, cloud credentials.
- **Vars** (`${{ vars.X }}`) — non-sensitive config (region, project id,
  static URLs). Safe to print in logs.

The plan lists each value as secret or var; a token placed in `vars` is a
security finding (route to `securing-ci`). Never `echo` a secret; GitHub

From hierovision/ai-framework, MIT.

More from hierovision/ai-framework