Skip to content

[docs] Self-healing documentation fix: workflow_run.conclusion filter - 2026-04-30 #29324

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Apr 30, 2026
Merged

[docs] Self-healing documentation fix: workflow_run.conclusion filter - 2026-04-30 #29324

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3872b71
docs(triggers): document workflow_run.conclusion filtering
github-actions[bot] Apr 30, 2026
793e2b7
docs(triggers): trim workflow_run.conclusion section
Copilot Apr 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions docs/src/content/docs/reference/triggers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,6 +279,32 @@ Workflows with `workflow_run` triggers include automatic security protections:

See the [Security Architecture](/gh-aw/introduction/architecture/) for details.

#### Conclusion Filtering (`conclusion:`)

Use `conclusion:` to restrict the trigger to specific workflow run outcomes. The compiler compiles this into a guarded `if:` condition so the workflow only runs for the matching conclusions. Other combined triggers (such as `workflow_dispatch`) are not blocked by the guard.

Copilot AI Apr 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The wording here implies conclusion: filters the trigger ("restrict the trigger" / "workflow only runs"), but GitHub Actions can’t filter workflow_run at the event level; this feature is implemented by compiling conclusion: into an if: on the activation job. As a result, a run may still be created and then skipped when the conclusion doesn’t match. Consider rephrasing to explicitly say the compiler injects a guarded activation-job if: that skips execution unless the conclusion matches (while remaining a no-op for other events).

Suggested change
Use `conclusion:` to restrict the trigger to specific workflow run outcomes. The compiler compiles this into a guarded `if:` condition so the workflow only runs for the matching conclusions. Other combined triggers (such as `workflow_dispatch`) are not blocked by the guard.
For `workflow_run`, use `conclusion:` to have the compiler inject a guarded `if:` on the activation job for specific workflow run outcomes. This does not filter the GitHub Actions event itself: a workflow run may still be created and then skipped when the conclusion does not match. Other combined triggers (such as `workflow_dispatch`) are not blocked by the guard.

Copilot uses AI. Check for mistakes.

```yaml wrap
on:
workflow_run:
workflows: ["CI"]
types: [completed]
conclusion: failure # Single conclusion
```

```yaml wrap
on:
workflow_run:
workflows: ["CI"]
types: [completed]
conclusion: [failure, cancelled] # Multiple conclusions
workflow_dispatch: # Safely combined — guard ensures dispatch passes through
```

Valid `conclusion` values: `success`, `failure`, `cancelled`, `skipped`, `timed_out`, `action_required`, `neutral`, `stale`.

> [!NOTE]
> The `conclusion` field compiles into a GitHub Actions `if:` condition: `github.event_name != 'workflow_run' || (github.event.workflow_run.conclusion == 'failure')`. This means the workflow still runs when triggered by other events in the same `on:` block.

### Deployment Status Triggers (`deployment_status:`)

Trigger workflows when a GitHub deployment status changes. [Full event reference](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#deployment_status).
Expand Down
Loading