Skip to content

CI/CD & Releases

GitHub Actions automates the quality gate, releases, and dependency updates. See ADR 0011 for the design rationale.

Workflows

Workflow Trigger What it does
ci.yml PRs, pushes to master pre-commit at image-pinned tool versions, gitleaks history scan, Conventional Commits check, make build + BATS suite + make test-init (heavy jobs are path-filtered)
release.yml tags v* (stable vX.Y.Z and prerelease vX.Y.Z-rc.N) changelog-gated validation → amd64 build + test → multi-arch (amd64 + arm64) push to Docker Hub → GitHub Release. Prereleases skip the changelog gate (see Releases)
docs.yml pushes to master (docs paths) + manual workflow_dispatch builds MkDocs site and deploys to Cloudflare Pages (dev-container.pages.dev)
renovate.yml weekly Sunday 04:00 UTC + manual workflow_dispatch self-hosted Renovate opens dependency-update PRs; reuses the Docker Hub credentials (DOCKERHUB_USERNAME / DOCKERHUB_TOKEN) for authenticated docker.io lookups to dodge anonymous rate limits

Image tags

Released images are published to docker.io/felipecoelho90/dev-container with tags:

Tag Meaning
X.Y.Z Immutable release (e.g. 2.0.0)
X.Y Latest patch for this minor (e.g. 2.0)
X Latest minor for this major (e.g. 2)
latest Most recent release

The X tag is the recommended pin for consuming projects — it picks up security patches automatically while staying on the same major version contract.

Releases

Versioning follows SemVer over the container contract (see ADR 0010):

  • MAJOR — contract breaks: a tool removed or renamed, mount/env/entrypoint changes, egress model changes.
  • MINOR — additive changes: new tools, new services or features, template additions, and a major-version bump of a bundled tool (e.g. Terraform 1.x → 2.x). A bundled-tool major is additive for this image's contract, not a patch.
  • PATCH — fixes and routine Renovate pin/patch bumps, doc corrections.

The step-by-step release checklist is canonical in AGENTS.md → Versioning and Releases (#### Release checklist). It is not duplicated here — follow it there so the single source of truth stays consistent.

Prerelease (RC) flow

Tags shaped vX.Y.Z-rc.N are treated as prereleases by release.yml:

  • They skip the changelog gate — no matching ## [X.Y.Z] CHANGELOG section is required.
  • They publish only the exact version tag (e.g. 2.1.0-rc.1) to Docker Hub; the moving X.Y, X, and latest tags are not moved.
  • They create a GitHub prerelease with auto-generated notes.

Stable vX.Y.Z tags require the changelog section and publish the full X.Y.Z / X.Y / X / latest tag set.

Required repository secrets

Configure these in Settings → Secrets and variables → Actions:

Secret Purpose
DOCKERHUB_USERNAME Docker Hub account (image + layer-cache push/pull)
DOCKERHUB_TOKEN Docker Hub access token (Read & Write)
RENOVATE_TOKEN Classic PAT with repo + workflow scopes for the weekly Renovate workflow
CLOUDFLARE_ACCOUNT_ID Cloudflare account ID (found in the dashboard right sidebar)
CLOUDFLARE_API_TOKEN Cloudflare API token with Cloudflare Pages:Edit permission

Version management

All tool versions are pinned and updated automatically by Renovate, which runs weekly (Sunday) from .github/workflows/renovate.yml:

  • Dockerfile ARGs — each version has a # renovate: datasource=X depName=Y comment
  • .mise.toml — Python/Ruby via the native mise manager
  • .pre-commit-config.yaml — hook versions via the pre-commit manager
  • .github/workflows/ — action SHA pins via the github-actions manager
  • docs/requirements.txt — MkDocs Material via the pip_requirements manager

See renovate.json for grouping and automerge rules.

Documentation site

docs.yml builds the MkDocs site and deploys it to Cloudflare Pages with wrangler pages deploy site --branch=master. The public site lives at https://dev-container.pages.dev/.

Two things must hold for the public site to update:

  1. The workflow must actually run. It triggers only on pushes to master that touch its paths (docs/**, mkdocs.yml, docs/requirements.txt, and .github/workflows/docs.yml itself). A change to the deploy logic alone — such as the 2.2.1 migration to wrangler-action@v4 — would not redeploy if the workflow file is missing from paths, leaving the live site on the previous (broken) deploy until an unrelated docs change happens to trigger it. The workflow path is now included in paths to prevent this. To force a redeploy: gh workflow run docs.yml --ref master.
  2. Production branch = master. Cloudflare serves the production alias (dev-container.pages.dev) only from deployments whose branch matches the Pages project's configured production branch (dashboard → Pages → dev-container → Settings → Builds & deployments). Any other branch produces a preview deployment at a per-branch URL.