Devops Stinger

---
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/<date>-pipeline-audit.md` (standalone) or `library/requirements/<lifecycle>/prd-<###>-<title>/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