Skip to content

Deployment Checklist

Purpose

Deployment Checklist is the release-window execution checklist. Its unique job is to capture the pre-deploy checks, validation gates, staged rollout, and rollback for a specific release.

It is not a runbook, monitoring design, implementation plan, or release note. Point to those artifacts instead of duplicating them.

Example

Show a worked example of this artifact
---
ddx:
  id: example.deployment-checklist.depositmatch.csv-import
  authoring:
    home: repo
  depends_on:
    - example.implementation-plan.depositmatch
    - example.test-plan.depositmatch
---

# Deployment Checklist

## Release

- **Component**: DepositMatch CSV Import v1, behind the `csvImportV1` flag (defaults off in production)
- **Release version**: `release-2026-05-12-csv-import`
- **Related artifacts**: implementation plan, test plan, API-001

## Before Deploy

- **Plan reviewed**: Migration plan shows only `import_sessions` and `import_files`; nothing else changes.
- **Order of operations**: Migration first, then API and web with the flag off, then enable the flag.
- **Config is complete**: Storage bucket name and credentials are non-empty after render. An empty bucket disables uploads silently, so the smoke script asserts a real upload succeeds.
- **Access verified**: The upload service account can write to the source-file bucket and no other bucket, confirmed by a staging upload.

## Validation Gates

| Gate | Must Pass Before | Check |
|------|------------------|-------|
| CI green on main, P0 upload tests pass | staging | `pnpm test && pnpm test:e2e -- upload-csv` |
| Migration applied | production | Staging migration job log |
| Valid CSV pair uploads; PDF is rejected | production | Staging smoke script |
| No raw CSV row values in logs | production | Log query for fixture sentinel values |
| Health green 15 minutes, flag off | canary | `curl -fsS https://api.depositmatch.example/healthz` |
| Upload 5xx below 1%, p95 under 2s | full pilot | Upload dashboard |

## Rollout Stages

| Stage | Deploy Action | Exit Condition |
|-------|---------------|----------------|
| Staging | Deploy, migrate, enable flag | Happy path and rejection pass |
| Production, flag off | Deploy and migrate | Health green 15 minutes |
| Canary | Enable for one pilot firm | 3 successful imports or 30 minutes without a trigger |
| Full pilot | Enable for all pilot firms | Gates above hold |

## Rollback

**Path**: Disable `csvImportV1`; the previous deploy stays in place, so recovery is immediate. If the migration blocks the API deploy, restore the previous task definition.

| Signal | Threshold | Immediate Action |
|--------|-----------|------------------|
| Upload 5xx | Above 1% for 15 minutes | Disable the flag |
| Partial session or file commit | Any | Disable flag, stop canary, run cleanup script |
| Raw row values in logs | Any confirmed | Disable flag, purge logs per runbook |

Reference

ActivityDeploy — Ship to users with appropriate operational support, monitoring, and rollback plans.
Default locationdocs/helix/05-deploy/deployment-checklist.md
RequiresNone
EnablesNone
InformsMonitoring Setup
HELIX documentsdocs/helix/05-deploy/deployment-checklist.md
Generation prompt
Show the full generation prompt
# Deployment Checklist Generation Prompt

Create a concise, service-specific deployment checklist for this release.

## Purpose

Deployment Checklist is the **release-window execution checklist**. Its unique
job is to capture the pre-deploy checks, validation gates, staged rollout, and
rollback for a specific release.

It is not a runbook, monitoring design, implementation plan, or release note.
Point to those artifacts instead of duplicating them.

## Reference Anchors

Use these local resource summaries as grounding:

- `docs/resources/google-sre-release-engineering.md` grounds repeatable,
  staged, evidence-based releases with explicit rollback paths.
- `docs/resources/microsoft-azure-well-architected-framework.md` grounds
  operational readiness, reliability, and deployment risk checks.

## Focus

- Keep the checklist short enough to use during the release itself.
- Include only the checks that materially change the technical go/no-go decision.
- Before Deploy covers the failures that actually bite: an unreviewed plan, a
  dependency landing out of order, config that is silently empty, and grants
  assumed rather than verified. Answer them for this release, not generically.
- Exclude adoption, user-count, revenue, survey-score, and community-uptake
  thresholds. Product and market goals do not determine technical readiness.
- Make validation gates and rollback triggers explicit.
- Omit owners, timestamps, and status checkboxes; the tracker and git hold them.
- Point to supporting artifacts such as `monitoring-setup` or `runbook`
  instead of duplicating them.
- Avoid communication boilerplate, launch marketing tasks, or generic
  enterprise release wish lists.

## Boundary Test

| If you are writing... | Put it in... |
|---|---|
| Build sequence and implementation validation | Implementation Plan |
| Operational procedures and incident response | Runbook |
| Dashboards, alerts, and SLO instrumentation | Monitoring Setup |
| User-facing release communication | Release Notes |
| Release-window go/no-go checks and rollback triggers | Deployment Checklist |

## Completion Criteria

- Before Deploy is answered for this release.
- Each gate names the signal or command that proves it.
- Rollback returns to the last working state; a failed deploy never replaces it.
Template
Show the template structure
---
ddx:
  id: deployment-checklist
  authoring:
    home: repo
---

# Deployment Checklist

## Release

- **Component**: [name]
- **Release version**: [tag/build]
- **Related artifacts**: [runbook, monitoring-setup, release-notes]

## Before Deploy

- **Plan reviewed**: [For infra or config changes, the plan/diff was read and every change is expected. Name anything unrelated that would also change.]
- **Order of operations**: [What must land first (infra variable, migration, grant) and what depends on it.]
- **Config is complete**: [Every required env/config value is non-empty after render. Name the values that fail silently when empty.]
- **Access verified**: [The deploy principal holds the grants it needs, checked by a real run, not assumed from a merged change.]

## Validation Gates

| Gate | Must Pass Before | Check |
|------|------------------|-------|
| [Build and tests] | staging | [CI link / command] |
| [Migration or data check] | production | [query / log] |
| [Critical path works] | full rollout | [test / smoke script] |
| [Error rate and latency] | full rollout | [threshold and dashboard] |

## Rollout Stages

| Stage | Deploy Action | Exit Condition |
|-------|---------------|----------------|
| Staging | [steps] | [what must be true] |
| Canary | [steps] | [what must be true] |
| Full | [steps] | [what must be true] |

## Rollback

**Path**: [How to get back to the last working state, and how long that takes. A failed deploy must not replace the working one.]

| Signal | Threshold | Immediate Action |
|--------|-----------|------------------|
| [error rate / failed path / data issue] | [threshold] | [command or runbook section] |
Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition
model-primary
Issuer
HELIX helix
Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source
artifact-types/deploy/deployment-checklist.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:9e3cec3d…72869b71

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-11-16T15:52:45Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifact-types/deploy/deployment-checklist/",
        "digest": {
          "alg": "sha256",
          "value": "9e3cec3d524d2be9787e8ceacadb3efa072ab3d6d4b2cb44d2dd5fe872869b71"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "beeKotehWTMhZb8JcIGB9A7YIcIcFN1a0YngfHiu-tnL39NOPc85FIyLz4wXJRW4Ua3Gb9JOBWlZELdDMIxoCw",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}