diff --git a/.github/workflows/build-push-docker-image.yml b/.github/workflows/build-push-docker-image.yml index 2b481114d..fa69bc1dc 100644 --- a/.github/workflows/build-push-docker-image.yml +++ b/.github/workflows/build-push-docker-image.yml @@ -11,7 +11,8 @@ permissions: {} env: REGISTRY: ghcr.io - REGISTRY_IMAGE: ghcr.io/${{ github.repository }} + # Branch builds go to the -dev package; production images are published only by release.yml. + REGISTRY_IMAGE: ghcr.io/${{ github.repository }}-dev jobs: build: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 49c0a184e..dce7e3493 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,5 +1,21 @@ name: Release +# Release images are published only from a release tag, after the tag passes +# the preflight checks and a reviewer approves the `release` environment. +# +# preflight -> build -> publish (environment: release, needs approval) +# +# `build` pushes the per-platform images by digest to the staging package +# ghcr.io/-dev (the same package used by branch builds), never to the +# production package ghcr.io/. The reviewer approves the images that were +# actually built (their digests are in the job summaries). Only `publish`, which +# runs after the approval of the `release` environment, writes to the production +# package: it assembles the tagged manifest lists from the staged digests of +# this run, then signs and attests them. It logs in to ghcr.io with a credential +# that exists only as a secret of the `release` environment; the workflow token +# (GITHUB_TOKEN) is used only for the staging package. Nothing reaches +# ghcr.io/ before the approval. + on: workflow_dispatch: push: @@ -7,19 +23,68 @@ on: - "v*.*.*" - "v*.*.*-*" +# One release run per tag. A run waiting for approval is never cancelled by +# another run. concurrency: - group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} - cancel-in-progress: true + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: false permissions: {} env: REGISTRY: ghcr.io + # Production package: written only by `publish`, after approval, with the + # credential held by the `release` environment. REGISTRY_IMAGE: ghcr.io/${{ github.repository }} - REGEX_IMAGE: ${{ github.repository }}:\\d+.\\d+.\\d+ + # Staging package: `build` pushes the per-platform images here, by digest. + STAGING_IMAGE: ghcr.io/${{ github.repository }}-dev + REGEX_IMAGE: ${{ github.repository }}:\\d+\\.\\d+\\.\\d+ jobs: + # Gate 1: the ref must be a release tag (vX.Y.Z or vX.Y.Z-
) whose commit
+  # is on develop or on a release/* branch, and the version must not be
+  # published yet (published versions are immutable).
+  preflight:
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.ancestry.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Check tag ancestry
+        id: ancestry
+        run: scripts/release/check_tag_ancestry.sh "$GITHUB_REF"
+
+      - name: Check the version is not already published
+        env:
+          VERSION: ${{ steps.ancestry.outputs.version }}
+        run: |
+          for tag in "${VERSION}" "${VERSION}-no_shell" "${VERSION}-dev"; do
+            image="${REGISTRY_IMAGE}:${tag}"
+            if out=$(docker buildx imagetools inspect "$image" 2>&1); then
+              echo "::error::${image} is already published; release versions are immutable, tag a new version instead"
+              exit 1
+            fi
+            if ! grep -qi "not found" <<< "$out"; then
+              echo "::error::cannot tell whether ${image} is already published:"
+              echo "$out"
+              exit 1
+            fi
+            echo "${image} is not published yet"
+          done
+
+  # Builds the platform images and stages them by digest in the staging package
+  # (STAGING_IMAGE) with the workflow token; nothing is written to the production
+  # package here. The digests of what was built are listed in each job summary
+  # for the reviewer.
   build:
+    needs: preflight
     permissions:
       contents: read
       packages: write
@@ -47,30 +112,29 @@ jobs:
       - name: Prepare
         run: |
           platform=${{ matrix.platform }}
-          echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV
+          echo "PLATFORM_PAIR=${platform//\//-}" >> "$GITHUB_ENV"
           VARIANT_SUFFIX="${{ matrix.variant.suffix }}"
-          echo "VARIANT_SUFFIX=$VARIANT_SUFFIX" >> $GITHUB_ENV
+          echo "VARIANT_SUFFIX=$VARIANT_SUFFIX" >> "$GITHUB_ENV"
           PLATFORM_VARIANT="${platform//\//-}${VARIANT_SUFFIX}"
-          echo "PLATFORM_VARIANT=$PLATFORM_VARIANT" >> $GITHUB_ENV
+          echo "PLATFORM_VARIANT=$PLATFORM_VARIANT" >> "$GITHUB_ENV"
 
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
 
+      # Only exact version tags are published: no moving X.Y or latest tags.
       - name: Docker meta (prod)
         id: meta_prod
         if: matrix.variant.suffix == ''
         uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302  # v6.2.0
         with:
           images: ${{ env.REGISTRY_IMAGE }}
+          flavor: |
+            latest=false
           tags: |
-            type=ref,event=branch
-            type=ref,event=pr
             type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{version}},suffix=-no_shell
-            type=semver,pattern={{major}}.{{minor}},suffix=-no_shell
 
       - name: Docker meta (dev)
         id: meta_dev
@@ -78,37 +142,38 @@ jobs:
         uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302  # v6.2.0
         with:
           images: ${{ env.REGISTRY_IMAGE }}
+          flavor: |
+            latest=false
           tags: |
-            type=ref,event=branch,suffix=-dev
-            type=ref,event=pr,suffix=-dev
             type=semver,pattern={{version}},suffix=-dev
-            type=semver,pattern={{major}}.{{minor}},suffix=-dev
 
       - name: Image name builder (prod)
         id: image_builder_prod
         if: matrix.variant.suffix == ''
         run: |
-          IMAGE=$(jq -ecr '.tags | map(select(match("${{ env.REGEX_IMAGE }}", "i"))) | first| sub(":.*$";"")' <<< "$DOCKER_METADATA_OUTPUT_JSON")
-          echo "IMAGE=$IMAGE" >> $GITHUB_OUTPUT
+          IMAGE=$(jq -ecr '.tags | map(select(test("${{ env.REGEX_IMAGE }}"; "i"))) | first | sub(":.*$";"")' <<< "$DOCKER_METADATA_OUTPUT_JSON")
+          echo "IMAGE=$IMAGE" >> "$GITHUB_OUTPUT"
 
       - name: Image name builder (dev)
         id: image_builder_dev
         if: matrix.variant.suffix != ''
         run: |
-          IMAGE=$(jq -ecr '.tags | map(select(match("${{ env.REGEX_IMAGE }}-dev", "i"))) | first| sub(":.*$";"")' <<< "$DOCKER_METADATA_OUTPUT_JSON")
-          echo "IMAGE=$IMAGE" >> $GITHUB_OUTPUT
+          IMAGE=$(jq -ecr '.tags | map(select(test("${{ env.REGEX_IMAGE }}.*-dev$"; "i"))) | first | sub(":.*$";"")' <<< "$DOCKER_METADATA_OUTPUT_JSON")
+          echo "IMAGE=$IMAGE" >> "$GITHUB_OUTPUT"
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069  # v4.4.1
 
-      - name: Login to Docker Hub
+      - name: Login to the container registry (staging package)
         uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550  # v4.8.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Build and push by digest
+      # Each platform image carries an SBOM and full (mode=max) build provenance.
+      # The image is pushed to the staging package, not to the production one.
+      - name: Build and push by digest to staging
         id: build
         uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc  # v7.4.0
         with:
@@ -120,22 +185,33 @@ jobs:
           cache-to: type=gha,mode=max
           build-args: |
             INCLUDE_SHELL=${{ matrix.variant.include_shell }}
-          outputs: type=image,name=${{ (matrix.variant.suffix == '') && steps.image_builder_prod.outputs.IMAGE || steps.image_builder_dev.outputs.IMAGE }},push-by-digest=true,push=true
+          sbom: true
+          provenance: mode=max
+          outputs: type=image,name=${{ env.STAGING_IMAGE }},push-by-digest=true,push=true
 
       - name: Verify version in image
         run: |
-          IMAGE_NAME="${{ (matrix.variant.suffix == '') && steps.image_builder_prod.outputs.IMAGE || steps.image_builder_dev.outputs.IMAGE }}"
+          IMAGE_NAME="${STAGING_IMAGE}"
           DIGEST="${{ steps.build.outputs.digest }}"
           out=$(docker run --rm "${IMAGE_NAME}@${DIGEST}" version) || { echo "ERROR: docker run failed"; exit 1; }
           ver=$(echo "$out" | awk '/^Version:/{print $2}')
           [ -n "$ver" ] || { echo "ERROR: Docker image has no version embedded"; exit 1; }
           echo "Version check passed: $ver"
+          echo "VERSION_IN_IMAGE=$ver" >> "$GITHUB_ENV"
 
+      # The digest files are what `publish` lists and promotes.
       - name: Export digest
         run: |
           mkdir -p /tmp/digests
           digest="${{ steps.build.outputs.digest }}"
           touch "/tmp/digests/${digest#sha256:}.${{ env.PLATFORM_VARIANT }}"
