feat: release-gate action #7

Merged
robin.wieske merged 2 commits from feat/release-gate into main 2026-11-10 23:11:15 +01:00
Owner

Summary

release-gate/: Docker action (Python 3.14 slim, pinned digest) that reads the Forgejo API and decides:

  • mode: release: publish the draft now or not
  • mode: promote: which tag to promote to prod, or why none
  • mode: recheck: whether a queued deploy_prod (source=auto) may still deploy

The gate only reads and never writes. The calling workflow acts on decision. Rules follow docs/plan.md. README: release-gate/README.md. Closes #2.

Layout: forgejo.py (API client with retries, GET only), rules.py (all rules), main.py (inputs, outputs, step summary).

Inputs / outputs

Input Default Output Meaning
mode required decision publish / promote / skip / dry-run
token, repo required tag draft or candidate tag
api_url https://forgejo.entwirr.me/api/v1 release_id id of that release
default_branch main critical true / false
auto_release, auto_promote off reasons JSON array of critical reasons
automation_paused "" skip_reason every failed check, joined with ; (also filled in dry-run)
deps_threshold / deps_max_age_days / soak_days 10 / 14 / 4 pre_notice_needed critical, and the 24h notice is the only thing missing
prod_version_url, candidate "" env_keys_new JSON array of new .env.example keys
requires_repo, requires_version_url ""

How each rule is implemented

