Manually triggering GitHub Actions workflows can be very useful at times, in addition to GitHub Actions ability to be triggered on certain events, such as a push to a repository or the creation of a pull request. In this article, we’ll look at configuring manual triggers on GitHub Actions workflows and some of the configuration options available.
Table of Contents
Add Manual Trigger in GitHub Actions
A manual trigger in GitHub Actions allows you to manually trigger a workflow instead of relying on automatic triggers. Manual triggers can be useful in a variety of scenarios, such as when you want to test a specific feature or deploy your code to a specific environment.
Configuring a manual trigger in GitHub Actions can be done by adding a workflow_dispatch
event to the YAML configuration. This event allows you to trigger the workflow manually using the GitHub Actions web interface or the GitHub API.
The following is an example of how to configure a manual trigger in a GitHub Actions workflow:
name: Manual Trigger Workflow
# configure manual trigger
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Build project
run: |
npm install
npm run build
In this example, the YAML defines a workflow named “Manual Trigger Workflow” that has a manual trigger by using the workflow_dispatch
event. The build
job in the workflow checks out the code and builds the project.
Once the GitHub Action is configured with a manual trigger using workflow_dispatch
, then the “Run workflow” dropdown / button will display on the Actions page of GitHub. This is where you will go on GitHub to manually trigger the GitHub Actions workflow to execute as needed.

Configuration Options for Manual Triggers
There are several configuration options available for the workflow_dispatch
event when configuring manual triggers in GitHub Actions. Let’s take a look at some of the most commonly used configuration options.
Configure Inputs
Inputs allow you to provide additional data to your workflow when you trigger it manually. For example, you may want to provide a specific version number or a target environment for your deployment.
workflow_dispatch.inputs
is a dictionary of key-value pairs that represent the inputs passed to the workflow when it is manually triggered. Each key represents an input name, while the corresponding value represents the input value. These input values are then accessible within the workflow for reference.
The following example shows a sample configuration of a couple inputs
on the workflow_dispatch
manual trigger:
name: Manual Trigger Workflow
on:
workflow_dispatch:
inputs:
branch:
description: 'The branch to build'
required: true
environment:
description: 'The environment to deploy to'
required: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Build project
run: |
npm install
npm run build --branch ${{ github.event.inputs.branch }}
- name: Deploy Project
uses: my-deploy-action@v1
with:
environment: ${{ github.event.inputs.environment }}
In this example, we’ve defined a workflow that runs two jobs: build
and deploy
. The workflow is triggered manually using the workflow_dispatch
event. We’ve also defined two inputs using the inputs
key: branch
and environment
. The branch
input specifies the branch to build, while the environment
input specifies the environment to deploy to.
To manually trigger the workflow and pass values for the inputs, you can navigate to the Actions tab in your repository, select the workflow you want to trigger, and click the “Run workflow” button. This will open a dialog box where you can enter values for the inputs. In the example above, you would enter the branch name and environment name you want to use.
Once the workflow is triggered, the inputs are passed to the workflow as an object in the github.event.inputs
field. We can reference the input values in our pipeline steps using the ${{ }}
syntax. In the example above, we’ve used the github.event.inputs.branch
and github.event.inputs.environment
values in our npm run build
and my-deploy-action
steps, respectively.
workflow_dispatch.inputs
is a powerful feature of GitHub Actions that allows you to pass inputs to your workflows when manually triggering them. By defining inputs in your workflow file and referencing them in your pipeline steps, you can make your pipelines more flexible and customizable.
Once the workflow_dispatch.inputs
are configured on a GitHub Actions workflow, then the Run workflow
dropdown / button on the Actions page of GitHub will display the inputs
with the ability to configure then when triggering the workflow execution. The following screenshot shows an example of what this looks like on GitHub.

Configure Input Options
The configuration of workflow_dispatch.inputs
supports a couple additional parameters that can be used to configure preset available options that can be selected. This will have the end result of the GitHub Actions UI to show a dropdown of the available options for the input
rather than a free-form text box.
The following are a couple configuration parameters for workflow_dispatch.inputs
that can be used:
default
– Enables the configuration of the default value for the input.type: choice
– Configured the input to be a dropdown of options, rather than a text box.options
– Allows the configuration of the different options available within the choice dropdown.
The following is an example of configuring an input named logLevel
with the default value of warning
and a couple available options
to choose from when manually triggering the workflow:
on:
workflow_dispatch:
inputs:
logLevel:
description: 'Log level'
required: true
default: 'warning'
type: choice
options:
- info
- warning
- debug
Configure Branches
By default, manual triggers are only available on the default branch of your repository. However, you can configure manual triggers to be available on other branches as well.
The following is an example of how to configure manual triggers for a specific branch:
name: Manual Trigger Workflow
on:
workflow_dispatch:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Build project
run: |
npm install
npm run build
In the example above, we have configured the workflow_dispatch
event to be available on the main
branch.
Configure Permissions
You can also configure manual triggers to require certain permissions. For example, you may want to require that only certain users or teams can manually trigger the workflow.
The following is an example of how to configure permissions for workflow_dispatch
manual trigger:
name: Manual Trigger Workflow
on:
workflow_dispatch:
permissions:
users:
- username
teams:
- teamname
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Build project
run: |
npm install
npm run build
In the example above, we have configured the workflow_dispatch
event to require that the user with the username username
or the team with the name teamname
has permission to trigger the workflow.
Conclusion
Configuring a manual trigger using workflow_dispatch
in GitHub Actions can be a powerful way to enhance the automation of your workflow pipelines. The inputs
can be customized to allow text input or even a dropdown of preset options. By using the workflow_dispatch
event with permissions
, you can ensure that only authorized users or teams can trigger your workflow. With the right configuration, you can customize your GitHub Actions workflow pipelines to suit your teams needs.
Thanks for the post!
I tried this but I am able to trigger a workflow without being in the list of authorized users. Not sure whats going on.