ADR-0110
ADR-0110-the-app-may-change-and-dispatch-workflows-so-no-agent-acts-under-the-maintainers-identity-dispatch-is-a-closed-list-and-every-workflow-change-still-waits.md
ADR-0110 — The App may change and dispatch workflows, so no agent acts under the maintainer's identity: dispatch is a closed list, and every workflow change still waits for the maintainer
Date: 2026-11-04
Status: accepted (2026-11-04: the maintainer decided the recommended answer, option A, with its three preconditions in the order written; the charter diff below lands only in the maintainer's own signed charter commit, a class R act) — constitutional, class R under ADR-0088 decision 2: it would amend ADR-0088 decision 3
("never administration, workflows or variables") and widen the charter's scope-D. Written by an agent;
under ADR-0088 decision 4 the maintainer decides, and the agent's writing is disclosed throughput, not
independent review
Deciders: the maintainer
Method: read on a fresh clone of stranxik/runward at main@b7d8c62: runward/delegation.md,
runward/runbook.md (the App's installation entry and the stop), every file of .github/workflows/
(triggers, permissions: blocks, secrets. references, environment: keys), docs/verifying-a-release.md
(the flags of every gh attestation verify), src/lib/delegation.ts (the charter reader's closed key set),
ADR-0082, ADR-0088, ADR-0090, ADR-0103. Not measured: GitHub's behaviour for any permission named here on
runward's own repository; the npm trusted-publisher configuration (it is read on npmjs.com, not in the tree)
Relates to: ADR-0082,
ADR-0088,
ADR-0090,
ADR-0085,
ADR-0103,
ADR-0111 (proposed, the companion record on verdict-path merges)
Would amend, by name, once accepted: ADR-0088 decision 3, for workflows and actions: write only
(administration and variables stay refused); the runbook's App entry, which repeats it
Context
What the charter and the doctrine say. ADR-0082: an agent acts "as itself", "never under a human's
name". ADR-0088 decision 3: delegated acts run under runward-steward, "never administration, workflows
or variables". The runbook installs the App with metadata: read, contents: write,
pull_requests: write, repository_advisories: write, actions: read, checks: read, statuses: read.
What that leaves undone, and how it has been done. Two kinds of act recur in runward's delivery and the App cannot make either:
- A change to a file under
.github/workflows/. GitHub refuses a push that creates or modifies a workflow file from a token without theworkflowspermission. ADR-0103's Consequences records it: "Agent sessions cannot push workflow files; the change sits in its own commit", pushed by the maintainer. - A dispatch or a re-run.
gh workflow runand a re-run needactions: write. ADR-0103 decision 2 makesgh workflow run mutation-ratchet.yml -f module=<m> -f mode=measurethe remedy every stale module names, and the documented-commands guard, the release verification and the artifact round trip are dispatched on demand.
When the maintainer is not available for each of these, the only credential that can make them is the maintainer's own. An agent that uses it acts under a human's identity: the outcome ADR-0082 exists to prevent, and the attribution defect ADR-0088's Context measured for merges. Stage 1 already says the maintainer's credential is within agent reach; that is a disclosure of a risk, not a licence to use it.
What the workflows can reach, read on main@b7d8c62.
- No workflow references a repository secret (
secrets.appears in none of the 13 files), and the runbook records that the repository keeps no Actions secret. What a workflow can obtain beyond itsGITHUB_TOKENis an OIDC token, in the jobs that declareid-token: write:release.yml(npm trusted publishing and provenance),build-and-attest.yml(Sigstore),mutation-ratchet.yml'ssummaryjob (Sigstore),scorecard.yml. - No workflow declares an
environment:. The npm publish inrelease.ymlis gated byif: github.event_name == 'release', a condition written in the workflow file itself. ci.yml, which carries the requiredtestchecks, runs onpull_request, so a pull request is judged by the workflow file at its own head.delegation-stop.ymlandnet-shrink.ymlrun onpull_request_target, from the default branch's copy, so a pull request that edits them is not judged by its edit.- The verification guide pins
--signer-workflowon itsgh attestation verifycommands and carries no--source-ref. - The charter reader refuses any field it does not know (
src/lib/delegation.ts, "a field the gate does not read is a promise nobody checks"), so a new charter key needs a CLI change; existing keys do not.
What the two permissions add, beyond today's contents: write. Today the App can already push a branch,
and every workflow triggered by that push runs, but only as the workflow files already are. With workflows
the App can write the file that runs. On a branch, a workflow file written by the App can declare any
permissions: the repository allows, including id-token: write, drop any if: condition, and be
dispatched on that branch's ref. With actions: write it can also dispatch any workflow that has
workflow_dispatch, with any inputs, re-run any run, cancel runs, delete runs, logs and artifacts, and
enable or disable a workflow. GitHub offers no per-workflow scoping of either permission.
So the risk the maintainer named is real in its general form and narrower in runward's: there is no secret to
exfiltrate, but there are two credentials a branch workflow could mint. The first is the npm publish
credential, if npm's trusted publisher for runward and runward-forge is bound to the repository and the
workflow file name only, without an environment the branch cannot enter. The second is a Sigstore identity
naming a runward workflow, on a branch ref the verification guide does not pin. The third risk is
self-judgement: a pull request that edits ci.yml is judged by its own edit.
Options considered
- A. Grant both permissions, with preconditions that close the minting paths, a closed dispatch list
enforced where the tree can enforce it and detected where it cannot, and
.github/**kept a pre-merge path. No agent needs the maintainer's credential for these acts; the maintainer keeps the merge of every workflow change. - B. Keep the permissions refused, and queue every workflow change and dispatch for the maintainer. No new risk; the acts wait, or are made under the maintainer's credential when they cannot wait, which is the defect this record exists for.
- C. A second App holding only
actions: write, for dispatch, and the maintainer keeps workflow-file pushes. Smaller blast radius for dispatch alone; two keys under the same custody in stage 1, and the workflow-file half of the defect stays open. - D. Dispatch through a relay workflow on the default branch (
workflow_dispatchorrepository_dispatchreceived by a workflow that checks its own allowlist and calls the target with itsGITHUB_TOKEN). The allowlist would then run frommainonly. But aGITHUB_TOKEN"will not create a new workflow run" (ADR-0088 Context), so the relay cannot start the target; and starting the relay already needsactions: writeorcontents: writewith arepository_dispatchscope the App would hold anyway.
Decision
Decided (2026-11-04). The maintainer accepted the recommendation below: option A, with its three preconditions in the order written. Nothing in the charter changes until the maintainer's signed charter commit; until then the record states a decision, not a mechanism in force.
Recommended: A, in this order. Nothing is granted before items 1 to 4 hold.
- The publish credential leaves the reach of a branch workflow (precondition, class R). An environment
releasewhose deployment rule admits only tagsv*; npm's trusted publishers forrunwardandrunward-forgebound to that environment; thepublishjob ofrelease.ymldeclaringenvironment: release(a workflow change, through a pull request the maintainer merges). Then a run on a branch ref, whatever its workflow file says, cannot enter the environment, and npm refuses its OIDC exchange. Thev*tag ruleset that refuses the App (ADR-0088 T5, measured on the lab repository) is read back on runward before the grant: a tag the App could create would be a ref the environment admits. - The release attestations name their ref (precondition). Every
gh attestation verifyof the guide and ofverify-release.ymlthat checks a release artifact gains--source-ref refs/tags/vX.Y.Z, held in lockstep by the documented-commands guard, so an attestation minted on a branch under a runward workflow's name fails the documented verification. Whether--signer-workflowalone already refuses it is measured first (What would settle it); if it does, the pin stays as a stated defence, not a fix. Measured 2026-11-04, gh 2.100.0, on runward's v0.46.0 tarball:--signer-workflowgiven without a ref accepted the provenance, and the same file with@refs/tags/v0.45.0or@refs/heads/mainappended refused it; so the bare flag does not bind the ref, and the pin is a fix, not a defence.--source-ref refs/tags/v0.46.0passed and--source-ref refs/heads/mainfailed on every guide command for that release. The pin is in the guide and inverify-release.yml, held bytest/unit/documented-commands.test.js. Lab measure, 2026-11-04,stranxik/runward-delegation-lab: a workflow pushed on branchlab/branch-mintattested a probe file (run 41857529412), and the same workflow attested another from taglab-ok-1(run 41857542858). The branch-minted attestation passed--signer-workflowalone (exit 0) and failed with--source-ref refs/tags/lab-ok-1(exit 1); the tag-minted one passed with its tag and failed with--source-ref refs/heads/lab/branch-mint. The branch and the run were the maintainer's credential, not the App's: the App holds noworkflowspermission yet, and who wrote the workflow does not enter the certificate's ref. The npm half of the lab measure (a throwaway package's trusted publisher bound to av*-only environment) has not been run. - The closed dispatch list lives in the tree and is enforced on
main's copy..github/dispatch-allowlist.json(under.github/**, so a pre-merge path) names the workflows a delegate may dispatch or re-run, and the inputs it may pass. Proposed content, each verified to publish nothing and to write to nothing outside its run:mutation-ratchet.ymlwithmodulenon-empty andmode: measureonly (withmoduleempty thesummaryjob runs and signs a ratchet summary, which is a release's act, ADR-0079);documented-commands.yml(contents: read; runs the guide against a published release);verify-release.yml(contents: read; read-only verification of a published release);verify-artifact-roundtrip.yml(permissions: {}; "packs nothing, attests nothing, publishes nothing"). Never on the list:release.yml,build-and-attest.yml,scorecard.yml(publishes results underid-token: write),watch-external-facts.yml(issues: write),codeql.yml,gitlab-bench.yml(an external account; its own record if wanted).
- Each workflow on the list that takes inputs refuses, in its first job, a run whose
github.triggering_actoris a delegate and whose inputs are outside the list (for the ratchet: an emptymodule, ormode: gate). Each workflow withworkflow_dispatchthat is not on the list refuses, in its first job, any run whosegithub.triggering_actoris a delegate. - A guard test,
test/unit/dispatch-allowlist.test.js, in the required suite: every listed file exists and hasworkflow_dispatch; no listed workflow has a job withid-token,attestations,contents,packages,issuesorpull-requestsatwritethat the allowed inputs can reach; every workflow withworkflow_dispatchis either listed or carries the delegate refusal; the refusals name the delegates ofrunward/delegation.md. Positive controls: a listed workflow givenid-token: writefails it; an unlisted dispatchable workflow without the refusal fails it. - What this enforces, said as it is. The refusals and the test hold
main's copy. A dispatch on a branch ref runs that branch's copy, which the App can write: there, nothing in the tree enforces the list. Items 1 and 2 are what keep such a run from reaching npm or a verifiable release identity.
- Dispatches are detected after the fact. A weekly workflow,
dispatch-audit.yml(actions: read,contents: read), lists the runs of the period whosetriggering_actoris a delegate and whose event isworkflow_dispatch, or whoserun_attemptis above 1, and compares each with the list, its inputs and its ref (mainonly). Any run outside them is the pre-merge event « a workflow dispatched or re-run by a delegate outside the closed list », printed in the weekly digest. Declared: it reads the forge's run list, and a deleted run is not in it. - Workflow-file changes by the App land only through pull requests, and every one waits. The App never
pushes to
main(the branch protection already requires pull requests);.github/**stays inpre-merge-paths, and this record makes it permanent rather than a stage-1 measure: becauseci.ymlruns from the pull request's head, a workflow change is the one change that writes its own required checks, and no machine lane (ADR-0111) may ever merge it. - A re-run of a red required check stays a pre-merge event. The App may re-run a required check of a
listed workflow, or any check of its own pull request; a check red then green on re-run makes that pull
request wait for the maintainer whatever paths it touches, as the charter already says. The App never
deletes a run, a log or an artifact, and never disables or enables a workflow: none is in
scope-D, and item 4 lists what it can see of them. - Workflow permissions stay minimal. Every workflow keeps a top-level
permissions:ofcontents: reador{}, and a job raises a scope only for the step that needs it, asrelease.ymlandmutation-ratchet.ymlalready do; the guard test of item 3 reads the listed workflows, andtest/unit/workflow-contract*.test.jsstays the place for the others. - The grant, and its revocation, are the maintainer's (class R). From the App's settings, add
Workflows: read and write and Actions: read and write, then accept the new permissions on runward's
installation.
administrationandvariablesstay refused: the stop reads a repository variable the App must not set (runbook, "The stop"). Revocation is removing the two permissions, or uninstalling the App.
The charter diff proposed (class R, the maintainer's own signed commit, ADR-0088 decision 5: a widening
of scope-D cannot ride a renewal). It uses only keys the reader already knows:
scope-D:
- merges outside the pre-merge list
- agent ratification of manifest rows
- non-constitutional ADRs
- Dependabot merges (with cooldown)
- defect-register entries
- documentation syncs
- advisory drafts by the App (never by the GITHUB_TOKEN)
- golden regeneration
+ - workflow-file changes by the App, through a pull request only, merged by the maintainer (ADR-0110)
+ - workflow dispatch and re-run by the App, only the workflows and inputs of .github/dispatch-allowlist.json on the default branch (ADR-0110)
...
pre-merge-events:
- lock opt-ins (regulated, agentRatification, identities, singleAccountable, structureContract)
- README claims
- disagreement between agents
- a check red then green on re-run
- a ratchet drop
- any gate-bypass.log line
- the net shrank
+ - a workflow dispatched or re-run by a delegate outside the closed list
And in the charter's prose, under Classes, after the D sentence:
+The App holds `workflows` and `actions: write` (ADR-0110): it may open pull requests that change workflow
+files, which wait for the maintainer as every `.github/**` change does, and it may dispatch or re-run only
+the workflows of `.github/dispatch-allowlist.json`. It never holds `administration` or `variables`.
The runbook's App entry changes the same way, in the same commit.
Alternatives discarded
- B, the status quo. It keeps the permissions refused on paper while the acts are made under the maintainer's credential when they cannot wait: the false attribution ADR-0082 forbids, with no record of it.
- C, a dispatch-only second App. It halves the defect and doubles the keys under one custody in stage 1; worth reopening only if stage 2 separates custodies.
- D, a relay workflow. A
GITHUB_TOKENcannot start another workflow, so the relay cannot do the one thing it is for. - Grant without items 1 and 2. A branch workflow written by the App could then mint the npm publish credential, if the trusted publisher is not bound to an environment, and a Sigstore identity the guide does not tell from a release's. Whether either is possible today is not measured; the grant waits for the answer.
- Let a workflow change merge on green checks. The required
testchecks of that pull request run the workflow file the pull request wrote.
Consequences
- The attribution defect closes for these acts. Every workflow change, dispatch and re-run is the App's
on the forge, with the run's
triggering_actornaming it; the maintainer's credential is no longer the only one that can make them. In stage 1 it is still within agent reach, and the banner says so: this changes who acts, not what an agent could do. - The App's blast radius grows, and the record names how far. On a branch it can run any workflow it
writes. What stops that run reaching npm is the environment (item 1); what stops it passing for a release's
attestation is the ref pin (item 2); what judges a workflow change is the maintainer before merge (item 5).
What nothing stops: a branch run spending Actions minutes, reading the repository variable, and deleting
runs, logs or artifacts, including the run artifacts ADR-0103 cites for 30 days. Deletion is outside
scope-D, and outside what the tree can detect. - The maintainer's load moves, it does not vanish. Workflow changes still wait for the maintainer, now as pull requests opened by the App instead of commits made under the maintainer's credential. Dispatches and allowed re-runs stop waiting.
- Work it needs: the environment and the npm binding (class R, on GitHub and npmjs.com); the
environment:line, the delegate refusals,dispatch-allowlist.json, the guard test and the audit workflow (pull requests,.github/**, merged by the maintainer);--source-refin the guide andverify-release.yml. - No CLI change and no verdict change. The charter keeps its key set; the gate reads
scope-Dandpre-merge-eventsas strings, as today.
What would settle it
- For A: on the lab repository, an App-written workflow on a branch, dispatched by the App, is refused
the npm OIDC exchange for a throwaway package whose trusted publisher is bound to an environment limited to
v*tags, and admitted from av*tag; the same branch run's attestation failsgh attestation verify --signer-workflow <wf> --source-ref refs/tags/<tag>, and whether it passes--signer-workflowalone is recorded. Then on runward: thev*tag ruleset read back refusing the App; the guard test's positive controls failing as described; four weeks ofdispatch-audit.ymlwith every delegate run inside the list. - Against A: a delegate run outside the list that
dispatch-audit.ymldid not report; any path by which a branch run reached npm or produced an attestation the documented verification accepts; a workflow change merged without the maintainer.
Reevaluation trigger (mandatory, dated)
Reopen at the charter's renewal on 2026-12-31, or earlier on: a delegate run outside the closed list; a
deleted run, log or artifact found missing that a record cites; GitHub offering per-workflow scoping of
actions: write or of workflows; npm changing what its trusted publishing binds; ADR-0088 stage 2 holding
(the App key leaves agent reach, and item 1's assumptions change).
Trigger set on: 2026-11-04 · Watched via: dispatch-audit.yml's weekly output in the digest, the
GitHub and npm changelogs at each release's runbook step.
References
runward/delegation.md(scope-D,pre-merge-paths,pre-merge-events);runward/runbook.md(the App's installation entry, the stop);src/lib/delegation.ts(the closed key set)..github/workflows/*.ymlatmain@b7d8c62:release.yml(id-token: writein the publish job, noenvironment:),mutation-ratchet.yml(thesummaryjob and its condition),ci.yml(pull_request),delegation-stop.ymlandnet-shrink.yml(pull_request_target).docs/verifying-a-release.md(--signer-workflow, and--source-ref refs/tags/vX.Y.Zfrom 2026-11-04).- ADR-0082; ADR-0088 decisions 2, 3, 5 and Context (T2, T5; the
GITHUB_TOKENstarts no workflow); ADR-0090; ADR-0079; ADR-0103 decision 2 and Consequences. - GitHub App permissions: https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps (not re-read for this record); npm trusted publishing: https://docs.npmjs.com/trusted-publishers (environment binding not verified, as ADR-0088 already records).