From 21021ca9e83374982eb56ba3532bc8623e3a5e23 Mon Sep 17 00:00:00 2001 From: Arnau Bennassar Date: Tue, 17 Nov 2026 10:25:22 +0000 Subject: [PATCH 01/11] ci: add release tag ancestry check Verify that a release tag points at a commit reachable from develop or a release/* branch, and expose the version without the leading v. Co-Authored-By: Claude Sonnet 5.5 --- scripts/release/check_tag_ancestry.sh | 56 ++++++++++++++ scripts/release/check_tag_ancestry_test.sh | 89 ++++++++++++++++++++++ 2 files changed, 145 insertions(+) create mode 100755 scripts/release/check_tag_ancestry.sh create mode 100755 scripts/release/check_tag_ancestry_test.sh diff --git a/scripts/release/check_tag_ancestry.sh b/scripts/release/check_tag_ancestry.sh new file mode 100755 index 000000000..42925c65a --- /dev/null +++ b/scripts/release/check_tag_ancestry.sh @@ -0,0 +1,56 @@ +#!/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 + +if [[ ! "$ref" =~ ^refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then + echo "error: '$ref' is not a release tag (expected refs/tags/vX.Y.Z or refs/tags/vX.Y.Z-
)" >&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..1e92acc2f
--- /dev/null
+++ b/scripts/release/check_tag_ancestry_test.sh
@@ -0,0 +1,89 @@
+#!/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 "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"

From 0070561fa9c382ffe4aba366890b4cf750016389 Mon Sep 17 00:00:00 2001
From: Arnau Bennassar 
Date: Tue, 17 Nov 2026 10:25:33 +0000
Subject: [PATCH 02/11] ci: push branch build images to the -dev package

Branch builds from the build-push workflow now go to ghcr.io//-dev
instead of the production package, so every tag and manifest list from this
workflow lands in the development package. Production images are published by
the release workflow only.

Co-Authored-By: Claude Haiku 5.5 
---
 .github/workflows/build-push-docker-image.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/build-push-docker-image.yml b/.github/workflows/build-push-docker-image.yml
index 7a0899d8e..46827c4e8 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:

From f8dbb81c22d5ad18fb327376c690891f372e4ff0 Mon Sep 17 00:00:00 2001
From: Arnau Bennassar 
Date: Tue, 17 Nov 2026 10:26:44 +0000
Subject: [PATCH 03/11] ci: add release settings audit script

Checks the tag ruleset, release environment, branch rules, teams and
GHCR package settings through read-only GitHub API calls.

Co-Authored-By: Claude Sonnet 5.5 
---
 scripts/release/check_release_settings.sh     | 205 ++++++++++++++++++
 .../release/check_release_settings_test.sh    |  59 +++++
 ...rulesets_targets_tag_includes_parents_true |   1 +
 .../repos_acme_widget_environments_release    |   2 +
 .../pass/orgs_acme_packages_container_widget  |   1 +
 .../pass/orgs_acme_teams_release-approvers    |   1 +
 .../pass/orgs_acme_teams_release-manager      |   1 +
 .../repos_acme_widget_environments_release    |   2 +
 ...onments_release_deployment-branch-policies |   1 +
 ...me_widget_git_matching-refs_heads_release_ |   1 +
 .../repos_acme_widget_rules_branches_develop  |   1 +
 ...os_acme_widget_rules_branches_release_1.10 |   1 +
 .../pass/repos_acme_widget_rulesets_7         |   4 +
 ...rulesets_targets_tag_includes_parents_true |   1 +
 14 files changed, 281 insertions(+)
 create mode 100755 scripts/release/check_release_settings.sh
 create mode 100755 scripts/release/check_release_settings_test.sh
 create mode 100644 scripts/release/testdata/no_ruleset/repos_acme_widget_rulesets_targets_tag_includes_parents_true
 create mode 100644 scripts/release/testdata/no_self_review/repos_acme_widget_environments_release
 create mode 100644 scripts/release/testdata/pass/orgs_acme_packages_container_widget
 create mode 100644 scripts/release/testdata/pass/orgs_acme_teams_release-approvers
 create mode 100644 scripts/release/testdata/pass/orgs_acme_teams_release-manager
 create mode 100644 scripts/release/testdata/pass/repos_acme_widget_environments_release
 create mode 100644 scripts/release/testdata/pass/repos_acme_widget_environments_release_deployment-branch-policies
 create mode 100644 scripts/release/testdata/pass/repos_acme_widget_git_matching-refs_heads_release_
 create mode 100644 scripts/release/testdata/pass/repos_acme_widget_rules_branches_develop
 create mode 100644 scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.10
 create mode 100644 scripts/release/testdata/pass/repos_acme_widget_rulesets_7
 create mode 100644 scripts/release/testdata/pass/repos_acme_widget_rulesets_targets_tag_includes_parents_true

diff --git a/scripts/release/check_release_settings.sh b/scripts/release/check_release_settings.sh
new file mode 100755
index 000000000..64d6194d9
--- /dev/null
+++ b/scripts/release/check_release_settings.sh
@@ -0,0 +1,205 @@
+#!/usr/bin/env bash
+# Audits the repository and organization settings that gate releases.
+# Read-only: only GET calls are made through the GitHub CLI.
+#
+# Usage: check_release_settings.sh [--json]
+# Env:   REPO (agglayer/aggkit), ORG (owner of REPO), APPROVERS_TEAM
+#        (release-approvers), RELEASE_TEAM (release-manager), ENVIRONMENT (release)
+# 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}"
+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() {
+  local err
+  err="$(mktemp)"
+  API_BODY=""
+  if API_BODY="$(gh api "$1" 2>"$err")"; then
+    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"; 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
+  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;"
+  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, deploys only from tags $TAG_PATTERN"
+  else
+    problems="${problems% ;}"; report FAIL environment "$ENVIRONMENT:${problems%;}"
+  fi
+}
+
+# --- 3 ---------------------------------------------------------------------
+check_branch_rules() {
+  local branch rules refs newest
+  newest=""
+  if api "repos/$REPO/git/matching-refs/heads/release/"; then refs="$API_BODY"
+    newest="$(jq -r '.[].ref | sub("^refs/heads/"; "")' <<<"$refs" | sort -V | tail -n1)"
+  fi
+  for branch in develop "$newest"; do
+    if [ -z "$branch" ]; then
+      report MANUAL branch-rules "no release/* branch found to check"
+      continue
+    fi
+    if ! api "repos/$REPO/rules/branches/$branch"; then
+      report MANUAL "branch-rules[$branch]" "cannot read effective rules (HTTP $API_STATUS)"
+      continue
+    fi
+    rules="$API_BODY"
+    local 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;"
+    if [ -z "$problems" ]; then
+      report PASS "branch-rules[$branch]" "pull_request with at least 1 approval, deletion and force push forbidden"
+    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 -> Manage Actions access: only $REPO with role Write, and 'Inherit access from source repository' as intended$extra"
+}
+
+
+check_teams
+check_tag_ruleset
+check_environment
+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..4e3ec4f03
--- /dev/null
+++ b/scripts/release/check_release_settings_test.sh
@@ -0,0 +1,59 @@
+#!/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: teams PASS" "$(has '^PASS teams'; echo $?)"
+expect "all-pass: both branch checks PASS" "$(has '^PASS branch-rules\[develop\]' && 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 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/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_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..7750e7c1d
--- /dev/null
+++ b/scripts/release/testdata/no_self_review/repos_acme_widget_environments_release
@@ -0,0 +1,2 @@
+{"name":"release","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/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..d6546d14e
--- /dev/null
+++ b/scripts/release/testdata/pass/repos_acme_widget_environments_release
@@ -0,0 +1,2 @@
+{"name":"release","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_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.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_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"}]

From fbfbc059d4ebd7df15cf191b7f2db2652ceec6ca Mon Sep 17 00:00:00 2001
From: Arnau Bennassar 
Date: Tue, 17 Nov 2026 10:28:57 +0000
Subject: [PATCH 04/11] ci: gate releases on an approved environment and sign
 and attest images

Split the release workflow into preflight, approve, build and publish jobs:

- preflight checks that the ref is a release tag whose commit is on develop
  or a release/* branch, and that the version is not already published
- approve waits on the protected release environment before anything is
  pushed to the registry
- build publishes only exact version tags (no moving X.Y or latest tags)
  and adds an SBOM and mode=max provenance to every image
- publish creates the manifest lists, signs them with cosign keyless and
  pushes a GitHub build-provenance attestation for each

The production manifest list now contains only the production platform
images; previously it also picked up the -dev images. Runs for the same tag
no longer cancel each other.

Co-Authored-By: Claude Sonnet 5.5 
---
 .github/workflows/release.yml | 155 +++++++++++++++++++++++++++++-----
 1 file changed, 134 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 02d10bb70..7b3fcb138 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,5 +1,13 @@
 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 -> approve (environment: release) -> build -> publish
+#
+# Nothing is pushed to the registry before `approve` succeeds: `build` pushes
+# per-platform images by digest, so the approval gate sits in front of it.
+
 on:
   workflow_dispatch:
   push:
@@ -7,19 +15,75 @@ 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
   REGISTRY_IMAGE: ghcr.io/${{ github.repository }}
-  REGEX_IMAGE: ${{ github.repository }}:\\d+.\\d+.\\d+
+  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@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5.1.0
+        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
+
+  # Gate 2: deployment review. The `release` environment requires approval by
+  # a release approver other than the person who triggered the run.
+  approve:
+    needs: preflight
+    permissions: {}
+    environment: release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Approved release
+        env:
+          TAG: ${{ github.ref_name }}
+          COMMIT: ${{ github.sha }}
+          VERSION: ${{ needs.preflight.outputs.version }}
+        run: echo "Approved release of tag ${TAG} (commit ${COMMIT}), version ${VERSION}"
+
   build:
+    needs: approve
     permissions:
       contents: read
       packages: write
@@ -47,30 +111,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@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5.1.0
         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@c299e40c65443455700f0fdfc63efafe5b349051  # v5.10.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,25 +141,24 @@ jobs:
         uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051  # v5.10.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@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3.12.0
@@ -108,6 +170,7 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      # Each platform image carries an SBOM and full (mode=max) build provenance.
       - name: Build and push by digest
         id: build
         uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6.19.2
@@ -120,6 +183,8 @@ jobs:
           cache-to: type=gha,mode=max
           build-args: |
             INCLUDE_SHELL=${{ matrix.variant.include_shell }}
+          sbom: true
+          provenance: mode=max
           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
 
       - name: Verify version in image
@@ -145,12 +210,18 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
-  merge:
+  # Creates the tagged multi-platform manifest lists, 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.
+  publish:
     permissions:
       contents: read
       packages: write
+      id-token: write
+      attestations: write
     runs-on: arm-runner-2204
     needs:
+      - preflight
       - build
     strategy:
       matrix:
@@ -180,12 +251,54 @@ jobs:
         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)
+          SUFFIX="${{ matrix.variant.suffix }}"
+          args=()
+          while IFS= read -r tag; do
+            tag="${tag//[[:space:]]/}"
+            if [ -n "$tag" ]; then args+=(-t "$tag"); fi
+          done <<< "$TAGS"
+          # Digest files are named .-; take only the
+          # platform images of this variant (the prod pattern also downloads -dev).
+          for f in *; do
+            case "$f" in
+              *-dev) [ "$SUFFIX" = "-dev" ] || continue ;;
+              *) [ -z "$SUFFIX" ] || continue ;;
+            esac
+            args+=("${IMAGE_NAME}@sha256:${f%%.*}")
+          done
+          docker buildx imagetools create "${args[@]}"
 
-      - name: Inspect image
+      - name: Resolve manifest list digest
+        id: manifest
         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 }}"
+          FIRST_TAG=$(echo "$TAGS" | head -n1)
+          DIGEST=$(docker buildx imagetools inspect "$FIRST_TAG" --format '{{json .Manifest}}' | jq -er .digest)
+          echo "Manifest list of ${FIRST_TAG}: ${DIGEST}"
+          echo "image=${IMAGE_NAME}" >> "$GITHUB_OUTPUT"
+          echo "digest=${DIGEST}" >> "$GITHUB_OUTPUT"
+
+      - 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 list
+        env:
+          IMAGE: ${{ steps.manifest.outputs.image }}
+          DIGEST: ${{ steps.manifest.outputs.digest }}
+        run: cosign sign --yes "${IMAGE}@${DIGEST}"
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8  # v4.2.2
+        with:
+          subject-name: ${{ steps.manifest.outputs.image }}
+          subject-digest: ${{ steps.manifest.outputs.digest }}
+          push-to-registry: true
+
+      - name: Inspect image
+        run: |
           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)

From c89383d2a04acd630ac08293453026b92ade2917 Mon Sep 17 00:00:00 2001
From: Arnau Bennassar 
Date: Tue, 17 Nov 2026 10:30:30 +0000
Subject: [PATCH 05/11] docs: describe release image verification and release
 settings

Document the published image tags, how to verify signatures and build
provenance, and the repository settings that protect releases.

Co-Authored-By: Claude Sonnet 5.5 
---
 docs/SUMMARY.md               |   2 +
 docs/release_admin_runbook.md | 168 ++++++++++++++++++++++++++++++++++
 docs/release_lifecycle.md     |   7 ++
 docs/release_verification.md  |  83 +++++++++++++++++
 4 files changed, 260 insertions(+)
 create mode 100644 docs/release_admin_runbook.md
 create mode 100644 docs/release_verification.md

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..a22aa050f
--- /dev/null
+++ b/docs/release_admin_runbook.md
@@ -0,0 +1,168 @@
+# 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, checks that the tagged commit is on `develop` or a `release/*` branch, and then waits for a reviewer other than the person who started it to approve the `release` environment before anything is pushed. These checks only hold if the settings below are in place: otherwise one account could move a tag, change a protected branch, or push to the package 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` container package.
+- 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: only the team `release-manager`; organization admins may be added as "Always" only if their use is audited (the audit log records ruleset bypasses).
+
+```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/**` (or the equivalent classic branch protection rules).
+
+- Require a pull request before merging, with at least 1 approving review.
+- No direct pushes (do not add bypass actors).
+- 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.
+
+### 5. Restrict the `aggkit` package
+
+UI: Organization -> Packages -> `aggkit` -> Package settings.
+
+- Manage Actions access: only `agglayer/aggkit` with role Write.
+- Disable "Inherit access from source repository" (so repository roles do not grant push to the package).
+- Manage access: remove any individual user or team that has Write or Admin, except the package admins.
+
+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}'`.
+
+### 6. Configure `aggkit-dev` after the first branch build
+
+The `aggkit-dev` package is created the first time `Build and Push Docker Image` runs for a branch. After that run, open Organization -> Packages -> `aggkit-dev` -> Package settings and set:
+
+- Visibility: as wanted for test images (public or internal).
+- Manage Actions access: `agglayer/aggkit` with role Write.
+
+`aggkit-dev` is not a release channel and nothing in it is signed as a release.
+
+### 7. 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` and `ENVIRONMENT` override the defaults (`agglayer/aggkit`, `agglayer`, `release-approvers`, `release-manager`, `release`).
+
+Expected: every line is `PASS`, except the package control, which prints `MANUAL` and must be confirmed by hand as in step 5. The script exits non-zero when any control prints `FAIL`. The script only reads settings; it changes nothing.
+
+### 8. 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 then waits on the `approve` job for review.
+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 `approve`.
+4. After approval and 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.
+
+## 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.
+- Any workflow in the repository that has `packages: write` can push to the package while the package grants Actions write to the repository. Review workflow changes with that in mind. Optional hardening: use a push credential stored only as a `release` environment secret, and have the package grant no Actions write access to the repository, so only jobs that passed the environment approval can push.
+- 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..605d6e8ea 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 a reviewer approves the release. 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..14266c826
--- /dev/null
+++ b/docs/release_verification.md
@@ -0,0 +1,83 @@
+# 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.
+
+**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.
+
+### 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.

From 473efcdcb5fea10914a2cfd87b7b8e67d8631902 Mon Sep 17 00:00:00 2001
From: Arnau Bennassar 
Date: Tue, 17 Nov 2026 16:09:58 +0000
Subject: [PATCH 06/11] ci: run publish on a hosted runner and reject
 non-semver and dev release tags

Co-Authored-By: Claude Sonnet 5.5 
---
 .github/workflows/release.yml              |  2 +-
 scripts/release/check_tag_ancestry.sh      | 16 ++++++++++++++--
 scripts/release/check_tag_ancestry_test.sh |  4 ++++
 3 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7b3fcb138..6cbbc6c06 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -219,7 +219,7 @@ jobs:
       packages: write
       id-token: write
       attestations: write
-    runs-on: arm-runner-2204
+    runs-on: ubuntu-latest
     needs:
       - preflight
       - build
diff --git a/scripts/release/check_tag_ancestry.sh b/scripts/release/check_tag_ancestry.sh
index 42925c65a..0e20b8352 100755
--- a/scripts/release/check_tag_ancestry.sh
+++ b/scripts/release/check_tag_ancestry.sh
@@ -15,8 +15,20 @@ if [[ -z "$ref" ]]; then
   exit 1
 fi
 
-if [[ ! "$ref" =~ ^refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
-  echo "error: '$ref' is not a release tag (expected refs/tags/vX.Y.Z or refs/tags/vX.Y.Z-
)" >&2
+# 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
 
diff --git a/scripts/release/check_tag_ancestry_test.sh b/scripts/release/check_tag_ancestry_test.sh
index 1e92acc2f..4e81a316c 100755
--- a/scripts/release/check_tag_ancestry_test.sh
+++ b/scripts/release/check_tag_ancestry_test.sh
@@ -63,6 +63,10 @@ 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 ""
 

From 88d020773a555fb01bd134547e8089f9ec070564 Mon Sep 17 00:00:00 2001
From: Arnau Bennassar 
Date: Tue, 17 Nov 2026 16:09:58 +0000
Subject: [PATCH 07/11] ci: fail release settings check on admin bypass and
 ruleset bypass actors

Check the release environment for administrator bypass, all release/* branches
(paginated) and bypass actors on the branch rulesets. State that only rulesets
are read and that organization admins may bypass the tag ruleset (audited).

Co-Authored-By: Claude Sonnet 5.5 
---
 scripts/release/check_release_settings.sh     | 57 +++++++++++++------
 .../release/check_release_settings_test.sh    | 14 ++++-
 .../repos_acme_widget_environments_release    |  2 +
 ...pos_acme_widget_rules_branches_release_1.2 |  1 +
 .../repos_acme_widget_rulesets_9              |  1 +
 .../repos_acme_widget_environments_release    |  2 +-
 ...pos_acme_widget_rules_branches_release_1.1 |  1 +
 .../repos_acme_widget_environments_release    |  2 +-
 ...pos_acme_widget_rules_branches_release_1.1 |  1 +
 ...pos_acme_widget_rules_branches_release_1.2 |  1 +
 10 files changed, 62 insertions(+), 20 deletions(-)
 create mode 100644 scripts/release/testdata/admin_bypass/repos_acme_widget_environments_release
 create mode 100644 scripts/release/testdata/branch_bypass/repos_acme_widget_rules_branches_release_1.2
 create mode 100644 scripts/release/testdata/branch_bypass/repos_acme_widget_rulesets_9
 create mode 100644 scripts/release/testdata/old_branch_weak/repos_acme_widget_rules_branches_release_1.1
 create mode 100644 scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.1
 create mode 100644 scripts/release/testdata/pass/repos_acme_widget_rules_branches_release_1.2

diff --git a/scripts/release/check_release_settings.sh b/scripts/release/check_release_settings.sh
index 64d6194d9..9b7b784ec 100755
--- a/scripts/release/check_release_settings.sh
+++ b/scripts/release/check_release_settings.sh
@@ -1,6 +1,7 @@
 #!/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
@@ -40,11 +41,17 @@ report() { # status control detail
 # 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
+  local err raw
   err="$(mktemp)"
   API_BODY=""
-  if API_BODY="$(gh api "$1" 2>"$err")"; then
+  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)"
@@ -76,7 +83,7 @@ check_teams() {
 # --- 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"; then
+  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
@@ -104,6 +111,8 @@ check_tag_ruleset() {
     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")"
@@ -133,6 +142,8 @@ check_environment() {
     || 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 \
@@ -144,36 +155,48 @@ check_environment() {
     problems="$problems no custom deployment policy;"
   fi
   if [ -z "$problems" ]; then
-    report PASS environment "$ENVIRONMENT requires $APPROVERS_TEAM, prevents self review, deploys only from tags $TAG_PATTERN"
+    report PASS environment "$ENVIRONMENT requires $APPROVERS_TEAM, prevents self review, admins cannot bypass, deploys only from tags $TAG_PATTERN"
   else
-    problems="${problems% ;}"; report FAIL environment "$ENVIRONMENT:${problems%;}"
+    report FAIL environment "$ENVIRONMENT:${problems%;}"
   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 newest
-  newest=""
-  if api "repos/$REPO/git/matching-refs/heads/release/"; then refs="$API_BODY"
-    newest="$(jq -r '.[].ref | sub("^refs/heads/"; "")' <<<"$refs" | sort -V | tail -n1)"
+  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
-  for branch in develop "$newest"; do
-    if [ -z "$branch" ]; then
-      report MANUAL branch-rules "no release/* branch found to check"
-      continue
-    fi
-    if ! api "repos/$REPO/rules/branches/$branch"; then
+  [ "${#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"
-    local problems=""
+    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"
+      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
diff --git a/scripts/release/check_release_settings_test.sh b/scripts/release/check_release_settings_test.sh
index 4e3ec4f03..259682467 100755
--- a/scripts/release/check_release_settings_test.sh
+++ b/scripts/release/check_release_settings_test.sh
@@ -40,7 +40,7 @@ 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: teams PASS" "$(has '^PASS teams'; echo $?)"
-expect "all-pass: both branch checks PASS" "$(has '^PASS branch-rules\[develop\]' && has '^PASS branch-rules\[release/1.10\]'; 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 $?)"
 
@@ -52,6 +52,18 @@ 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 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 $?)"
 
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_self_review/repos_acme_widget_environments_release b/scripts/release/testdata/no_self_review/repos_acme_widget_environments_release
index 7750e7c1d..1a9b5e851 100644
--- a/scripts/release/testdata/no_self_review/repos_acme_widget_environments_release
+++ b/scripts/release/testdata/no_self_review/repos_acme_widget_environments_release
@@ -1,2 +1,2 @@
-{"name":"release","protection_rules":[{"id":1,"type":"required_reviewers","prevent_self_review":false,"reviewers":[{"type":"Team","reviewer":{"id":1002,"slug":"release-approvers","name":"release-approvers"}}]}],
+{"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/repos_acme_widget_environments_release b/scripts/release/testdata/pass/repos_acme_widget_environments_release
index d6546d14e..ee8928fad 100644
--- a/scripts/release/testdata/pass/repos_acme_widget_environments_release
+++ b/scripts/release/testdata/pass/repos_acme_widget_environments_release
@@ -1,2 +1,2 @@
-{"name":"release","protection_rules":[{"id":1,"type":"required_reviewers","prevent_self_review":true,"reviewers":[{"type":"Team","reviewer":{"id":1002,"slug":"release-approvers","name":"release-approvers"}}]}],
+{"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_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.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}}]

From 867add30cddcb308028ab61d58457abee1b674d8 Mon Sep 17 00:00:00 2001
From: Arnau Bennassar 
Date: Tue, 17 Nov 2026 16:09:58 +0000
Subject: [PATCH 08/11] docs: describe recovery from a failed signing step and
 package requirements

Co-Authored-By: Claude Sonnet 5.5 
---
 docs/release_admin_runbook.md | 15 +++++++++++----
 docs/release_verification.md  |  4 +++-
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/docs/release_admin_runbook.md b/docs/release_admin_runbook.md
index a22aa050f..c47d5df90 100644
--- a/docs/release_admin_runbook.md
+++ b/docs/release_admin_runbook.md
@@ -72,7 +72,7 @@ UI: Repository (or Organization) -> Settings -> Rules -> Rulesets -> New tag rul
 
 - 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: only the team `release-manager`; organization admins may be added as "Always" only if their use is audited (the audit log records ruleset bypasses).
+- 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)
@@ -94,10 +94,10 @@ Confirm: `gh api repos/agglayer/aggkit/rulesets --jq '.[] | {name, target, enfor
 
 ### 4. Protect `develop` and `release/*`
 
-UI: Repository -> Settings -> Rules -> Rulesets -> New branch ruleset, targeting `develop` and `release/**` (or the equivalent classic branch protection rules).
+UI: Repository -> 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).
+- 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
@@ -117,7 +117,7 @@ gh api -X POST repos/agglayer/aggkit/rulesets --input - <<'JSON'
 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.
+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
 
@@ -125,6 +125,7 @@ UI: Organization -> Packages -> `aggkit` -> Package settings.
 
 - Manage Actions access: only `agglayer/aggkit` with role Write.
 - 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.
 
 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}'`.
@@ -161,6 +162,12 @@ Before the first real release, push a pre-release tag (for example `v0.0.0-rc.1`
 
 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
+
+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 finishes signing, 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.
diff --git a/docs/release_verification.md b/docs/release_verification.md
index 14266c826..4fc3e76e3 100644
--- a/docs/release_verification.md
+++ b/docs/release_verification.md
@@ -12,7 +12,9 @@ Release images are published to `ghcr.io/agglayer/aggkit`, one set of tags per r
 | `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.
+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.
+
+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.
 

From 4b43e44625eb21594f60feaa696138076606f919 Mon Sep 17 00:00:00 2001
From: Arnau Bennassar 
Date: Tue, 17 Nov 2026 17:40:42 +0000
Subject: [PATCH 09/11] ci: use the same checkout version in the release
 preflight

The preflight job pinned actions/checkout to v5.1.0 while the build job
uses v7.0.1. Pin preflight to the same commit so both jobs run the same
checkout action.

Co-Authored-By: Claude Haiku 5.5 
---
 .github/workflows/release.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 1bbdf3d7c..308cc4d75 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -40,7 +40,7 @@ jobs:
       version: ${{ steps.ancestry.outputs.version }}
     steps:
       - name: Checkout
-        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5.1.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false

From 89bc85bcd84853a3cea3c349903cd1e321f0d85b Mon Sep 17 00:00:00 2001
From: Arnau Bennassar 
Date: Thu, 19 Nov 2026 10:32:44 +0000
Subject: [PATCH 10/11] ci: stage release images in aggkit-dev and promote them
 by digest after approval

The release workflow now runs preflight, build, approve and publish. The
build job pushes the per-platform images by digest to the staging package
ghcr.io/agglayer/aggkit-dev, so the reviewer approves images that were
actually built and the production package is untouched before approval.
After approval, publish creates the tagged manifest lists in
ghcr.io/agglayer/aggkit from the staged digests of the same run, then signs
and attests them.

Co-Authored-By: Claude Sonnet 5.5 
---
 .github/workflows/release.yml | 121 ++++++++++++++++++++++++++--------
 docs/release_admin_runbook.md |  38 +++++++----
 docs/release_lifecycle.md     |   2 +-
 docs/release_verification.md  |   6 ++
 4 files changed, 128 insertions(+), 39 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 308cc4d75..a1fc78403 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -3,10 +3,15 @@ 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 -> approve (environment: release) -> build -> publish
+#   preflight -> build -> approve (environment: release) -> publish
 #
-# Nothing is pushed to the registry before `approve` succeeds: `build` pushes
-# per-platform images by digest, so the approval gate sits in front of it.
+# `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, writes to the production package: it assembles the
+# tagged manifest lists from the staged digests of this run, then signs and
+# attests them. Nothing reaches ghcr.io/ before `approve` succeeds.
 
 on:
   workflow_dispatch:
@@ -25,7 +30,10 @@ permissions: {}
 
 env:
   REGISTRY: ghcr.io
+  # Production package: written only by `publish`, after approval.
   REGISTRY_IMAGE: ghcr.io/${{ github.repository }}
+  # 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:
@@ -67,23 +75,11 @@ jobs:
             echo "${image} is not published yet"
           done
 
-  # Gate 2: deployment review. The `release` environment requires approval by
-  # a release approver other than the person who triggered the run.
-  approve:
-    needs: preflight
-    permissions: {}
-    environment: release
-    runs-on: ubuntu-latest
-    steps:
-      - name: Approved release
-        env:
-          TAG: ${{ github.ref_name }}
-          COMMIT: ${{ github.sha }}
-          VERSION: ${{ needs.preflight.outputs.version }}
-        run: echo "Approved release of tag ${TAG} (commit ${COMMIT}), version ${VERSION}"
-
+  # Builds the platform images and stages them by digest in the staging package
+  # (STAGING_IMAGE); 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: approve
+    needs: preflight
     permissions:
       contents: read
       packages: write
@@ -171,7 +167,8 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       # Each platform image carries an SBOM and full (mode=max) build provenance.
-      - name: Build and push by digest
+      # 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:
@@ -185,22 +182,31 @@ jobs:
             INCLUDE_SHELL=${{ matrix.variant.include_shell }}
           sbom: true
           provenance: mode=max
-          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
+          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 `approve` lists and `publish` 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
@@ -208,10 +214,53 @@ 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
 
-  # Creates the tagged multi-platform manifest lists, then signs each one with
-  # cosign (keyless, bound to this workflow's identity) and pushes a GitHub
+  # Gate 2: deployment review. The `release` environment requires approval by
+  # a release approver other than the person who triggered the run. The
+  # reviewer decides on the images staged by `build` (digests in the build job
+  # summaries); the job itself runs after the approval and records what was
+  # approved. `publish` promotes exactly these digests.
+  approve:
+    needs:
+      - preflight
+      - build
+    permissions: {}
+    environment: release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download staged digests
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
+        with:
+          path: /tmp/digests
+          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"
+
+  # Runs only after the approval. 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.
   publish:
     permissions:
@@ -223,6 +272,7 @@ jobs:
     needs:
       - preflight
       - build
+      - approve
     strategy:
       matrix:
         variant:
@@ -246,7 +296,10 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Create manifest list and push
+      # Sources are the staged per-platform digests of this run; the 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 list from staged digests and push
         working-directory: /tmp/digests
         run: |
           IMAGE_NAME="${{ (matrix.variant.suffix == '') && needs.build.outputs.IMAGE_NAME_PROD || needs.build.outputs.IMAGE_NAME_DEV }}"
@@ -257,15 +310,29 @@ jobs:
             tag="${tag//[[:space:]]/}"
             if [ -n "$tag" ]; then args+=(-t "$tag"); fi
           done <<< "$TAGS"
+          [ "${#args[@]}" -gt 0 ] || { echo "::error::no tags to publish"; exit 1; }
           # Digest files are named .-; take only the
           # platform images of this variant (the prod pattern also downloads -dev).
+          sources=0
           for f in *; do
             case "$f" in
               *-dev) [ "$SUFFIX" = "-dev" ] || continue ;;
               *) [ -z "$SUFFIX" ] || continue ;;
             esac
-            args+=("${IMAGE_NAME}@sha256:${f%%.*}")
+            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 this variant, found ${sources}"
+            exit 1
+          fi
+          echo "Promoting ${sources} staged images of ${STAGING_IMAGE} to ${IMAGE_NAME}"
           docker buildx imagetools create "${args[@]}"
 
       - name: Resolve manifest list digest
diff --git a/docs/release_admin_runbook.md b/docs/release_admin_runbook.md
index c47d5df90..ad9eae7d6 100644
--- a/docs/release_admin_runbook.md
+++ b/docs/release_admin_runbook.md
@@ -4,13 +4,20 @@ This page is for organization owners and repository admins. It describes the Git
 
 ## 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, checks that the tagged commit is on `develop` or a `release/*` branch, and then waits for a reviewer other than the person who started it to approve the `release` environment before anything is pushed. These checks only hold if the settings below are in place: otherwise one account could move a tag, change a protected branch, or push to the package directly.
+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 four 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. `approve` waits for a reviewer other than the person who started the run to approve the `release` environment, so the reviewer decides on images that were actually built. After the approval it prints the tag, the commit, the version and the staged digests.
+4. `publish` runs only after the approval. It 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.
+
+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, 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` container package.
+- Package admin on the `aggkit` and `aggkit-dev` container packages.
 - 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`.
@@ -130,14 +137,18 @@ UI: Organization -> Packages -> `aggkit` -> Package settings.
 
 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}'`.
 
-### 6. Configure `aggkit-dev` after the first branch build
+Note what the workflow permissions mean for this package. The `build` job has `packages: write`, because it has to push to `aggkit-dev`; `GITHUB_TOKEN` permissions are not scoped per package, so the token of `build` can also write to any package that grants the repository Actions write, `aggkit` included. What keeps `build` out of `aggkit` is what its steps do: they push only to `ghcr.io/agglayer/aggkit-dev`, and the job never creates a tag in `aggkit`. The reviewers of the release approve the images that `build` staged; `publish` is the only job that writes to `aggkit`. See the residual risks for the optional hardening that removes the token-level write access.
 
-The `aggkit-dev` package is created the first time `Build and Push Docker Image` runs for a branch. After that run, open Organization -> Packages -> `aggkit-dev` -> Package settings and set:
+### 6. 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, and `publish` needs to read the staged images (Write includes it).
 - Visibility: as wanted for test images (public or internal).
-- Manage Actions access: `agglayer/aggkit` with role Write.
+- 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.
+`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.
 
 ### 7. Run the settings check
 
@@ -155,21 +166,26 @@ Expected: every line is `PASS`, except the package control, which prints `MANUAL
 
 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 then waits on the `approve` job for review.
+1. The `Release` run finishes `preflight` and `build`, and then waits on the `approve` job for review. 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 `approve`.
-4. After approval and 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.
+3. A `v*` tag on a commit that is not on `develop` or a `release/*` branch fails in `preflight` and never reaches `build` or `approve`.
+4. After approval, `approve` prints the tag, the commit, the version and the same digests, and `publish` creates the tags in `aggkit`. The platform image digests inside the published manifest list match the staged digests.
+5. 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
 
-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 finishes signing, or cut a new version. A full re-run of the whole workflow fails in `preflight` because the version is already published.
+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`, `build` and `approve` 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.
-- Any workflow in the repository that has `packages: write` can push to the package while the package grants Actions write to the repository. Review workflow changes with that in mind. Optional hardening: use a push credential stored only as a `release` environment secret, and have the package grant no Actions write access to the repository, so only jobs that passed the environment approval can push.
+- Any workflow in the repository that has `packages: write` can push to the packages while they grant Actions write to the repository. This includes the `build` job of the release workflow, which writes to `aggkit-dev` and, because the token is not scoped per package, could write to `aggkit` if its steps were changed. Review workflow changes with that in mind. Optional hardening: use a push credential for `aggkit` stored only as a `release` environment secret, and have `aggkit` grant no Actions write access to the repository, so only jobs that passed the environment approval can push to it.
+- 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 605d6e8ea..8c1f73b00 100644
--- a/docs/release_lifecycle.md
+++ b/docs/release_lifecycle.md
@@ -36,7 +36,7 @@ As a quick reference this is the diagram of the branching cycle:
 
 ## Publishing and verifying images
 
-Release images are published only from a release tag, after the tagged commit passes the release checks and a reviewer approves the release. Each image is signed and has build provenance and an SBOM.
+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.
diff --git a/docs/release_verification.md b/docs/release_verification.md
index 4fc3e76e3..7bf05b565 100644
--- a/docs/release_verification.md
+++ b/docs/release_verification.md
@@ -14,6 +14,8 @@ Release images are published to `ghcr.io/agglayer/aggkit`, one set of tags per r
 
 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`.
+
 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.
@@ -26,6 +28,10 @@ The production tag `X.Y.Z` resolves to a manifest list that contains the product
 
 `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.

From c7157cf1879116427e441bb066a2977d097a66e8 Mon Sep 17 00:00:00 2001
From: Arnau Bennassar 
Date: Thu, 19 Nov 2026 15:22:12 +0000
Subject: [PATCH 11/11] ci: hold the production registry credential in the
 release environment

The publish job is the only job that uses the release environment and it logs in
to ghcr.io/agglayer/aggkit with a credential stored only as secrets of that
environment. The workflow token no longer has write access to the production
package, and the staging and signing steps keep working with the same login.
The settings check reports the environment secrets, and the runbook describes
how to create the credential and restrict the package.
---
 .github/workflows/release.yml                 | 227 ++++++++++--------
 docs/release_admin_runbook.md                 |  68 ++++--
 docs/release_verification.md                  |   2 +-
 scripts/release/check_release_settings.sh     |  26 +-
 .../release/check_release_settings_test.sh    |   5 +
 ...s_acme_widget_environments_release_secrets |   1 +
 ...s_acme_widget_environments_release_secrets |   1 +
 7 files changed, 206 insertions(+), 124 deletions(-)
 create mode 100644 scripts/release/testdata/no_secrets/repos_acme_widget_environments_release_secrets
 create mode 100644 scripts/release/testdata/pass/repos_acme_widget_environments_release_secrets

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a1fc78403..dce7e3493 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -3,15 +3,18 @@ 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 -> approve (environment: release) -> publish
+#   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, writes to the production package: it assembles the
-# tagged manifest lists from the staged digests of this run, then signs and
-# attests them. Nothing reaches ghcr.io/ before `approve` succeeds.
+# 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:
@@ -30,7 +33,8 @@ permissions: {}
 
 env:
   REGISTRY: ghcr.io
-  # Production package: written only by `publish`, after approval.
+  # Production package: written only by `publish`, after approval, with the
+  # credential held by the `release` environment.
   REGISTRY_IMAGE: ghcr.io/${{ github.repository }}
   # Staging package: `build` pushes the per-platform images here, by digest.
   STAGING_IMAGE: ghcr.io/${{ github.repository }}-dev
@@ -76,8 +80,9 @@ jobs:
           done
 
   # Builds the platform images and stages them by digest in the staging package
-  # (STAGING_IMAGE); nothing is written to the production package here. The
-  # digests of what was built are listed in each job summary for the reviewer.
+  # (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:
@@ -159,7 +164,7 @@ jobs:
       - 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 }}
@@ -194,7 +199,7 @@ jobs:
           echo "Version check passed: $ver"
           echo "VERSION_IN_IMAGE=$ver" >> "$GITHUB_ENV"
 
-      # The digest files are what `approve` lists and `publish` promotes.
+      # The digest files are what `publish` lists and promotes.
       - name: Export digest
         run: |
           mkdir -p /tmp/digests
@@ -218,16 +223,32 @@ jobs:
           # days) and a re-run of `publish`.
           retention-days: 30
 
-  # Gate 2: deployment review. The `release` environment requires approval by
-  # a release approver other than the person who triggered the run. The
-  # reviewer decides on the images staged by `build` (digests in the build job
-  # summaries); the job itself runs after the approval and records what was
-  # approved. `publish` promotes exactly these digests.
-  approve:
+  # 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
-    permissions: {}
+    # 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:
@@ -257,116 +278,118 @@ jobs:
             done
           } | tee -a "$GITHUB_STEP_SUMMARY"
 
-  # Runs only after the approval. 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.
-  publish:
-    permissions:
-      contents: read
-      packages: write
-      id-token: write
-      attestations: write
-    runs-on: ubuntu-latest
-    needs:
-      - preflight
-      - build
-      - approve
-    strategy:
-      matrix:
-        variant:
-          - { suffix: "", description: "production" }
-          - { suffix: "-dev", description: "development" }
-    steps:
-      - name: Download digests
-        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
-        with:
-          path: /tmp/digests
-          pattern: digests-*${{ matrix.variant.suffix }}
-          merge-multiple: true
+      - 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 }}
 
-      # Sources are the staged per-platform digests of this run; the manifest
+      # 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 list from staged digests and push
+      - 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: |
-          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 }}"
-          SUFFIX="${{ matrix.variant.suffix }}"
-          args=()
-          while IFS= read -r tag; do
-            tag="${tag//[[:space:]]/}"
-            if [ -n "$tag" ]; then args+=(-t "$tag"); fi
-          done <<< "$TAGS"
-          [ "${#args[@]}" -gt 0 ] || { echo "::error::no tags to publish"; exit 1; }
-          # Digest files are named .-; take only the
-          # platform images of this variant (the prod pattern also downloads -dev).
-          sources=0
-          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"
+          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
-            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 this variant, found ${sources}"
-            exit 1
-          fi
-          echo "Promoting ${sources} staged images of ${STAGING_IMAGE} to ${IMAGE_NAME}"
-          docker buildx imagetools create "${args[@]}"
-
-      - name: Resolve manifest list digest
-        id: manifest
-        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 }}"
-          FIRST_TAG=$(echo "$TAGS" | head -n1)
-          DIGEST=$(docker buildx imagetools inspect "$FIRST_TAG" --format '{{json .Manifest}}' | jq -er .digest)
-          echo "Manifest list of ${FIRST_TAG}: ${DIGEST}"
-          echo "image=${IMAGE_NAME}" >> "$GITHUB_OUTPUT"
-          echo "digest=${DIGEST}" >> "$GITHUB_OUTPUT"
+            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 list
+      - name: Sign manifest lists
         env:
-          IMAGE: ${{ steps.manifest.outputs.image }}
-          DIGEST: ${{ steps.manifest.outputs.digest }}
-        run: cosign sign --yes "${IMAGE}@${DIGEST}"
+          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: |
+          cosign sign --yes "${IMAGE_PROD}@${DIGEST_PROD}"
+          cosign sign --yes "${IMAGE_DEV}@${DIGEST_DEV}"
 
-      - name: Attest build provenance
+      - name: Attest build provenance (prod)
         uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8  # v4.2.2
         with:
-          subject-name: ${{ steps.manifest.outputs.image }}
-          subject-digest: ${{ steps.manifest.outputs.digest }}
+          subject-name: ${{ steps.manifest.outputs.image_prod }}
+          subject-digest: ${{ steps.manifest.outputs.digest_prod }}
           push-to-registry: true
 
-      - name: Inspect image
+      - 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 images
+        env:
+          TAGS_PROD: ${{ needs.build.outputs.TAGS_PROD }}
+          TAGS_DEV: ${{ needs.build.outputs.TAGS_DEV }}
         run: |
-          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/release_admin_runbook.md b/docs/release_admin_runbook.md
index ad9eae7d6..d79fcf64c 100644
--- a/docs/release_admin_runbook.md
+++ b/docs/release_admin_runbook.md
@@ -4,20 +4,20 @@ This page is for organization owners and repository admins. It describes the Git
 
 ## 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 four jobs, in this order:
+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. `approve` waits for a reviewer other than the person who started the run to approve the `release` environment, so the reviewer decides on images that were actually built. After the approval it prints the tag, the commit, the version and the staged digests.
-4. `publish` runs only after the approval. It 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.
+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, or push to the packages directly.
+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`.
@@ -130,27 +130,54 @@ Confirm: `gh api repos/agglayer/aggkit/rules/branches/develop --jq '.[].type'` l
 
 UI: Organization -> Packages -> `aggkit` -> Package settings.
 
-- Manage Actions access: only `agglayer/aggkit` with role Write.
+- 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.
+- 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}'`.
 
-Note what the workflow permissions mean for this package. The `build` job has `packages: write`, because it has to push to `aggkit-dev`; `GITHUB_TOKEN` permissions are not scoped per package, so the token of `build` can also write to any package that grants the repository Actions write, `aggkit` included. What keeps `build` out of `aggkit` is what its steps do: they push only to `ghcr.io/agglayer/aggkit-dev`, and the job never creates a tag in `aggkit`. The reviewers of the release approve the images that `build` staged; `publish` is the only job that writes to `aggkit`. See the residual risks for the optional hardening that removes the token-level write access.
+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. Configure `aggkit-dev` before the first release
+### 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, and `publish` needs to read the staged images (Write includes it).
+- 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.
 
-### 7. Run the settings check
+### 8. Run the settings check
 
 From a checkout of the repository, with `gh` and `jq` available and enough access to read the settings:
 
@@ -158,19 +185,20 @@ From a checkout of the repository, with `gh` and `jq` available and enough acces
 scripts/release/check_release_settings.sh
 ```
 
-Optional: `--json` prints the results as JSON; the environment variables `REPO`, `ORG`, `APPROVERS_TEAM`, `RELEASE_TEAM` and `ENVIRONMENT` override the defaults (`agglayer/aggkit`, `agglayer`, `release-approvers`, `release-manager`, `release`).
+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 step 5. The script exits non-zero when any control prints `FAIL`. The script only reads settings; it changes nothing.
+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.
 
-### 8. Dry run with a release candidate
+### 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 waits on the `approve` job for review. 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).
+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 `approve`.
-4. After approval, `approve` prints the tag, the commit, the version and the same digests, and `publish` creates the tags in `aggkit`. The platform image digests inside the published manifest list match the staged digests.
-5. 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.
+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.
 
@@ -178,14 +206,16 @@ Tag names are immutable once published, so use a throwaway version for the dry r
 
 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`, `build` and `approve` 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.
+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.
-- Any workflow in the repository that has `packages: write` can push to the packages while they grant Actions write to the repository. This includes the `build` job of the release workflow, which writes to `aggkit-dev` and, because the token is not scoped per package, could write to `aggkit` if its steps were changed. Review workflow changes with that in mind. Optional hardening: use a push credential for `aggkit` stored only as a `release` environment secret, and have `aggkit` grant no Actions write access to the repository, so only jobs that passed the environment approval can push to it.
+- 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_verification.md b/docs/release_verification.md
index 7bf05b565..0988bdea2 100644
--- a/docs/release_verification.md
+++ b/docs/release_verification.md
@@ -14,7 +14,7 @@ Release images are published to `ghcr.io/agglayer/aggkit`, one set of tags per r
 
 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`.
+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.
 
diff --git a/scripts/release/check_release_settings.sh b/scripts/release/check_release_settings.sh
index 9b7b784ec..eb0611e79 100755
--- a/scripts/release/check_release_settings.sh
+++ b/scripts/release/check_release_settings.sh
@@ -5,7 +5,9 @@
 #
 # Usage: check_release_settings.sh [--json]
 # Env:   REPO (agglayer/aggkit), ORG (owner of REPO), APPROVERS_TEAM
-#        (release-approvers), RELEASE_TEAM (release-manager), ENVIRONMENT (release)
+#        (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
@@ -15,6 +17,7 @@ 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
@@ -161,6 +164,24 @@ check_environment() {
   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.
@@ -212,13 +233,14 @@ check_package() {
   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 -> Manage Actions access: only $REPO with role Write, and 'Inherit access from source repository' as intended$extra"
+  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
 
diff --git a/scripts/release/check_release_settings_test.sh b/scripts/release/check_release_settings_test.sh
index 259682467..beb156229 100755
--- a/scripts/release/check_release_settings_test.sh
+++ b/scripts/release/check_release_settings_test.sh
@@ -39,6 +39,7 @@ 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 $?)"
@@ -52,6 +53,10 @@ 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 $?)"
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/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"}]}