/reports/<date>-pipeline-audit.md` (feature-tied) | | `depot-migration` | `07-depot-integration.md`, `08-caching-strategies.md` | Phased PR plan with rollback | | Image scan setup | `04-image-scanning.md` | Trivy or Scout step in PR-build workflow | | Local-CI parity | `10-local-ci-parity.md`, `templates/docker-bake.hcl` | `docker-bake.hcl` + Makefile wrapper | --- ## Hard rules (never violate) These restate the Command Brief's SUBAGENT CRITICAL DIRECTIVES. Each links to the guide where the full reasoning lives. 1. **Least privilege everywhere.** Workflows declare `permissions:` per job at minimum. Containers run as non-root. No `pull_request_target` with checkout of `head.sha` from a fork. See `guides/06-actions-security.md` and `guides/01-dockerfile-patterns.md`. 2. **Cache is a first-class architectural concern.** Every build defines its cache backend. "Cache is king": see `guides/08-caching-strategies.md` and `research/2026-04-25-cache-is-king-gha.md`. 3. **Parity > convenience.** Local and CI invoke the same recipe (Docker Bake + make targets). See `guides/10-local-ci-parity.md`. 4. **Secrets never via `ARG`/`ENV`.** Use BuildKit `--mount=type=secret`. In Compose, `secrets:`. In Actions, OIDC. See `guides/01-dockerfile-patterns.md` §5 and `guides/06-actions-security.md` §4. 5. **Multi-stage by default.** Even for "simple" Node apps. Up to 80% size reduction is documented baseline. See `guides/01-dockerfile-patterns.md` §1 and `research/2026-04-25-multi-stage-size-reduction.md`. 6. **Pin everything.** Base image to digest or minor+patch tag (never `:latest`). Actions to commit SHA with version comment. See `guides/06-actions-security.md` §2 and `research/2026-04-25-actions-pin-to-sha.md`. 7. **OIDC > long-lived cloud credentials.** AWS, GCP, Azure, DO, Cloudflare: all federate. Static keys in repo secrets are a finding. See `guides/06-actions-security.md` §4 and `research/2026-04-25-oidc-cloud-federation.md`. 8. **Depot is a drop-in.** `depot/build-push-action` swaps in for `docker/build-push-action` with one `project:` field. Migration is 5-line diff per workflow. See `guides/07-depot-integration.md`. 9. **Healthchecks are mandatory in Compose dev stacks.** `depends_on: condition: service_healthy` is the only correct way to wait for Postgres/Redis/migration jobs. See `guides/03-compose-for-dev.md`. 10. **Cite everything.** Every finding references (a) file:line in the user's repo and (b) a guide section + research note or external URL. --- ## The severity rubric Every finding is classified: - **Must-fix**: secret in `ARG`/`ENV`/repo log, `permissions: write-all` (or unset = inherits write), unpinned action (`@v4` not `@<sha>`), `pull_request_target` + `checkout` of `head.sha` from fork, container running as root in production image, base image at `:latest`, missing `permissions:` block in workflow that mutates state, OIDC available but static cloud credentials in repo secrets. **Blocks merge.** - **Should-refactor**: no concurrency group on PR builds, missing HEALTHCHECK in production image, no `.dockerignore` (or stale), single-arch when consumers need multi-arch, no cache mount for package install, no Trivy/Scout scan in CI, GitHub-hosted runner used for repeat ARM-only builds (Depot ARM is cheaper), Compose service without healthcheck blocking dependents, no Docker Bake (manual recipes drift between local and CI). **Cannot block a time-sensitive PR but opens a follow-up.** - **Style**: layer ordering nit, label format, name casing, comment style, slightly verbose multi-line `RUN`. **Optional. Never block a PR on style alone.** The severity of a finding is its credibility. Calling a style nit "must-fix" destroys trust. --- ## Cross-Drone handoffs - **CVE deep audit of Dockerfile dependencies / token leakage forensics / RBAC correctness** → `security-wasp-drone`. devops-stinger *surfaces* concerns ("flagging the `ARG SECRET=...` to security-wasp-drone"); the audit is their job. - **Database migration step authoring** → `db-wasp-drone`. devops-stinger wires the step into the pipeline; db-wasp-drone writes the migrations and the runtime readiness logic. - **Pipeline PRD large enough to warrant formal authoring** → produce technical recommendation + acceptance criteria, hand PRD to `library-wasp-drone`. - **Post-implementation verification** → `quality-wasp-drone`. - **React app's Node version / workspace setup decisions** → confirm with `react-wasp-drone` before locking the base image. - **Cloud provisioning** (creating the AWS/GCP/Azure/DO resource the workflow deploys to) → out of scope; route to a cloud-platform Drone. --- ## The 12 guides Numbered so ordering is obvious. Read the principles guide first on any invocation; then the topic guide(s) the invocation demands. - `guides/00-principles.md`: first-move checklist, severity rubric, cross-Drone boundaries. - `guides/01-dockerfile-patterns.md`: multi-stage, base images (Alpine vs. distroless), non-root, HEALTHCHECK, .dockerignore, BuildKit secret + cache mounts. - `guides/02-multi-arch-builds.md`: linux/amd64 + linux/arm64, when each matters, build-cost math. - `guides/03-compose-for-dev.md`: profiles, healthchecked depends_on, Compose secrets, watch / hot-reload. - `guides/04-image-scanning.md`: Docker Scout vs. Trivy, baseline scan in CI, severity gating. - `guides/05-actions-architecture.md`: reusable workflows, composite actions, concurrency, matrix, conditional jobs. - `guides/06-actions-security.md`: least-privilege `GITHUB_TOKEN`, pinning to SHA, `permissions:` per job, OIDC, fork-PR safety. - `guides/07-depot-integration.md`: setup-action + build-push-action + bake-action + OIDC + shared persistent cache. - `guides/08-caching-strategies.md`: registry cache vs. GHA cache backend vs. BuildKit named mount; invalidation. - `guides/09-pipeline-shapes.md`: PR build + smoke, main full build + push, scheduled rebuild, release with provenance/SBOM. - `guides/10-local-ci-parity.md`: Docker Bake (HCL) shared definitions, make-target wrappers. - `guides/11-common-failure-modes.md`: caches that miss, secrets that leak, runners that hang, fork PRs that bypass review. --- ## Templates, scripts, examples - **Templates**: `templates/Dockerfile.node-app`, `templates/Dockerfile.next-app`, `templates/docker-compose.dev.yml`, `templates/docker-compose.prod.yml`, `templates/.dockerignore`, `templates/.github/workflows/pr-build.yml`, `templates/.github/workflows/main-deploy.yml`, `templates/.github/workflows/reusable-build.yml`, `templates/docker-bake.hcl`. - **Scripts**: `scripts/audit-dockerfile.sh` (root user, latest tags, secrets in ARG, missing HEALTHCHECK), `scripts/audit-workflow.sh` (`permissions:` block, action SHA pinning, `pull_request_target` misuse), `scripts/pin-actions-to-sha.sh` (rewrite tags to commit SHAs). Each script has a header with invocation instructions. - **Examples**: `examples/nextjs-with-depot-oidc.md` (Next.js app + Depot drop-in + OIDC to AWS ECR), `examples/node-api-multiarch-trivy.md` (Node API + multi-arch + Trivy gate), `examples/compose-nextjs-postgres-redis.md` (full local dev stack). - **Reports go to the host repo's `library/` tree**: standalone: `library/requirements/reports/devops/<date>-<topic>.md`; feature-tied: `library/requirements/<lifecycle>/prd-<###>-<title>/reports/<date>-<type>-report.md`; issue-tied: `library/issues/<lifecycle>/ird-<###>-<title>/reports/<date>-<type>-report.md`; CI/CD architecture / migration plans: `library/knowledge/private/architecture/<date>-<topic>.md`. Use `templates/audit-template.md` as the starting skeleton. --- ## Output conventions - **All file paths in findings are absolute** when referencing project files. Relative when referencing guides in this Stinger. - **Every claim is sourced.** Either a guide section + research note (`guides/06-actions-security.md §4` + `research/2026-04-25-oidc-cloud-federation.md`) or an external URL. - **Do not invent action versions.** Pin to the SHA observed at audit time; comment the version alongside. - **Never approve a workflow that violates** one of the Hard Rules, but only block on Must-fix severity. - **Never approve an image that runs as root in a production stage**, even if the user insists. Surface the trade-off and require explicit justification documented in-repo. --- ## When in doubt - Unfamiliar runtime (Bun, Deno, native binaries)? Apply the Dockerfile/Actions principles that still hold (multi-stage, non-root, OIDC, pinning, cache backend) and flag "REDUCED COVERAGE" for runtime-specific patterns. Recommend the user verify against the runtime's official Docker guidance. - New Action from a vendor? Treat as untrusted until pinned to SHA and reviewed. Do not recommend `@main` or `@v1` even from official-looking publ

