Orchestrating Manual and Programmatic Execution via GitHub workflow_dispatch

The introduction of the workflow_dispatch event marks a fundamental shift in how automation is handled within the GitHub Actions ecosystem. Traditionally, workflows were reactive, triggered by specific Git events such as a push or a pull_request. However, the workflow_dispatch event introduces a proactive mechanism, allowing users to manually initiate a workflow run. This capability transforms a static CI/CD pipeline into a dynamic toolset that can be invoked on demand. By integrating this event into a YAML configuration, developers gain the ability to trigger runs via the GitHub user interface (UI) through a "Run workflow" button located on the Actions tab. This manual trigger is not merely a binary switch; it provides a level of granularity that allows the operator to specify the exact Git branch the workflow should execute upon and provide custom input parameters.

The impact of this feature is significant for release management and testing. Instead of committing a "dummy" change to a branch just to trigger a pipeline, a developer can now fire a workflow with specific parameters, such as a target environment or a version tag, directly from the browser. This reduces noise in the Git history and provides a clean interface for non-technical stakeholders to trigger deployments or reports. Contextually, workflow_dispatch serves as the foundation for more complex automation patterns, including the chaining of workflows through third-party actions and the programmatic invocation of pipelines via the GitHub API. It bridges the gap between fully automated triggers and the need for human intervention or external orchestration.

The Mechanics of Manual Trigger Configuration

To implement a manual trigger, the workflow file must explicitly define the workflow_dispatch event under the on key. This tells GitHub to expose the workflow to the manual trigger interface.

yaml on: workflow_dispatch:

When this configuration is present, GitHub renders a "Run workflow" button on the Actions tab. This interface allows the user to select the branch and fill out any defined inputs.

Implementing Workflow Inputs

One of the most powerful aspects of workflow_dispatch is the ability to define inputs. These inputs are presented as form elements in the GitHub UI, allowing the user to pass data into the workflow at runtime. The format for defining these inputs is identical to the format used for action inputs.

The configuration requires a description to tell the user what the input is for, and optionally a required boolean and a default value.

For example:

yaml on: workflow_dispatch: inputs: logLevel: description: 'Log level' required: true default: 'warning' tags: description: 'Test scenario tags'

In this scenario, the logLevel input is mandatory and defaults to 'warning', while the tags input is optional. This allows the workflow to be flexible, adapting its behavior based on the user's specific needs for that particular run.

Accessing Inputs within the Workflow

Once a workflow is triggered via workflow_dispatch, the inputs are not accessed via the standard inputs context used in reusable workflows, but rather through the github.event.inputs context.

The following example demonstrates how to reference these inputs within a job:

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 data entered into the UI is passed directly to the runner, enabling dynamic execution paths based on user input.

Chaining Workflows via Third-Party Actions

While workflow_dispatch is primarily designed for human interaction, it can be leveraged programmatically to chain workflows together. This is achieved using third-party actions such as benc-uk/workflow-dispatch or the-actions-org/workflow-dispatch.

The primary use case for this architectural pattern is the separation of Continuous Integration (CI) and Continuous Deployment (CD). A CI workflow can be configured to run on every push to verify code quality; upon successful completion, it can programmatically trigger a separate CD workflow to handle the release or deployment process. This allows teams to maintain distinct workflows for different stages of the lifecycle while still maintaining a logical sequence of execution.

The Workflow Dispatch Action (benc-uk/workflow-dispatch)

The benc-uk/workflow-dispatch action simulates a manual trigger by calling the GitHub API to fire the workflow_dispatch event.

• Workflow Identification: The action requires the name, filename, or ID of the workflow to be triggered.
• Authentication: A Personal Access Token (PAT) is required.
• Repository Scope: By default, it triggers workflows in the same repository, but it can trigger workflows in external repositories by providing the repo parameter (e.g., microsoft/vscode).

Input Requirements and Constraints

When passing inputs through this action, they must be provided as a JSON encoded string.

yaml - name: Invoke workflow with inputs & wait uses: benc-uk/workflow-dispatch@v1 with: workflow: Another Workflow inputs: '{ "message": "blah blah", "something": true }' wait-for-completion: true

A critical technical constraint is that all values passed in the JSON string must be strings. Even if a value is intended to be a boolean or a number, it must be wrapped in quotes. To handle this on the receiving end, the triggered workflow should utilize the fromJson function to cast the input back to the appropriate data type.

The Workflow Dispatch and Wait Action (the-actions-org/workflow-dispatch)

This action is a fork of aurelien-baudet/workflow-dispatch and provides enhanced support for Node20 and improved management of the run-name option.

The run-name feature allows the triggering workflow to assign a specific name to the triggered run, which is essential for tracking and retrieving the run ID later.

