GitHub Actions workflow_dispatch event

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.

Understanding workflow_dispatch

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.

Configuring workflow_dispatch in your workflow

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:

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.

Defining inputs for workflow_dispatch

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.

Syntax for defining inputs

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

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.

Triggering a workflow with workflow_dispatch

Via GitHub UI

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.

Via GitHub API

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.

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.

Best practices and tips

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.