Skip to content

Trigger policy

Which events may start a workflow in this repository and in the repositories made from the templates, and why.

The rule

A workflow starts only from:

Trigger Runs in the context of
push The pushed branch or tag
pull_request The pull request's merge ref, with a read-only token for forks
merge_group The merge queue's temporary branch
workflow_call The caller's event: one of the rows above

release.yml is the one exception: it starts from workflow_run when the self-CI finishes on main, and checks out only the commit that self-CI tested.

Not allowed: workflow_dispatch, schedule, pull_request_target, issue_comment, workflow_run (outside release.yml) and the other events that run in the default branch's context. To run a workflow again, use Re-run jobs on its run; to run it on a branch, push the branch or open a draft pull request.

The self-CI enforces the rule: .github/scripts/check_triggers.py fails on any other trigger in .github/workflows/ or in a template's workflows.

Why

A run started by one of those events executes in the context of the default branch. It can write the Actions cache entries that every later run on main, and every release built from main, restores. If such a run executes code it checked out by a computed ref, that code could leave a poisoned cache entry behind (CodeQL actions/cache-poisoning/poisonable-step).

Several workflows here must run code checked out by a computed ref: the handbook checker and the template drift check run ci-tools' own scripts at the commit of the workflow (job.workflow_sha), and template drift runs driver-template's scaffold at the caller's recorded version. Those refs are trusted, but neither CodeQL nor a reviewer can tell that from the expression alone. Removing the privileged triggers removes the risk instead of explaining it away: no run of these workflows can write the default branch's cache from code that a pull request chose.

A manual trigger bought nothing a re-run does not give: every check already runs on each push and pull request.

For callers

Repositories made from driver-template follow the same rule: their workflow files have no workflow_dispatch either. An ESP-IDF clean build needs no manual input: the caches are keyed by IDF commit and source, and gh cache delete --all empties them when a clean build is wanted.

Code scanning: untrusted checkout

Code scanning runs security-and-quality, which includes actions/untrusted-checkout/medium. That query reports every actions/checkout whose ref: names a ref, SHA or head in a workflow a pull request can start; it cannot tell a pinned ci-tools or handbook commit from a pull request's branch. Every reusable workflow here checks out that way by design, and what the query warns about (a self-hosted runner, a cache or artifact that a privileged workflow later trusts) is ruled out by this trigger policy, GitHub-hosted runners, read-only tokens and persist-credentials: false. .github/codeql/codeql-config.yml therefore excludes the medium variant, with this reasoning, and keeps actions/untrusted-checkout/high (privileged triggers), which reports any regression.