Orchestrating Manual Intervention in GitHub Actions via Workflow Dispatch and Third Party Approval Mechanisms

The automation of software delivery pipelines often reaches a critical juncture where purely programmatic triggers are insufficient. In professional DevOps environments, the transition from a staging environment to a production environment typically requires a "human-in-the-loop" verification process to ensure that all quality gates have been met and that the business is ready for the release. GitHub Actions provides two primary paradigms for achieving this: the native workflow_dispatch event for manual initiation and the use of specialized actions, such as manual-approval, for mid-workflow pauses. Understanding the nuances of these mechanisms is essential for maintaining the integrity of a Continuous Deployment (CD) pipeline while avoiding the costly overhead of high-tier enterprise licensing when only basic approval gates are required.

The Workflow Dispatch Event for Manual Triggers

The workflow_dispatch event is a native GitHub Actions trigger that allows users to manually start a workflow run. Unlike event-driven triggers such as push or pull_request, which are reactive, workflow_dispatch is proactive, placing the control of the execution in the hands of the operator.

When a workflow is configured with the workflow_dispatch trigger, a "Run workflow" button appears on the Actions tab of the GitHub user interface. This allows an authorized user to trigger the process without having to push a dummy commit or modify a file to spark a run.

One of the most powerful aspects of this trigger is the ability to select the specific branch on which the workflow should execute. This provides immense flexibility for testing different versions of a pipeline or deploying specific feature branches to a test environment without merging them into the default branch first.

Furthermore, workflow_dispatch supports the definition of custom inputs. These inputs act as form elements in the GitHub UI, allowing the operator to pass parameters into the workflow at runtime. This is particularly useful for specifying version numbers, target environments, or log levels.

The configuration for these inputs follows a specific syntax within the YAML file:

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

When the workflow is triggered, these inputs are captured and stored within the github.event context. To access and utilize these values within a job, the github.event.inputs object must be referenced.

For example, a job designed to print these inputs would be structured as follows:

yaml jobs: printInputs: runs-on: ubuntu-latest steps: - run: | echo "Log level: ${{ github.event.inputs.logLevel }}" echo "Tags: ${{ github.event.inputs.tags }}"

This capability transforms a static automation script into a dynamic tool that can be tailored to the specific needs of a release window by the person triggering the event.

Troubleshooting the Run Workflow Button Visibility

A recurring challenge for developers, particularly those working in private repositories or migrating existing workflows, is the disappearance or absence of the "Run workflow" button. This issue often manifests as a gap between the successful definition of the workflow_dispatch syntax and the actual visibility of the trigger in the UI.

Common scenarios include users adding the workflow_dispatch trigger to an existing workflow in a specific branch and finding that the button does not appear. Some users have attempted to resolve this by renaming the workflow file (e.g., to generate_license_activation.yaml) or merging it into the base branch, yet the workflow still fails to appear in the list of available actions.

The visibility of the "Run workflow" button is contingent upon several factors:

• The workflow file must be present on the default branch for the trigger to be recognized by the GitHub UI in the general "All workflows" view.
• If the workflow is on a non-default branch, the user must first select that specific workflow from the list to see the run options.
• Syntax errors in the YAML file can prevent the workflow from being registered, although GitHub does not always provide immediate, explicit feedback for these specific trigger failures.

In some cases, users have reported that the button does not appear even when the syntax is correct and the file is in the correct directory (.github/workflows/). This has been observed in both public and private repositories, leading to confusion regarding whether "secret sauce" or specific repository settings are required.

Implementing Manual Approval via Third Party Actions

While GitHub provides native environment-based approvals, this feature is restricted. For private repositories, native manual approvals require GitHub Enterprise. To circumvent this limitation and provide manual gating in private repositories without Enterprise licenses, third-party actions such as manual-approval are employed.

The manual-approval action allows a workflow to pause its execution and wait for an explicit "approved" or "denied" signal from designated users or teams before proceeding to the next step.

The operational logic of this action is centered around the creation of a GitHub Issue. When the workflow reaches the manual-approval step, the action automatically creates an issue in the repository and assigns it to the specified approvers. The workflow then enters a wait state.

The workflow will proceed only if the following conditions are met:

• All designated approvers respond to the issue with an approved keyword.
• The approved keywords are "approve", "approved", "lgtm", or "yes". These are case-insensitive and can be followed by optional punctuation, such as a period or an exclamation mark.

Conversely, the workflow will terminate with a failed status if:

• Any of the approvers respond with a denied keyword.
• The denied keywords are "deny", "denied", or "no". These are also case-insensitive and allow for optional punctuation.

Once a decision is reached (either approval or denial), the manual-approval action automatically closes the initial GitHub issue to maintain repository cleanliness.