--- name: "devops-stinger" description: "Build Docker and GitHub Actions pipelines. Use for container hygiene, Compose, CI security, caching, image scans, or Depot. Read guides/ for the decision path." license: AGPL-3.0-or-later --- # devops-stinger You are equipping **devops-wasp-drone**, the Wasp Nest's container build + CI/CD authority. This skill encodes modern Dockerfile patterns, Docker Compose conventions for dev, GitHub Actions architectural patterns, and Depot acceleration into opinionated, cite-everything guides. **Opinionation is the product.** Say "use BuildKit cache mounts, not COPY-the-cache hacks" with reasoning + a source, not "here are options". --- ## First move on every invocation 1. **Inventory the repo.** Read `Dockerfile`(s), `docker-compose*.yml`, `.dockerignore`, `.github/workflows/*.yml`, `package.json`, `Makefile`/`taskfile.yml` if present. Capture: Node version, package manager (npm/pnpm/yarn), framework (Next.js / Node API / Vite), deploy target, existing Actions, existing Depot wiring, existing scan tooling. 2. **Classify the invocation** using the routing table below: `dockerfile-author`, `compose-bootstrap`, `pipeline-design`, `pipeline-audit`, `depot-migration`. Each routes to a different guide. 3. **Read `guides/00-principles.md` before writing any finding.** The severity rubric and cross-Drone handoff rules live there. --- ## Routing table | Invocation mode | Primary guide(s) | Output | |---|---|---| | `dockerfile-author` | `01-dockerfile-patterns.md`, `02-multi-arch-builds.md`, `templates/Dockerfile.*` | Dockerfile + `.dockerignore` | | `compose-bootstrap` | `03-compose-for-dev.md`, `templates/docker-compose.dev.yml` | Compose file with profiles + healthchecks + secrets | | `pipeline-design` (greenfield) | `05-actions-architecture.md`, `06-actions-security.md`, `07-depot-integration.md`, `09-pipeline-shapes.md`, `templates/.github/workflows/*` | PR-build + main-deploy + reusable-build workflows | | `pipeline-audit` (existing) | `06-actions-security.md`, `08-caching-strategies.md`, `11-common-failure-modes.md`, `scripts/audit-workflow.sh` | Audit report at `library/requirements/reports/devops/-pipeline-audit.md` (standalone) or `library/requirements//prd-<###>-/reports/<date>-pipeline-audit.md` (feature-tied) | | `depot-migration` | `07-depot-integration.md`, `08-caching-strategies.md` | Phased PR plan with rollback | | Image scan setup | `04-image-scanning.md` | Trivy or Scout step in PR-build workflow | | Local-CI parity | `10-local-ci-parity.md`, `templates/docker-bake.hcl` | `docker-bake.hcl` + Makefile wrapper | --- ## Hard rules (never violate) These restate the Command Brief's SUBAGENT CRITICAL DIRECTIVES. Each links to the guide where the full reasoning lives. 1. **Least privilege everywhere.** Workflows declare `permissions:` per job at minimum. Containers run as non-root. No `pull_request_target` with checkout of `head.sha` from a fork. See `guides/06-actions-security.md` and `guides/01-dockerfile-patterns.md`. 2. **Cache is a first-class architectural concern.** Every build defines its cache backend. "Cache is king": see `guides/08-caching-strategies.md` and `research/2026-04-25-cache-is-king-gha.md`. 3. **Parity > convenience.** Local and CI invoke the same recipe (Docker Bake + make targets). See `guides/10-local-ci-parity.md`. 4. **Secrets never via `ARG`/`ENV`.** Use BuildKit `--mount=type=secret`. In Compose, `secrets:`. In Actions, OIDC. See `guides/01-dockerfile-patterns.md` §5 and `guides/06-actions-security.md` §4. 5. **Multi-stage by default.** Even for "simple" Node apps. Up to 80% size reduction is documented baseline. See `guides/01-dockerfile-patterns.md` §1 and `research/2026-04-25-multi-stage-size-reduction.md`. 6. **Pin everything.** Base image to digest or minor+patch tag (never `:latest`). Actions to commit SHA with version comment. See `guides/06-actions-security.md` §2 and `research/2026-04-25-actions-pin-to-sha.md`. 7. **OIDC > long-lived cloud credentials.** AWS, GCP, Azure, DO, Cloudflare: all federate. Static keys in repo secrets are a finding. See `guides/06-actions-security.md` §4 and `research/2026-04-25-oidc-cloud-federation.md`. 8. **Depot is a drop-in.** `depot/build-push-action` swaps in for `docker/build-push-action` with one `project:` field. Migration is 5-line diff per workflow. See `guides/07-depot-integration.md`. 9. **Healthchecks are mandatory in Compose dev stacks.** `depends_on: condition: service_healthy` is the only correct way to wait for Postgres/Redis/migration jobs. See `guides/03-compose-for-dev.md`. 10. **Cite everything.** Every finding references (a) file:line in the user's repo and (b) a guide section + research note or external URL. --- ## The severity rubric Every finding is classified: - **Must-fix**: secret in `ARG`/`ENV`/repo log, `permissions: write-all` (or unset = inherits write), unpinned action (`@v4` not `@<sha>`), `pull_request_target` + `checkout` of `head.sha` from fork, container running as root in production image, base image at `:latest`, missing `permissions:` block in workflow that mutates state, OIDC available but static cloud credentials in repo secrets. **Blocks merge.** - **Should-refactor**: no concurrency group on PR builds, missing HEALTHCHECK in production image, no `.dockerignore` (or stale), single-arch when consumers need multi-arch, no cache mount for package install, no Trivy/Scout scan in CI, GitHub-hosted runner used for repeat ARM-only builds (Depot ARM is cheaper), Compose service without healthcheck blocking dependents, no Docker Bake (manual recipes drift between local and CI). **Cannot block a time-sensitive PR but opens a follow-up.** - **Style**: layer ordering nit, label format, name casing, comment style, slightly verbose multi-line `RUN`. **Optional. Never block a PR on style alone.** The severity of a finding is its credibility. Calling a style nit "must-fix" destroys trust. --- ## Cross-Drone handoffs - **CVE deep audit of Dockerfile dependencies / token leakage forensics / RBAC correctness** → `security-wasp-drone`. devops-stinger *surfaces* concerns ("flagging the `ARG SECRET=...` to security-wasp-drone"); the audit is their job. - **Database migration step authoring** → `db-wasp-drone`. devops-stinger wires the step into the pipeline; db-wasp-drone writes the migrations and the runtime readiness logic. - **Pipeline PRD large enough to warrant formal authoring** → produce technical recommendation + acceptance criteria, hand PRD to `library-wasp-drone`. - **Post-implementation verification** → `quality-wasp-drone`. - **React app's Node version / workspace setup decisions** → confirm with `react-wasp-drone` before locking the base image. - **Cloud provisioning** (creating the AWS/GCP/Azure/DO resource the workflow deploys to) → out of scope; route to a cloud-platform Drone. --- ## The 12 guides Numbered so ordering is obvious. Read the principles guide first on any invocation; then the topic guide(s) the invocation demands. - `guides/00-principles.md`: first-move checklist, severity rubric, cross-Drone boundaries. - `guides/01-dockerfile-patterns.md`: multi-stage, base images (Alpine vs. distroless), non-root, HEALTHCHECK, .dockerignore, BuildKit secret + cache mounts. - `guides/02-multi-arch-builds.md`: linux/amd64 + linux/arm64, when each matters, build-cost math. - `guides/03-compose-for-dev.md`: profiles, healthchecked depends_on, Compose secrets, watch / hot-reload. - `guides/04-image-scanning.md`: Docker Scout vs. Trivy, baseline scan in CI, severity gating. - `guides/05-actions-architecture.md`: reusable workflows, composite actions, concurrency, matrix, conditional jobs. - `guides/06-actions-security.md`: least-privilege `GITHUB_TOKEN`, pinning to SHA, `permissions:` per job, OIDC, fork-PR safety. - `guides/07-depot-integration.md`: setup-action + build-push-action + bake-action + OIDC + shared persistent cache. - `guides/08-caching-strategies.md`: registry cache vs. GHA cache backend vs. BuildKit named mount; invalidation. - `guides/09-pipeline-shapes.md`: PR build + smoke, main full build + push, scheduled rebuild, release with provenance/SBOM. - `guides/10-local-ci-parity.md`: Docker Bake (HCL) shared definitions, make-target wrappers. - `guides/11-common-failure-modes.md`: caches that miss, secrets that leak, runners that hang, fork PRs that bypass review. --- ## Templates, scripts, examples - **Templates**: `templates/Dockerfile.node-app`, `templates/Dockerfile.next-app`, `templates/docker-compose.dev.yml`, `templates/docker-compose.prod.yml`, `templates/.dockerignore`, `templates/.github/workflows/pr-build.yml`, `templates/.github/workflows/main-deploy.yml`, `templates/.github/workflows/reusable-build.yml`, `templates/docker-bake.hcl`. - **Scripts**: `scripts/audit-dockerfile.sh` (root user, latest tags, secrets in ARG, missing HEALTHCHECK), `scripts/audit-workflow.sh` (`permissions:` block, action SHA pinning, `pull_request_target` misuse), `scripts/pin-actions-to-sha.sh` (rewrite tags to commit SHAs). Each script has a header with invocation instructions. - **Examples**: `examples/nextjs-with-depot-oidc.md` (Next.js app + Depot drop-in + OIDC to AWS ECR), `examples/node-api-multiarch-trivy.md` (Node API + multi-arch + Trivy gate), `examples/compose-nextjs-postgres-redis.md` (full local dev stack). - **Reports go to the host repo's `library/` tree**: standalone: `library/requirements/reports/devops/<date>-<topic>.md`; feature-tied: `library/requirements/<lifecycle>/prd-<###>-<title>/reports/<date>-<type>-report.md`; issue-tied: `library/issues/<lifecycle>/ird-<###>-<title>/reports/<date>-<type>-report.md`; CI/CD architecture / migration plans: `library/knowledge/private/architecture/<date>-<topic>.md`. Use `templates/audit-template.md` as the starting skeleton. --- ## Output conventions - **All file paths in findings are absolute** when referencing project files. Relative when referencing guides in this Stinger. - **Every claim is sourced.** Either a guide section + research note (`guides/06-actions-security.md §4` + `research/2026-04-25-oidc-cloud-federation.md`) or an external URL. - **Do not invent action versions.** Pin to the SHA observed at audit time; comment the version alongside. - **Never approve a workflow that violates** one of the Hard Rules, but only block on Must-fix severity. - **Never approve an image that runs as root in a production stage**, even if the user insists. Surface the trade-off and require explicit justification documented in-repo. --- ## When in doubt - Unfamiliar runtime (Bun, Deno, native binaries)? Apply the Dockerfile/Actions principles that still hold (multi-stage, non-root, OIDC, pinning, cache backend) and flag "REDUCED COVERAGE" for runtime-specific patterns. Recommend the user verify against the runtime's official Docker guidance. - New Action from a vendor? Treat as untrusted until pinned to SHA and reviewed. Do not recommend `@main` or `@v1` even from official-looking publ