TL;DR #
workflow_dispatch trigger in GitHub Actions allows manual runs but only from the default branch. To test a manual workflow before merging, use GitHub CLI:
gh workflow run <workflow_name> --ref <branch_name>
If it’s never run before, trigger it once via push or pull_request triggers and then use GitHub CLI.
This simple trick lets you verify and debug GitHub Actions before they hit your main branch - without dummy merges and commits.
Intro #
GitHub Actions is a great tool for automating CI/CD and other workflows in your repository. By adding a manual trigger, you can start workflows from the Actions tab:
on:
workflow_dispatch:
However, GitHub only shows the “Run workflow” button for workflows that exist in the default branch (usually main or master).
This limitation means you can’t manually run a new workflow from a feature branch before merging it.
Luckily, there’s a simple workaround.
Run GitHub workflows from a branch using GitHub CLI #
You can trigger any workflow manually from the command line using the GitHub CLI:
gh workflow run <workflow_name> --ref <branch_name>
This command runs the workflow from the given branch, even if it’s not merged into the default branch yet.
Handling new and never triggered workflows #
However, there is one catch - the workflow must have run at least once so GitHub knows about it.
If it’s brand new and hasn’t been triggered yet, GitHub doesn’t recognize it for manual runs and you will not see it in the list of workflows: gh workflow list.
To initialize it, temporarily add a regular trigger like this:
on:
push:
pull_request:
Push a small change to the branch so the workflow runs once.
After that, you can safely remove these triggers, keep only workflow_dispatch and run your workflow via the GitHub CLI.
That’s it! 😉