From ef2518d727ab092bf4ee321c7cd265038863475a Mon Sep 17 00:00:00 2001 From: Christian Tabedzki <35670232+tabedzki@users.noreply.github.com> Date: Mon, 2 Nov 2026 11:32:23 -0500 Subject: [PATCH 1/3] ci: publish a `dev` Docker image on every push to dev Trigger the Docker publish workflow on pushes to the dev branch (direct commits and PR merges). Each build is tagged with the moving `dev` tag and an immutable `dev-` tag; `latest` is now gated to tag refs so a dev build can never reach prod via Watchtower. A per-ref concurrency group cancels superseded dev builds so a stale build cannot overwrite `dev`. Document the `dev` image in the getting-started guide. Assisted-by: ClaudeCode:claude-opus-5-5 --- .github/workflows/docker-publish.yml | 15 ++++++++++++++- docs/getting-started.md | 4 ++++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index b945795..2cacd85 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -2,11 +2,20 @@ name: Build and Push Docker Image on: push: + branches: + - dev # Every commit/merge on dev publishes `dev` + `dev-` tags: - 'v*' # Trigger on tags that start with 'v' release: types: [published] +# Serialise builds per ref so an older dev build can never finish last and +# overwrite the `dev` tag with stale code. Superseded dev builds are +# cancelled; release builds always run to completion. +concurrency: + group: docker-publish-${{ github.ref }} + cancel-in-progress: ${{ github.ref == 'refs/heads/dev' }} + env: REGISTRY: ghcr.io IMAGE_NAME: ${{ github.repository }} @@ -40,9 +49,13 @@ jobs: # Pre-releases (PEP 440 a/b/rc/dev, e.g. v1.4.1rc1) get only their # own tag, never `latest`: prod pulls `latest` via Watchtower, so an # RC must not roll out on its own. contains() is case-insensitive. + # Pushes to the dev branch get the moving `dev` tag plus an immutable + # `dev-` tag, and never `latest`. tags: | type=ref,event=tag - type=raw,value=latest,enable=${{ !contains(github.ref_name, 'a') && !contains(github.ref_name, 'b') && !contains(github.ref_name, 'rc') && !contains(github.ref_name, 'dev') }} + type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/') && !contains(github.ref_name, 'a') && !contains(github.ref_name, 'b') && !contains(github.ref_name, 'rc') && !contains(github.ref_name, 'dev') }} + type=raw,value=dev,enable=${{ github.ref == 'refs/heads/dev' }} + type=sha,prefix=dev-,format=short,enable=${{ github.ref == 'refs/heads/dev' }} - name: Build and push Docker image id: build diff --git a/docs/getting-started.md b/docs/getting-started.md index fd3e355..bac7c18 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -46,6 +46,10 @@ docker run --rm \ The application will be available at `http://localhost:5008`. +To try unreleased changes, use `ghcr.io/m-beau/pixelmap:dev` instead. It is +rebuilt on every commit to the `dev` branch, and each build is also pinned as +`dev-` (e.g. `dev-697dbdd`). + :::{note} On Apple Silicon (M1/M2) or ARM Linux, add `--platform linux/amd64` to the Docker command. ::: From c54673b83e5af1f65e4ec274af0ab62e56932669 Mon Sep 17 00:00:00 2001 From: Christian Tabedzki <35670232+tabedzki@users.noreply.github.com> Date: Mon, 2 Nov 2026 11:35:06 -0500 Subject: [PATCH 2/3] ci: lint GitHub Actions workflows with actionlint Add a workflow that runs a pinned actionlint (with shellcheck for run blocks) on pushes and PRs to main/dev that touch .github/workflows. Assisted-by: ClaudeCode:claude-opus-5-5 --- .github/workflows/actionlint.yml | 36 ++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 .github/workflows/actionlint.yml diff --git a/.github/workflows/actionlint.yml b/.github/workflows/actionlint.yml new file mode 100644 index 0000000..05584a7 --- /dev/null +++ b/.github/workflows/actionlint.yml @@ -0,0 +1,36 @@ +name: Lint workflows + +on: + push: + branches: [ main, dev ] + paths: + - .github/workflows/** + pull_request: + branches: [ main, dev ] + paths: + - .github/workflows/** + workflow_dispatch: + +permissions: + contents: read + +jobs: + actionlint: + runs-on: ubuntu-latest + env: + ACTIONLINT_VERSION: '1.7.12' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + # Script and binary are both pinned to the same release so a new + # actionlint version can't change the rules without a reviewed bump. + # shellcheck is preinstalled on the runner, so `run:` blocks are + # checked too. + - name: Download actionlint + id: get_actionlint + run: bash <(curl -fsSL "https://raw.githubusercontent.com/rhysd/actionlint/v${ACTIONLINT_VERSION}/scripts/download-actionlint.bash") "${ACTIONLINT_VERSION}" + + - name: Run actionlint + run: ${{ steps.get_actionlint.outputs.executable }} -color From e6f3679bbcde1fc03d4821d070d7cea74886ad9e Mon Sep 17 00:00:00 2001 From: Christian Tabedzki <35670232+tabedzki@users.noreply.github.com> Date: Mon, 2 Nov 2026 11:36:10 -0500 Subject: [PATCH 3/3] ci: publish `latest` on every merge to main Pushes to main now build the image and tag it `latest` plus an immutable `main-`, so prod (Watchtower on `latest`) follows main without waiting for a version tag. Version tags keep their existing tagging. Superseded builds on any branch are cancelled so `latest`/`dev` can't be overwritten by a stale build. Assisted-by: ClaudeCode:claude-opus-5-5 --- .github/workflows/docker-publish.yml | 16 ++++++++++------ docs/getting-started.md | 3 +++ 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 2cacd85..ee15859 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -3,6 +3,7 @@ name: Build and Push Docker Image on: push: branches: + - main # Every merge to main publishes `latest` + `main-` - dev # Every commit/merge on dev publishes `dev` + `dev-` tags: - 'v*' # Trigger on tags that start with 'v' @@ -10,11 +11,11 @@ on: types: [published] # Serialise builds per ref so an older dev build can never finish last and -# overwrite the `dev` tag with stale code. Superseded dev builds are -# cancelled; release builds always run to completion. +# overwrite a moving tag (`dev`/`latest`) with stale code. Superseded branch +# builds are cancelled; tag/release builds always run to completion. concurrency: group: docker-publish-${{ github.ref }} - cancel-in-progress: ${{ github.ref == 'refs/heads/dev' }} + cancel-in-progress: ${{ startsWith(github.ref, 'refs/heads/') }} env: REGISTRY: ghcr.io @@ -49,11 +50,14 @@ jobs: # Pre-releases (PEP 440 a/b/rc/dev, e.g. v1.4.1rc1) get only their # own tag, never `latest`: prod pulls `latest` via Watchtower, so an # RC must not roll out on its own. contains() is case-insensitive. - # Pushes to the dev branch get the moving `dev` tag plus an immutable - # `dev-` tag, and never `latest`. + # Merges to main also get `latest` (so they deploy via Watchtower) + # plus an immutable `main-` tag for pinning/rollback. + # Pushes to dev get the moving `dev` tag plus `dev-`, and + # never `latest`. tags: | type=ref,event=tag - type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/') && !contains(github.ref_name, 'a') && !contains(github.ref_name, 'b') && !contains(github.ref_name, 'rc') && !contains(github.ref_name, 'dev') }} + type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' || (startsWith(github.ref, 'refs/tags/') && !contains(github.ref_name, 'a') && !contains(github.ref_name, 'b') && !contains(github.ref_name, 'rc') && !contains(github.ref_name, 'dev')) }} + type=sha,prefix=main-,format=short,enable=${{ github.ref == 'refs/heads/main' }} type=raw,value=dev,enable=${{ github.ref == 'refs/heads/dev' }} type=sha,prefix=dev-,format=short,enable=${{ github.ref == 'refs/heads/dev' }} diff --git a/docs/getting-started.md b/docs/getting-started.md index bac7c18..dde696f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -50,6 +50,9 @@ To try unreleased changes, use `ghcr.io/m-beau/pixelmap:dev` instead. It is rebuilt on every commit to the `dev` branch, and each build is also pinned as `dev-` (e.g. `dev-697dbdd`). +`latest` tracks the `main` branch and is rebuilt on every merge to `main`; +each of those builds is also pinned as `main-`. + :::{note} On Apple Silicon (M1/M2) or ARM Linux, add `--platform linux/amd64` to the Docker command. :::