GitHub Actions workflow_dispatch from non-default branch

Problem

When developing GitHub Actions workflows on non-default branches (not main/master), you may encounter issues with the workflow_dispatch event trigger. The GitHub Actions UI doesn't reliably display or allow running workflows from feature branches, even when they contain a properly configured workflow_dispatch trigger.

The core issue is that GitHub's interface seems to cache workflow definitions from the default branch, making it difficult to test workflows during development without first merging them.

Solution approaches

1. Using GitHub CLI (Recommended)

The most robust solution is using the GitHub CLI (gh) to run workflows on non-default branches:

# List available workflows
gh workflow list

# Run a specific workflow from a feature branch
gh workflow run "Workflow Name" --ref branch-name -f parameter=value

Prerequisite

The workflow must be "registered" with GitHub first. If it doesn't appear in gh workflow list, use one of the following methods to register it.

2. Temporary trigger registration

To register a workflow for workflow_dispatch, temporarily add a different trigger:

name: 'My Workflow'
on:
  workflow_dispatch:
    inputs:
      parameter:
        description: My Parameter
  push:  # Temporary trigger to register the workflow
    branches:
      - features/myfeature

After pushing this change and allowing the workflow to run once, you can remove the push trigger. The workflow will remain registered for workflow_dispatch.

3. Pull request trigger alternative

For teams that prefer not to use push triggers:

name: 'My Workflow'
on:
  workflow_dispatch:
    inputs:
      parameter:
        description: My Parameter
  pull_request:  # Temporary trigger

Create a pull request to trigger the workflow once, then remove the pull_request line.

Handling input parameters

When using temporary triggers, you may need to provide default values for workflow inputs:

name: 'My Workflow'
on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: Logging level
        type: string
        required: true
  push:  # Temporary trigger

env:
  LOG_LEVEL: ${{ inputs.logLevel || 'DEBUG' }}  # Default value

Complete workflow example

name: Feature Branch Test
on:
  workflow_dispatch:
    inputs:
      environment:
        description: Deployment environment
        type: choices
        options:
          - staging
          - production
        required: true
      debug:
        description: Enable debug mode
        type: boolean
        default: false
  push:
    branches:
      - features/**  # Temporary - remove after registration

env:
  DEPLOY_ENV: ${{ inputs.environment || 'staging' }}
  DEBUG_MODE: ${{ inputs.debug }}

jobs:
  test-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        
      - name: Show deployment info
        run: |
          echo "Deploying to $DEPLOY_ENV"
          echo "Debug mode: $DEBUG_MODE"
          echo "Branch: $GITHUB_REF"

Best practices

1. Use GitHub CLI for development: The gh workflow run command is the most reliable way to test workflows on feature branches.

2. Register workflows temporarily: Use push or pull request triggers only briefly to register workflows, then remove them.

3. Document workflow registration: Add comments to remind team members to remove temporary triggers after registration.

4. Test thoroughly: After registration, verify the workflow works with both CLI and UI triggers.

WARNING

Workflows may become unregistered if all their run logs are deleted. Keep at least one successful run to maintain registration for non-default branch workflows.

Summary

While GitHub's UI has limitations for testing workflow_dispatch events on feature branches, the GitHub CLI provides a reliable alternative. By temporarily adding push or pull request triggers to register workflows, then using gh workflow run for testing, you can effectively develop and test workflows without merging to the default branch prematurely.