Technical Configuration of the Manual Approval Action

To integrate the manual-approval action into a pipeline, it must be defined as a step within a job. This requires the provision of a GitHub token for authentication and a list of users or organization teams who are authorized to approve the action.

The implementation follows this structure:

yaml steps: - uses: trstringer/manual-approval@v1 with: secret: ${{ github.TOKEN }} approvers: user1,user2,org-team1 minimum-approvals: 1 issue-title: "Deploying v1.3.5 to prod from staging" issue-body: "Please approve or deny the deployment of version"

Since version 1.10.0, the handling of issue content has been updated to improve clarity and flexibility:

• The issue-title input is now used exactly as provided, without any predefined strings being appended or wrapped around it.
• The issue-body and issue-body-file-path inputs are no longer used to set the primary description of the issue. Instead, they are added as comments to the issue after it has been created.

This change ensures that the main issue body remains concise while providing detailed context via comments.

Infrastructure Compatibility and Constraints

The manual-approval action is not a universal binary; it is designed for specific environments. Compatibility is strictly limited to Linux-based runners.

The following runner architectures are supported:

• Linux/amd64: Standard 64-bit Intel or AMD (x86_64) systems.
• Linux/arm64: 64-bit ARM systems, such as those used by Apple M1.
• Linux/arm/v8: 64-bit ARM architecture.

The action is explicitly unsupported on the following:

• Windows/amd64: 64-bit Windows systems are currently not compatible.
• Any non-Linux runner regardless of architecture.

Users must also be aware of the temporal constraints associated with pausing a workflow. The approval duration is subject to the global GitHub Actions timeout, which is 35 days. If the approvers do not respond within this window, the workflow will time out and fail. Additionally, the usage costs for the runner may apply during the wait period, depending on how the action manages the polling or waiting mechanism.

Development and Testing Cycle for Approval Actions

For developers creating or modifying the manual-approval action, a rigorous build and test cycle is required to ensure stability before releasing new versions. This involves the use of container registries and specific tagging strategies.

To test a new version of the action, the following process is utilized:

1. Build and push the image to a container registry:
   bash VERSION=1.7.1-rc.1 make IMAGE_REPO=ghcr.io/trstringer/manual-approval-test push

2. Modify the action.yaml file to point to the test image:
   yaml image: docker://ghcr.io/trstringer/manual-approval-test:1.7.0-rc.1

3. Execute a test workflow specifying the development branch:
   ```yaml

• name: Wait for approval
  uses: your-github-user/manual-approval@your-dev-branch
  with:
  secret: ${{ secrets.GITHUB_TOKEN }}
  approvers: trstringer
  ```

Once the testing phase is complete, the release process involves creating a release branch, merging the changes into the default branch, and updating the version tags. The local and remote tag management process is as follows:

bash git checkout main && git fetch origin && git merge origin main git tag -d v1 && git push --delete origin v1 git tag v1.7.0 && git tag v1 && git push origin --tags

This ensures that the v1 tag always points to the latest stable release of the action.

Comparison of Manual Intervention Methods

The following table provides a technical comparison between the native workflow_dispatch trigger and the manual-approval action.

Conclusion: Strategic Analysis of Manual Gating

The integration of manual approval mechanisms into GitHub Actions represents a critical balance between velocity and safety. While the industry trend leans toward "Continuous Deployment," the reality of regulatory compliance and business risk often necessitates "Continuous Delivery," where the final push to production is a conscious human decision.

The workflow_dispatch event is the ideal tool for administrative tasks, such as triggering a manual backup or deploying a specific hotfix branch. However, its utility is limited to the start of the pipeline. For complex pipelines where a workflow must pass through multiple automated tests and then wait for a sign-off, the manual-approval action fills a critical gap for those not utilizing GitHub Enterprise.

The reliance on GitHub Issues for approval is a clever utilization of the platform's existing social coding features to create a makeshift state machine. By leveraging issue assignments and keyword monitoring, the action creates an audit trail of who approved a release and when. This auditability is essential for SOC2 or ISO compliance, providing a documented history of manual intervention.

However, users must be cautious regarding the 35-day timeout and the lack of Windows support. The transition from version 1.10.0's handling of issue bodies to comments indicates a move toward more structured data handling, preventing the pollution of the main issue description and allowing for a cleaner conversation thread. Ultimately, the choice between these tools depends on whether the manual intervention is required at the inception of the workflow or as a quality gate within the execution flow.

Sources

1. Manual Workflow Approval GitHub Marketplace
2. GitHub Blog: Manual triggers with workflow_dispatch
3. GitHub Community Discussion 25756
4. GitHub Community Discussion 58022