[Koan-Bot]

🔁 repro: unconfirmed (KOAN_ROOT=/tmp/test-koan .venv/bin/pytest koan/tests/test_docker.py::TestDevImagePublishing -q) — no failing run observed before the fix

Summary

• Every push to main now builds and publishes a commit-pinned sha-<full-commit-sha> image to GHCR, plus a rolling devel tag
• A newer push cancels an in-flight dev build, so devel cannot regress to an older commit
• Release-owned tags (stable, latest, semver) are never minted by the dev workflow
• Docs and workflow comments describe the dev-image flow and the manual publish workflow's remaining role

Why

Fixes merged between releases were not pullable without a manual dispatch of the publish workflow. Publishing a commit-traceable image on every push to main makes those fixes available immediately (#2529).

How

• Added publish-dev-container.yml, triggered on push to main, which calls the shared docker-publish.yml worker
• Passed tags type=sha,format=long,prefix=sha- and type=raw,value=devel
• Set a concurrency group with cancel-in-progress: true to prevent stale builds from overwriting devel
• Updated the header comments in docker-publish.yml and publish-container.yml to name the new workflow
• Updated docs/setup/docker.md and docs/operations/maint.md to describe the sha and devel tags

Testing

• New TestDevImagePublishing class in koan/tests/test_docker.py checks that a main-push workflow publishes a sha-tagged image
• Tests check that no main-push publish workflow mints semver, stable, or latest tags
• Tests check that every main-push publish workflow sets cancel-in-progress: true

Limitations & Risk

• A cancelled commit gets no sha- tag; only a later commit's image contains its changes
• The workflow only runs after merge to main; it does not validate images on PRs

Out of scope

• Release tagging and release.yml are unchanged
• The manual publish-container.yml dispatch behaviour is unchanged apart from its documentation

Not tested

• The actual GHCR push and tag resolution are not exercised; tests only parse the workflow YAML
• The docs/ text changes have no test coverage

Fixes #2529

---

Quality Report

Changes: 6 files changed, 119 insertions(+), 18 deletions(-)

Code scan: clean

Tests: failed (4 failed, 403
tests)

Branch hygiene: clean

Generated by Skuggi

[Father-Koan]

PR Review — fix: Publsh dev docker images

Adds an automatic main-push workflow that publishes sha-<commit> and :devel images through the shared docker-publish worker, but the manual publish workflow still defaults to devel and can be run on incubating, which breaks the new ":devel is always the newest main build" guarantee.

• Reuses the docker-publish.yml worker unchanged, so the image-clean guard and build cache apply to dev images with no duplication
• cancel-in-progress concurrency correctly stops an older in-flight run from overwriting :devel after a newer one
• Tags are only type=sha and type=raw, so metadata-action's latest=auto flavor won't mint :latest on a branch push
• The new tests check the release-tag ban and the concurrency setting across every main-push publish workflow, not just this file
• Docs in docker.md and maint.md are updated together and explain the cancelled-commit trade-off honestly

Open Questions

1. Should :devel be reserved for the automatic main build, or is overwriting it with a manual incubating dispatch an intended escape hatch?

---

🟡 Important

1. Manual dispatch still defaults to `devel`, so `:devel` can regress
.github/workflows/publish-container.yml:18

This PR makes :devel mean "rolling, always the newest main build" and says it "never regresses to a stale commit" (docs/setup/docker.md:97-100, publish-dev-container.yml:18-20). The sibling manual workflow breaks that promise, and this PR edits that workflow without fixing it.

• publish-container.yml can still be dispatched on incubating (case main|incubating).
• Its tag input still defaults to devel.
• It runs outside the publish-dev-container concurrency group.

If an operator dispatches it on incubating and keeps the default, :devel gets overwritten with the incubating tree. That tree is usually behind main. Anyone who pulls :devel to get a fix merged after the release (the use case in #2529) silently gets an image without that fix. It stays that way until the next push to main.

No check catches this. TestDevImagePublishing only looks at main-push workflows, and the validator in publish-container.yml only rejects stable/latest/semver.

Fix, either way:

• Make devel reserved to the automatic workflow. Change the manual default to something like test, and add devel to the reserved-tag regex on line 54.
• Or allow devel only when github.ref_name == main.

Then update the docker.md paragraph that says the manual workflow's default is devel.

Traced failure: Operator opens Actions → 🐳 Publish Container, picks ref incubating, accepts default tag devel → validate job passes (case main|incubating, tag not in the reserved regex) → docker-publish.yml pushes ghcr.io/anantys-oss/koan:devel built from incubating → make docker-pull-up KOAN_IMAGE=...:devel pulls an image without fixes that are on main but not yet on incubating, even though the docs say :devel is always the newest main build.

        default: devel

---

Checklist

• No hardcoded secrets (uses GITHUB_TOKEN via secrets: inherit)
• Release-owned tags (stable/latest/semver) never minted outside release.yml
• Rolling devel tag semantics consistent across publish workflows — warning ＃1
• Least-privilege workflow permissions (contents: read, packages: write)
• Docs updated alongside behavior change
• No privacy leaks or undeclared durable-spec edits

---

Automated review by Skuggi HEAD=ffc8317 1 min 22s

[Father-Koan]

Warning

Important issues found.

• Manual dispatch still defaults to devel, so :devel can regress

[Koan-Bot]

PR Review — fix: Publsh dev docker images

Adds an automatic main-push workflow that publishes immutable sha-<commit> tags and a rolling :devel through the shared docker-publish worker. The manual publish workflow can still overwrite :devel from incubating, which breaks the docs' new promise that :devel is "always the newest main build".

• Reuses docker-publish.yml unchanged, so the dev, manual and release flows still share one build/push path
• Passes only type=sha and type=raw rules, so metadata-action never mints :latest on a branch push
• cancel-in-progress concurrency stops an older run from overwriting :devel after a newer push to main
• The new tests scan every main-push publish workflow for release tags and concurrency, not just the new file, and the PyYAML on: True quirk is handled
• docker.md still claims docker-publish.yml runs the image-clean guard, which the xfail test shows it does not

Open Questions

1. Should :devel be reserved for the automatic main build (making the manual workflow default to another tag), or is overwriting it from incubating an intended escape hatch? If so, the docs' 'never regresses' wording should go.

---

🟡 Important

1. Manual dispatch can still overwrite `:devel` with a non-main tree, breaking the new guarantee
.github/workflows/publish-container.yml:18

This PR changes what :devel promises. The docs now say it is "rolling, always the newest main build" and that it "never regresses to a stale commit" (docs/setup/docker.md, and the comment block in publish-dev-container.yml). The manual workflow sitting next to it still breaks that promise, and this PR edits that file without closing the gap:

• publish-container.yml still accepts the incubating ref (case main|incubating, line ~35).
• Its tag input still defaults to devel.
• It runs outside the publish-dev-container concurrency group, so cancel-in-progress does not protect against it.

The incubating tree usually trails main. An operator who dispatches on it and keeps the default silently replaces :devel with an image that lacks post-release fixes. That is exactly the #2529 use case this PR is meant to serve. The image stays wrong until the next push to main.

The same race exists on main. A manual build of commit X that finishes after the automatic build of a newer commit Y leaves :devel pointing at X.

Nothing catches this. TestDevImagePublishing only looks at workflows that run on push to main. The tag validator here (line ~54) only rejects stable/latest/semver.

Fix, either:

• Reserve devel for the automatic workflow: change the default to something like test, add devel to the reserved-tag regex, and add a test asserting that no workflow_dispatch publisher defaults to devel.
• Or keep the manual devel path but drop the "always newest main / never regresses" wording from the docs.

Either way, update the docker.md paragraph that still says the manual workflow defaults to devel. (This confirms the prior automated review's finding; the current diff does not address it.)

Traced failure: An operator opens Actions → 🐳 Publish Container, picks ref incubating and keeps the default tag devel. The validate job passes: incubating matches main|incubating, and devel does not match ^(stable|latest|v?[0-9]+...)$. docker-publish.yml then pushes ghcr.io/anantys-oss/koan:devel built from incubating. A user who runs make docker-pull-up KOAN_IMAGE=...:devel to get a fix merged to main after the release gets an image without that fix, even though docker.md says :devel is always the newest main build.

        default: devel

🟢 Suggestions

1. Doc says docker-publish.yml runs the image-clean guard; it doesn't, and the PR extends that claim to dev images
docs/setup/docker.md:228-231

The edited sentence now says docker-publish.yml is "the shared build/push workflow behind the release, dev, and manual-publish flows" and that it runs scripts/verify_image_clean.sh. The worker has no such step: it is checkout → buildx → login → metadata → build-push. The repo knows this: TestImageCleanGuard.test_docker_publish_workflow_runs_the_guard is xfail, because a maintainer still has to wire it (#2383).

The inaccuracy predates this PR, but this PR rewrites the line. It also raises the stakes: images used to be published only on a manual or release dispatch, and now one is published on every push to main. Reword it to describe the current state (the guard is not yet wired), or wire the guard in the same change.

The prior automated review's point that "the image-clean guard … applies to dev images" is incorrect for the same reason.

This is enforced at build time: `docker-publish.yml` (the shared build/push
workflow behind the release, dev, and manual-publish flows) runs
`scripts/verify_image_clean.sh` against the freshly built image and fails the
build if any of that tooling is found under `/app`. See issue #2383.

---

Checklist

• No hardcoded secrets (GITHUB_TOKEN via secrets: inherit)
• Release-owned tags (stable/latest/semver) never minted outside release.yml
• Rolling devel tag semantics consistent across publish workflows — warning ＃1
• Least-privilege workflow permissions (contents: read, packages: write)
• Docs accurately describe the shipped behavior — warning ＃1, suggestion ＃1
• No privacy leaks or undeclared durable-spec edits
• New tests use KOAN_ROOT-safe, boundary-free checks (YAML parsing only, no real external calls)

---

To rebase and address feedback, mention me: @Koan-Bot rebase critical (fixes 🔴 only), @Koan-Bot rebase important (fixes 🔴 + 🟡), or @Koan-Bot rebase --fix for all. (A bare @Koan-Bot rebase only rebases onto the base branch.)

---

Automated review by Skuggi HEAD=ffc8317 2 min

[Koan-Bot]

Warning

Important issues found.

• Manual dispatch can still overwrite :devel with a non-main tree, breaking the new guarantee

[Koan-Bot]

Rebase with requested adjustments

Branch koan.atoomic/fix-issue-2529 was rebased onto main and review feedback was applied.

Changes applied

• Both review points are addressed. Per the task rules, I did not run the tests, including the new one.
• Review items:
• 1. Manual dispatch defaulted to devel, so :devel could regress (request; both reviewers raised it).
• 2. docker.md claimed docker-publish.yml runs the image-clean guard, but it doesn't (request).
• .github/workflows/publish-container.yml (header, inputs.tag, Validate tag step): the manual workflow can no longer publish devel, which now belongs only to publish-dev-container.yml (per reviewers' option 1). The tag default changed from devel to test, and devel was added to the reserved-tag regex with the release tags. The input description, header comment and error messages were updated to match.
• koan/tests/test_docker.py (TestDevImagePublishing.test_manual_publish_cannot_overwrite_devel): new test, as reviewers requested. It fails if any workflow_dispatch publisher defaults to devel, or if publish-container.yml's reserved-tag regex leaves out devel.
• docs/setup/docker.md:108-111: the manual-workflow paragraph now says the default tag is test and that devel is reserved.
• docs/operations/maint.md:74-77: same fix (default test, devel refused).
• docs/setup/docker.md:229-233: reworded the image-clean guard paragraph. verify_image_clean.sh is not yet wired into docker-publish.yml, so published images rely on .dockerignore alone (work tracked in Release workflow must exclude repo dev tooling (CLAUDE.md, AGENTS.md, .claude/) from the final Docker image #2383). This matches the existing xfail on `test_docker_

Stats

6 files changed, 152 insertions(+), 30 deletions(-)

Actions performed

• Already-solved check: negative (confidence=high, reasoning=None of the last 30 commits on main adds an automatic dev-image publish workflow that runs on push t)
• Rebased koan.atoomic/fix-issue-2529 onto upstream/main
• Applied review feedback
• Pre-push CI check: previous run passed
• Force-pushed koan.atoomic/fix-issue-2529 to origin
• Private review gate skipped: already reviewed head ffc8317 (clean)
• CI check enqueued in ## CI (async)

CI status

CI will be checked asynchronously.

---

Automated by Skuggi

[atoomic]

@Master-Koan rr

[Master-Koan]

@Father-Koan:

Resolved at current head. Manual default now test. devel added to reserved regex (publish-container.yml:55). New test guards it. Remaining gap: sha- tags still allowed manually.

[Master-Koan]

PR Review — fix: Publsh dev docker images

Adds a main-push workflow that publishes sha-<commit> and a rolling :devel through the shared docker-publish worker, and reserves devel in the manual publisher so it can no longer regress. Both earlier blocking findings are resolved at this head; what remains is that the manual workflow can still mint sha- tags.

• Both earlier review points are fixed: manual dispatch now defaults to test and refuses devel, and docker.md no longer claims the image-clean guard is wired (this matches the existing xfail)
• concurrency with cancel-in-progress correctly stops an older build from overwriting :devel, and the docs state the cost (cancelled commits get no sha- tag)
• docker-publish.yml is reused unchanged and metadata-action's latest=auto won't add latest for raw/sha tags on a branch push, so release-owned tags stay with release.yml
• Tracing the YAML and regex parsing by hand, the four new TestDevImagePublishing tests pass against these workflows; the quality report's 4 failures were not identified and look unrelated to this change

Open Questions

None — no open questions.

---

🟢 Suggestions

1. Manual dispatch can still overwrite a `sha-` tag
.github/workflows/publish-container.yml:55

The reserved-tag regex now refuses devel, but it still accepts any sha-… tag. The format check ^[a-z0-9][a-z0-9._-]{0,127}$ lets sha-<40 hex> through.

The docs (docs/setup/docker.md) and the header of publish-dev-container.yml now describe sha-<full-commit-sha> as immutable, pinned to that exact main commit. A maintainer who dispatches 🐳 Publish Container on incubating with tag=sha-<some main sha> would replace that image with a build of a different tree. Anyone pinned to that tag for traceability would then pull the wrong code without any warning.

This takes a deliberate (or copy-paste) choice of tag. That is unlike the old devel default, which made the mistake the easy path. So this is non-blocking.

Fix: reserve the sha- namespace in the same regex as the other owned tags, for example ^(stable|latest|devel|sha-.*|v?[0-9]+(\.[0-9]+){1,2})$. Then extend test_manual_publish_cannot_overwrite_devel to cover it.

if printf '%s' "$TAG" | grep -qE '^(stable|latest|devel|v?[0-9]+(\.[0-9]+){1,2})$'; then

2. The reserved-tag check splits the regex text on `|` instead of running it
koan/tests/test_docker.py:745-749

The test pulls the ERE out of the Validate tag step, then checks "devel" in group(1).split("|"). This checks how the regex is spelled, not what it does. A behaviour-preserving rewrite of the pattern would make the test fail even though devel is still refused, for example ^(stable|latest|dev(el)?|…)$, or devel placed in its own grep line.

The test already extracts the pattern, so it can test behaviour instead. Strip the shell quoting, then assert re.fullmatch(pattern, "devel") (POSIX ERE and Python re agree for this pattern). You could also feed devel / sha-abc / test through grep -E with subprocess, as the existing bash -n tests do. That also covers the sha- suggestion above for free.

reserved = re.search(r"grep -qE '(\^\([^']*)'", manual.split("Validate tag", 1)[1])
assert reserved and "devel" in reserved.group(1).split("|"), (

3. Dev images publish whether or not the commit's tests pass
.github/workflows/publish-dev-container.yml:10-12

The workflow runs on every push to main with no dependency on tests.yml, which runs on the same trigger. When a merge breaks main, the next :devel (and its sha- tag) still ships that commit's image. Users who follow the new docs advice to pull :devel for post-release fixes would get it.

This is a reasonable trade-off for a dev channel, and the docs call :devel the "newest main build", not a verified one. If you want the channel gated, trigger on workflow_run: { workflows: ["Tests"], types: [completed], branches: [main] } and require github.event.workflow_run.conclusion == 'success'. Note that this changes the ref to workflow_run.head_sha, so the type=sha tag needs that value. Otherwise, add one line to docs/setup/docker.md saying :devel is ungated.

on:
  push:
    branches: [main]

---

Checklist

• Release-owned tags (stable/latest/semver) never minted outside release.yml
• devel owned by a single workflow and cannot regress
• Commit-pinned sha- tags cannot be overwritten from another tree — suggestion ＃1
• Least-privilege workflow permissions (contents: read, packages: write)
• No hardcoded secrets or shell interpolation of dispatch input
• Tests check behaviour rather than spelling of config text — suggestion ＃2
• Docs describe the shipped behaviour
• No privacy leaks or undeclared durable-spec edits

---

Automated review by Skuggi HEAD=846e81d 2 min 19s

[Master-Koan]

Tip

No blocking issues found — ready to merge.

[Master-Koan]

Rebase with requested adjustments

Branch koan.atoomic/fix-issue-2529 was rebased onto main and review feedback was applied.

Changes applied

• I made four changes to address the reviews. Per instructions, I didn't run the tests; the caller runs them.
• .github/workflows/publish-container.yml:55 — the reserved-tag regex now also blocks sha-.*. A manual dispatch can no longer overwrite a commit-pinned sha- image with a build of a different tree (suggestion Fix Python 3.8 compat, journal path, BACKLOG status #1). I updated the header comment (lines 9-11), the tag input description (line 17) and the step comment (lines 55-56) to match.
• koan/tests/test_docker.py:746-758 (test_manual_publish_cannot_overwrite_devel) — the test no longer checks how the regex is spelled. It now runs the extracted pattern with re.fullmatch:
• it must block devel, a full sha- tag, stable, latest and v1.2;
• it must allow test and pr-123.
• This covers the test-behaviour request (suggestion Add signal trap for clean shutdown in run.sh #2) and the sha- coverage from suggestion Fix Python 3.8 compat, journal path, BACKLOG status #1.
• docs/setup/docker.md:102-103 — added a line saying :devel is not gated on tests, with a tip to pin a known-good sha- tag. This is the docs option the reviewer offered (suggestion Add crash recovery on startup (US 3.3) #3).
• docs/setup/docker.md:112-113 and docs/operations/maint.md:74-75 — both docs now say sha-* is reserved alongside devel, so they match the new regex.

Not changed (and why)

• Manual dispatch defaulting to devel (the change requests from Father-Koan and Koan-Bot): already fixed in an earlier pass. At .github/workflows/publish-container.yml:19 the default is now test, and line 55 already blocks devel.
• Making dev images wait fo

Stats

6 files changed, 165 insertions(+), 30 deletions(-)

Actions performed

• Already-solved check: negative (confidence=high, reasoning=main has no publish-dev-container.yml or any recent commit that publishes images automatically on pu)
• Rebased koan.atoomic/fix-issue-2529 onto origin/main
• Applied review feedback
• Pre-push CI check: previous run passed
• Force-pushed koan.atoomic/fix-issue-2529 to fork-Koan-Bot
• Private review gate skipped: disabled by config
• CI check enqueued in ## CI (async)

CI status

CI will be checked asynchronously.

---

Automated by Skuggi