Release

  1. Kill switches: automation_paused == true → skip, and this wins over dry-run. If auto_release is anything other than on or dry-run, it counts as off → skip. dry-run computes everything and returns decision=dry-run.

  2. Exactly one draft, with a strict vX.Y.Z tag that is newer than the highest published non-prerelease release.

  3. Draft not empty. PRs in the draft come from the API, not from the markdown:

    • take the commits of compare/<last tag sha>...<default_branch>;
    • keep the closed PRs that are merged, have base = default branch, and whose merge_commit_sha is in that commit set;
    • page by sort=recentupdate, and stop at the first full page that is older than the tag commit.
  4. Content rule:

    • a non-dependency PR, or
    • a dependency PR labelled security, or
    • at least deps_threshold dependency PRs, or
    • the oldest dependency PR was merged more than deps_max_age_days ago.

    A dependency PR has the label dependency or a title starting with chore(deps).

  • Critical when any of these is in the range:
    • a PR labelled security, breaking-change or caution;
    • a PR labelled major;
    • new migrations (diff of the database/migrations directory listing between the two refs);
    • new .env.example keys (raw file at both refs, same rules as env-diff: export counts, commented # KEY= does not).

Promote

  • Prod version first: read /version (plain text or JSON).
  • Candidate: walk published strict releases from the highest semver down, stopping at prod's version. Take the first one whose tag commit has latest deploy/staging = success (combined status endpoint) and is at least soak_days old.
    • A tag whose staging is failure, pending or missing is passed over. So a failed newer tag does not block an older one, and a failed candidate is never picked.
  • Checks 1–7 are all evaluated, and every failure is reported:
    1. Kill switches.
    2. Prod at or above the candidate → skip, not an error.
    3. Open release-blocker issues. The label is also checked on the client side, in case the server ignores the filter.
    4. New env keys between prod's tag and the candidate, unless the release body contains <!-- env-acknowledged -->.
    5. Irreversible migrations: every migration added or changed in the range, read at the candidate. Comments and strings are blanked, and only up() is scanned for dropColumn|dropTable|renameColumn|dropIfExists|Schema::drop. A hit gives "manual deploy required".
    6. Critical (computed over the whole range from prod to the candidate) needs notify/pre-prod = success that is at least 24h old.
      • Missing or not success → pre_notice_needed=true, but only if nothing else blocks.
      • Younger than 24h → skip, with the time it becomes due.
    7. .release/requires.json {"kima/portal": "vX.Y.Z"} at the candidate must be ≤ the live /version at requires_version_url.

Recheck: checks the kill switches, then release-blocker issues, then whether prod is below candidate → promote. Otherwise → skip.

Tests

86 pytest tests, with no network. A fake requests session answers from hand-written fixtures (tests/fixtures/release.json, promote.json, migrations/*.php). The fixture shapes were checked against read-only fj api GETs on Aevana/aevana (releases, pulls, tags, compare, combined status, contents, raw).

Every rule has passing and failing tests. They include:

  • dry-run in both directions, the kill switches, and pause overriding dry-run
  • 0 or 2 drafts, a non-strict draft tag, an empty draft
  • dependency rules: threshold, custom threshold, max age (including exactly 14 days), security override, title-only dependency PRs
  • each critical reason, and the first release
  • soak boundary (exactly 4d passes, 4d−1s does not), a newer tag failing staging, the candidate failing staging, a missing staging status, soak 0
  • prod equal, newer, JSON body, unreachable, garbage
  • a blocker issue, env keys with and without the ack, the four migration cases (including down()-only drops and strings/comments)
  • pre-notice: missing, failed, under 24h, exactly 24h, and while another check blocks
  • critical computed over the range, kima requires (met, unmet, missing file, bad JSON)
  • recheck, outputs and the summary, the token never sent to /version or printed, pagination, query params

CI: .github/workflows/test_release_gate.yaml (pull_request + push to main) runs in python:3.14-slim@sha256:…. The tests also pass locally, and the image builds and runs (docker build plus a smoke run).

Deviations / not verified

  • Not verified: whether Forgejo accepts the cross-repo subdirectory form uses: https://forgejo.entwirr.me/Wi3eDigital/laravel-deploy-actions/release-gate@<sha>. This must be confirmed in the Aevana pilot.
  • Changes from the issue text, per the agreed design:
    • a Docker action, not a composite one;
    • outputs decision/tag instead of publish/candidate;
    • an added recheck mode;
    • the drafter runs in the workflow before the gate, not inside it.
  • soak_days=0: a missing deploy/staging status is allowed (homepage has no staging). A failure still excludes the tag.
  • The .release/requires.json format is defined here: {"<requires_repo>": "vX.Y.Z"}. A missing file means no requirement.
  • deploy_staging must post the commit status context deploy/staging explicitly. Today Aevana only has job-named statuses such as Deploy to Staging / deploy (release), so promote would find no candidate.
  • If prod /version is unreachable or unparsable, or prod's version has no tag, the step fails with exit 1, so that schedule.failed fires.
  • Irreversible detection is widened by Schema::drop(. Not detected: dropTimestamps, dropSoftDeletes, dropMorphs, raw SQL.
  • CI downloads the commit's source archive with the Python stdlib instead of using actions/checkout, because the slim image has neither node nor git.
  • The Python image digest is reused from forgejo-release-drafter-action, which Renovate manages.

🤖 Generated with Claude Code

https://claude.ai/code/session_0114prpbjyD3Bqt26YpZ1MEL

## Summary `release-gate/`: Docker action (Python 3.14 slim, pinned digest) that reads the Forgejo API and decides: - `mode: release`: publish the draft now or not - `mode: promote`: which tag to promote to prod, or why none - `mode: recheck`: whether a queued `deploy_prod` (`source=auto`) may still deploy The gate only reads and never writes. The calling workflow acts on `decision`. Rules follow `docs/plan.md`. README: `release-gate/README.md`. Closes #2. Layout: `forgejo.py` (API client with retries, GET only), `rules.py` (all rules), `main.py` (inputs, outputs, step summary). ## Inputs / outputs | Input | Default | | Output | Meaning | |---|---|---|---|---| | `mode` | required | | `decision` | `publish` / `promote` / `skip` / `dry-run` | | `token`, `repo` | required | | `tag` | draft or candidate tag | | `api_url` | `https://forgejo.entwirr.me/api/v1` | | `release_id` | id of that release | | `default_branch` | `main` | | `critical` | `true` / `false` | | `auto_release`, `auto_promote` | `off` | | `reasons` | JSON array of critical reasons | | `automation_paused` | `""` | | `skip_reason` | every failed check, joined with `; ` (also filled in dry-run) | | `deps_threshold` / `deps_max_age_days` / `soak_days` | `10` / `14` / `4` | | `pre_notice_needed` | critical, and the 24h notice is the only thing missing | | `prod_version_url`, `candidate` | `""` | | `env_keys_new` | JSON array of new `.env.example` keys | | `requires_repo`, `requires_version_url` | `""` | | | | ## How each rule is implemented **Release** 1. Kill switches: `automation_paused == true` → skip, and this wins over dry-run. If `auto_release` is anything other than `on` or `dry-run`, it counts as `off` → skip. `dry-run` computes everything and returns `decision=dry-run`. 2. Exactly one draft, with a strict `vX.Y.Z` tag that is newer than the highest published non-prerelease release. 3. Draft not empty. PRs in the draft come from the API, not from the markdown: - take the commits of `compare/<last tag sha>...<default_branch>`; - keep the closed PRs that are merged, have base = default branch, and whose `merge_commit_sha` is in that commit set; - page by `sort=recentupdate`, and stop at the first full page that is older than the tag commit. 4. Content rule: - a non-dependency PR, or - a dependency PR labelled `security`, or - at least `deps_threshold` dependency PRs, or - the oldest dependency PR was merged more than `deps_max_age_days` ago. A dependency PR has the label `dependency` or a title starting with `chore(deps)`. - Critical when any of these is in the range: - a PR labelled `security`, `breaking-change` or `caution`; - a PR labelled `major`; - new migrations (diff of the `database/migrations` directory listing between the two refs); - new `.env.example` keys (raw file at both refs, same rules as env-diff: `export` counts, commented `# KEY=` does not). **Promote** - Prod version first: read `/version` (plain text or JSON). - Candidate: walk published strict releases from the highest semver down, stopping at prod's version. Take the first one whose tag commit has latest `deploy/staging` = `success` (combined status endpoint) and is at least `soak_days` old. - A tag whose staging is failure, pending or missing is passed over. So a failed newer tag does not block an older one, and a failed candidate is never picked. - Checks 1–7 are all evaluated, and every failure is reported: 1. Kill switches. 2. Prod at or above the candidate → skip, not an error. 3. Open `release-blocker` issues. The label is also checked on the client side, in case the server ignores the filter. 4. New env keys between prod's tag and the candidate, unless the release body contains `<!-- env-acknowledged -->`. 5. Irreversible migrations: every migration added or changed in the range, read at the candidate. Comments and strings are blanked, and only `up()` is scanned for `dropColumn|dropTable|renameColumn|dropIfExists|Schema::drop`. A hit gives "manual deploy required". 6. Critical (computed over the whole range from prod to the candidate) needs `notify/pre-prod` = `success` that is at least 24h old. - Missing or not success → `pre_notice_needed=true`, but only if nothing else blocks. - Younger than 24h → skip, with the time it becomes due. 7. `.release/requires.json` `{"kima/portal": "vX.Y.Z"}` at the candidate must be ≤ the live `/version` at `requires_version_url`. **Recheck**: checks the kill switches, then `release-blocker` issues, then whether prod is below `candidate` → `promote`. Otherwise → `skip`. ## Tests 86 pytest tests, with no network. A fake `requests` session answers from hand-written fixtures (`tests/fixtures/release.json`, `promote.json`, `migrations/*.php`). The fixture shapes were checked against read-only `fj api` GETs on Aevana/aevana (releases, pulls, tags, compare, combined status, contents, raw). Every rule has passing and failing tests. They include: - dry-run in both directions, the kill switches, and pause overriding dry-run - 0 or 2 drafts, a non-strict draft tag, an empty draft - dependency rules: threshold, custom threshold, max age (including exactly 14 days), security override, title-only dependency PRs - each critical reason, and the first release - soak boundary (exactly 4d passes, 4d−1s does not), a newer tag failing staging, the candidate failing staging, a missing staging status, soak 0 - prod equal, newer, JSON body, unreachable, garbage - a blocker issue, env keys with and without the ack, the four migration cases (including `down()`-only drops and strings/comments) - pre-notice: missing, failed, under 24h, exactly 24h, and while another check blocks - critical computed over the range, kima requires (met, unmet, missing file, bad JSON) - recheck, outputs and the summary, the token never sent to `/version` or printed, pagination, query params CI: `.github/workflows/test_release_gate.yaml` (pull_request + push to main) runs in `python:3.14-slim@sha256:…`. The tests also pass locally, and the image builds and runs (`docker build` plus a smoke run). ## Deviations / not verified - **Not verified:** whether Forgejo accepts the cross-repo subdirectory form `uses: https://forgejo.entwirr.me/Wi3eDigital/laravel-deploy-actions/release-gate@<sha>`. This must be confirmed in the Aevana pilot. - Changes from the issue text, per the agreed design: - a Docker action, not a composite one; - outputs `decision`/`tag` instead of `publish`/`candidate`; - an added `recheck` mode; - the drafter runs in the workflow before the gate, not inside it. - `soak_days=0`: a missing `deploy/staging` status is allowed (homepage has no staging). A `failure` still excludes the tag. - The `.release/requires.json` format is defined here: `{"<requires_repo>": "vX.Y.Z"}`. A missing file means no requirement. - `deploy_staging` must post the commit status context `deploy/staging` explicitly. Today Aevana only has job-named statuses such as `Deploy to Staging / deploy (release)`, so promote would find no candidate. - If prod `/version` is unreachable or unparsable, or prod's version has no tag, the step fails with exit 1, so that `schedule.failed` fires. - Irreversible detection is widened by `Schema::drop(`. Not detected: `dropTimestamps`, `dropSoftDeletes`, `dropMorphs`, raw SQL. - CI downloads the commit's source archive with the Python stdlib instead of using `actions/checkout`, because the slim image has neither node nor git. - The Python image digest is reused from forgejo-release-drafter-action, which Renovate manages. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0114prpbjyD3Bqt26YpZ1MEL
Docker action that decides from the Forgejo API whether to publish the
draft, which tag to promote, and whether a queued auto deploy may run.
Rules follow docs/plan.md. Read-only; pytest fixture tests run in CI.

Closes #2

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0114prpbjyD3Bqt26YpZ1MEL
fix(release-gate): string-aware migration scan, Schema::drop
All checks were successful
Test release-gate / pytest (pull_request) Successful in 24s
4570c745db
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0114prpbjyD3Bqt26YpZ1MEL
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Wi3eDigital/laravel-deploy-actions!7
No description provided.