GitHub Actions workflow_run Chained Workflow Never Triggers

A workflow that should start when another one finishes (via on.workflow_run) never runs. The trigger only fires for the workflow file on the default branch, and the referenced workflow name and completion type must match exactly.

What this error means

The downstream workflow_run workflow never appears in the Actions tab after the upstream workflow completes, even though the upstream run succeeded. There is no error - the trigger simply did not match.

on:
  workflow_run:
    workflows: ["Build"]      # must match the upstream 'name:' exactly
    types: [completed]
# nothing runs because the upstream workflow's name is actually "build" (lowercase)

Common causes

The workflow_run file is not on the default branch

A workflow_run-triggered workflow only fires from the version of the file on the repository default branch. A new file on a feature branch is ignored until merged.

Workflow name does not match

The workflows: list matches against the upstream workflow name: value, not its filename. A mismatch in case or wording means no trigger.

Wrong or missing types filter

Without types: it defaults to requested + completed. If you only want completed runs you must filter, and you still need to check the upstream conclusion yourself.

How to fix it

Match the name and merge to default

Reference the exact upstream name: and ensure the workflow_run file is on the default branch.

on:
  workflow_run:
    workflows: ["Build"]     # equals the upstream workflow's name: "Build"
    types: [completed]
jobs:
  deploy:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps: [{ run: ./deploy.sh }]

Gate on the upstream conclusion

1. A completed event fires for any conclusion - check github.event.workflow_run.conclusion to act only on success.
2. Use github.event.workflow_run.head_sha / head_branch to operate on the right commit.
3. Remember the trigger uses the default-branch copy of this file, so test by merging it.

How to prevent it

• Keep workflow_run chains on the default branch and reference the exact upstream name.
• Always check workflow_run.conclusion before acting on a completed event.
• Document the upstream/downstream contract so renames do not silently break the chain.

Frequently asked questions

Related guides