Implementing manual approval gates within continuous integration and continuous delivery (CI/CD) pipelines is a critical requirement for maintaining security and stability in software deployment processes. While the need for human verification before code reaches production environments is universal, the mechanisms for achieving this in GitHub Actions have evolved significantly. Historically, developers faced a dichotomy: utilize native GitHub features that required paid Enterprise licenses or rely on complex community-built workarounds. The modern landscape presents two distinct paths: the native environment protection rules, which offer robust, integrated approval workflows for public and enterprise repositories, and community-driven actions that simulate approval gates for private repositories without enterprise overhead. Understanding the technical nuances, limitations, and implementation strategies of both approaches is essential for engineers seeking to balance automation with necessary human oversight.
The Native Approach: Environment Protection and Fork Safety
The most straightforward method for implementing approval workflows in GitHub Actions is through the native "Environments" feature combined with protection rules. This approach integrates directly into the GitHub interface, providing a seamless experience for maintainers and contributors alike. The primary driver for this feature is often security, particularly when dealing with pull requests from external forks. Workflow runs triggered by a contributor's pull request from a fork may require manual approval from a maintainer with write access before any code execution begins. This safeguard prevents malicious actors from injecting harmful code into workflow files within the .github/workflows/ directory, which could potentially exfiltrate secrets or compromise the repository infrastructure.
Configuration of these approval requirements can be applied at three distinct hierarchical levels: the repository, the organization, or the entire enterprise. This granularity allows administrators to enforce strict security policies on sensitive projects while permitting more relaxed automation for internal development branches. The process for a maintainer to review and approve a pending workflow is structured and deliberate. Upon navigating to the Pull Requests tab, the maintainer selects the specific pull request requiring review and proceeds to the "Files changed" section. A critical step in this process is the inspection of proposed changes, with heightened alertness directed toward modifications in the .github/workflows/ directory. Once the maintainer is satisfied that the workflow changes are benign, they interact with the "Awaiting approval" button located in the upper right corner, which opens the Merge status panel. From there, the specific action to "Approve workflows to run" executes the pending jobs.
It is important to note the lifecycle management of these pending workflows. Workflow runs that remain in an awaiting approval state for more than 30 days are automatically deleted by the system. This timeout mechanism prevents stale workflows from cluttering the action history and ensures that outdated code does not accidentally execute after a long period of neglect. For organizations utilizing Azure App Service or similar cloud infrastructure, integrating this approval flow allows for a controlled deployment pipeline where the final push to production is contingent upon this explicit maintainer approval, mirroring the approval flow features traditionally found in tools like Azure Pipelines.
Community Workarounds: The Manual Approval Action
For organizations that do not have access to GitHub Enterprise or prefer to manage approval logic within the workflow syntax itself, community actions provide a viable alternative. The trstringer/manual-approval action is a prominent example of this approach. Unlike the native environment feature, this action pauses the workflow and requires manual approval from designated approvers without the mandatory use of GitHub Environments. This makes it freely available for use on private repositories that may not have enterprise-level permissions configured.
The mechanism of this action relies on GitHub Issues and comment-based interactions. When the workflow reaches the manual-approval step, the action creates an issue in the containing repository and assigns it to the specified list of approvers. The workflow then enters a suspended state, waiting for user interaction. The resolution of this wait state is determined by specific keywords typed into the issue comments. If all designated approvers respond with an approved keyword, the workflow resumes execution. Conversely, if any approver responds with a denied keyword, the workflow exits immediately with a failed status. This binary logic ensures that the deployment process is either fully authorized or explicitly rejected, with no ambiguity.
The keywords for approval and denial are standardized and case-insensitive, with optional punctuation such as periods or exclamation marks. Approved keywords include "approve", "approved", "lgtm", and "yes". Denied keywords include "deny", "denied", and "no". Once the approval condition is met or the workflow is denied, the action automatically closes the initial GitHub issue, keeping the repository tidy. This approach offers a high degree of control over the approval process, allowing teams to define exactly who must approve a deployment and how many approvals are required.
Configuration and Technical Constraints
Configuring the manual-approval action requires careful attention to input parameters and system compatibility. The action is compatible with specific runner architectures, primarily Linux-based systems. Supported runners include Linux/amd64 for 64-bit Intel/AMD (x86_64) processors, Linux/arm64 for 64-bit ARM (such as Apple M1), and Linux/arm/v8 for 64-bit ARM architectures. However, Windows/amd64 runners and non-Linux runners of any architecture are currently unsupported. This limitation restricts the use of this specific action in Windows-based CI/CD pipelines, requiring teams to either use Linux runners for approval steps or adopt alternative solutions for Windows environments.
Recent updates to the action have altered how issue content is handled. Starting from version 1.10.0, the behavior for issue contents changed significantly. The issue-body and issue-body-file-path inputs are now added as comments on the issue rather than being set as the main description or body. Additionally, the issue title is now exactly what is provided as input, rather than being appended to or wrapped in a predefined string. This change allows for more precise control over the context presented to approvers.
The configuration snippet below demonstrates the standard implementation of this action:
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 1.3.5"
In this configuration, the secret parameter utilizes the GitHub token to authenticate the action, ensuring that only authorized entities can create and close issues. The approvers field accepts a comma-separated list of users or organization teams. The minimum-approvals parameter defines the threshold for continuation; in this case, only one approval is required from the list of approvers. This flexibility allows teams to implement varying levels of scrutiny depending on the criticality of the deployment.
Operational Considerations and Notifications
While the technical implementation of approval workflows is robust, the operational reality involves human factors and system timeouts. A critical constraint of the manual-approval action is that it is subject to the broader 35-day timeout for a GitHub Actions workflow. This means that if an approver does not respond within 35 days, the workflow will eventually timeout and fail, regardless of the approval status. Teams must consider this limitation when designing their approval processes, ensuring that approvers are available and responsive within this timeframe. Additionally, usage costs associated with the runner time should be considered, as the workflow remains active and consumes resources while waiting for approval.
To mitigate the risk of delayed approvals, integrating notification systems is highly recommended. GitHub's native environment approval process notifies reviewers through standard GitHub notification channels, such as email. For custom actions, teams can implement external notifications to ensure approvers are aware of pending requests. One effective method involves using webhooks to send messages to communication platforms like Google Chat. The following code snippet illustrates how to notify a team via Google Chat when a deployment approval is requested:
yaml
notification:
runs-on: ubuntu-latest
steps:
- name: Notify on Google Chat
run: |
GOOGLE_CHAT_ROOM="xYO8qAAAAE"
MESSAGE="Deployment approval request. Click [here](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}) to approve."
curl -X POST -H 'Content-Type: application/json' \
-d '{ "text": "'"$MESSAGE"'" }' "${{ secrets.PROAPPROVAL }}"
This step sends a POST request to a configured webhook, containing a direct link to the GitHub Actions run. This ensures that the approver can click through and approve the workflow step directly from their chat interface, reducing the friction of navigating to the repository. Similarly, notifications can be sent after the deployment is complete to confirm success or failure, providing a closed-loop communication channel.
Conclusion
The evolution of approval workflows in GitHub Actions reflects the growing complexity of modern CI/CD pipelines. The native environment protection rules provide a secure, integrated solution for fork-based pull requests and enterprise environments, offering a user-friendly interface for maintainers to review and approve changes. However, for teams operating in private repositories without enterprise licenses, community actions like trstringer/manual-approval offer a powerful alternative. These actions leverage GitHub Issues to create robust approval gates, complete with keyword-based resolution and configurable approver lists.
Despite the availability of these tools, engineers must carefully consider the technical constraints, such as runner compatibility and workflow timeouts. The shift towards Linux-only support for certain community actions and the 35-day timeout limit necessitate thoughtful planning in workflow design. Furthermore, the integration of external notifications ensures that human approvers are effectively engaged, bridging the gap between automated systems and human oversight. As GitHub Actions continues to mature, the distinction between native and community solutions may blur, but for now, understanding the strengths and limitations of both approaches is essential for building secure, efficient, and reliable deployment pipelines.