+          {
+            echo "### Staged ${{ matrix.variant.description }} image, ${{ matrix.platform }}"
+            echo ""
+            echo "- Image: \`${STAGING_IMAGE}@${digest}\`"
+            echo "- Version reported by the image: \`${VERSION_IN_IMAGE}\`"
+            echo "- Has an SBOM and mode=max build provenance"
+          } >> "$GITHUB_STEP_SUMMARY"
 
       - name: Upload digest
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
@@ -143,50 +219,177 @@ jobs:
           name: digests-${{ env.PLATFORM_VARIANT }}
           path: /tmp/digests/*
           if-no-files-found: error
-          retention-days: 1
+          # The files are empty and must outlive the approval wait (up to 30
+          # days) and a re-run of `publish`.
+          retention-days: 30
 
-  merge:
-    permissions:
-      contents: read
-      packages: write
-    runs-on: arm-runner-2204
+  # Gate 2: deployment review, and the only job that can write the production
+  # package. The `release` environment requires approval by a release approver
+  # other than the person who triggered the run, and it is the only place that
+  # holds the credential for ghcr.io/ (secrets RELEASE_REGISTRY_USER and
+  # RELEASE_REGISTRY_TOKEN). The workflow token is never used for that package,
+  # so no other job, and no other workflow, can write to it. The reviewer
+  # decides on the images staged by `build` (digests in the build job
+  # summaries); this job runs after the approval and promotes exactly these
+  # digests.
+  #
+  # Creates the tagged multi-platform manifest lists in the production package
+  # from the staged digests built in this run (taken from the build artifacts,
+  # not looked up by tag), then signs each one with cosign (keyless, bound to
+  # this workflow's identity) and pushes a GitHub build-provenance attestation
+  # for it to the registry. The signatures and attestations are pushed with the
+  # same release credential. Both variants are handled in this one job so that
+  # a release needs a single approval.
+  publish:
     needs:
+      - preflight
       - build
-    strategy:
-      matrix:
-        variant:
-          - { suffix: "", description: "production" }
-          - { suffix: "-dev", description: "development" }
+    # No packages permission: the workflow token cannot write any package here.
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    environment: release
+    runs-on: ubuntu-latest
     steps:
-      - name: Download digests
+      - name: Download staged digests
         uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
         with:
           path: /tmp/digests
-          pattern: digests-*${{ matrix.variant.suffix }}
+          pattern: digests-*
           merge-multiple: true
 
+      - name: Approved release
+        env:
+          TAG: ${{ github.ref_name }}
+          COMMIT: ${{ github.sha }}
+          VERSION: ${{ needs.preflight.outputs.version }}
+        run: |
+          {
+            echo "### Approved release"
+            echo ""
+            echo "- Tag: \`${TAG}\`"
+            echo "- Commit: \`${COMMIT}\`"
+            echo "- Version: \`${VERSION}\`"
+            echo "- Staged platform images (digest, platform and variant):"
+            for f in /tmp/digests/*; do
+              name=$(basename "$f")
+              echo "  - \`${STAGING_IMAGE}@sha256:${name%%.*}\` (${name#*.})"
+            done
+          } | tee -a "$GITHUB_STEP_SUMMARY"
+
+      - name: Check the release registry credential
+        env:
+          REGISTRY_USER: ${{ secrets.RELEASE_REGISTRY_USER }}
+          REGISTRY_TOKEN: ${{ secrets.RELEASE_REGISTRY_TOKEN }}
+        run: |
+          if [ -z "$REGISTRY_USER" ] || [ -z "$REGISTRY_TOKEN" ]; then
+            echo "::error::the secrets RELEASE_REGISTRY_USER and RELEASE_REGISTRY_TOKEN must be set in the release environment"
+            exit 1
+          fi
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069  # v4.4.1
 
-      - name: Login to Docker Hub
+      # The credential for the production package. It is stored only as secrets
+      # of the `release` environment, and it also serves the cosign signature
+      # and the attestation pushes below (both read the registry login).
+      - name: Login to the container registry with the release credential
         uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550  # v4.8.0
         with:
           registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
+          username: ${{ secrets.RELEASE_REGISTRY_USER }}
+          password: ${{ secrets.RELEASE_REGISTRY_TOKEN }}
 
-      - name: Create manifest list and push
+      # Sources are the staged per-platform digests of this run; each manifest
+      # list is created in the production package under the final tags. The
+      # source images keep their SBOM and provenance attestation manifests.
+      - name: Create manifest lists from staged digests and push
+        id: manifest
         working-directory: /tmp/digests
+        env:
+          IMAGE_NAME_PROD: ${{ needs.build.outputs.IMAGE_NAME_PROD }}
+          TAGS_PROD: ${{ needs.build.outputs.TAGS_PROD }}
+          IMAGE_NAME_DEV: ${{ needs.build.outputs.IMAGE_NAME_DEV }}
+          TAGS_DEV: ${{ needs.build.outputs.TAGS_DEV }}
+        run: |
+          promote() {
+            local variant="$1" suffix="$2" image="$3" tags="$4"
+            local args=() tag first_tag="" f digest manifest_digest sources=0
+            while IFS= read -r tag; do
+              tag="${tag//[[:space:]]/}"
+              if [ -n "$tag" ]; then
+                args+=(-t "$tag")
+                [ -n "$first_tag" ] || first_tag="$tag"
+              fi
+            done <<< "$tags"
+            [ "${#args[@]}" -gt 0 ] || { echo "::error::no tags to publish for the ${variant} variant"; exit 1; }
+            # Digest files are named .-; take only the
+            # platform images of this variant.
+            for f in *; do
+              case "$f" in
+                *-dev) [ "$suffix" = "-dev" ] || continue ;;
+                *) [ -z "$suffix" ] || continue ;;
+              esac
+              digest="${f%%.*}"
+              if ! [[ "$digest" =~ ^[0-9a-f]{64}$ ]]; then
+                echo "::error::unexpected digest file name: $f"
+                exit 1
+              fi
+              args+=("${STAGING_IMAGE}@sha256:${digest}")
+              sources=$((sources + 1))
+            done
+            # One image per platform (linux/amd64 and linux/arm64).
+            if [ "$sources" -ne 2 ]; then
+              echo "::error::expected 2 staged platform images for the ${variant} variant, found ${sources}"
+              exit 1
+            fi
+            echo "Promoting ${sources} staged images of ${STAGING_IMAGE} to ${image}"
+            docker buildx imagetools create "${args[@]}"
+            manifest_digest=$(docker buildx imagetools inspect "$first_tag" --format '{{json .Manifest}}' | jq -er .digest)
+            echo "Manifest list of ${first_tag}: ${manifest_digest}"
+            {
+              echo "image_${variant}=${image}"
+              echo "digest_${variant}=${manifest_digest}"
+            } >> "$GITHUB_OUTPUT"
+          }
+          promote prod "" "$IMAGE_NAME_PROD" "$TAGS_PROD"
+          promote dev "-dev" "$IMAGE_NAME_DEV" "$TAGS_DEV"
+
+      - name: Install cosign
+        uses: sigstore/cosign-installer@756fe2d284c7292c4e9b62c8a28f1e5629c59532  # v4.1.3
+
+      # Keyless signature: the certificate identity is this workflow at the
+      # release tag, issued through GitHub's OIDC token.
+      - name: Sign manifest lists
+        env:
+          IMAGE_PROD: ${{ steps.manifest.outputs.image_prod }}
+          DIGEST_PROD: ${{ steps.manifest.outputs.digest_prod }}
+          IMAGE_DEV: ${{ steps.manifest.outputs.image_dev }}
+          DIGEST_DEV: ${{ steps.manifest.outputs.digest_dev }}
         run: |
-          IMAGE_NAME="${{ (matrix.variant.suffix == '') && needs.build.outputs.IMAGE_NAME_PROD || needs.build.outputs.IMAGE_NAME_DEV }}"
-          TAGS="${{ (matrix.variant.suffix == '') && needs.build.outputs.TAGS_PROD || needs.build.outputs.TAGS_DEV }}"
-          docker buildx imagetools create $(jq -cRr 'split("\n") | map(gsub("\\s+";"")) | map("-t "+ .) | join(" ")' <<< "$TAGS") \
-            $(for f in *${{ matrix.variant.suffix }}; do echo "${IMAGE_NAME}@sha256:${f%%.*}"; done)
+          cosign sign --yes "${IMAGE_PROD}@${DIGEST_PROD}"
+          cosign sign --yes "${IMAGE_DEV}@${DIGEST_DEV}"
+
+      - name: Attest build provenance (prod)
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8  # v4.2.2
+        with:
+          subject-name: ${{ steps.manifest.outputs.image_prod }}
+          subject-digest: ${{ steps.manifest.outputs.digest_prod }}
+          push-to-registry: true
+
+      - name: Attest build provenance (dev)
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8  # v4.2.2
+        with:
+          subject-name: ${{ steps.manifest.outputs.image_dev }}
+          subject-digest: ${{ steps.manifest.outputs.digest_dev }}
+          push-to-registry: true
 
-      - name: Inspect image
+      - name: Inspect images
+        env:
+          TAGS_PROD: ${{ needs.build.outputs.TAGS_PROD }}
+          TAGS_DEV: ${{ needs.build.outputs.TAGS_DEV }}
         run: |
-          IMAGE_NAME="${{ (matrix.variant.suffix == '') && needs.build.outputs.IMAGE_NAME_PROD || needs.build.outputs.IMAGE_NAME_DEV }}"
-          TAGS="${{ (matrix.variant.suffix == '') && needs.build.outputs.TAGS_PROD || needs.build.outputs.TAGS_DEV }}"
-          # Use the first tag for inspection
-          FIRST_TAG=$(echo "$TAGS" | head -n1)
-          docker buildx imagetools inspect "$FIRST_TAG"
+          # Use the first tag of each variant for inspection
+          docker buildx imagetools inspect "$(head -n1 <<< "$TAGS_PROD")"
+          docker buildx imagetools inspect "$(head -n1 <<< "$TAGS_DEV")"
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 677f5cabc..2177bf9a3 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -12,6 +12,8 @@
 - [EthTxManager](./ethtxmanager.md)
 - [Etherman](./etherman.md)
 - [Release lifecycle](./release_lifecycle.md)
+  - [Verifying release images](./release_verification.md)
+  - [Release settings runbook](./release_admin_runbook.md)
 - [End-to-end tests](./e2e_tests.md)
 - [Exit certificate of a deprecated chain: SC-locked funds (delta mode)](./exit_certificate_deprecated_chain_sc_locked_funds.md)
 - [Common config artifacts](./common_config.md)
diff --git a/docs/release_admin_runbook.md b/docs/release_admin_runbook.md
new file mode 100644
index 000000000..d79fcf64c
--- /dev/null
+++ b/docs/release_admin_runbook.md
@@ -0,0 +1,221 @@
+# Release settings runbook
+
+This page is for organization owners and repository admins. It describes the GitHub settings that protect the release process and how to confirm them. For how the images are published and verified, see [Verifying release images](./release_verification.md).
+
+## Purpose
+
+A production image must not be publishable by a single account. The release workflow (`.github/workflows/release.yml`) only runs for a `v*` tag and has three jobs, in this order:
+
+1. `preflight` checks that the tagged commit is on `develop` or a `release/*` branch and that the version is not published yet.
+2. `build` builds the per-platform images (with SBOM and build provenance) and pushes them by digest to the staging package `ghcr.io/agglayer/aggkit-dev`. It writes nothing to the production package `ghcr.io/agglayer/aggkit`. Its job summaries list the staged digests.
+3. `publish` uses the `release` environment, so it waits for a reviewer other than the person who started the run to approve it, and the reviewer decides on images that were actually built. After the approval it prints the tag, the commit, the version and the staged digests, creates the tagged manifest lists in `ghcr.io/agglayer/aggkit` from the approved staged digests of the same run (the digests come from the build job artifacts, not from a tag lookup), then signs them and creates the attestations. It is the only job with `id-token` and `attestations` write permissions, and the only job that can write to `aggkit`: it logs in to `ghcr.io` with a credential that is stored only as secrets of the `release` environment (`RELEASE_REGISTRY_USER` and `RELEASE_REGISTRY_TOKEN`). The workflow token (`GITHUB_TOKEN`) has no write access to `aggkit`, so neither `build` nor any other workflow of the repository can publish there.
+
+Nothing reaches `aggkit` before the approval. These checks only hold if the settings below are in place: otherwise one account could move a tag, change a protected branch, read the credential, or push to the packages directly.
+
+## Prerequisites
+
+- Organization owner: create teams, org-level rulesets, manage package settings.
+- Repository admin on `agglayer/aggkit`: environments, rulesets, branch rules.
+- Package admin on the `aggkit` and `aggkit-dev` container packages.
+- A dedicated machine account, owned by the organization and not used by people, to hold the registry credential (step 6).
+- GitHub CLI (`gh`) logged in with `repo`, `admin:org` and `read:packages` scopes for the `gh api` commands.
+
+Names used below: org `agglayer`, repository `agglayer/aggkit`, teams `release-approvers` and `release-manager`, environment `release`.
+
+## Steps
+
+### 1. Create the teams
+
+UI: Organization -> Teams -> New team.
+
+- `release-approvers`: people who may approve a release. Keep it small, and do not add everyone who can push tags.
+- `release-manager`: people who may bypass the tag ruleset (for example to delete a tag created by mistake). Keep it even smaller.
+
+```bash
+gh api -X POST orgs/agglayer/teams -f name=release-approvers -f privacy=closed
+gh api -X POST orgs/agglayer/teams -f name=release-manager -f privacy=closed
+gh api -X PUT orgs/agglayer/teams/release-approvers/repos/agglayer/aggkit -f permission=push
+```
+
+Confirm: `gh api orgs/agglayer/teams/release-approvers --jq .slug` and the same for `release-manager` print the slug.
+
+### 2. Configure the `release` environment
+
+UI: Repository -> Settings -> Environments -> `release`.
+
+- Required reviewers: team `release-approvers`.
+- Prevent self-review: on (the person who triggered the run cannot approve it).
+- Allow administrators to bypass: off.
+- Deployment branches and tags: "Selected branches and tags", with one rule of type tag, pattern `v*`.
+
+```bash
+APPROVERS_ID=$(gh api orgs/agglayer/teams/release-approvers --jq .id)
+gh api -X PUT repos/agglayer/aggkit/environments/release --input - < Settings -> Rules -> Rulesets -> New tag ruleset.
+
+- Enforcement: Active. Target: tags matching `refs/tags/v*` (include pattern `v*`).
+- Rules: restrict creations, restrict updates, restrict deletions, block force pushes (non-fast-forward).
+- Bypass list: the team `release-manager`. Organization admins may also bypass this ruleset (as "Always"): this is accepted on purpose, and every bypass is recorded in the organization audit log, which should be reviewed. The settings check fails for any other bypass actor.
+
+```bash
+RELEASE_MANAGER_ID=$(gh api orgs/agglayer/teams/release-manager --jq .id)
+gh api -X POST repos/agglayer/aggkit/rulesets --input - < Settings -> Rules -> Rulesets -> New branch ruleset, targeting `develop` and `release/**`. The settings check only reads rulesets, not classic branch protection rules, so use rulesets here: a repository protected only by classic branch protection is reported as failing.
+
+- Require a pull request before merging, with at least 1 approving review.
+- No direct pushes (do not add bypass actors; the settings check fails when a ruleset that applies to these branches has any).
+- Restrict deletions and block force pushes.
+
+```bash
+gh api -X POST repos/agglayer/aggkit/rulesets --input - <<'JSON'
+{
+  "name": "protected-branches",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {"ref_name": {"include": ["refs/heads/develop", "refs/heads/release/**"], "exclude": []}},
+  "rules": [
+    {"type": "pull_request", "parameters": {"required_approving_review_count": 1, "dismiss_stale_reviews_on_push": true, "require_code_owner_review": false, "require_last_push_approval": false, "required_review_thread_resolution": false}},
+    {"type": "deletion"},
+    {"type": "non_fast_forward"}
+  ],
+  "bypass_actors": []
+}
+JSON
+```
+
+Confirm: `gh api repos/agglayer/aggkit/rules/branches/develop --jq '.[].type'` lists `pull_request`, `deletion` and `non_fast_forward`; repeat with a `release/...` branch. The settings check covers `develop` and every `release/*` branch.
+
+### 5. Restrict the `aggkit` package
+
+UI: Organization -> Packages -> `aggkit` -> Package settings.
+
+- Manage Actions access: remove `agglayer/aggkit`. The repository must have no Actions access to this package, so that its workflow token cannot write to it.
+- Disable "Inherit access from source repository" (so repository roles do not grant push to the package).
+- Visibility: keep the package public. The `preflight` job checks whether a version already exists without logging in, so a private or internal package makes every release fail there.
+- Manage access: remove any individual user or team that has Write or Admin, except the package admins and the machine account of step 6.
+
+The API does not expose the Actions access list or inheritance, so this step is checked by hand. Confirm by reading the settings page and by listing direct grants: `gh api orgs/agglayer/packages/container/aggkit --jq '{visibility, repository: .repository.full_name}'`.
+
+The `build` job has `packages: write` because it has to push to `aggkit-dev`. `GITHUB_TOKEN` permissions are not scoped per package: the token can write to every package that grants the repository Actions access. That is why the repository must not appear in the Actions access of `aggkit`. With that setting, no job that uses the workflow token can write to `aggkit`, whatever its steps do, and the only credential that can is the one in the `release` environment, which a job gets only after the environment approval.
+
+### 6. Create the release registry credential
+
+`ghcr.io` accepts a personal access token (classic) of a user, and does not accept a fine-grained token or an app token for packages. Use a dedicated machine account for it:
+
+1. Give the account no access to the `agglayer/aggkit` repository: it must not be able to push branches or tags. Its package access is granted directly on the packages.
+2. UI: Organization -> Packages -> `aggkit` -> Package settings -> Manage access: invite the machine account with the role Write.
+3. UI: Organization -> Packages -> `aggkit-dev` -> Package settings -> Manage access: invite the machine account with the role Read (or keep `aggkit-dev` public). `publish` reads the staged images there and copies them to `aggkit`.
+4. As the machine account, create a personal access token (classic) with the single scope `write:packages` (it includes `read:packages`), a short expiry and a note naming its purpose. If the organization enforces SAML single sign-on, authorize the token for it.
+5. Store it as secrets of the `release` environment only (UI: Repository -> Settings -> Environments -> `release` -> Environment secrets), not as repository or organization secrets, because those would be readable by every workflow:
+
+```bash
+gh secret set RELEASE_REGISTRY_USER --repo agglayer/aggkit --env release --body ''
+gh secret set RELEASE_REGISTRY_TOKEN --repo agglayer/aggkit --env release
+```
+
+The second command asks for the token on the terminal. Delete the token from any other place afterwards. Rotate it before it expires: create a new token, update the environment secret, then revoke the old one. A dry run (step 9) confirms the new token works.
+
+Confirm:
+
+```bash
+gh api repos/agglayer/aggkit/environments/release/secrets --jq '.secrets[].name'
+gh secret list --repo agglayer/aggkit
+gh secret list --org agglayer
+```
+
+The first lists `RELEASE_REGISTRY_TOKEN` and `RELEASE_REGISTRY_USER`; the other two must not list either name. Values are never readable through the API.
+
+### 7. Configure `aggkit-dev` before the first release
+
+Release builds push their per-platform images to `aggkit-dev`, so the package settings must exist and be right before the first release is tagged. The package is created the first time an image is pushed to it, for example by running `Build and Push Docker Image` on a branch once. After that, open Organization -> Packages -> `aggkit-dev` -> Package settings and set:
+
+- Manage Actions access: `agglayer/aggkit` with role Write. The `build` job needs it to stage the images. `publish` reads the staged images with the machine account of step 6, which has the Read role here.
+- Visibility: as wanted for test images (public or internal).
+- Manage access: do not grant individual users or other teams Write beyond the package admins, and do not add other repositories to Actions access. `publish` promotes the digests recorded by the `build` job of the same run, so nothing that someone else pushes to `aggkit-dev` is promoted, but keeping the package tight limits pollution and confusion.
+- Do not enable a cleanup policy that deletes untagged versions: the staged release images are untagged digests, and they must still exist when the approval is given and `publish` runs.
+
+`aggkit-dev` is not a release channel and nothing in it is signed as a release. It holds branch builds and the staged, not yet approved, release images. The `Build and Push Docker Image` workflow keeps writing branch builds there with the same permission.
+
+### 8. Run the settings check
+
+From a checkout of the repository, with `gh` and `jq` available and enough access to read the settings:
+
+```bash
+scripts/release/check_release_settings.sh
+```
+
+Optional: `--json` prints the results as JSON; the environment variables `REPO`, `ORG`, `APPROVERS_TEAM`, `RELEASE_TEAM`, `ENVIRONMENT` and `REGISTRY_SECRETS` override the defaults (`agglayer/aggkit`, `agglayer`, `release-approvers`, `release-manager`, `release`, `RELEASE_REGISTRY_USER RELEASE_REGISTRY_TOKEN`).
+
+Expected: every line is `PASS`, except the package control, which prints `MANUAL` and must be confirmed by hand as in steps 5 and 6. The check lists the names of the environment secrets (`environment-secrets`); it cannot tell whether the same names also exist as repository or organization secrets, so confirm that with the commands of step 6. If the token cannot read environment secrets (this needs repository admin access), that line prints `MANUAL` instead. The script exits non-zero when any control prints `FAIL`. The script only reads settings; it changes nothing.
+
+### 9. Dry run with a release candidate
+
+Before the first real release, push a pre-release tag (for example `v0.0.0-rc.1`, from a commit on `develop` or a `release/*` branch) and check each control:
+
+1. The `Release` run finishes `preflight` and `build`, and then `publish` waits for review of the `release` environment. The `build` job summaries show the staged image digests in `ghcr.io/agglayer/aggkit-dev`, and nothing exists yet in `ghcr.io/agglayer/aggkit` for the version (`docker buildx imagetools inspect ghcr.io/agglayer/aggkit:` reports not found).
+2. The person who pushed the tag cannot approve the run, and a user outside `release-approvers` cannot either.
+3. A `v*` tag on a commit that is not on `develop` or a `release/*` branch fails in `preflight` and never reaches `build` or `publish`.
+4. After approval, `publish` prints the tag, the commit, the version and the same digests, and creates the tags in `aggkit`. The platform image digests inside the published manifest list match the staged digests. The login to `ghcr.io` in `publish` succeeds with the release credential, and the signature and attestation pushes work with it.
+5. A run started from a branch is not accepted by the `release` environment, so it cannot read `RELEASE_REGISTRY_TOKEN`.
+6. After a green run, verify the result as described in [Verifying release images](./release_verification.md): `cosign verify` succeeds for the new tags, and `gh attestation verify` succeeds.
+
+Tag names are immutable once published, so use a throwaway version for the dry run and do not reuse it.
+
+## When publishing fails part way
+
+If `preflight` or `build` fails, nothing was written to `aggkit`; only untagged staged digests may remain in `aggkit-dev`, and a re-run after fixing the cause is safe. If a run is not approved or is rejected, the staged images stay in `aggkit-dev` unreferenced and are not published. The staged digests that `publish` needs are kept as run artifacts for 30 days, which is also the longest a run can wait for approval; a run approved or re-run after the artifacts expired fails in `publish` without writing anything, so tag a new version instead.
+
+The `publish` job pushes the manifest lists first and then signs them and creates the attestation. If signing or the attestation fails after the manifests were pushed, the version is already visible in the registry but is not signed. Do not trust or use an unsigned published version. Either use "Re-run failed jobs" on the run, which skips `preflight` and `build`, asks for the approval of the `release` environment again, and finishes the publication with the same staged digests, or cut a new version. A full re-run of the whole workflow fails in `preflight` because the version is already published.
+
+Besides the version tags, the package also lists signature and attestation artifacts (tags such as `sha256-.sig` and referrers of the images). These are expected and are not extra releases.
+
+## Residual risks
+
+- Two colluding maintainers (one starting the run, one in `release-approvers`) can still publish an image. Keep the approver team small and review membership regularly.
+- Whoever can read the `release` environment secrets, or create and replace the machine account token, can publish to `aggkit` without a release run. Keep the repository admins and the owners of the machine account few, audit changes to the environment secrets, and rotate the token on a schedule and after any change in who can administer the repository.
+- A tag that passes the environment rules gives its workflow run, after the approval, the registry credential. The run uses the workflow file of the tagged commit, so the tag ruleset (step 3), the protection of the branches the tag must come from (step 4) and the review of the approvers are what keep a modified workflow from using it. The environment only deploys from `v*` tags, so a workflow on a branch cannot get the credential.
+- If the `aggkit` package ever grants the repository Actions access again (for example when the package is recreated, or inheritance is switched back on), `GITHUB_TOKEN` with `packages: write` can write to it again from any workflow, and the environment credential no longer is the only way in. Re-check step 5 after any change to the package, and keep running the settings check.
+- A staged image can be tampered with only in a bounded way. `publish` promotes the exact digests recorded by the `build` job of the same run, and a digest is the hash of the content, so a different image pushed to `aggkit-dev` cannot take their place and is never promoted. Anyone with write access to `aggkit-dev` can still add or delete versions there (for example delete a staged image, which makes `publish` fail), but cannot change what is promoted. For that reason `aggkit-dev` should grant write access only to the repository and the package admins, but it is not part of the trust base of a published image.
+- The reviewer sees the staged digests in the `build` job summaries before approving, not a human-readable review of the code in the images. The approval confirms the tag, the commit and that the build succeeded, including the version check inside the image.
+- The ancestry check in `preflight` relies on steps 3 and 4. Tag-triggered runs use the workflow file from the tagged commit, so someone who can push a tag could also push a modified workflow. Protecting tags (step 3) and the branches the tags must come from (step 4) is what keeps this check meaningful.
diff --git a/docs/release_lifecycle.md b/docs/release_lifecycle.md
index 3a8533bad..8c1f73b00 100644
--- a/docs/release_lifecycle.md
+++ b/docs/release_lifecycle.md
@@ -34,6 +34,13 @@ As a quick reference this is the diagram of the branching cycle:
 
 ![image.png](assets/gitflow.png)
 
+## Publishing and verifying images
+
+Release images are published only from a release tag, after the tagged commit passes the release checks and the images are built and staged, and a reviewer approves them. The approved images are then promoted by digest to the release package. Each image is signed and has build provenance and an SBOM.
+
+- [Verifying release images](./release_verification.md): published tags, signature and provenance verification, pinning by digest.
+- [Release settings runbook](./release_admin_runbook.md): the repository and organization settings that protect the release process, and how to check them.
+
 ## FAQ
 
 ### Should I cherry pick commits made to a release branch while it’s still unmerged?
diff --git a/docs/release_verification.md b/docs/release_verification.md
new file mode 100644
index 000000000..0988bdea2
--- /dev/null
+++ b/docs/release_verification.md
@@ -0,0 +1,91 @@
+# Verifying release images
+
+This page is for people who run Aggkit. It explains which images are published, how to check that an image really came from the Aggkit release process, and how to pin it in a deployment.
+
+## Published tags
+
+Release images are published to `ghcr.io/agglayer/aggkit`, one set of tags per release version `X.Y.Z` (for example `1.2.3`, or `1.2.3-rc.1` for a pre-release):
+
+| Tag | Content |
+| --- | --- |
+| `X.Y.Z` | Production image, no shell. `linux/amd64` and `linux/arm64`. |
+| `X.Y.Z-no_shell` | Alias of `X.Y.Z` (same image). |
+| `X.Y.Z-dev` | Development image that includes a shell, for debugging. Not recommended for production. |
+
+Only exact versions are published and a published version is never overwritten. The package also lists signature and attestation artifacts next to these tags (for example `sha256-.sig` tags and referrers of the images); they are not extra versions.
+
+Release images reach `ghcr.io/agglayer/aggkit` only through the release workflow, in this order: the platform images are built and staged in `ghcr.io/agglayer/aggkit-dev` (see below), a reviewer approves them, and only then are the tags above created in `aggkit` from those exact images and signed. A release that fails to build or is not approved never appears in `aggkit`. The credential that can write to `aggkit` is stored only as secrets of the release environment that the reviewer approves; the workflow token of the repository, which builds and stages the images, cannot write to `aggkit`.
+
+If signing or attestation fails after the manifests were pushed, the version is visible but unsigned. Treat an unsigned version as unusable: it is either completed by re-running the failed jobs or replaced by a new version. Always verify the signature before using an image.
+
+**Change:** the moving `X.Y` tags (for example `1.2`, `1.2-no_shell`, `1.2-dev`) and the `latest` tag are no longer published. Pin an exact version. Existing `X.Y` and `latest` tags in the registry are not updated any more, so a deployment that follows them silently stays on an old image.
+
+Each platform image carries an SBOM and build provenance, and each manifest list is signed (see below).
+
+The production tag `X.Y.Z` resolves to a manifest list that contains the production images only. The `-dev` platform images are assembled into their own manifest list under `X.Y.Z-dev`.
+
+### Branch builds
+
+`ghcr.io/agglayer/aggkit-dev` holds images built manually from a branch, tagged with the branch name, a timestamp and the commit. They are for testing only, are not release candidates and are not signed as releases. Do not use them in production.
+
+### Staged release candidates
+
+`aggkit-dev` is also the staging area of the release workflow. While a release is built and waiting for approval, its per-platform images are pushed there by digest, without a tag, next to the branch builds. These images are not published releases: they are unsigned, may belong to a release that is never approved, and can be written to by anyone who has write access to `aggkit-dev`. Use only the tags in `ghcr.io/agglayer/aggkit`, and verify them as described below. The approved images are copied to `aggkit` by digest, so the platform images in a published version are the ones that were built and reviewed in the same run.
+
+### Images published before this change
+
+Images published before signing was introduced are unsigned and have no attestation. `cosign verify` and `gh attestation verify` fail for them. Use a version published after this change when you need verified images.
+
+## Verify the signature
+
+Every release image is signed with [cosign](https://docs.sigstore.dev/cosign/overview/) keyless signing. The signing identity is the release workflow of this repository, running at a `v*` tag:
+
+```bash
+cosign verify ghcr.io/agglayer/aggkit: \
+  --certificate-identity-regexp '^https://github.com/agglayer/aggkit/.github/workflows/release.yml@refs/tags/v.*$' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+```
+
+A successful run prints the verified claims, including the workflow identity and the tag. Any other identity, issuer or an unsigned image makes the command fail.
+
+## Verify build provenance
+
+Release images also have a GitHub build provenance attestation, stored in the registry next to the image. Verify it with the GitHub CLI:
+
+```bash
+gh attestation verify oci://ghcr.io/agglayer/aggkit: \
+  --repo agglayer/aggkit \
+  --signer-workflow agglayer/aggkit/.github/workflows/release.yml
+```
+
+This confirms the image was built by the release workflow of `agglayer/aggkit`.
+
+## Inspect the SBOM
+
+The platform images carry a software bill of materials:
+
+```bash
+docker buildx imagetools inspect ghcr.io/agglayer/aggkit: --format '{{ json .SBOM }}'
+```
+
+The build provenance of the platform images can be read the same way with `--format '{{ json .Provenance }}'`.
+
+## Pin by digest
+
+Tags can be moved by whoever has push access to the registry; a digest cannot. Resolve the digest of a version you verified and deploy that:
+
+```bash
+docker buildx imagetools inspect ghcr.io/agglayer/aggkit: --format '{{json .Manifest}}' | jq -r .digest
+```
+
+Then reference the image as `ghcr.io/agglayer/aggkit@sha256:` (optionally keeping the tag for readability: `aggkit:@sha256:`). Verify the signature against the digest, not only the tag:
+
+```bash
+cosign verify ghcr.io/agglayer/aggkit@sha256: \
+  --certificate-identity-regexp '^https://github.com/agglayer/aggkit/.github/workflows/release.yml@refs/tags/v.*$' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+```
+
+## Enforce verification in the cluster
+
+Running the commands above by hand only helps if someone remembers to do it. For deployments that matter, enforce the check at admission time, so an image that is unsigned or signed by a different identity is refused. Kubernetes admission controllers such as Sigstore policy-controller, Kyverno or Ratify can require a valid cosign signature with the same identity regexp and issuer shown above, and can require images to be referenced by digest.
diff --git a/scripts/release/check_release_settings.sh b/scripts/release/check_release_settings.sh
new file mode 100755
index 000000000..eb0611e79
--- /dev/null
+++ b/scripts/release/check_release_settings.sh
@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+# Audits the repository and organization settings that gate releases.
+# Read-only: only GET calls are made through the GitHub CLI.
+# Branch rules are read from rulesets only; classic branch protection is not checked.
+#
+# Usage: check_release_settings.sh [--json]
+# Env:   REPO (agglayer/aggkit), ORG (owner of REPO), APPROVERS_TEAM
+#        (release-approvers), RELEASE_TEAM (release-manager), ENVIRONMENT (release),
+#        REGISTRY_SECRETS (space separated names of the environment secrets that
+#        hold the production registry credential)
+# Output: one line per control: PASS|FAIL|MANUAL : 
+# Exit:   1 when any control FAILs, otherwise 0.
+set -uo pipefail
+
+REPO="${REPO:-agglayer/aggkit}"
+ORG="${ORG:-${REPO%%/*}}"
+APPROVERS_TEAM="${APPROVERS_TEAM:-release-approvers}"
+RELEASE_TEAM="${RELEASE_TEAM:-release-manager}"
+ENVIRONMENT="${ENVIRONMENT:-release}"
+REGISTRY_SECRETS="${REGISTRY_SECRETS:-RELEASE_REGISTRY_USER RELEASE_REGISTRY_TOKEN}"
+TAG_PATTERN='v*'
+
+JSON=0
+case "${1:-}" in
+  --json) JSON=1 ;;
+  "") ;;
+  *) echo "usage: $0 [--json]" >&2; exit 2 ;;
+esac
+
+for tool in gh jq; do
+  command -v "$tool" >/dev/null 2>&1 || { echo "missing required tool: $tool" >&2; exit 2; }
+done
+
+RESULTS=()
+FAILED=0
+
+report() { # status control detail
+  RESULTS+=("$(jq -cn --arg s "$1" --arg c "$2" --arg d "$3" '{status:$s,control:$c,detail:$d}')")
+  [ "$1" = FAIL ] && FAILED=1
+  [ "$JSON" -eq 1 ] || printf '%s %s: %s\n' "$1" "$2" "$3"
+}
+
+# api PATH: on success stores the body in API_BODY. On failure sets API_STATUS
+# to the HTTP status (or "error") and returns 1. Never call it in a subshell.
+API_STATUS=""
+API_BODY=""
+# api PATH [paginate]: with a second argument the endpoint is a JSON array that
+# is fetched page by page and merged into one array.
+api() {
+  local err raw
+  err="$(mktemp)"
+  API_BODY=""
+  if raw="$(gh api ${2:+--paginate} "$1" 2>"$err")"; then
+    if [ -n "${2:-}" ]; then
+      raw="$(jq -s 'add // []' <<<"$raw")" || { rm -f "$err"; API_STATUS=error; return 1; }
+    fi
+    API_BODY="$raw"
+    rm -f "$err"; API_STATUS=200; return 0
+  fi
+  API_STATUS="$(grep -o 'HTTP [0-9]*' "$err" | head -n1 | cut -d' ' -f2)"
+  API_STATUS="${API_STATUS:-error}"
+  rm -f "$err"
+  return 1
+}
+
+# --- 4 (done first: the tag ruleset check needs the release team id) -------
+TEAM_ID=""
+check_teams() {
+  local slug body missing=""
+  for slug in "$RELEASE_TEAM" "$APPROVERS_TEAM"; do
+    if api "orgs/$ORG/teams/$slug"; then body="$API_BODY"
+      [ "$slug" = "$RELEASE_TEAM" ] && TEAM_ID="$(jq -r '.id' <<<"$body")"
+    elif [ "$API_STATUS" = 404 ] || [ "$API_STATUS" = 403 ]; then
+      missing="$missing $slug($API_STATUS)"
+    else
+      missing="$missing $slug(error)"
+    fi
+  done
+  if [ -z "$missing" ]; then
+    report PASS teams "$RELEASE_TEAM and $APPROVERS_TEAM exist in $ORG"
+  else
+    report MANUAL teams "could not read:$missing; the API answers 404 for a missing team and also for a team the token cannot see, so grant the token org read (read:org) or check https://github.com/orgs/$ORG/teams"
+  fi
+}
+
+# --- 1 ---------------------------------------------------------------------
+check_tag_ruleset() {
+  local list ids id summary src detail found=0 best="" ok
+  if ! api "repos/$REPO/rulesets?targets=tag&includes_parents=true" paginate; then
+    report MANUAL tag-ruleset "cannot read rulesets (HTTP $API_STATUS); check https://github.com/$REPO/settings/rules"
+    return
+  fi
+  list="$API_BODY"
+  ids="$(jq -r '.[] | "\(.id)\t\(.source_type // "Repository")\t\(.source // "")"' <<<"$list")"
+  while IFS=$'\t' read -r id summary src; do
+    [ -n "$id" ] || continue
+    if [ "$summary" = Organization ]; then
+      api "orgs/${src:-$ORG}/rulesets/$id" || continue
+    else
+      api "repos/$REPO/rulesets/$id" || continue
+    fi
+    detail="$API_BODY"
+    ok="$(jq -r --arg pat "refs/tags/$TAG_PATTERN" '
+      def covers: ((.conditions.ref_name.include // []) | any(. == $pat or . == "~ALL" or . == "refs/tags/**" or . == "refs/tags/*"))
+                  and (((.conditions.ref_name.exclude // []) | any(. == $pat)) | not);
+      ([.rules[].type] ) as $t
+      | if (.enforcement == "active") and covers
+           and ($t | index("creation")) and ($t | index("update"))
+           and ($t | index("deletion")) and ($t | index("non_fast_forward"))
+        then "yes" else "no" end' <<<"$detail")"
+    if [ "$ok" = yes ]; then found=1; best="$detail"; break; fi
+  done <<<"$ids"
+  if [ "$found" -eq 0 ]; then
+    report FAIL tag-ruleset "no active tag ruleset covers refs/tags/$TAG_PATTERN with creation, update, deletion and non_fast_forward rules"
+    return
+  fi
+  # Organization admins may bypass the tag ruleset on purpose: that use is
+  # recorded in the organization audit log. Any other actor is a failure.
+  local name actors bad
+  name="$(jq -r '.name' <<<"$best")"
+  actors="$(jq -r '[.bypass_actors[]? | "\(.actor_type)#\(.actor_id // "-")(\(.bypass_mode // "always"))"] | if length == 0 then "none" else join(", ") end' <<<"$best")"
+  if [ -z "$TEAM_ID" ]; then
+    report MANUAL tag-ruleset "ruleset '$name' has the required rules; bypass actors: $actors; the id of team $RELEASE_TEAM is not readable, so verify the bypass list by hand"
+    return
+  fi
+  bad="$(jq -r --argjson tid "$TEAM_ID" '[.bypass_actors[]? | select((.actor_type == "Team" and .actor_id == $tid) or .actor_type == "OrganizationAdmin" | not) | "\(.actor_type)#\(.actor_id // "-")"] | join(", ")' <<<"$best")"
+  if ! jq -e --argjson tid "$TEAM_ID" 'any(.bypass_actors[]?; .actor_type == "Team" and .actor_id == $tid)' <<<"$best" >/dev/null; then
+    report FAIL tag-ruleset "ruleset '$name' bypass actors: $actors; $RELEASE_TEAM is not among them"
+  elif [ -n "$bad" ]; then
+    report FAIL tag-ruleset "ruleset '$name' bypass is broader than $RELEASE_TEAM and org admins: $bad (all: $actors)"
+  else
+    report PASS tag-ruleset "ruleset '$name' is active on refs/tags/$TAG_PATTERN with creation, update, deletion, non_fast_forward; bypass actors: $actors"
+  fi
+}
+
+# --- 2 ---------------------------------------------------------------------
+check_environment() {
+  local env pols problems=""
+  if ! api "repos/$REPO/environments/$ENVIRONMENT"; then
+    report FAIL environment "environment $ENVIRONMENT not readable (HTTP $API_STATUS)"
+    return
+  fi
+  env="$API_BODY"
+  jq -e --arg t "$APPROVERS_TEAM" 'any(.protection_rules[]?; .type == "required_reviewers" and any(.reviewers[]?; .type == "Team" and (.reviewer.slug == $t or .reviewer.name == $t)))' <<<"$env" >/dev/null \
+    || problems="$problems required reviewers do not include team $APPROVERS_TEAM;"
+  jq -e 'any(.protection_rules[]?; .type == "required_reviewers" and .prevent_self_review == true)' <<<"$env" >/dev/null \
+    || problems="$problems prevent_self_review is not enabled;"
+  jq -e '.can_admins_bypass == false' <<<"$env" >/dev/null \
+    || problems="$problems administrators can bypass the environment protection rules (can_admins_bypass is not false);"
+  if jq -e '.deployment_branch_policy.custom_branch_policies == true' <<<"$env" >/dev/null; then
+    if api "repos/$REPO/environments/$ENVIRONMENT/deployment-branch-policies"; then pols="$API_BODY"
+      jq -e --arg p "$TAG_PATTERN" '(.branch_policies | length) > 0 and all(.branch_policies[]; .type == "tag" and .name == $p)' <<<"$pols" >/dev/null \
+        || problems="$problems deployment policies are not restricted to tags $TAG_PATTERN ($(jq -r '[.branch_policies[]? | "\(.type):\(.name)"] | join(",")' <<<"$pols"));"
+    else
+      problems="$problems cannot read deployment policies (HTTP $API_STATUS);"
+    fi
+  else
+    problems="$problems no custom deployment policy;"
+  fi
+  if [ -z "$problems" ]; then
+    report PASS environment "$ENVIRONMENT requires $APPROVERS_TEAM, prevents self review, admins cannot bypass, deploys only from tags $TAG_PATTERN"
+  else
+    report FAIL environment "$ENVIRONMENT:${problems%;}"
+  fi
+}
+
+# The credential for the production package must exist only as secrets of the
+# release environment. Secret values are never readable; only the names are.
+check_environment_secrets() {
+  local name missing=""
+  if ! api "repos/$REPO/environments/$ENVIRONMENT/secrets"; then
+    report MANUAL environment-secrets "cannot read the secrets of environment $ENVIRONMENT (HTTP $API_STATUS); check https://github.com/$REPO/settings/environments that ${REGISTRY_SECRETS// /, } exist there"
+    return
+  fi
+  for name in $REGISTRY_SECRETS; do
+    jq -e --arg n "$name" 'any(.secrets[]?; .name == $n)' <<<"$API_BODY" >/dev/null || missing="$missing $name"
+  done
+  if [ -z "$missing" ]; then
+    report PASS environment-secrets "environment $ENVIRONMENT has the secrets ${REGISTRY_SECRETS// /, }; also check that they are not repository or organization secrets"
+  else
+    report FAIL environment-secrets "environment $ENVIRONMENT is missing the secrets:${missing// /, }"
+  fi
+}
+
+# --- 3 ---------------------------------------------------------------------
+# Only rulesets are inspected (rules/branches returns ruleset rules); classic
+# branch protection is not read and is reported as missing rules.
+check_branch_rules() {
+  local branch rules refs problems rid rsrc rbody bypass branches=()
+  if api "repos/$REPO/git/matching-refs/heads/release/" paginate; then refs="$API_BODY"
+    while IFS= read -r branch; do
+      [ -n "$branch" ] && branches+=("$branch")
+    done < <(jq -r '.[].ref | sub("^refs/heads/"; "")' <<<"$refs" | sort -V)
+  fi
+  [ "${#branches[@]}" -gt 0 ] || report MANUAL branch-rules "no release/* branch found to check"
+  for branch in develop "${branches[@]}"; do
+    if ! api "repos/$REPO/rules/branches/$branch" paginate; then
+      report MANUAL "branch-rules[$branch]" "cannot read effective rules (HTTP $API_STATUS)"
+      continue
+    fi
+    rules="$API_BODY"
+    problems=""
+    jq -e 'any(.[]; .type == "pull_request" and (.parameters.required_approving_review_count // 0) >= 1)' <<<"$rules" >/dev/null \
+      || problems="$problems pull_request with at least 1 approval missing (found $(jq -r '[.[] | select(.type == "pull_request") | .parameters.required_approving_review_count] | if length == 0 then "no pull_request rule" else join(",") end' <<<"$rules"));"
+    jq -e 'any(.[]; .type == "deletion")' <<<"$rules" >/dev/null || problems="$problems deletion not forbidden;"
+    jq -e 'any(.[]; .type == "non_fast_forward")' <<<"$rules" >/dev/null || problems="$problems force push not forbidden;"
+    # Bypass actors of every ruleset that contributes a rule to this branch.
+    while IFS=$'\t' read -r rid rsrc; do
+      [ -n "$rid" ] || continue
+      if [ "$rsrc" = Organization ]; then
+        api "orgs/$ORG/rulesets/$rid" || { problems="$problems cannot read bypass actors of ruleset $rid (HTTP $API_STATUS);"; continue; }
+      else
+        api "repos/$REPO/rulesets/$rid" || { problems="$problems cannot read bypass actors of ruleset $rid (HTTP $API_STATUS);"; continue; }
+      fi
+      rbody="$API_BODY"
+      bypass="$(jq -r '[.bypass_actors[]? | "\(.actor_type)#\(.actor_id // "-")"] | join(", ")' <<<"$rbody")"
+      [ -z "$bypass" ] || problems="$problems ruleset '$(jq -r '.name' <<<"$rbody")' has bypass actors: $bypass;"
+    done < <(jq -r '[.[] | select(.ruleset_id != null) | "\(.ruleset_id)\t\(.ruleset_source_type // "Repository")"] | unique | .[]' <<<"$rules")
+    if [ -z "$problems" ]; then
+      report PASS "branch-rules[$branch]" "pull_request with at least 1 approval, deletion and force push forbidden, no bypass actors"
+    else
+      problems="${problems# }"; report FAIL "branch-rules[$branch]" "${problems%;}"
+    fi
+  done
+}
+
+# --- 5 ---------------------------------------------------------------------
+check_package() {
+  local name pkg extra=""
+  name="${REPO#*/}"
+  if api "orgs/$ORG/packages/container/$name"; then pkg="$API_BODY"
+    extra=" (visibility: $(jq -r '.visibility' <<<"$pkg"), linked repository: $(jq -r '.repository.full_name // "none"' <<<"$pkg"))"
+  else
+    extra=" (package not readable, HTTP $API_STATUS; the token may lack read:packages)"
+  fi
+  report MANUAL ghcr-package-acl "the API does not expose package Actions access or inheritance; check https://github.com/orgs/$ORG/packages/container/$name/settings: 'Inherit access from source repository' must be off and Manage Actions access must not list $REPO, so that besides the package admins only the credential held by environment $ENVIRONMENT can write$extra"
+}
+
+
+check_teams
+check_tag_ruleset
+check_environment
+check_environment_secrets
+check_branch_rules
+check_package
+
+if [ "$JSON" -eq 1 ]; then
+  printf '%s\n' "${RESULTS[@]}" | jq -s '.'
+fi
+exit "$FAILED"
diff --git a/scripts/release/check_release_settings_test.sh b/scripts/release/check_release_settings_test.sh
new file mode 100755
index 000000000..beb156229
--- /dev/null
+++ b/scripts/release/check_release_settings_test.sh
@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Tests check_release_settings.sh against a stub `gh` that serves fixtures.
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# Stub gh: `gh api [flags] PATH` prints testdata/$SCENARIO/ (falling back
+# to testdata/pass), with '/', '?', '&' and '=' mapped to '_'.
+cat > "$TMP/gh" <<'STUB'
+#!/usr/bin/env bash
+[ "${1:-}" = api ] || { echo "stub gh: unsupported: $*" >&2; exit 2; }
+shift
+path=""
+for a in "$@"; do case "$a" in -*) ;; *) path="$a"; break ;; esac; done
+name="$(printf '%s' "$path" | tr '/?&=' '____')"
+for dir in "$SCENARIO" pass; do
+  if [ -f "$TESTDATA/$dir/$name" ]; then cat "$TESTDATA/$dir/$name"; exit 0; fi
+done
+echo "gh: Not Found (HTTP 404)" >&2
+exit 1
+STUB
+chmod +x "$TMP/gh"
+
+export TESTDATA="$HERE/testdata" REPO=acme/widget
+FAILS=0
+
+run() { # scenario -> sets OUT and RC
+  OUT="$(PATH="$TMP:$PATH" SCENARIO="$1" "$HERE/check_release_settings.sh" "${@:2}" 2>&1)"
+  RC=$?
+}
+expect() { # description, condition result
+  if [ "$2" -eq 0 ]; then echo "ok   $1"; else echo "FAIL $1"; FAILS=$((FAILS + 1)); fi
+}
+has() { grep -Eq "$1" <<<"$OUT"; }
+
+run pass
+expect "all-pass: exit 0" "$([ "$RC" -eq 0 ]; echo $?)"
+expect "all-pass: no FAIL lines" "$(has '^FAIL' && echo 1 || echo 0)"
+expect "all-pass: tag ruleset PASS" "$(has '^PASS tag-ruleset' ; echo $?)"
+expect "all-pass: environment PASS" "$(has '^PASS environment'; echo $?)"
+expect "all-pass: environment secrets PASS" "$(has '^PASS environment-secrets'; echo $?)"
+expect "all-pass: teams PASS" "$(has '^PASS teams'; echo $?)"
+expect "all-pass: both branch checks PASS" "$(has '^PASS branch-rules\[develop\]' && has '^PASS branch-rules\[release/1.1\]' && has '^PASS branch-rules\[release/1.2\]' && has '^PASS branch-rules\[release/1.10\]'; echo $?)"
+expect "package ACL is MANUAL" "$(has '^MANUAL ghcr-package-acl'; echo $?)"
+expect "package visibility reported" "$(has 'visibility: private'; echo $?)"
+
+run no_ruleset
+expect "missing tag ruleset: FAIL line" "$(has '^FAIL tag-ruleset'; echo $?)"
+expect "missing tag ruleset: exit 1" "$([ "$RC" -eq 1 ]; echo $?)"
+
+run no_self_review
+expect "no prevent-self-review: FAIL line" "$(has '^FAIL environment.*prevent_self_review'; echo $?)"
+expect "no prevent-self-review: exit 1" "$([ "$RC" -eq 1 ]; echo $?)"
+
+run no_secrets
+expect "missing environment secret: FAIL line" "$(has '^FAIL environment-secrets.*RELEASE_REGISTRY_TOKEN'; echo $?)"
+expect "missing environment secret: exit 1" "$([ "$RC" -eq 1 ]; echo $?)"
+
+run admin_bypass
+expect "admin bypass on environment: FAIL line" "$(has '^FAIL environment.*can_admins_bypass'; echo $?)"
+expect "admin bypass on environment: exit 1" "$([ "$RC" -eq 1 ]; echo $?)"
+
+run branch_bypass
+expect "branch ruleset bypass actor: FAIL line" "$(has '^FAIL branch-rules\[release/1.2\].*bypass actors'; echo $?)"
+expect "branch ruleset bypass actor: exit 1" "$([ "$RC" -eq 1 ]; echo $?)"
+
+run old_branch_weak
+expect "older release branch without rules: FAIL line" "$(has '^FAIL branch-rules\[release/1.1\]'; echo $?)"
+expect "older release branch without rules: exit 1" "$([ "$RC" -eq 1 ]; echo $?)"
+
+run pass --json
+expect "--json is a valid array" "$(jq -e 'type == "array" and length > 0' <<<"$OUT" >/dev/null; echo $?)"
+
+[ "$FAILS" -eq 0 ] || { echo "$FAILS check(s) failed"; exit 1; }
+echo "all tests passed"
diff --git a/scripts/release/check_tag_ancestry.sh b/scripts/release/check_tag_ancestry.sh
new file mode 100755
index 000000000..0e20b8352
--- /dev/null
+++ b/scripts/release/check_tag_ancestry.sh
@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Verify that a release tag points at a commit reachable from origin/develop
+# or from an origin/release/* branch, and emit the version (without "v").
+#
+# Usage: GITHUB_REF=refs/tags/v1.2.3 check_tag_ancestry.sh
+#        check_tag_ancestry.sh refs/tags/v1.2.3
+# Env:   REMOTE (default: origin), SKIP_FETCH=1 to skip fetching branches.
+set -euo pipefail
+
+ref="${1:-${GITHUB_REF:-}}"
+remote="${REMOTE:-origin}"
+
+if [[ -z "$ref" ]]; then
+  echo "error: no ref given (set GITHUB_REF or pass it as first argument)" >&2
+  exit 1
+fi
+
+# Strict semver: no leading zeros in X.Y.Z, dot-separated prerelease
+# identifiers (numeric ones without leading zeros).
+num='(0|[1-9][0-9]*)'
+ident='(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)'
+re="^refs/tags/v${num}\\.${num}\\.${num}(-${ident}(\\.${ident})*)?\$"
+if [[ ! "$ref" =~ $re ]]; then
+  echo "error: '$ref' is not a release tag (expected refs/tags/vX.Y.Z or refs/tags/vX.Y.Z-
, semver without leading zeros)" >&2
+  exit 1
+fi
+
+# A prerelease named dev or ending in -dev would produce an image tag that
+# collides with the dev variant of another version.
+if [[ "$ref" =~ (-|\.)dev$ ]]; then
+  echo "error: '$ref' has a prerelease that is or ends in 'dev', which is reserved for dev images" >&2
+  exit 1
+fi
+
+tag="${ref#refs/tags/}"
+version="${tag#v}"
+
+if ! commit="$(git rev-parse --verify --quiet "refs/tags/${tag}^{commit}")"; then
+  echo "error: cannot resolve tag '$tag' to a commit" >&2
+  exit 1
+fi
+
+if [[ "${SKIP_FETCH:-}" != "1" ]]; then
+  git fetch --no-tags "$remote" \
+    '+refs/heads/develop:refs/remotes/origin/develop' \
+    '+refs/heads/release/*:refs/remotes/origin/release/*'
+fi
+
+bases=()
+if git rev-parse --verify --quiet refs/remotes/origin/develop >/dev/null; then
+  bases+=("origin/develop")
+fi
+while IFS= read -r b; do
+  bases+=("$b")
+done < <(git for-each-ref --format='%(refname:short)' 'refs/remotes/origin/release/*')
+
+for base in "${bases[@]}"; do
+  if git merge-base --is-ancestor "$commit" "refs/remotes/$base"; then
+    echo "ok: tag $tag ($commit) is an ancestor of $base"
+    if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
+      echo "version=$version" >>"$GITHUB_OUTPUT"
+    fi
+    exit 0
+  fi
+done
+
+echo "error: tag $tag (commit $commit) is not an ancestor of origin/develop or any origin/release/* branch" >&2
+exit 1
diff --git a/scripts/release/check_tag_ancestry_test.sh b/scripts/release/check_tag_ancestry_test.sh
new file mode 100755
index 000000000..4e81a316c
--- /dev/null
+++ b/scripts/release/check_tag_ancestry_test.sh
@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Tests for check_tag_ancestry.sh using a throwaway repository and a fake origin.
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+script="$script_dir/check_tag_ancestry.sh"
+
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+export GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null
+export GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@example.com
+export GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@example.com
+
+git init -q --bare "$tmp/origin.git"
+git init -q -b develop "$tmp/work"
+cd "$tmp/work"
+git remote add origin "$tmp/origin.git"
+
+commit() { git commit -q --allow-empty -m "$1"; }
+
+commit base
+git tag v1.0.0
+commit dev-only
+git tag v1.1.0
+git push -q origin develop
+
+git checkout -q -b release/0.11 v1.0.0
+commit rel-only
+git tag v0.11.1
+git tag v0.11.2-rc.1
+git push -q origin release/0.11
+
+git checkout -q --orphan attacker
+git rm -rfq . 2>/dev/null || true
+commit evil
+git tag v9.9.9
+git push -q origin attacker
+
+git checkout -q develop
+
+failures=0
+run() { # name expected(0|1) ref
+  local name="$1" want="$2" ref="$3" out got=0
+  out="$tmp/gh_output"
+  : >"$out"
+  GITHUB_OUTPUT="$out" GITHUB_REF="$ref" "$script" >"$tmp/log" 2>&1 || got=$?
+  if [[ "$got" -ne 0 ]]; then got=1; fi
+  if [[ "$got" -eq "$want" ]]; then
+    echo "PASS: $name"
+  else
+    echo "FAIL: $name (exit $got, wanted $want)"
+    cat "$tmp/log"
+    failures=$((failures + 1))
+  fi
+}
+
+run "tag on develop" 0 refs/tags/v1.1.0
+run "tag on develop and release" 0 refs/tags/v1.0.0
+run "tag only on release/0.11" 0 refs/tags/v0.11.1
+run "prerelease tag on release/0.11" 0 refs/tags/v0.11.2-rc.1
+run "tag on unrelated branch" 1 refs/tags/v9.9.9
+run "malformed tag" 1 refs/tags/v1.2
+run "malformed tag prefix" 1 refs/tags/1.1.0
+run "malformed prerelease" 1 'refs/tags/v1.1.0-bad_pre'
+run "leading zero in major" 1 refs/tags/v01.2.3
+run "leading zero in prerelease" 1 refs/tags/v1.2.3-rc.01
+run "dev prerelease" 1 refs/tags/v1.2.3-dev
+run "prerelease ending in dev" 1 refs/tags/v1.2.3-rc-dev
+run "branch ref" 1 refs/heads/develop
+run "empty ref" 1 ""
+
+# Version output.
+: >"$tmp/gh_output"
+GITHUB_OUTPUT="$tmp/gh_output" GITHUB_REF=refs/tags/v0.11.2-rc.1 "$script" >/dev/null 2>&1
+if grep -qx 'version=0.11.2-rc.1' "$tmp/gh_output"; then
+  echo "PASS: version output"
+else
+  echo "FAIL: version output"
+  failures=$((failures + 1))
+fi
+
+# Works without fetching when remote refs are already present.
+git fetch -q --no-tags origin '+refs/heads/develop:refs/remotes/origin/develop' '+refs/heads/release/*:refs/remotes/origin/release/*'
+got=0
+SKIP_FETCH=1 GITHUB_REF=refs/tags/v0.11.1 "$script" >/dev/null 2>&1 || got=$?
+if [[ "$got" -eq 0 ]]; then echo "PASS: SKIP_FETCH"; else echo "FAIL: SKIP_FETCH"; failures=$((failures + 1)); fi
+
+if [[ "$failures" -ne 0 ]]; then
+  echo "$failures test(s) failed"
+  exit 1
+fi
+echo "all tests passed"
diff --git a/scripts/release/testdata/admin_bypass/repos_acme_widget_environments_release b/scripts/release/testdata/admin_bypass/repos_acme_widget_environments_release
new file mode 100644
index 000000000..a09452248
--- /dev/null
+++ b/scripts/release/testdata/admin_bypass/repos_acme_widget_environments_release
@@ -0,0 +1,2 @@
+{"name":"release","can_admins_bypass":true,"protection_rules":[{"id":1,"type":"required_reviewers","prevent_self_review":true,"reviewers":[{"type":"Team","reviewer":{"id":1002,"slug":"release-approvers","name":"release-approvers"}}]}],
+ "deployment_branch_policy":{"protected_branches":false,"custom_branch_policies":true}}
diff --git a/scripts/release/testdata/branch_bypass/repos_acme_widget_rules_branches_release_1.2 b/scripts/release/testdata/branch_bypass/repos_acme_widget_rules_branches_release_1.2
new file mode 100644
index 000000000..0888c23ed
--- /dev/null
+++ b/scripts/release/testdata/branch_bypass/repos_acme_widget_rules_branches_release_1.2
@@ -0,0 +1 @@
+[{"type":"deletion","ruleset_id":9,"ruleset_source_type":"Repository"},{"type":"non_fast_forward","ruleset_id":9,"ruleset_source_type":"Repository"},{"type":"pull_request","ruleset_id":9,"ruleset_source_type":"Repository","parameters":{"required_approving_review_count":1}}]
\ No newline at end of file
diff --git a/scripts/release/testdata/branch_bypass/repos_acme_widget_rulesets_9 b/scripts/release/testdata/branch_bypass/repos_acme_widget_rulesets_9
new file mode 100644
index 000000000..a237240cb
--- /dev/null
+++ b/scripts/release/testdata/branch_bypass/repos_acme_widget_rulesets_9
@@ -0,0 +1 @@
+{"id":9,"name":"release branches","bypass_actors":[{"actor_type":"RepositoryRole","actor_id":5,"bypass_mode":"always"}]}
\ No newline at end of file
diff --git a/scripts/release/testdata/no_ruleset/repos_acme_widget_rulesets_targets_tag_includes_parents_true b/scripts/release/testdata/no_ruleset/repos_acme_widget_rulesets_targets_tag_includes_parents_true
new file mode 100644
index 000000000..fe51488c7
--- /dev/null
+++ b/scripts/release/testdata/no_ruleset/repos_acme_widget_rulesets_targets_tag_includes_parents_true
@@ -0,0 +1 @@
+[]
diff --git a/scripts/release/testdata/no_secrets/repos_acme_widget_environments_release_secrets b/scripts/release/testdata/no_secrets/repos_acme_widget_environments_release_secrets
new file mode 100644
index 000000000..a182c6fd3
--- /dev/null
+++ b/scripts/release/testdata/no_secrets/repos_acme_widget_environments_release_secrets
@@ -0,0 +1 @@
+{"total_count":1,"secrets":[{"name":"RELEASE_REGISTRY_USER","created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}]}
diff --git a/scripts/release/testdata/no_self_review/repos_acme_widget_environments_release b/scripts/release/testdata/no_self_review/repos_acme_widget_environments_release
new file mode 100644
index 000000000..1a9b5e851
--- /dev/null
+++ b/scripts/release/testdata/no_self_review/repos_acme_widget_environments_release
@@ -0,0 +1,2 @@
+{"name":"release","can_admins_bypass":false,"protection_rules":[{"id":1,"type":"required_reviewers","prevent_self_review":false,"reviewers":[{"type":"Team","reviewer":{"id":1002,"slug":"release-approvers","name":"release-approvers"}}]}],
+ "deployment_branch_policy":{"protected_branches":false,"custom_branch_policies":true}}
diff --git a/scripts/release/testdata/old_branch_weak/repos_acme_widget_rules_branches_release_1.1 b/scripts/release/testdata/old_branch_weak/repos_acme_widget_rules_branches_release_1.1
new file mode 100644
index 000000000..0637a088a
--- /dev/null
+++ b/scripts/release/testdata/old_branch_weak/repos_acme_widget_rules_branches_release_1.1
@@ -0,0 +1 @@
+[]
\ No newline at end of file
diff --git a/scripts/release/testdata/pass/orgs_acme_packages_container_widget b/scripts/release/testdata/pass/orgs_acme_packages_container_widget
new file mode 100644
index 000000000..c67770d50
--- /dev/null
+++ b/scripts/release/testdata/pass/orgs_acme_packages_container_widget
@@ -0,0 +1 @@
+{"name":"widget","visibility":"private","repository":{"full_name":"acme/widget"}}
diff --git a/scripts/release/testdata/pass/orgs_acme_teams_release-approvers b/scripts/release/testdata/pass/orgs_acme_teams_release-approvers
new file mode 100644
index 000000000..a312bf564
--- /dev/null
+++ b/scripts/release/testdata/pass/orgs_acme_teams_release-approvers
@@ -0,0 +1 @@
+{"id":1002,"slug":"release-approvers"}
diff --git a/scripts/release/testdata/pass/orgs_acme_teams_release-manager b/scripts/release/testdata/pass/orgs_acme_teams_release-manager
new file mode 100644
index 000000000..f0289167f
--- /dev/null
+++ b/scripts/release/testdata/pass/orgs_acme_teams_release-manager
@@ -0,0 +1 @@
+{"id":1001,"slug":"release-manager"}
diff --git a/scripts/release/testdata/pass/repos_acme_widget_environments_release b/scripts/release/testdata/pass/repos_acme_widget_environments_release
new file mode 100644
index 000000000..ee8928fad
--- /dev/null
+++ b/scripts/release/testdata/pass/repos_acme_widget_environments_release
@@ -0,0 +1,2 @@
+{"name":"release","can_admins_bypass":false,"protection_rules":[{"id":1,"type":"required_reviewers","prevent_self_review":true,"reviewers":[{"type":"Team","reviewer":{"id":1002,"slug":"release-approvers","name":"release-approvers"}}]}],
+ "deployment_branch_policy":{"protected_branches":false,"custom_branch_policies":true}}
diff --git a/scripts/release/testdata/pass/repos_acme_widget_environments_release_deployment-branch-policies b/scripts/release/testdata/pass/repos_acme_widget_environments_release_deployment-branch-policies
new file mode 100644
index 000000000..55ed583fd
--- /dev/null
+++ b/scripts/release/testdata/pass/repos_acme_widget_environments_release_deployment-branch-policies
@@ -0,0 +1 @@
+{"total_count":1,"branch_policies":[{"id":1,"name":"v*","type":"tag"}]}
diff --git a/scripts/release/testdata/pass/repos_acme_widget_environments_release_secrets b/scripts/release/testdata/pass/repos_acme_widget_environments_release_secrets
new file mode 100644
index 000000000..9e30f5fb7
--- /dev/null
+++ b/scripts/release/testdata/pass/repos_acme_widget_environments_release_secrets
@@ -0,0 +1 @@
+{"total_count":2,"secrets":[{"name":"RELEASE_REGISTRY_TOKEN","created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"},{"name":"RELEASE_REGISTRY_USER","created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}]}
diff --git a/scripts/release/testdata/pass/repos_acme_widget_git_matching-refs_heads_release_ b/scripts/release/testdata/pass/repos_acme_widget_git_matching-refs_heads_release_
new file mode 100644
index 000000000..b72cab6a3
--- /dev/null
+++ b/scripts/release/testdata/pass/repos_acme_widget_git_matching-refs_heads_release_
@@ -0,0 +1 @@
+[{"ref":"refs/heads/release/1.1"},{"ref":"refs/heads/release/1.10"},{"ref":"refs/heads/release/1.2"}]
diff --git a/scripts/release/testdata/pass/repos_acme_widget_rules_branches_develop b/scripts/release/testdata/pass/repos_acme_widget_rules_branches_develop
new file mode 100644
index 000000000..6f0c32c91
--- /dev/null
+++ b/scripts/release/testdata/pass/repos_acme_widget_rules_branches_develop
@@ -0,0 +1 @@
+[{"type":"deletion"},{"type":"non_fast_forward"},{"type":"pull_request","parameters":{"required_approving_review_count":1}}]
diff --git a/scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.1 b/scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.1
new file mode 100644
index 000000000..6f0c32c91
--- /dev/null
+++ b/scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.1
@@ -0,0 +1 @@
+[{"type":"deletion"},{"type":"non_fast_forward"},{"type":"pull_request","parameters":{"required_approving_review_count":1}}]
diff --git a/scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.10 b/scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.10
new file mode 100644
index 000000000..6f0c32c91
--- /dev/null
+++ b/scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.10
@@ -0,0 +1 @@
+[{"type":"deletion"},{"type":"non_fast_forward"},{"type":"pull_request","parameters":{"required_approving_review_count":1}}]
diff --git a/scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.2 b/scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.2
new file mode 100644
index 000000000..6f0c32c91
--- /dev/null
+++ b/scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.2
@@ -0,0 +1 @@
+[{"type":"deletion"},{"type":"non_fast_forward"},{"type":"pull_request","parameters":{"required_approving_review_count":1}}]
diff --git a/scripts/release/testdata/pass/repos_acme_widget_rulesets_7 b/scripts/release/testdata/pass/repos_acme_widget_rulesets_7
new file mode 100644
index 000000000..5db53489e
--- /dev/null
+++ b/scripts/release/testdata/pass/repos_acme_widget_rulesets_7
@@ -0,0 +1,4 @@
+{"id":7,"name":"release tags","target":"tag","enforcement":"active",
+ "conditions":{"ref_name":{"include":["refs/tags/v*"],"exclude":[]}},
+ "bypass_actors":[{"actor_id":1001,"actor_type":"Team","bypass_mode":"always"},{"actor_id":1,"actor_type":"OrganizationAdmin","bypass_mode":"always"}],
+ "rules":[{"type":"creation"},{"type":"update"},{"type":"deletion"},{"type":"non_fast_forward"}]}
diff --git a/scripts/release/testdata/pass/repos_acme_widget_rulesets_targets_tag_includes_parents_true b/scripts/release/testdata/pass/repos_acme_widget_rulesets_targets_tag_includes_parents_true
new file mode 100644
index 000000000..3f870b8fd
--- /dev/null
+++ b/scripts/release/testdata/pass/repos_acme_widget_rulesets_targets_tag_includes_parents_true
@@ -0,0 +1 @@
+[{"id":7,"name":"tags","target":"tag","source_type":"Repository","source":"acme/widget","enforcement":"active"}]