GitHub Actions workflow_dispatch event

Kenny DuMez
Kenny DuMez
Graphite software engineer

GitHub Actions provides a platform to automate software workflows directly within your GitHub repository. One of the key features of GitHub Actions is the workflow_dispatch event, which allows you to manually trigger workflows from the GitHub UI or via the GitHub API. This guide will explore how to configure and use the workflow_dispatch event, including how to define inputs for more dynamic workflows.

The workflow_dispatch event is specifically designed for situations where you want to control when a workflow runs, rather than having it trigger automatically on code changes or pull request activities. This is particularly useful for workflows that perform manual tasks such as deploying software to production, database migrations, or any process that requires manual oversight.

To utilize the workflow_dispatch event, you need to add it to your workflow file in the .github/workflows directory of your repository. Here is a basic example to get started:

Terminal
name: Manual Workflow
on:
workflow_dispatch:
jobs:
example_job:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Run a script
run: echo "This is a manually triggered workflow."

In this example, the workflow is named "Manual Workflow" and will only be triggered manually through the GitHub UI or API.

One of the powerful features of workflow_dispatch is the ability to define inputs, which allow you to manually pass parameters to the workflow when it is triggered. This makes your workflows more flexible and adaptable.

Inputs are defined under the workflow_dispatch key. Here’s how you can define and use them:

Terminal
name: Deploy Workflow
on:
workflow_dispatch:
inputs:
environment:
description: 'Environment to deploy to'
required: true
default: 'staging'
version:
description: 'Application version'
required: true
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Deploy
run: |
echo "Deploying version ${{ github.event.inputs.version }} to ${{ github.event.inputs.environment }}"

In this configuration, there are two inputs: environment and version. Each input can have a description, a required flag, and a default value.

To trigger a workflow_dispatch event through the GitHub UI:

  1. Navigate to the Actions tab of your repository.
  2. Select the workflow you want to run.
  3. Click on the "Run workflow" dropdown.
  4. Fill in the required inputs (if any) and click "Run workflow".

This manual triggering allows you to input parameters like the environment and version directly through the GitHub interface.

You can also trigger a workflow using the GitHub API, which is useful for integrating with external systems like Cloud services that execute actions based on events, such as deploying resources or reacting to monitoring alerts.

Terminal
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token YOUR_GITHUB_TOKEN" \
https://api.github.com/repos/username/repo-name/actions/workflows/workflow_id/dispatches \
-d '{"ref":"main","inputs":{"environment":"prod","version":"1.2.3"}}'

Replace YOUR_GITHUB_TOKEN, username, repo-name, workflow_id, and the input values appropriately.

  1. Use descriptive names for inputs: This makes it easier for others to understand what values are expected.
  2. Secure sensitive information: If your workflows use sensitive data, make sure to use secrets and encrypt data where necessary.
  3. Validate inputs: Always validate inputs inside your workflows to prevent unexpected errors or misuse.

The workflow_dispatch event adds a layer of flexibility and control to your GitHub workflows, enabling manual triggers with custom inputs. Whether integrating with external systems or managing deployments directly from GitHub, workflow_dispatch provides the tools necessary for robust workflow management.

For more information on the workflow_dispatch event see the official GitHub documentation.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2