Skip to content

feat: add the check-release action - #83

Merged
uniqueg merged 4 commits into
mainfrom
feat/82-check-release
Nov 16, 2026
Merged

uniqueg merged 4 commits into
mainfrom
feat/82-check-release

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds the composite action actions/check-release for the prepare job of the release workflows, so that the twelve copies of the release tag checks can be replaced by one. Like publish-release, its script (check.py) uses only the Python standard library and gh. It reads everything from the GitHub API at the release commit, so it runs nothing of the tagged commit and needs no checkout.

It fails the release unless all of these hold:

  • the tag is annotated, its tag object carries the tag's name, its signature is verified by GitHub, and it points to the commit of the run;
  • the tag is <tag-prefix>MAJOR.MINOR.PATCH, optionally followed by an a/alpha/b/beta/rc pre-release with a number. This is the strictest form common to the existing copies;
  • the commit is the head of the release branch or one of its ancestors. The branch is looked up as refs/heads/<branch>, so a tag with the same name can't stand in for it;
  • CI has a successful run for a push of the commit, optionally only for pushes to ci-branch;
  • CITATION.cff at the commit has the release version and a date-released that is not in the future in any time zone (as TESK, krini and cloud-components require);
  • the package version passed by the caller, if any, equals the release version.

All checks run and each finding is an error annotation; only the version-dependent checks are skipped when the tag isn't a release version.

