From 751b379d06d57f911e44442168a8ff4ab1556ee9 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sat, 14 Nov 2026 07:44:15 +0000 Subject: [PATCH 1/3] fork-follow: grant actions: write to the release call; test called-workflow permissions The first run of Fork follow upstream (workflow_dispatch, after FORK_PUSH_TOKEN moved into the fork-push Environment) ended in startup_failure: its release job grants actions: read, but fork-release.yml's tests job asks for actions: write (fork-tests.yml's fleet_watch). GitHub refuses a run whose called workflow asks for more than the caller grants, even for a skipped job, before any job starts and without a log. fork-reusable-permissions.test.py walks every fork-*.yml workflow and its local reusable calls (nested too) and fails when a called job asks for more than its caller grants. It fails on the old fork-follow.yml and passes on the fix; it first proves itself on made-up workflows. Co-Authored-By: Claude Opus 5.5 --- .github/fork-ci-tests.txt | 1 + .../scripts/fork-reusable-permissions.test.py | 158 ++++++++++++++++++ .github/workflows/fork-follow.yml | 6 +- 3 files changed, 164 insertions(+), 1 deletion(-) create mode 100644 .github/scripts/fork-reusable-permissions.test.py diff --git a/.github/fork-ci-tests.txt b/.github/fork-ci-tests.txt index d944208939900..065c643178e70 100644 --- a/.github/fork-ci-tests.txt +++ b/.github/fork-ci-tests.txt @@ -14,6 +14,7 @@ .github/scripts/fork-ci-release.test.py .github/scripts/fork-release-workflow.test.py .github/scripts/fork-release.test.sh +.github/scripts/fork-reusable-permissions.test.py .github/scripts/fork-schema-check.test.cjs .github/scripts/fork-secret-scan.test.sh .github/scripts/fork-test-shards.test.cjs diff --git a/.github/scripts/fork-reusable-permissions.test.py b/.github/scripts/fork-reusable-permissions.test.py new file mode 100644 index 0000000000000..afa161d5721e1 --- /dev/null +++ b/.github/scripts/fork-reusable-permissions.test.py @@ -0,0 +1,158 @@ +"""A called workflow may not ask for more token permissions than its caller grants. + + python3 .github/scripts/fork-reusable-permissions.test.py + +GitHub refuses such a run before any job starts ("startup_failure", no log), even when the +job that asks for more would be skipped, so a schedule-only workflow can stay broken for days +unnoticed. This walks every fork-*.yml workflow, follows each local `uses: +./.github/workflows/X.yml` call (nested calls too) and checks that every job of the called +workflow asks for at most what the calling job grants. Needs PyYAML. First it proves the +check itself on small made-up workflows. Any FAIL exits 1. +""" + +import pathlib +import sys +import tempfile + +import yaml + +LEVEL = {"none": 0, "read": 1, "write": 2} +# Scopes read-all / write-all expand to (GitHub's list; id-token and models have no read/write split +# that matters here, but are listed so a write-all grant covers them). +SCOPES = [ + "actions", "attestations", "checks", "contents", "deployments", "discussions", "id-token", + "issues", "models", "packages", "pages", "pull-requests", "repository-projects", + "security-events", "statuses", +] +UNKNOWN = object() # no permissions anywhere: the repository default applies, not known here + + +def normalise(perms): + """dict scope -> level, or UNKNOWN when perms is None.""" + if perms is None: + return UNKNOWN + if perms == {} or perms == "": + return {} + if perms == "read-all": + return {s: 1 for s in SCOPES} + if perms == "write-all": + return {s: 2 for s in SCOPES} + if isinstance(perms, dict): + return {str(k): LEVEL[str(v)] for k, v in perms.items()} + raise ValueError(f"unreadable permissions: {perms!r}") + + +def load(root, rel): + data = yaml.safe_load((root / rel).read_text()) + return data if isinstance(data, dict) else {} + + +def excess(asked, granted): + """Scopes asked above the grant, as 'scope: asked > granted'.""" + if asked is UNKNOWN or granted is UNKNOWN: + return [] + out = [] + for scope, level in sorted(asked.items()): + have = granted.get(scope, 0) + if level > have: + name = {v: k for k, v in LEVEL.items()} + out.append(f"{scope}: {name[level]} > {name[have]}") + return out + + +def walk(root, rel, granted, chain, problems, seen): + """Check workflow `rel`, called with token `granted`, and the workflows it calls.""" + key = (rel, repr(granted)) + if key in seen: + return + seen.add(key) + wf = load(root, rel) + top = normalise(wf.get("permissions")) + for job_id, job in (wf.get("jobs") or {}).items(): + if not isinstance(job, dict): + continue + own = normalise(job.get("permissions")) + effective = own if own is not UNKNOWN else (top if top is not UNKNOWN else granted) + if chain: # a called workflow: its jobs may not ask for more than the caller grants + for item in excess(effective, granted): + problems.append(f"{' -> '.join(chain + [rel])} job {job_id} asks {item} (caller grants less)") + uses = job.get("uses") + if isinstance(uses, str) and uses.startswith("./.github/workflows/"): + callee = uses[2:].split("@", 1)[0] + if not (root / callee).is_file(): + problems.append(f"{rel} job {job_id} calls missing {callee}") + continue + walk(root, callee, effective, chain + [f"{rel}:{job_id}"], problems, seen) + + +def check_tree(root): + problems = [] + for path in sorted((root / ".github/workflows").glob("fork-*.yml")): + walk(root, str(path.relative_to(root)), UNKNOWN, [], problems, set()) + return problems + + +def selftest(): + """The check must catch the bug it exists for, nested and with skipped jobs, and pass the fix.""" + caller = """ +permissions: {contents: read} +jobs: + release: + if: false + permissions: {actions: read, contents: write} + uses: ./.github/workflows/mid.yml +""" + mid = """ +permissions: {actions: read, contents: read} +jobs: + tests: + permissions: {actions: write, contents: read} + uses: ./.github/workflows/leaf.yml + publish: + permissions: {contents: write} + runs-on: ubuntu-latest + steps: [{run: "true"}] +""" + leaf = """ +permissions: {contents: read} +jobs: + watch: + if: false + permissions: {actions: write} + runs-on: ubuntu-latest + steps: [{run: "true"}] +""" + cases = [ + ("caller grants actions: read, nested job asks write -> fail", caller, True), + ("caller grants actions: write -> pass", caller.replace("actions: read, contents: write", "actions: write, contents: write"), False), + ("caller grants nothing ({}) -> fail", caller.replace("{actions: read, contents: write}", "{}"), True), + ("caller grants write-all -> pass", caller.replace("{actions: read, contents: write}", "write-all"), False), + ] + ok = True + for name, text, want_fail in cases: + with tempfile.TemporaryDirectory() as tmp: + root = pathlib.Path(tmp) + (root / ".github/workflows").mkdir(parents=True) + (root / ".github/workflows/fork-a.yml").write_text(text) + (root / ".github/workflows/mid.yml").write_text(mid) + (root / ".github/workflows/leaf.yml").write_text(leaf) + got_fail = bool(check_tree(root)) + good = got_fail == want_fail + print(("ok " if good else "FAIL ") + "selftest: " + name) + ok &= good + return ok + + +def main(): + ok = selftest() + root = pathlib.Path(__file__).resolve().parents[2] + problems = check_tree(root) + for p in problems: + print("FAIL " + p) + if not problems: + print("ok every called fork workflow asks for at most what its caller grants") + sys.exit(0 if ok and not problems else 1) + + +if __name__ == "__main__": + main() diff --git a/.github/workflows/fork-follow.yml b/.github/workflows/fork-follow.yml index 6fe7d2f64aeb5..d05c33aee90b9 100644 --- a/.github/workflows/fork-follow.yml +++ b/.github/workflows/fork-follow.yml @@ -287,8 +287,12 @@ jobs: name: Release needs: [plan] if: needs.plan.outputs.action == 'release' || needs.plan.outputs.action == 'rebase' + # A called workflow's job may not ask for more than this grants, even a skipped one, or GitHub + # refuses the whole run at start-up: fork-release.yml's tests job asks for actions: write + # (fork-tests.yml's fleet_watch). fork-release.yml's top level keeps its other jobs at read. + # Test: fork-reusable-permissions.test.py. permissions: - actions: read + actions: write contents: write uses: ./.github/workflows/fork-release.yml # By name, only what fork-release.yml declares (release-desktop.yml's signing secrets). From 5d084d77331aab49d413be310ebab42ff8daa8aa Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sat, 14 Nov 2026 08:22:45 +0000 Subject: [PATCH 2/3] fork-reusable-permissions test: check callee top level, refuse unknown grants, prove each rule Lens minors on #66 (issuecomment-6874463655), fixed in the same round: - a called workflow's own top-level permissions are compared with the caller's grant; - a job that calls a workflow with no permissions set anywhere fails instead of being skipped; - selftest cases for: only the second level asks more, a callee job taking the callee's top level, top level above the grant while every job asks less, `{}` on the calling job, and a caller with no permissions. Each guard was removed once; the selftest fails each time. Co-Authored-By: Claude Opus 5.5 --- .../scripts/fork-reusable-permissions.test.py | 43 +++++++++++++------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/.github/scripts/fork-reusable-permissions.test.py b/.github/scripts/fork-reusable-permissions.test.py index afa161d5721e1..6cb97a633b426 100644 --- a/.github/scripts/fork-reusable-permissions.test.py +++ b/.github/scripts/fork-reusable-permissions.test.py @@ -68,6 +68,9 @@ def walk(root, rel, granted, chain, problems, seen): seen.add(key) wf = load(root, rel) top = normalise(wf.get("permissions")) + if chain: # a called workflow's own top level may not ask for more than the caller grants either + for item in excess(top, granted): + problems.append(f"{' -> '.join(chain + [rel])} top-level permissions ask {item} (caller grants less)") for job_id, job in (wf.get("jobs") or {}).items(): if not isinstance(job, dict): continue @@ -82,6 +85,9 @@ def walk(root, rel, granted, chain, problems, seen): if not (root / callee).is_file(): problems.append(f"{rel} job {job_id} calls missing {callee}") continue + if effective is UNKNOWN: # the repository default applies: nothing here can be checked + problems.append(f"{rel} job {job_id} calls {callee} without permissions (set them on the job or workflow)") + continue walk(root, callee, effective, chain + [f"{rel}:{job_id}"], problems, seen) @@ -93,7 +99,7 @@ def check_tree(root): def selftest(): - """The check must catch the bug it exists for, nested and with skipped jobs, and pass the fix.""" + """The check must catch each rule it exists for and pass the fixed shapes.""" caller = """ permissions: {contents: read} jobs: @@ -122,23 +128,36 @@ def selftest(): runs-on: ubuntu-latest steps: [{run: "true"}] """ + grant_write = caller.replace("actions: read, contents: write", "actions: write, contents: write") + plain_job = " runs-on: ubuntu-latest\n steps: [{run: \"true\"}]\n" cases = [ - ("caller grants actions: read, nested job asks write -> fail", caller, True), - ("caller grants actions: write -> pass", caller.replace("actions: read, contents: write", "actions: write, contents: write"), False), - ("caller grants nothing ({}) -> fail", caller.replace("{actions: read, contents: write}", "{}"), True), - ("caller grants write-all -> pass", caller.replace("{actions: read, contents: write}", "write-all"), False), + # (name, caller, mid, leaf, want_fail) + ("first level asks more than the caller grants -> fail", caller, mid, leaf, True), + ("caller grants enough at every level -> pass", grant_write, mid, leaf, False), + ("caller grants write-all -> pass", caller.replace("{actions: read, contents: write}", "write-all"), mid, leaf, False), + ("only the second level asks more -> fail", grant_write, mid, + leaf.replace("permissions: {actions: write}", "permissions: {contents: write}"), True), + ("callee job without permissions takes the callee's top level (asks more) -> fail", grant_write, + "permissions: {actions: write, contents: write, issues: write}\njobs:\n build:\n" + plain_job, leaf, True), + ("callee top level asks more though every job asks less -> fail", grant_write, + "permissions: {pages: write}\njobs:\n build:\n permissions: {contents: read}\n" + plain_job, leaf, True), + ("job permissions {} grant nothing, not the workflow default -> fail", + "permissions: write-all\njobs:\n release:\n permissions: {}\n uses: ./.github/workflows/mid.yml\n", + "jobs:\n build:\n permissions: {contents: read}\n" + plain_job, leaf, True), + ("caller with no permissions anywhere calls a workflow -> fail", + "jobs:\n release:\n uses: ./.github/workflows/mid.yml\n", mid, leaf, True), ] ok = True - for name, text, want_fail in cases: + for name, top_text, mid_text, leaf_text, want_fail in cases: with tempfile.TemporaryDirectory() as tmp: root = pathlib.Path(tmp) (root / ".github/workflows").mkdir(parents=True) - (root / ".github/workflows/fork-a.yml").write_text(text) - (root / ".github/workflows/mid.yml").write_text(mid) - (root / ".github/workflows/leaf.yml").write_text(leaf) - got_fail = bool(check_tree(root)) - good = got_fail == want_fail - print(("ok " if good else "FAIL ") + "selftest: " + name) + (root / ".github/workflows/fork-a.yml").write_text(top_text) + (root / ".github/workflows/mid.yml").write_text(mid_text) + (root / ".github/workflows/leaf.yml").write_text(leaf_text) + problems = check_tree(root) + good = bool(problems) == want_fail + print(("ok " if good else "FAIL ") + "selftest: " + name + ("" if good else f"\n | {problems}")) ok &= good return ok From f39d893ce065e991181bda73a185ba82f79b2690 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sat, 14 Nov 2026 08:25:39 +0000 Subject: [PATCH 3/3] test(fork-ci): prove inheritance and nested top-level checks on their own Re-check lens minors on #66: the inheritance case failed only via the top-level check, and the top-level check was tested one level deep only. Each new case fails when its rule is removed (checked by mutation). Co-Authored-By: Claude Opus 5.5 --- .github/scripts/fork-reusable-permissions.test.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/scripts/fork-reusable-permissions.test.py b/.github/scripts/fork-reusable-permissions.test.py index 6cb97a633b426..dacf00b7c33a7 100644 --- a/.github/scripts/fork-reusable-permissions.test.py +++ b/.github/scripts/fork-reusable-permissions.test.py @@ -137,10 +137,15 @@ def selftest(): ("caller grants write-all -> pass", caller.replace("{actions: read, contents: write}", "write-all"), mid, leaf, False), ("only the second level asks more -> fail", grant_write, mid, leaf.replace("permissions: {actions: write}", "permissions: {contents: write}"), True), - ("callee job without permissions takes the callee's top level (asks more) -> fail", grant_write, - "permissions: {actions: write, contents: write, issues: write}\njobs:\n build:\n" + plain_job, leaf, True), + # Proves inheritance on its own: mid's top level fits the grant, so only a job that wrongly took the + # caller's write-all grant (instead of mid's top level) would let the leaf's actions: write through. + ("callee job without permissions passes on the callee's top level, not the caller's grant -> fail", + caller.replace("{actions: read, contents: write}", "write-all"), + "permissions: {contents: read}\njobs:\n build:\n uses: ./.github/workflows/leaf.yml\n", leaf, True), ("callee top level asks more though every job asks less -> fail", grant_write, "permissions: {pages: write}\njobs:\n build:\n permissions: {contents: read}\n" + plain_job, leaf, True), + ("second-level callee top level asks more though its jobs ask less -> fail", grant_write, mid, + leaf.replace("permissions: {contents: read}", "permissions: {pages: write}"), True), ("job permissions {} grant nothing, not the workflow default -> fail", "permissions: write-all\njobs:\n release:\n permissions: {}\n uses: ./.github/workflows/mid.yml\n", "jobs:\n build:\n permissions: {contents: read}\n" + plain_job, leaf, True),