truestack-ci-and-delivery

name

truestack-ci-and-delivery

description

Set up CI/CD and ship safely to a self-hosted server — pipeline stages (lint, type-check, test, build), SHA-pinned Actions, least-privilege workflow permissions and GitHub Actions secrets (runtime secrets/.env on the server belong to truestack-deploy-and-runtime), semver + CHANGELOG releases, and health-gated deploy with rollback. Use whenever the user says "set up CI", "set up CI/CD", "GitHub Actions workflow", "lint and tests on PR", "required status checks", "branch protection", "merge queue", "pin actions", "SHA pin", "workflow permissions", "GITHUB_TOKEN", "OIDC (keyless cloud/deploy credentials for workflows)", "cache dependencies", "Docker layer caching", "release automation", "semantic versioning", "bump the version", "generate changelog", "tag a release", "conventional commits", "the CI pipeline that ships a release to production", "health-gated deploy step", "rollback in CI", "smoke test before traffic", or "sequence a migration step in the deploy".

truestack-ci-and-delivery

The path from a green PR to a running server, made boring on purpose. CI proves the change; delivery ships the exact artifact CI proved and can undo it in seconds. One self-hosted box, no autoscale — so the pipeline must be cheap, the deploy reversible, and the secrets never leave the server. Accuracy and reversibility beat clever automation.

Read project memory first — CLAUDE.md is auto-loaded (Principles + Boundaries); consult .ai/memory/ for the existing CI provider, deploy target, image registry, branch rules, and release tooling. Don't invent a workflow that contradicts what's recorded. If none exists, run truestack-project-memory.

Deploys, migrations, and force-pushing tags are irreversible / data-touching — route the design of a new pipeline or deploy strategy through truestack-architecture-planning's approval gate before wiring it, and know that the PreToolUse gate in hooks/ will already stop a destructive/deploy/migration command at run time (it forces a human yes). See hooks/README.md.

Where this skill sits: it owns the pipeline — encoding the checks as automated CI (it does not replace the one-shot truestack-quality-control pass on the current change; it makes those checks run on every PR), the release/versioning, and the deploy step that gates and triggers a release. The on-box cutover mechanics (nginx reload, container swap, SIGTERM drain, the rollback runbook) belong to truestack-deploy-and-runtime; authoring the migration DDL/backfill belongs to truestack-database-migrations; a cron trigger inside a workflow lives here, but scheduling an assistant/agent run is truestack-task-scheduling.

1. Pipeline stages — fast, required, in order

On every PR run the cheap gates first so failures surface in seconds: lint → type-check → unit tests → build. Fail fast, run independent jobs in parallel, and keep the whole PR run under a few minutes so the box (and the team) isn't waiting. Build the deployable artifact in CI, not on the server — the server only pulls what CI proved.

2. Gate the branch on a small, stable set of checks

Protect the default branch with a GitHub Ruleset (layers cleanly, auditable) — not ad-hoc branch toggles. Make required only the fast, deterministic checks (lint, type-check, unit, build). Keep slow or flaky jobs (e2e, perf, optional scanners) non-required / informational so a flake can't wedge every merge. Require checks to run on the PR's merge result, not a stale branch ("require branches up to date"). A merge queue is usually overkill for a small team — but if you enable one, the checks must also trigger on the merge_group event (and third-party CI on the gh-readonly-queue/<base> prefix), or queued PRs merge with no checks actually running. Hand the pre-merge depth (test review, six-axis review, safety) to truestack-quality-control — these checks are the gate, QC is the judgment.

3. Supply chain — pin, then wait

• SHA-pin every third-party action to the full 40-char commit SHA, never @v4 / @main. Tags are mutable: real compromises (tj-actions in 2025 among others) rewrote tags out from under pinned-by-tag users — auto-research a current example before citing one. Pin your own reusable workflows too.
• Pinning is necessary but not sufficient. New SHAs need a 7–14 day cooldown before adoption — most supply-chain compromises are detected within days of publication, so the delay catches the bulk of them. This skill sets the initial SHA pins and wires the pipeline stage that enforces the policy; the ongoing bump-and-cooldown bot policy (Renovate/Dependabot config — the github-actions ecosystem included — plus app deps, CVEs, SBOMs) is truestack-dependency-management.