Inputs: tag (default github.ref_name), commit (default github.sha), tag-prefix (default v), branch (default main), workflow (default ci.yml), ci-branch (default dev; empty means any branch), citation (default CITATION.cff; empty means no check), version (default empty, no check), token.
Outputs: version, prerelease (the same rule as publish-release's prerelease: auto, cross-checked in the tests) and sha.
Permissions: contents: read and actions: read.

Also changed: the action's README, the repository README entry and test command, and ci.yml. The test job now gets actions: read and new steps: the unit tests, the script against this repository's real tags, and the action itself on v1.2.0.

Part of #82

Still open in #82: adoption by a first repository, in a separate PR after the next release of this repository (candidate: tesk-api for 2.0.0). Note for adopters: version must match the tag exactly, so tesk-api (which compares only the base version of pom.xml) has to pass the full version or none. This repository's own release.yml switches over with #65's sub-issue for its own release process.

Verification

  • bash tests/check-release/test.sh: 36 tests OK (unittest, stand-in for gh). Branch coverage of check.py is 99%; the only uncovered line is the __main__ guard, which the subprocess test runs.
  • All test scripts pass: pr-title, gate, labels, publish-release, check-release, scan-image, release.
  • pre-commit run --all-files passes: check-jsonschema, markdownlint, shellcheck, actionlint and gitleaks. I ran gitleaks-all only on staged content, because my local tool caches under the clone trigger false positives; CI runs it on a clean checkout.
  • ruff format --check passes, and mypy --strict --python-version 3.10 actions/check-release/check.py reports no issues.
  • Against the real API, locally:
    • this repository's v1.2.0 passes (outputs 1.2.0, false, bf3840c…);
    • v1.0.0 fails as lightweight;
    • a wrong commit fails three ways (tag, branch, CI);
    • v1.2 fails as not a release version;
    • a missing CITATION.cff fails;
    • tesk-api's v1.2.0 passes with citation: CITATION.cff, version: 1.2.0 and either ci-branch: dev or an empty ci-branch.
  • CI: all checks passed on 8230921 (Lint; Test, including the real-API steps and the action run on the latest release, v1.2.0; CodeQL; Sourcery; CI passed): https://github.com/elixir-cloud-aai/.github/actions/runs/43809672726

Declined review findings

  • Switch this repository's own release.yml to the action in this PR: out of scope. The task is the action only, and this repository's release process is reworked under ci: share the release steps across repos #65 (release with publish-release).
  • Use the same version grammar as publish-release: kept stricter on purpose. It accepts lower case only and requires the patch and the pre-release number, so all repositories tag alike. The README says so, and the tests cross-check the prerelease rule on the versions that both accept.
  • Sourcery: re-read refs before returning (TOCTOU): narrows but does not close the window; sha is the event commit, and tags are immutable by rulesets. Strip of version: intended, for command output with a trailing newline. Empty ci-branch counting tag pushes and the fixed v1.2.0 run: fixed in 8230921 (README note; CI tests the latest release).
  • Fail on a date-released older than some window: a release can be prepared days or weeks before the tag, so any fixed window would risk false failures. The README states that only "set, valid, not in the future" is checked.

Open questions

None.

🤖 Generated with Claude Code

uniqueg and others added 3 commits November 16, 2026 05:36
Add the composite action actions/check-release for the prepare job of
release workflows. It fails unless the tag is annotated, named as
pushed, signed with a signature that GitHub verified and points to the
commit of the run; the tag is a release version after tag-prefix; the
commit is on the release branch; the CI workflow passed for a push of
the commit; and CITATION.cff and the package version (passed by the
caller) match the release version, with a date-released that is not in
the future. Everything is read from the GitHub API at the commit, all
checks run, and each finding is an error annotation. Outputs: version,
prerelease (the rule of publish-release's auto) and sha.

Tests in tests/check-release/ (unittest, stand-in for gh), and CI steps
against this repository's real tags (v1.0.0 lightweight, v1.2.0 signed).

Part of #82

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Look up the release branch as refs/heads/<branch> and compare its head
  SHA, so that a tag named like the branch doesn't count
- Validate the tag input before it goes into API paths
- Read `#` in CITATION.cff as a comment only after whitespace, as YAML
  does (`1.2.0#x` is a value)
- CI: define the released SHA once; check the errors of one call at once
- README: stricter tag grammar than publish-release, skipped checks,
  branch flow (ci-branch), date-released scope, checkout, Tests section
- Tests: more prerelease parity cases, typed helpers

Part of #82

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`version:1.2.0` is no key in YAML, so it now fails as a malformed value
instead of being read as the version. Also: docstring order in
check_branch, and the branch flow in the README worded for repositories
that develop on dev (this repository merges into main).

Part of #82

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 inputs, permissions, and outputs as the public interface used by release workflows.

  • actions/check-release/action.yml L1-88

Implementation

Implement the release validation flow and its supporting version, tag, branch, CI, and citation checks, including comments that explain the behavior.

  • actions/check-release/check.py L1-575

Configuration

Grant CI the API permissions the action needs and add script, real-API, and composite-action checks to the test job.

  • .github/workflows/ci.yml L62-65, L190-280

Documentation

Document the action’s validation rules, configuration, usage, outputs, and tests, and add it to the repository’s action and test-command listings.

  • README.md L111-113, L136-139, L150
  • actions/check-release/README.md L1-159

Tests

Add unit tests for settings, version and citation parsing, API-backed checks, error annotations, and script execution against a stand-in for the GitHub CLI.

  • tests/check-release/test.sh L1-8
  • tests/check-release/test_check.py L1-764

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 05:13

@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 4 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="actions/check-release/check.py" line_range="279" />
<code_context>
+    """
+    repo, tag = settings.repository, settings.tag
+    try:
+        ref = _api(gh, f"repos/{repo}/git/ref/tags/{_quote(tag)}")
+    except CheckError as error:
+        raise CheckError(f"Could not look up the tag '{tag}': {error}") from error
</code_context>
<issue_to_address>
**Release proceeds after refs change**

When another writer retargets the tag or force-pushes the branch after its ref is read but before the check returns, `check_tag` and `check_branch` validate the tag object and branch head they captured earlier without rereading the mutable refs. A retarget or force-push can therefore leave the check successful and emit `sha` for a commit that no longer satisfies the gate.

Re-fetch the tag ref and branch head before returning success, and fail if either no longer satisfies the release checks.

Also at `actions/check-release/check.py:329`, `actions/check-release/check.py:336`, `actions/check-release/check.py:520`.
</issue_to_address>

### Comment 2
<location path="actions/check-release/check.py" line_range="369-370" />
<code_context>
+        "status": "success",
+        "per_page": "1",
+    }
+    if settings.ci_branch:
+        query["branch"] = settings.ci_branch
+    path = (
+        f"repos/{settings.repository}/actions/workflows/"
</code_context>
<issue_to_address>
**Tag CI run satisfies branch check**

When `ci-branch` is empty and the CI workflow has a successful run for a tag push of the release commit, a successful CI run triggered by a tag push has `event=push` and can match the release commit’s `head_sha`. With no branch filter, `check_ci` counts that run and accepts the release even though CI never passed for a branch push.

When `ci-branch` is empty, inspect candidate runs and accept only runs associated with a branch push, or require callers to specify a branch.
</issue_to_address>

### Comment 3
<location path="actions/check-release/check.py" line_range="144" />
<code_context>
+    r"(?P<major>0|[1-9][0-9]*)\.(?P<minor>0|[1-9][0-9]*)\.(?P<patch>0|[1-9][0-9]*)"
+    r"(?:[-.]?(?P<pre>a|alpha|b|beta|rc)[-.]?(?P<number>0|[1-9][0-9]*))?",
+    re.ASCII,
+)
+# Inputs that go into API paths and queries
+REPOSITORY = re.compile(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", re.ASCII)
</code_context>
<issue_to_address>
**Whitespace package versions pass**

When the caller supplies a package version with leading or trailing whitespace, `Settings.from_env` strips `VERSION` before `check` compares it with the release version, so an input such as `" 1.2.0 "` passes for tag `v1.2.0` despite not matching exactly; the package-version check misses the discrepancy.

Preserve the supplied package version for the equality check, or reject it if trimming would change it.
</issue_to_address>

### Comment 4
<location path=".github/workflows/ci.yml" line_range="68" />
<code_context>
+      actions: read
+    env:
+      # check-release: the commit of this repository's tag v1.2.0
+      RELEASED_SHA: bf3840c9c072aaf37d6cafe199aaa1994087d1ef
     steps:
       - name: Check out repository
</code_context>
<issue_to_address>
**CI test disappears after retention**

When gitHub expires or deletes the successful Actions run for the hard-coded release commit under its retention policy, `check_ci` finds no matching run for the fixed `RELEASED_SHA` and fails the test job on every subsequent run, blocking unrelated changes.

Avoid making the permanent suite depend on a retained historical run, or keep that run available.

Also at `.github/workflows/ci.yml:242`, `actions/check-release/check.py:373`.
</issue_to_address>

Sourcery assessment

Needs a human reviewer. 4 findings to address first, and a consuming release workflow can proceed when this action reports that the tag, commit, branch, and CI checks passed; if a faulty check accepts an invalid release, downstream jobs may publish artifacts that reverting the action cannot retract. This PR adds the checker but does not wire it into this repository’s publishing workflow.

Blocking findings: actions/check-release/check.py:279, actions/check-release/check.py:370, actions/check-release/check.py:144, .github/workflows/ci.yml:68


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

Comment thread actions/check-release/check.py Resolved
Comment thread actions/check-release/check.py Resolved
Comment thread actions/check-release/check.py Resolved
Comment thread .github/workflows/ci.yml Resolved
The real-API steps used the fixed commit of v1.2.0, whose CI run may
expire. Test the tag of the latest release instead, whose CI run is
recent, as each release requires one. Also document that an empty
ci-branch counts pushes of tags too.

Part of #82

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg
uniqueg merged commit 9b8bcc8 into main Nov 16, 2026
7 checks passed
@uniqueg
uniqueg deleted the feat/82-check-release branch November 16, 2026 05:25
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