[hardening] Limit privileged workflow_run wakes by conclusion and branch

[coygeek]

[hardening] Limit privileged workflow_run wakes by conclusion and branch

Summary

The example DeployBot workflow runs a privileged DeployBot job on every completed workflow_run event for the configured CI workflow name. GitHub documents that workflow_run fires regardless of the upstream workflow's conclusion, supports branch filters, and gives the downstream workflow access to secrets and write tokens even if the upstream workflow was unprivileged.

DeployBot's example should demonstrate the narrow privileged trigger pattern it expects users to copy.

Evidence

• examples/github-workflow.yml configures workflow_run for workflows: [CI] and types: [completed] in lines 8-11.
• The job-level if block filters pull_request_target and check_suite, but has no workflow_run branch or conclusion guard in examples/github-workflow.yml lines 29-51.
• The example workflow grants write permissions for contents, pull requests, issues, and actions in examples/github-workflow.yml lines 16-21.
• The GitHub Docs source repository is https://github.com/github/docs/; the GitHub Actions source says a workflow_run workflow can access secrets and write tokens even if the previous workflow was not privileged in https://github.com/github/docs/blob/main/content/actions/reference/workflows-and-actions/events-that-trigger-workflows.md.
• The GitHub Docs source repository is https://github.com/github/docs/; the source says workflow_run triggers regardless of the previous workflow's conclusion and recommends using github.event.workflow_run.conclusion for conditional behavior in https://github.com/github/docs/blob/main/content/actions/reference/workflows-and-actions/events-that-trigger-workflows.md.
• The GitHub Docs source repository is https://github.com/github/docs/; the source says workflow_run supports branches / branches-ignore filters in https://github.com/github/docs/blob/main/content/actions/reference/workflows-and-actions/events-that-trigger-workflows.md.
• The current public GitHub Docs page has the same workflow_run semantics: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflow_run

Impact

Users copying the example can run a write-token DeployBot job for failed, cancelled, or irrelevant upstream CI runs. DeployBot's internal checks reduce the chance of an unsafe merge, but the workflow still expands the privileged execution surface and creates unnecessary queue wakeups.

Because workflow_run is specifically a privilege-boundary event in GitHub Actions, examples should be conservative by default.

Proposed fix

• Add a branches filter under the workflow_run trigger for the intended base/default branch where possible.
• Add a workflow_run guard to the job if, for example requiring:
  • github.event.workflow_run.conclusion == 'success'
  • github.event.workflow_run.head_branch == github.event.repository.default_branch when the DeployBot handoff expects default-branch CI.
• Document how to adapt the branch guard if a repository intentionally uses workflow_run events from a protected release branch.
• Add a workflow syntax/test fixture if the project already validates example workflows.

Verification

• Review examples/github-workflow.yml against GitHub's workflow_run docs.
• python3 -m pytest -q