The automation landscape of continuous integration and continuous deployment (CI/CD) has evolved significantly, moving beyond simple event-driven reactions to code changes. Historically, workflows in GitHub Actions were primarily triggered by pushes, pull requests, or schedules. However, the introduction of the workflow_dispatch event fundamentally altered this paradigm by enabling users to manually trigger workflows directly from the GitHub interface. This capability addresses a critical operational need: the ability to execute specific tasks, such as performance audits or staged deployments, without generating unnecessary noise in the repository’s commit history or triggering redundant automated checks.
The Workflow Dispatch Event
The cornerstone of manual execution in GitHub Actions is the workflow_dispatch event. Introduced to give developers explicit control over when workflows run, this event creates a "Run workflow" button on the Actions tab of a repository. This interface element allows users to initiate a workflow run on demand, selecting the specific branch or tag on which the workflow should execute. This feature is particularly valuable for scenarios where automatic triggers are inappropriate or insufficient, such as running Lighthouse performance audits, executing database migrations in a staging environment, or triggering a manual review process before a production release.
By decoupling the trigger from code commits, teams can maintain a cleaner git history. Automated workflows that rely on push or pull_request events will run every time code is modified, which can lead to "cluttering up the commit history" with status checks and log outputs that may not be relevant to every single commit. With workflow_dispatch, developers can invoke expensive or time-consuming jobs only when necessary, ensuring that the primary feedback loop for code contributions remains efficient and unburdened by unrelated operational tasks.
Configuring Workflow Inputs
One of the most powerful aspects of workflow_dispatch is the ability to define inputs. These inputs allow the workflow to accept parameters at runtime, which are then presented as form elements in the GitHub UI. This transforms a static workflow file into a dynamic tool that can be customized for each execution. Inputs are defined using the same format as action inputs, supporting various data types and constraints.
To utilize inputs, developers specify them under the workflow_dispatch trigger in the workflow YAML file. Key attributes for each input include:
description: A string that explains the purpose of the input, displayed in the UI.required: A boolean indicating whether the input must be provided.default: A fallback value if the user does not provide one.
The following example demonstrates how to define inputs for a workflow that requires a log level and test scenario tags:
yaml
on:
workflow_dispatch:
inputs:
logLevel:
description: 'Log level'
required: true
default: 'warning'
tags:
description: 'Test scenario tags'
Once the workflow is triggered, these inputs become available within the github.event context. This allows subsequent steps in the workflow to access and utilize the provided values. For instance, a job can print these inputs to the logs or use them to configure environment variables for the execution environment.
yaml
jobs:
printInputs:
runs-on: ubuntu-latest
steps:
- run: |
echo "Log level: ${{ github.event.inputs.logLevel }}"
echo "Tags: ${{ github.event.inputs.tags }}"
This mechanism ensures that the workflow is not only manually triggered but also context-aware, allowing operators to tailor the execution parameters to the specific needs of the current run.
Advanced Manual Triggers with Community Actions
While the native workflow_dispatch event provides robust manual triggering capabilities, some use cases require more granular control, particularly in complex workflows with multiple interdependent jobs. In such scenarios, community-developed actions like benhamiltonpro/manual-trigger offer an additional layer of flexibility. These actions are not certified by GitHub but are released under the MIT License, allowing developers to integrate them into their workflows to implement sophisticated gatekeeping mechanisms.
The manual-trigger action works by introducing a "gate" job that waits for manual confirmation before proceeding. This is achieved by setting an output variable, such as CONTINUE_JOBS, which downstream jobs check to determine whether they should execute. This pattern is useful for implementing approval workflows where a human operator must explicitly authorize a deployment or build step before it continues.
The following configuration illustrates how to structure a workflow with manual gates for build and deploy stages:
```yaml
manual-trigger-build:
runs-on: ubuntu-latest
outputs:
CONTINUEJOBS: ${{ steps.manual-trigger.outputs.CONTINUEJOBS }}
steps:
- name: manual-trigger
id: manual-trigger
uses: benhamiltonpro/manual-trigger@v1
with:
RUN_NAME: "build"
build:
needs: manual-trigger-build
if: ${{ needs.manual-trigger-build.outputs.CONTINUE_JOBS == 'true' }}
runs-on: ubuntu-latest
steps:
- name: Runs plan
run: echo "It runs plan"
manual-trigger-deploy:
needs: build
runs-on: ubuntu-latest
outputs:
CONTINUEJOBS: ${{ steps.manual-trigger.outputs.CONTINUEJOBS }}
steps:
- name: manual-trigger
id: manual-trigger
uses: benhamiltonpro/manual-trigger@v1
with:
RUN_NAME: "deploy"
deploy:
needs: manual-trigger-deploy
if: ${{ needs.manual-trigger-deploy.outputs.CONTINUE_JOBS == 'true' }}
runs-on: ubuntu-latest
steps:
- name: Runs deploy
run: echo "It runs deploy"
```
In this setup, the manual-trigger-build job waits for manual input before the build job proceeds. Similarly, the manual-trigger-deploy job acts as a gate before the deploy job runs. The flowchart for this process can be visualized as:
mermaid
flowchart LR;
manual-trigger-build-->build-->manual-trigger-deploy-->deploy;
This approach allows teams to implement strict approval chains within their CI/CD pipelines, ensuring that critical operations are not executed without explicit human authorization. It complements the native workflow_dispatch event by providing a way to pause and resume workflows at specific points, rather than just triggering the entire workflow from scratch.
Conclusion
The introduction of manual triggers in GitHub Actions has significantly enhanced the flexibility and control available to development teams. Whether using the native workflow_dispatch event to run ad-hoc tasks without cluttering commit history or leveraging community actions to implement complex approval gates, the ability to manually orchestrate workflows is a vital component of modern CI/CD strategies. By understanding how to configure inputs and structure conditional jobs, developers can create robust, efficient, and safe automation pipelines that adapt to the specific needs of their projects. As GitHub Actions continues to evolve, these manual trigger mechanisms will remain essential for balancing automation with human oversight.