If you’re developing a new GitHub Actions workflow, you may want to test it on a feature branch before merging it into your default branch. Unfortunately, GitHub Actions has a limitation: workflows that only exist on a branch and use workflow_dispatch cannot be triggered until GitHub has “seen” them at least once.
In this guide, we’ll walk through a simple and reliable workaround to test GitHub Actions workflows on a branch using a temporary push trigger and the GitHub CLI.
On your feature branch, create a new workflow file under .github/workflows/, starting with a minimal trigger using push:
on:
push:
At this stage, the job can be incomplete or just a placeholder. The important part is that the workflow runs at least once.
Push the branch to GitHub so the workflow is executed.
💡 You can cancel the job immediately if you don’t want it to finish.
Once the workflow has run a single time, GitHub internally registers it.
This is a key step: without it, GitHub won’t allow manual triggers from branches.
After the first run, you no longer need the push trigger.
As long as the workflow file remains in the branch, you can keep triggering it via gh until it’s fully tested and ready to be merged.
No additional push runs are required.
Testing GitHub Actions workflows on feature branches can be tricky due to current platform limitations. By temporarily enabling a push trigger, letting the workflow run once, and then switching to workflow_dispatch, you can safely and effectively test your workflow without polluting your default branch.
Until GitHub provides better native support for branch-only manual workflows, this workaround is one of the cleanest and most practical solutions available.
