Trigger GitHub Actions Manually with workflow_dispatch Inputs (2026)

You can trigger GitHub Actions workflows manually from the UI, which is great for testing or on-demand runs, but the real power comes when you can also pass inputs to those workflows.

Let’s say you have a workflow that deploys an application. You don’t want to deploy every time you push code, but you might want to deploy a specific version to a specific environment on demand. workflow_dispatch is how you enable this.

Here’s a simple main.yml that uses workflow_dispatch:

name: Manual Deploy

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy to'
        required: true
        default: 'staging'
        type: choice
        options:
        - staging
        - production
      version:
        description: 'Version to deploy'
        required: true
        type: string
      force_deploy:
        description: 'Force deployment even if no changes detected'
        required: false
        default: false
        type: boolean

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:

          ref: ${{ github.event.inputs.version }} # Use the input version for checkout



      - name: Deploy to ${{ github.event.inputs.environment }}

        run: |

          echo "Deploying version ${{ github.event.inputs.version }} to ${{ github.event.inputs.environment }}"


          if [ "${{ github.event.inputs.force_deploy }}" = "true" ]; then

            echo "Forcing deployment..."
            # Actual deployment commands here
          else
            echo "Performing standard deployment..."
            # Actual deployment commands here
          fi

When you push this to your repository, go to the "Actions" tab. You’ll see "Manual Deploy" listed. Click on it, and then click the "Run workflow" button. A dropdown will appear, showing the inputs you defined: environment, version, and force_deploy. You can select the environment, type in a version (e.g., v1.2.3), and choose whether to force the deploy.

The on.workflow_dispatch.inputs section is where the magic happens. Each key under inputs defines a parameter for your manual trigger.

• description: This is what shows up in the UI next to the input field. Make it clear what the user should provide.
• required: A boolean (true or false) indicating if this input must be filled out.
• default: A value that will be pre-filled in the UI. If the input is not required, this is the value used if the user leaves it blank.
• type: This determines the kind of input field in the UI. Common types include:
  • string: A simple text input.
  • boolean: A checkbox.
  • choice: A dropdown menu. You must also provide options as an array of strings for this type.
  • environment: A dropdown to select from your GitHub Environments.

Inside your workflow jobs, you access these inputs via the github.event.inputs context. For example, github.event.inputs.environment will give you the value selected for the environment input. This is crucial for making your workflow dynamic. In the example above, we use ${{ github.event.inputs.version }} to check out a specific tag and ${{ github.event.inputs.environment }} to conditionally run deployment logic.

The force_deploy input demonstrates a boolean type. When checked in the UI, its value becomes true, and when unchecked, it becomes false. Notice how we compare it as a string ("true") in the run command because that’s how it’s often passed in shell contexts.

The options array for type: choice is where you define the available selections for your dropdown. This is excellent for predefined values like deployment targets or release channels.

The real power here is in creating reusable workflows that can be triggered with specific parameters. Imagine a workflow that handles different types of builds, test suites, or deployment rollbacks, all controllable via these input parameters. You could even trigger these workflows from other workflows or external systems using the GitHub API, passing the same input parameters.

One subtle but incredibly useful aspect is how workflow_dispatch interacts with secrets. If you define an input of type: string but want to pass a secret value (like an API token), you should not put the secret directly into the input field. Instead, your workflow should reference a GitHub Secret that you’ve configured in your repository or organization settings (e.g., ${{ secrets.MY_API_TOKEN }}). The workflow_dispatch inputs are for parameters that control the workflow’s execution, not for sensitive credentials. The workflow then uses these parameters to decide which secrets to access or how to use them.

This mechanism allows for highly flexible and auditable on-demand operations directly from your repository’s UI.

You’ll next want to explore how to trigger these workflow_dispatch workflows programmatically using the GitHub API.