[Bug] workflow_dispatch on feature branches requires an initial syntax error push to become triggerable via GitHub CLI

[zhechen-hawl]

🏷️ Discussion Type

Bug

💬 Feature/Topic Area

ARC (Actions Runner Controller)

Discussion Details

Description
There is a severe indexing and UX inconsistency in GitHub Actions regarding how workflow_dispatch events are registered on non-default branches.

If a developer pushes a perfectly valid workflow_dispatch workflow to a feature branch, it remains completely hidden in the Actions UI, and attempts to trigger it via GitHub CLI (gh workflow run) will fail because the backend hasn't registered it.

To bypass this and actually test the workflow, developers must use a highly counter-intuitive workaround: push a fully commented-out YAML file first to deliberately trigger a syntax error. This error forces the system to register the workflow, which then permanently unlocks the ability to trigger it via the CLI.

Steps to Reproduce (The required workaround):

1，Create a new feature branch from main.

2，Create a new .github/workflows/test.yml file, but comment out the entire code (including the on: workflow_dispatch block).

3，Commit and push to the feature branch.

4，The GitHub Actions engine catches this, throws a syntax error (No event triggers defined in on), and logs a "failed run".

5，Go to the Actions tab. Because of the error log, the workflow now forcibly appears in the left sidebar.

6，Go back to the code, uncomment the YAML to restore the valid workflow_dispatch setup, and push again.

7，Actual Result: The manual "Run workflow" button is still missing from the web UI. However, because the initial error forced the backend to index the file, developers can now successfully trigger the workflow using the GitHub CLI: gh workflow run test.yml --ref .

(Note: If a developer skips the deliberate error in Step 2 and pushes the valid workflow immediately, it is never indexed, and even the gh CLI command will fail to find/run it).

Expected Behavior
Valid workflows with workflow_dispatch pushed to non-default branches should be immediately indexed by the backend. They should be visible in the Actions sidebar with a functional "Run workflow" UI button, and should be instantly triggerable via the gh CLI without requiring a dummy syntax error push.

Impact
This undocumented indexing limitation creates a terrible developer experience. It forces CI/CD engineers to intentionally break their codebase on the first commit just to register a workflow for command-line testing on a feature branch.

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[gistrec]

What about a workaround: temporarily add a push: trigger so the workflow runs once on the branch (registering it), then gh workflow run --ref <branch> works — you can drop the push: afterward. (Or put the workflow on the default branch once if you also want the UI button.) The underlying indexing behavior is undocumented, so the feedback is fair — you just don't need the deliberate-error step.