The workflow_dispatch event in GitHub Actions is designed to provide a manual trigger for workflows, allowing developers to execute specific automation tasks on demand via a "Run workflow" button in the GitHub user interface. However, a persistent and widely reported issue involves this button failing to appear or function correctly, even when the workflow syntax is valid and the file is properly located in the .github/workflows directory. This discrepancy often occurs not because the workflow is broken, but because of how GitHub caches workflow definitions, handles branch visibility, and processes UI interactions. Understanding the root causes requires examining three distinct failure modes: the visibility lag for new or renamed workflows, the inability to trigger workflows on non-default branches, and browser-specific client-side errors that prevent the UI from registering the click event.
The Visibility Lag and Caching Issue
One of the most common frustrations for developers is modifying an existing workflow to include the workflow_dispatch trigger, only to find that the "Run workflow" button does not appear in the GitHub Actions interface. This issue is frequently observed when a developer changes the trigger event of an existing workflow file or renames the workflow file itself. In several documented cases, users reported that after adding workflow_dispatch to an existing workflow or renaming the file to ensure it is treated as a new entry, the workflow would either disappear from the list entirely or remain listed without the manual trigger option.
The underlying mechanism here involves GitHub's internal indexing and caching of workflow definitions. When a workflow file is modified or renamed, GitHub Actions may take time to update the metadata associated with that workflow in the UI. In some instances, merging the branch containing the modified workflow into the default branch changes the name of the existing workflow in the UI, yet the "Run workflow" button still fails to appear. This suggests that the UI component responsible for rendering the trigger button is not correctly refreshing its state based on the updated YAML configuration.
Users have attempted various workarounds to force a refresh, including renaming the workflow file to a unique name like generate_license_activation.yaml or new_unity_license_activation.yaml and committing it to the default branch. Despite these efforts, the button often remains absent. In some cases, the workflow does not show up in the list at all after being renamed and committed to a branch, requiring a merge into the main branch to become visible again. However, even after the merge, the manual trigger option may still be missing. This behavior has been reported in both public and private repositories, indicating that the issue is not related to repository visibility settings or billing status, as users have confirmed they had available minutes and storage capacity.
Another factor in this visibility lag is the syntax validation process. GitHub Actions is supposed to validate the YAML syntax of workflow files. If the syntax is incorrect, GitHub should ideally provide an error message or indication of the problem. However, in many cases where the workflow_dispatch button is missing, no error is displayed, leading developers to suspect that the issue is a bug in the UI rather than a configuration error. Creating a minimal reproduction case with a simple build step that eliminates complex action libraries often yields the same result: the workflow runs automatically if triggered by other events, but the manual trigger button is conspicuously absent.
| Symptom | Potential Cause | Workaround |
|---|---|---|
| Workflow disappears after rename | GitHub caching/indexing lag | Merge to default branch, wait for refresh |
| Button missing after adding dispatch | UI state not refreshing | Create new file, delete old, merge |
| No error on invalid syntax | Silent failure in UI validation | Check raw YAML syntax manually |
| Works in new repos, not old | Legacy configuration state | Fork repo, test in fresh environment |
Triggering Workflows on Non-Default Branches
A more complex scenario arises when a developer needs to test a workflow_dispatch workflow on a feature branch before merging it into the default branch. GitHub Actions only displays workflows in the Actions tab if they are on the default branch or have run at least once. This creates a chicken-and-egg problem: to see the workflow and run it manually, it needs to have run, but to run it manually, it needs to be visible.
The standard solution for this involves temporarily adding a different trigger, such as pull_request, to the workflow file. By creating a pull request with the workflow, the pull_request event causes the workflow to run automatically. This initial run registers the workflow in the GitHub Actions system, making it visible in the Actions tab. Once the workflow is visible, the developer can remove the pull_request trigger and replace it with or add workflow_dispatch.
However, simply making the workflow visible is not always enough. Even after the workflow has run via a pull request and is visible in the Actions tab, the "Run workflow" button may still not appear in the UI for manual triggering. This is because the UI often relies on the workflow being on the default branch to offer the manual trigger option, or the cache has not yet updated to reflect the new trigger type.
The definitive solution for triggering a workflow on a non-default branch is to use the GitHub CLI (Command Line Interface). The GitHub CLI allows developers to trigger workflows directly from the terminal, bypassing the UI limitations. To use this method, the developer must first install the GitHub CLI and authenticate using the gh auth login command. Once authenticated, the developer can run the workflow using the gh workflow run command, specifying the workflow file name and the branch reference.
gh workflow run your-workflow.yml \
--ref your-branch \
-f input1=value1 \
-f input2=value2
If the workflow requires inputs, they can be passed using the -f flag. Upon successful execution, the CLI outputs a confirmation message such as "✓ Created workflow_dispatch event for your-workflow.yml at your-branch". The developer can then navigate to the GitHub Actions tab to view the logs of the triggered workflow. This method is reliable and does not depend on the UI's ability to render the "Run workflow" button. It is particularly useful for testing workflows in development branches where the manual trigger UI may be unavailable or buggy.
| Method | Pros | Cons |
|---|---|---|
| UI "Run workflow" button | User-friendly, no CLI needed | Fails on non-default branches, caching issues |
Temporary pull_request trigger |
Makes workflow visible | Requires extra commit, may fail if inputs missing |
GitHub CLI gh workflow run |
Works on any branch, reliable | Requires CLI installation and authentication |
Browser-Specific Client-Side Errors
While caching and branch issues are the most common causes of the missing workflow_dispatch button, browser-specific client-side errors can also prevent the button from functioning correctly, even when it is visible. Some users have reported that the "Run workflow" button appears in the UI but fails to execute when clicked. In these cases, clicking the button results in no visible action: the button may briefly highlight to indicate interaction, but it does not gray out, and no new workflow run appears in the Actions tab.
Investigation into these issues has revealed that browser extensions or built-in browser policies can interfere with the JavaScript execution required to trigger the workflow. Specifically, users browsing with Firefox have reported encountering "Referrer policy" errors in the browser console when attempting to click the "Run workflow" button. These errors can prevent the request from being sent to the GitHub API, effectively disabling the button.
In some instances, disabling browser extensions or switching to a different browser resolves the issue. For example, turning off a custom "Github Dark" user style or other UI-modifying extensions has been shown to eliminate visual glitches that might be masking the button or interfering with its click event. However, when the issue is rooted in browser-level policies like the Referrer Policy, simply disabling extensions may not be sufficient. The browser must allow the referrer information to be sent with the request, as GitHub's API may rely on this information to validate the request.
This type of failure is particularly insidious because it does not produce a clear error message in the GitHub UI. The button appears normal, the user clicks it, and nothing happens. The only way to diagnose this issue is to open the browser's developer tools and inspect the console for JavaScript errors or network request failures. If "Referrer policy" errors are present, switching to a different browser or adjusting browser security settings may be necessary to restore functionality.
| Browser Issue | Symptom | Solution |
|---|---|---|
| Referrer Policy Error | Button clicks but no run starts | Switch browser, adjust privacy settings |
| UI Extension Interference | Button missing or misaligned | Disable dark mode/user CSS extensions |
| JavaScript Console Errors | No visual feedback on click | Clear cache, hard refresh, check console |
Conclusion
The absence of the workflow_dispatch button in GitHub Actions is a multifaceted issue that stems from the interplay between GitHub's backend caching mechanisms, branch visibility rules, and client-side browser behaviors. Developers encountering this issue should first consider whether the workflow is on the default branch and whether it has been recently renamed or modified, as caching delays are the most common culprit. For workflows on non-default branches, the GitHub CLI provides a robust and reliable workaround that bypasses UI limitations entirely. Finally, browser-specific issues, particularly those related to referrer policies in browsers like Firefox, can silently prevent the button from functioning, necessitating a check of the browser console and a potential switch to a different browser. Understanding these distinct failure modes allows developers to troubleshoot and resolve the issue efficiently, ensuring that their manual trigger workflows are available when needed.