Skip to content

feat: add the release-image action - #85

Open
uniqueg wants to merge 6 commits into
mainfrom
feat/84-release-image
Open

uniqueg wants to merge 6 commits into
mainfrom
feat/84-release-image

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds the composite action actions/release-image, which releases an image that the release workflow pushed by digest and scanned. The caller logs in to the registry and grants id-token: write and attestations: write. In this order, the action:

  1. checks the image name (fully qualified, without tag or digest), the digest format (sha256: + 64 hex), the tag (a release version after tag-prefix, as check-release accepts it, at most 128 characters), and that the digest exists in the image's repository;
  2. fails if X.Y.Z already points to another digest; a re-run with the same digest passes;
  3. attests build provenance (actions/attest-build-provenance v4.2.2, pushed to the registry);
  4. signs the digest with cosign, keyless (sigstore/cosign-installer v4.1.3);
  5. checks the version tag again, then tags X.Y.Z, then decides latest and tags it for the highest stable release. Tags are copied as is (--prefer-index=false) and each one is checked to resolve to the digest. Each gh and docker call times out after 300 seconds.

Inputs: image, digest, tag (default github.ref_name), tag-prefix (default v), latest (auto or false), token.
Outputs: version, latest, tags.

latest rule: it uses publish-release's is_latest and parse_version and check-release's VERSION. They are loaded from the sibling scripts, not copied, so they can't drift apart.

  • Pre-releases never get latest.
  • A patch of an older line doesn't move it back.
  • From 1.0.0 it is the same release as GitHub's "Latest": releases count with GitHub's pre-release flag, as in publish-release.
  • Below 1.0.0, the highest stable version still gets latest, as the org's workflows do today. publish-release makes every 0.x release a GitHub pre-release, so GitHub's "Latest" stays empty there.
  • With a prefix, only same-prefix releases and tags count.
  • A higher stable tag whose image is already tagged in the registry, but whose release isn't published yet, keeps latest. Since X.Y.Z is tagged before the decision, this narrows the race between concurrent releases. Closing it fully needs the documented concurrency group, because registries can't set a tag atomically only if it is unchanged.

The README documents the digest hand-over for matrix jobs: one artifact per matrix entry, fail-fast: false, and per-image concurrency groups.

Part of #84. The adoption checkbox stays open until a repo switches to the action after the next release.

Verification

  • bash tests/release-image/test.sh: 44 tests OK. They use stand-ins for gh and docker and cover settings, the version check, the latest rule (also against publish.is_latest), tagging, error paths, and the script run as the action runs it. Branch coverage of release.py is 99%; only the __main__ guard is missed, and it runs in a subprocess test.
  • bash tests/check-release/test.sh and bash tests/publish-release/test.sh: OK.
  • ruff check, ruff format --check and mypy --strict --python-version 3.10 on the new files: clean. The repo has no config for these, so I ran them with defaults.
  • pre-commit (--all-files): passed for all hooks except gitleaks, actionlint and shellcheck, which couldn't install in the sandbox. I ran actionlint 1.7.12 (with shellcheck) and shellcheck 0.11.0 directly: clean. CI runs gitleaks.
  • New CI steps in the test job:
    • the unit tests;
    • the script against a local registry:3.0.0 with two single-manifest images and this repo's real releases. Cases: a new highest version (latest), a re-run, another digest of a published version (fails), a lower version (latest untouched) and latest: false;
    • the action itself once, with a moved version. It must fail at its first step and leave the tags unchanged.
  • Attesting and signing aren't run in CI. They need id-token: write and would publish attestations and Rekor entries for test images, so the first adopter's fork dry run covers them.
  • CI result: Lint, Test, CodeQL and CI passed are green on 8f2e8f1, the head after both rounds of Sourcery fixes, and the Sourcery review check passes with no open threads; the local-registry steps and the action wiring step ran and passed.

Declined review findings

  • Concurrent-release race between the second version check and imagetools create, and between two simultaneous latest decisions (Sourcery): a window of seconds. Registries have no atomic "set if unchanged", so the README asks callers for a concurrency group, as the existing copies already use.
  • Sourcery's "use GitHub's pre-release flag": followed from 1.0.0. Below 1.0.0 the flag is derived from the version, on purpose; otherwise 0.x repositories would never get a latest image.
  • Sourcery's security note on subprocess.run: a false positive. It gets an argument list with no shell, a fixed program, and validated values. It is now suppressed inline with nosemgrep, with the reason in a comment.
  • Sourcery's "assert the reason the action fails in CI": the job can't read a composite action's error. The script step asserts the exact message for the same inputs, and a passing action run would need id-token: write.

Open questions

None.

🤖 Generated with Claude Code

