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.

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.