4. Least-privilege permissions & secrets

• Default permissions: contents: read at the workflow level, then grant the minimum extra scope per job — only the release job gets contents: write, only a PR-comment job gets pull-requests: write. The legacy read/write default means one compromised action can push to the repo.
• Never expose secrets to pull_request_target or to fork-triggered runs. Mask and minimize what CI ever sees.
• OIDC is a cloud feature (AWS/GCP/Azure/Vault) — it does not apply to a bare self-hosted box. The self-hosted equivalent: don't put the server's SSH key or root creds in CI. Give CI a narrow dedicated deploy identity (a deploy user that can only pull the image + run the deploy script, or a registry token scoped to one repo). Keep app runtime secrets on the server (env file / secrets manager), injected at container start — never baked into the image or echoed through Actions logs.

5. Caching — fast, but untrusted

Key dependency and Docker-layer caches on the lockfile hash, and write a dependency-first Dockerfile (copy lockfile → install → then copy source) so only the code layer rebuilds. But treat the cache as an attack surface: Actions cache is only branch-scoped server-side, so a poisoned cache (e.g. via a Dependabot-bumped hash) can be restored into a trusted run. Never cache build secrets, and segregate PR caches from main.

6. Release — build once, version automatically

• Build the artifact once; deploy that exact immutable image everywhere. Reference it by content digest (sha256:…) or an immutable tag — never :latest. Tag images with both the git SHA and the semver. This is what makes rollback an image-swap, not a rebuild, and guarantees the tested thing is the shipped thing.
• Automate semver + CHANGELOG from Conventional Commits (release-please / semantic-release): merging to main computes the bump, generates the CHANGELOG, creates the git tag and Release — no human version-bump errors, a traceable tag per deploy. Keep the release job least-privileged and separate from the build job.

7. Migrations — decouple from the deploy, get the order right

This is the #1 deploy-incident cause. Use expand/contract and make every migration backward-compatible with the currently running app:

• Adding a column → migrate first, then deploy code that uses it.
• Removing a column → deploy code that stops using it first, then drop it later in a separate contract migration.
• On Postgres use CREATE INDEX CONCURRENTLY and backfill large tables in batches — never one giant locking statement on the single box.

This skill owns ordering the migration in the pipeline (migrate-first vs code-first relative to the cutover); authoring it — reversible up/down, idempotent batched backfills, lock/timeout discipline — is truestack-database-migrations.

8. Deploy — health-gated, rollback in seconds

The pipeline's deploy step ships the exact immutable digest and owns go/no-go: a health check + smoke test against the new container before any traffic switches, and automatic revert to the last known-good digest when the post-switch check fails. The cutover sequence itself — colors, digest recording, proxy flip, nginx -t, drain windows, SIGTERM/readiness mechanics — is truestack-deploy-and-runtime's runbook (its blue/green atomic-swap and idempotent-runbook sections): execute that, don't re-derive it here — a second copy of a runbook only exists to drift.

9. Close the loop

When the pipeline changes a recorded command, deploy step, branch rule, or release process, update .ai/memory/ in the same change so the code↔memory tally balances. Before calling delivery "done", hand to truestack-quality-control (the workflow YAML and deploy script are code — they get the same security and intent pass). Report against the goal honestly: if a check is flaky, a secret can't be scoped as tightly as ideal, or rollback isn't yet proven, say so with a completion score rather than declaring a done you can't prove (honesty contract).

Explain it simply

Say it in one plain line: "CI checks your code on every PR; release tags a version; deploy swaps in the new container only if it's healthy, and flips back instantly if it isn't."