uniqueg and others added 4 commits November 16, 2026 07:00
Add the composite action actions/release-image, which releases an image
pushed by digest: it checks the image name, the digest and the tag, fails
if the version's image tag points to another digest (a re-run with the
same digest passes), attests the build provenance (pushed to the
registry), signs the digest with cosign (keyless), and tags it X.Y.Z and,
for the highest stable release, latest, checking that each tag points to
the digest.

The latest decision uses publish-release's is_latest and check-release's
release versions, loaded from the scripts next to it, so that the rules
can't drift apart. Inputs tag-prefix and latest (auto or false) cover
prefixed tags such as foca-plugins'. The README documents the digest
hand-over for matrix jobs.

Part of #84

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Run the script's unit tests, then the script against a local registry
with two images and this repository's real releases (new highest version,
re-run, another digest, lower version, latest: false), and the action
itself once, with a version that points to another digest, so that it
stops before attesting and signing.

Part of #84

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review fixes:

- Tag with --prefer-index=false: by default, buildx wraps a single
  manifest in a new index with another digest, which moved X.Y.Z and
  then failed the digest check.
- Check the version's tag again right before tagging, as another run may
  have tagged it while this one attested and signed.
- Count only releases that are the prefix plus a release version (as
  check-release accepts it), with stability from check-release's
  VERSION instead of publish-release's private ranks; with an empty
  prefix, v tags no longer count.
- README: fail-fast: false and a longer artifact retention for matrix
  jobs, first-line digest read, concurrency cancellation, and the
  latest rule below 1.0.0 in the docstring.
- Tests for gh and create failures, loose versions and the above.

Part of #84

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Second review round:

- Count published releases as publish-release reads their versions
  (e.g., v2.0), so that the image's latest follows GitHub's Latest from
  1.0.0; only a further v after the prefix is excluded.
- Check the version's tag before deciding latest, so that a failed check
  logs no latest decision.
- Describe the re-check and the copy as is in the README and docstring.
- CI: push single image manifests (no attestations) and assert it, so
  that the local registry test covers --prefer-index=false.

Part of #84

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg uniqueg self-assigned this Nov 16, 2026
@sourcery-ai

sourcery-ai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

API

Define the composite action’s public inputs, outputs, permissions assumptions, and ordered validation, attestation, signing, and tagging steps.

  • actions/release-image/action.yml L1-100

Implement the release script’s shared version rules, validation, registry checks, latest decision, tagging, and outputs behind the action interface.

  • actions/release-image/release.py L1-626

Configuration

Wire unit, local-registry, and action-level release-image checks into the CI test job.

  • .github/workflows/ci.yml L281-395

Documentation

Document release-image behavior, latest selection, usage and permissions, matrix digest hand-off, inputs, outputs, and tests.

  • actions/release-image/README.md L1-239

List release-image among the repository’s actions and its local test command.

  • README.md L120-123, L140-142, L156

Tests

Add unit tests for settings, digest safety, latest decisions, tagging, failures, and execution of the release script.

  • tests/release-image/test.sh L1-9
  • tests/release-image/test_release.py L1-790

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@uniqueg
uniqueg marked this pull request as ready for review November 16, 2026 06:19

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 1 security issue, and 5 other issues