Example implementation:

yaml - name: Invoke workflow and handle result id: trigger-step uses: the-actions-org/workflow-dispatch@v4 env: RUN_NAME: ${{ github.repository }}/actions/runs/${{ github.run_id }} with: run-name: ${{ env.RUN_NAME }} workflow: Another Workflow token: ${{ secrets.PERSONAL_TOKEN }} inputs: >- { "run-name": "${{ env.RUN_NAME }}" }

Technical Specifications and Configuration Parameters

The following table outlines the detailed parameters available when using the workflow dispatch actions to trigger other workflows.

Advanced Triggering Options

The ref parameter is particularly useful for Pull Request (PR) contexts. If a user wants to trigger a target workflow using the context of a PR branch, they should set the ref to:

{{ github.event.pull_request.head.ref }}

This ensures that the triggered workflow runs against the source code of the PR rather than the default branch of the repository.

Authentication and Security Constraints

A critical security limitation exists regarding the use of the default GITHUB_TOKEN. GitHub explicitly prevents the automatically provided ${{ secrets.GITHUB_TOKEN }} from being able to fire the workflow_dispatch or repository_dispatch events.

The reason for this restriction is to prevent the creation of infinite loops where a workflow triggers itself or another workflow, which in turn triggers the first, potentially exhausting GitHub's compute resources.

To circumvent this, users must:
1. Manually create a Personal Access Token (PAT) with the necessary write permissions for the repository.
2. Store this PAT as an encrypted secret in the repository (e.g., ${{ secrets.PERSONAL_TOKEN }}).
3. Pass this secret into the token input of the dispatch action.

For those referencing target workflows by ID, the ID can be retrieved using the GitHub REST API:

curl https://api.github.com/repos/{{owner}}/{{repo}}/actions/workflows -H "Authorization: token {{pat-token}}"

Wait-for-Completion and Status Synchronization

When chaining workflows, it is often necessary to know if the triggered workflow succeeded before proceeding. The wait-for-completion feature provides this synchronization.

• Polling Mechanism: The action will poll the GitHub API to determine the status of the triggered run.
• Timeout: The default timeout for waiting is 900 seconds (15 minutes).
• Status Sync: If the sync-status option is set to true (and wait-for-completion is also true), the triggering action will mirror the result of the triggered workflow. If the target workflow fails or is cancelled, the triggering action will also be marked as failed.

Output Data Retrieval

When wait-for-completion is enabled, the action provides several critical outputs that can be used in subsequent steps of the triggering workflow:

• runId: The unique ID of the workflow run that was triggered.
• runUrl: The API URL of the triggered workflow run.
• runUrlHtml: The browser-accessible HTML URL of the triggered run.
• workflowId: The ID of the specific workflow that was executed.

Comparison of Native vs. Programmatic Triggering

It is important to distinguish between the manual use of workflow_dispatch and the programmatic use of dispatch actions.

• UI Trigger: Triggered via the "Run workflow" button; appears as "manually triggered" in the UI.
• Action Trigger: Triggered via API calls from another workflow; also appears as "manually triggered" in the UI because the action is simulating a manual trigger.

While workflow_dispatch is powerful, GitHub has introduced "reusable workflows" as a native alternative for chaining. Reusable workflows are fundamentally different as they are called as jobs within a workflow rather than as independent workflow runs, providing a more integrated approach to modularity.

Conclusion: Analytical Overview of the Dispatch Ecosystem

The workflow_dispatch event transforms GitHub Actions from a simple event-driven system into a sophisticated orchestration platform. By allowing both human-initiated and programmatically-invoked runs, it provides the flexibility required for complex enterprise release cycles. The ability to pass JSON-encoded inputs and specify Git references ensures that the automation is not just triggered, but tailored to the specific context of the execution.

However, the dependency on Personal Access Tokens (PATs) due to the GITHUB_TOKEN restriction introduces a layer of administrative overhead and security consideration. The requirement for PATs is a deliberate architectural choice by GitHub to prevent recursive loop failures, but it forces developers to manage external secrets.

The evolution from basic manual triggers to the ability to "wait for completion" and synchronize status via third-party actions like benc-uk/workflow-disaptch and the-actions-org/workflow-dispatch fills a critical gap in the GitHub Actions lifecycle. This capability allows for the construction of multi-stage pipelines where the output of one workflow serves as the trigger for another, all while maintaining a clear audit trail through the GitHub UI. In summary, workflow_dispatch is the essential bridge between automated CI and human-governed CD.

Sources

1. GitHub Blog: Manual triggers with workflow_dispatch
2. GitHub Marketplace: workflow-dispatch
3. GitHub Marketplace: workflow-dispatch-and-wait