GitHub Actions is a powerful platform that allows developers to automate, customize, and enhance their workflows directly in the GitHub environment. One of the notable features of GitHub Actions is the ability to run workflows manually. This is achieved through a feature known as workflow_dispatch.

Understanding workflow_dispatch

The workflow_dispatch event is a special trigger that allows users to manually execute a workflow from the GitHub user interface. This feature is particularly useful for running tasks that do not require automatic execution, such as generating reports, running tests on demand, or deploying to specific environments after verification.

Configuring a Manual Trigger

To set up a manual workflow trigger, you need to define it in your repository's workflow YAML file. Below is a basic example:

1name: Manual Trigger Example
2
3on:
4  workflow_dispatch:
5
6jobs:
7  example_job:
8    runs-on: ubuntu-latest
9    steps:
10    - name: Check out repository
11      uses: actions/checkout@v2
12      
13    - name: Run a sample script
14      run: echo "This is a manual trigger example"

In this example, the on: workflow_dispatch section specifies that the workflow should only be triggered manually. There are no automatic triggers (like push or pull_request), meaning it won't run unless a user explicitly starts it from the GitHub interface.

Advanced Use of Inputs

One powerful aspect of workflow_dispatch is the support for inputs. These inputs allow users to specify parameters when they trigger a workflow. For example, you might let users choose a specific testing environment or branch.

1name: Deploy
2
3on:
4  workflow_dispatch:
5    inputs:
6      environment:
7        description: 'Deployment environment'
8        required: true
9        default: 'staging'
10
11jobs:
12  deploy:
13    runs-on: ubuntu-latest
14    steps:
15    - name: Check out repository
16      uses: actions/checkout@v2
17
18    - name: Deploy to environment
19      run: |
20        echo "Deploying to ${{ github.event.inputs.environment }}"

When a user triggers this workflow, they will be prompted to select or enter their desired environment, enhancing flexibility and control over how and where workflows run.

Workflow Dispatch via API

In addition to using the GitHub UI, workflows can also be triggered programmatically using the GitHub API, which is useful for integrating with external systems.

Below is an example of triggering a workflow using GitHub's REST API with curl:

1curl -X POST \
2-H "Accept: application/vnd.github.v3+json" \
3-H "Authorization: Bearer YOUR_GITHUB_TOKEN" \
4https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/dispatches \
5-d '{"ref":"main","inputs":{"environment":"production"}}'

Remember to replace YOUR_GITHUB_TOKEN, OWNER, REPO, and WORKFLOW_ID with appropriate values.

Best Practices for Manual Triggers

• Security: Use inputs to let users specify necessary parameters, but validate these inputs within your jobs. Be cautious with sensitive operations.
• Documentation: Document the purpose and usage of manually triggered workflows so your team knows when and how to use them.
• Conditional Execution: Use guards (if statements) in your jobs to prevent unnecessary steps based on the provided inputs.
• Access Control: Ensure that only authorized personnel can trigger sensitive workflows by using repository settings and permissions.

Summary Table

By taking full advantage of workflow_dispatch in GitHub Actions, development teams can create more flexible, controlled, and efficient CI/CD pipelines tailored to their specific workflow needs.