Security issues:

  • Detected subprocess function 'run' without a static string. If this data can be controlled by a malicious actor, it may be an instance of command injection. Audit the use of this call to ensure it is not controllable by an external resource. You may consider using 'shlex.escape()'. (link)
Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="actions/release-image/release.py" line_range="474-486" />
<code_context>
+    # Again, right before tagging: another run may have tagged the version
+    # since the first check (attesting and signing take minutes)
+    check(settings, docker)
+    latest, reason = is_latest(settings, gh, docker)
+    print(
+        f"::notice title={TITLE}::latest {'set' if latest else 'not set'}: {reason}",
+        file=sys.stderr,
+    )
+    source = f"{settings.image}@{settings.digest}"
+    references = [f"{settings.image}:{settings.version}"]
+    if latest:
+        references.append(f"{settings.image}:latest")
+    for reference in references:
+        # Copy the source as is: by default, buildx wraps a single manifest
+        # in a new index, with another digest
+        docker(
+            [
+                "buildx",
</code_context>
<issue_to_address>
**Older release overwrites latest**

When two workflows releasing the same image overlap without sharing a concurrency group, and the lower version decides `latest` before the higher version's image tag exists, `is_latest` can return true for the lower release before the higher release has tagged its image; the higher run then writes its digest to `latest`, and the lower run's later `imagetools create` overwrites it, so users pulling `latest` receive the older image.

Serialize the decision and tag write across all workflows that release the same image, or otherwise ensure the latest decision is still valid immediately before updating `latest`.
</issue_to_address>

### Comment 2
<location path="actions/release-image/release.py" line_range="200" />
<code_context>
+                f"Invalid repository '{self.repository}': expected <owner>/<repo>"
+            )
+        try:
+            check_release.release_version(self.tag, self.prefix)
+        except check_release.CheckError as error:
+            raise ReleaseError(str(error)) from error
</code_context>
<issue_to_address>
**Accepted tags fail after signing**

When a release version exceeds the registry's 128-character image-tag limit, `Settings.validate` and `check_release.release_version` accept the version, so the action passes an invalid image tag downstream. The registry rejects it after the action has performed release side effects, and the release fails.

Reject image tags longer than 128 characters during validation, before performing release side effects.
</issue_to_address>

### Comment 3
<location path="actions/release-image/release.py" line_range="365" />
<code_context>
+    # Rank of "no pre-release" in publish-release's version keys
+    stable = publish_release.parse_version("0.0.0")[3]
+    return [
+        {"tag_name": version, "prerelease": key[3] != stable, "draft": False}
+        for name in names
+        if name.startswith(settings.prefix)
</code_context>
<issue_to_address>
**GitHub prereleases get incorrect latest status**

When a stable-looking release tag is explicitly published with `prerelease: true`, `_published` infers the prerelease flag from the version instead of GitHub's flag, so `is_latest` makes the wrong decision and the image's `latest` tag diverges from GitHub's Latest decision.

Use each GitHub release's actual prerelease flag when building the entries passed to `is_latest`.

Also at `actions/release-image/release.py:422`.
</issue_to_address>

### Comment 4
<location path="actions/release-image/release.py" line_range="386-387" />
<code_context>
+        a pre-release (`a`, `alpha`, `b`, `beta`, `rc`); major version 0
+        included.
+    """
+    match = check_release.VERSION.fullmatch(version)
+    return match is not None and match["pre"] is None
+
+
</code_context>
<issue_to_address>
**Higher pending image is ignored**

When a higher unpublished stable tag uses the two-component format accepted by publish-release and its image tag exists, `_is_stable` uses check-release's three-component version pattern, so the pending-tag scan skips the higher image and `is_latest` tags the lower release as `latest`.

Use publish-release's version rules to recognize stable pending tags in `_is_stable`.

Also at `actions/release-image/release.py:441`.
</issue_to_address>

### Comment 5
<location path="actions/release-image/release.py" line_range="219" />
<code_context>
+        ReleaseError: If the program fails; with its standard error.
+    """
+    command = [program, *args]
+    result = subprocess.run(command, capture_output=True, text=True, check=False)
+    if result.returncode != 0:
+        raise ReleaseError(f"{shlex.join(command)} failed: {result.stderr.strip()}")
</code_context>
<issue_to_address>
**Hung CLI blocks release**

When a `gh` or `docker` process hangs while waiting on a service, `subprocess.run` waits indefinitely for `gh` or `docker`; if a registry or API call hangs, the release job remains blocked and consumes its runner until the job-level timeout. `_run` does not set a timeout or handle `TimeoutExpired`.

Set a bounded timeout for CLI calls and convert timeout expiry into a clear release error.
</issue_to_address>

### Comment 6
<location path="actions/release-image/release.py" line_range="219" />
<code_context>
    result = subprocess.run(command, capture_output=True, text=True, check=False)
</code_context>
<issue_to_address>
**security (python.lang.security.audit.dangerous-subprocess-use-audit):** Detected subprocess function 'run' without a static string. If this data can be controlled by a malicious actor, it may be an instance of command injection. Audit the use of this call to ensure it is not controllable by an external resource. You may consider using 'shlex.escape()'.

*Source: opengrep*
</issue_to_address>

Sourcery assessment

Needs a human reviewer. 6 findings to address first, and if the action releases the wrong digest or makes the wrong tag decision, it can publish that digest under a version or latest tag and create provenance attestations and a cosign signature for it. Reverting the action does not erase registry tags or public attestations and transparency-log entries, though the affected image release is bounded.

Blocking findings: actions/release-image/release.py:486, actions/release-image/release.py:200, actions/release-image/release.py:365, actions/release-image/release.py:387, actions/release-image/release.py:219, and 1 more


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread actions/release-image/release.py Resolved
Comment thread actions/release-image/release.py Resolved
Comment thread actions/release-image/release.py Resolved
Comment thread actions/release-image/release.py Resolved
Comment thread actions/release-image/release.py Resolved
Comment thread actions/release-image/release.py Resolved
- Tag X.Y.Z first, then decide latest, so that a concurrent lower
  release sees the higher version's image tag; document that registries
  can't make the latest write atomic and need the concurrency group.
- From 1.0.0, use GitHub's pre-release flag of releases, as
  publish-release does; below 1.0.0, the version's.
- Recognise pending tags in publish-release's format (e.g., v1.3).
- Reject versions longer than an image tag may be (128 characters).
- Time out gh and docker calls after 300 seconds.

Part of #84

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg

uniqueg commented Nov 16, 2026

Copy link
Copy Markdown
Member Author

@sourcery-ai review

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 1 security issue, and 3 other issues

Security issues:

  • Detected subprocess function 'run' without a static string. If this data can be controlled by a malicious actor, it may be an instance of command injection. Audit the use of this call to ensure it is not controllable by an external resource. You may consider using 'shlex.escape()'. (link)
Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="actions/release-image/release.py" line_range="106-294" />
<code_context>
+NOT_FOUND = re.compile(r"not found|manifest unknown", re.IGNORECASE)
</code_context>
<issue_to_address>
**Registry errors can look like missing tags**

When the registry returns an error containing `not found` while the version tag exists, for example during a transient or provider-specific lookup failure, a transient or registry-specific error containing `not found` is treated as an absent tag, so `check` can pass and `tag` can overwrite an existing version tag with another digest, violating the immutable-version guarantee.

Recognize only confirmed missing-manifest responses for the relevant reference, and propagate other registry failures instead of treating them as an absent tag.
</issue_to_address>

### Comment 2
<location path=".github/workflows/ci.yml" line_range="296-306" />
<code_context>
+        env:
+          IMAGE: localhost:5000/release-image-test
+        run: |
+          docker run --detach --publish 5000:5000 --name registry registry:3.0.0
+          for name in a b; do
+            context="${RUNNER_TEMP}/image-${name}"
+            mkdir -p "${context}"
+            echo "${name}" > "${context}/${name}"
+            # A single image manifest (no attestations, so no index), which
+            # buildx would wrap in a new index unless told not to
+            printf 'FROM scratch\nCOPY %s /\n' "${name}" \
+              | docker build --provenance=false --sbom=false \
+                --tag "${IMAGE}:build-${name}" --file - "${context}"
+            docker push "${IMAGE}:build-${name}"
+            type="$(docker buildx imagetools inspect --raw "${IMAGE}:build-${name}" \
+              | jq -r .mediaType)"
</code_context>
<issue_to_address>
**Registry startup flakes CI**

When the detached registry has not started accepting requests before the first push, `docker push` gets a connection error, so the CI test job fails before exercising the release script.

Wait for the registry to accept connections before building and pushing images.
</issue_to_address>

### Comment 3
<location path=".github/workflows/ci.yml" line_range="379" />
<code_context>
+          OUTCOME: ${{ steps.moved-version.outcome }}
+          IMAGE: localhost:5000/release-image-test
+        run: |
+          if [[ "${OUTCOME}" != failure ]]; then
+            echo "::error::Expected the release of the moved version to fail, got ${OUTCOME}"
+            exit 1
</code_context>
<issue_to_address>
**Unrelated action failures pass**

When the action fails for a reason other than detecting that the version tag points to another digest, the “Expect the release of the moved version to fail” check at `.github/workflows/ci.yml:379` accepts any nonzero action outcome; an action that fails unconditionally before checking the version also leaves the existing tag unchanged, so this test passes without verifying the moved-version check or input wiring.

Assert the expected version-conflict error (or otherwise verify that the first check step failed for that reason).
</issue_to_address>

### Comment 4
<location path="actions/release-image/release.py" line_range="230-232" />
<code_context>
        result = subprocess.run(
            command, capture_output=True, text=True, check=False, timeout=TIMEOUT
        )
</code_context>
<issue_to_address>
**security (python.lang.security.audit.dangerous-subprocess-use-audit):** Detected subprocess function 'run' without a static string. If this data can be controlled by a malicious actor, it may be an instance of command injection. Audit the use of this call to ensure it is not controllable by an external resource. You may consider using 'shlex.escape()'.

*Source: opengrep*
</issue_to_address>

Sourcery assessment

Needs a human reviewer. 4 findings to address first, and if the version or latest decision is wrong, the action can publish an incorrect image tag and create a signature and provenance attestation for that digest. Tags can be corrected, but downstream pulls may already have used them, and published signing or attestation records are not undone by reverting.

Blocking findings: actions/release-image/release.py:294, .github/workflows/ci.yml:306, .github/workflows/ci.yml:379, actions/release-image/release.py:232


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread actions/release-image/release.py Resolved
Comment thread .github/workflows/ci.yml Resolved
Comment thread .github/workflows/ci.yml Resolved
Comment thread actions/release-image/release.py Resolved
Address Sourcery's second review:

- Treat an image tag as missing only if buildx's last error line is
  "<reference>: not found" or the registry answers MANIFEST_UNKNOWN; any
  other error that mentions "not found" fails, so that a version tag
  can't be overwritten after a lookup error.
- Suppress the subprocess audit rule inline, with the reason: an
  argument list without a shell, of a fixed program, with validated
  settings.
- CI: wait for the local registry before pushing to it.

Part of #84

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant