How to Use the workflow_dispatch Event for Manual Triggers

Introduction

We wanted to give some thoughts on how we can improve the control over our GitHub Actions workflows, especially for those pieces of tasks that require manual intervention. Instead of using automated triggers, we can use a manual trigger called workflow_dispatch, really useful when we need workflows to run at specific times.

What’s the workflow_dispatch event?

That said, this event, on the other hand, is designed to kick a workflow off manually from GitHub's UI or even via API. Rather, it is better suited for performing activities such as deploying to production, where the right moment of execution needs to be decided by a human.

We only need to add a simple configuration in our workflow file under the .github/workflows directory.

name: Workflow Dispatch Example

on:
  workflow_dispatch:

jobs:
  job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          echo "Hello, world!"
          sleep 10

Adding inputs for more dynamic workflows

One great feature of workflow_dispatch is that we can define inputs. It means we can pass parameters to the workflow when it's triggered, hence much flexible.

```yaml title=".github/workflows/manual-trigger.yml"
name: Custom Build Workflow

on:
workflow_dispatch:
inputs:
build_type:
description: 'Type of build to execute'
required: true
default: 'development'
include_tests:
description: 'Run tests during the build'
required: false
default: 'false'

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '14'
- name: Install dependencies
run: npm install
- name: Build project
run: |
echo "Building project with type ${{ github.event.inputs.build_type }}"
if [ "${{ github.event.inputs.include_tests }}" = "true" ]; then
echo "Running tests..."
npm test
fi

### How to trigger the workflow

You can trigger the workflow either from the GitHub UI. Here's a quick look at how to trigger via UI:

1. In the repo, click on the **Actions** tab.
2. Select the workflow that you want to run. 3. Click on **Run workflow**, fill in the required inputs, and click **Run**.


### Conclusion

Great for adding flexibility in your CI/CD pipelines, the `workflow_dispatch` event fully controls when and how specific workflows are triggered. Workflows can be manually started through the GitHub UI or API to customize them for particular needs, such as deploying to different environments or handling time-sensitive tasks that require human oversight.

<BlogWidget />