bootstrap-workflow-dispatch

GitHub does not reliably expose a brand-new workflow_dispatch workflow to gh workflow run until that workflow has been seen by Actions metadata at least once. Before merge, the default branch still points at the old workflow set, so a feature branch can hit:

HTTP 404: workflow <file>.yml not found on the default branch

The workaround is a one-shot branch-scoped push trigger that causes exactly one non-dispatch run on the feature branch, registering the workflow so later workflow_dispatch calls succeed.

Step 0 — confirm the failure mode

Verify the workflow is blocked for the expected reason:

gh workflow run <workflow-file>.yml --ref "$(git branch --show-current)"

If the error is workflow ... not found on the default branch, continue. If the failure is about bad inputs, missing permissions, or YAML syntax, fix that instead — this skill is only for the metadata-registration problem.

Step 1 — add the one-shot push trigger

Edit the workflow file and add a temporary push trigger next to workflow_dispatch, scoped to:

• the current feature branch name, and
• the workflow file's own path

Pattern:

on:
  workflow_dispatch: ...
  # One-shot bootstrap: GitHub only resolves `workflow_dispatch` for workflows
  # already registered in its Actions metadata, which happens on the first
  # non-dispatch run. Scoping this push trigger to the bootstrap branch plus this
  # file's path lets a single push register the workflow, then a follow-up commit
  # can remove the block before merge.
  push:
    branches: [your/current-branch]
    paths: ['.github/workflows/your-workflow.yml']

The branch scoping is critical: this must not become a general-purpose push trigger.

Step 2 — commit and push the bootstrap commit

Commit only the temporary trigger and push it:

git add .github/workflows/<workflow-file>.yml
git commit -m "ci: bootstrap workflow_dispatch registration for <workflow-name>"
git push -u origin "$(git branch --show-current)"

That push should fire exactly one non-dispatch run for the workflow and register it in GitHub Actions metadata for the branch.

Step 3 — retry the real dispatch

Re-run the intended gh workflow run ... command (or the wrapper script that uses it). If the workflow now dispatches, the bootstrap succeeded.

Step 4 — remove the temporary push trigger

Immediately delete the one-shot push block and commit the cleanup:

git add .github/workflows/<workflow-file>.yml
git commit -m "ci: drop one-shot push trigger after workflow registration"
git push -u origin "$(git branch --show-current)"

Do not leave the bootstrap trigger in the final PR diff unless a human explicitly asks for it.

Notes

• The bootstrap run is a normal Actions run, not a dispatch run.
• If you renamed the workflow file, the old filename may still 404 on the default branch too; that does not mean the trick failed.

Related

This skill ends the moment gh workflow run stops 404ing — registering the workflow is all it does. @.claude/skills/watch-ci/SKILL.md takes the other side, watching the run a successful dispatch produces.