From f16e521e9ea51fdb8e9d7c1d55b8d2034ccfaf1e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Javier=20Plaza=20Sisqu=C3=A9s?=
 <javierplazasisques@gmail.com>
Date: Wed, 16 Sep 2026 11:45:42 +0200
Subject: [PATCH] docs(docker-release): correct misleading security-events
 comment
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The comment implied a caller only needs security-events: write when
it actually sets scan_image: true. That's wrong: GitHub validates a
caller's granted permissions against a called reusable workflow's
top-level permissions block statically, regardless of which steps
run — so every caller must declare it unconditionally, or the run
fails before any job starts ("requesting security-events: write,
but is only allowed security-events: none").

This bit beacon-api's first real release.yml run. Fixed the comment
and added the missing permissions blocks to the README's promote-
mode example so nobody copies the same trap.
---
 .github/workflows/docker-release.yml | 14 ++++++++++----
 README.md                            | 14 ++++++++++++++
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/docker-release.yml b/.github/workflows/docker-release.yml
index 643f0dc..6942cca 100644
--- a/.github/workflows/docker-release.yml
+++ b/.github/workflows/docker-release.yml
@@ -108,10 +108,16 @@ permissions:
   # never exercise the login step. Callers MUST still declare packages: write
   # in the consumer workflow for the permission to be granted to GITHUB_TOKEN.
   packages: write
-  # security-events: write is required ONLY when scan_image=true, to upload
-  # the Trivy SARIF report. Same story as packages: write above — callers
-  # that don't enable scan_image never exercise the upload step, but callers
-  # that DO must also declare security-events: write themselves.
+  # security-events: write is only EXERCISED when scan_image=true (to upload
+  # the Trivy SARIF report), but GitHub validates every caller's granted
+  # permissions against this workflow's top-level declaration statically,
+  # not against which steps actually run — so EVERY caller must declare
+  # security-events: write in its own workflow, even one that never sets
+  # scan_image: true. Omitting it fails the run before any job starts
+  # ("requesting security-events: write, but is only allowed
+  # security-events: none") — this bit beacon-api's first real release.yml
+  # run (bump_mode=promote never passes scan_image, so it looked safe to
+  # drop, but the declaration here is unconditional regardless).
   security-events: write
 
 jobs:
diff --git a/README.md b/README.md
index b966053..a955666 100644
--- a/README.md
+++ b/README.md
@@ -460,6 +460,16 @@ on:
         required: false
         type: string
 
+# security-events: write is required here even though this example never
+# sets scan_image — docker-release.yml declares it unconditionally at its
+# own top level, and GitHub validates every caller's permissions against
+# that declaration statically, not against which steps actually run.
+# Omitting it fails the run before any job starts. Don't drop this.
+permissions:
+  contents: write
+  packages: write
+  security-events: write
+
 jobs:
   release:
     uses: sisques-labs/workflows/.github/workflows/docker-release.yml@main
@@ -473,6 +483,10 @@ jobs:
     secrets:
       DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
       DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+    permissions:
+      contents: write
+      packages: write
+      security-events: write
 ```
 
 **⚠️ Unvalidated risk:** `imagetools create` must copy the full multi-arch