GitHub Actions workflow_dispatch Missing - Only Runs from Default Branch

The manual "Run workflow" button does not appear, or running a branch uses the wrong workflow, because workflow_dispatch must be present on the default branch before the UI offers it, and the dispatch runs the selected branch's version of the file.

What this error means

There is no "Run workflow" button in the Actions tab for the workflow, or dispatching a feature branch runs an unexpected definition, because the trigger only takes effect once it is on the default branch.

on:
  workflow_dispatch:   # button only shows after this is on the DEFAULT branch
jobs:
  run:
    runs-on: ubuntu-latest
    steps: [{ run: ./task.sh }]

Common causes

Trigger not yet on the default branch

GitHub only surfaces the manual run UI for workflow_dispatch once the trigger exists on the default branch. Adding it only on a feature branch shows no button.

Branch selector runs that branch's file

When you dispatch and pick a branch, GitHub runs the workflow as defined on that branch. If the branch lacks the inputs or steps you expect, the run differs from the default-branch version.

How to fix it

Merge workflow_dispatch to the default branch

Add the trigger and merge it to the default branch so the manual run button appears, then dispatch any branch.

on:
  workflow_dispatch:
    inputs:
      ref:
        description: 'Branch or tag to build'
        required: false

Account for which branch runs

1. Remember the dispatched run uses the workflow file from the branch you select.
2. Keep input definitions in sync across branches you intend to dispatch.
3. Use the gh CLI (gh workflow run) once the trigger is on the default branch.

How to prevent it

• Add workflow_dispatch on the default branch first.
• Keep inputs consistent across dispatchable branches.
• Document that a dispatch runs the selected branch's workflow definition.

Related guides