The management of continuous integration and deployment (CI/CD) pipelines requires robust mechanisms for resource optimization and error handling. A critical aspect of this management is the ability to cancel redundant or stuck workflow runs. Historically, developers relied on third-party actions to terminate previous runs when new commits were pushed to the same branch. However, the landscape of GitHub Actions has evolved significantly. The introduction of native concurrency controls has largely rendered custom cancellation actions obsolete for standard use cases, while new REST API endpoints address edge cases involving stuck workflows. This article examines the transition from third-party solutions to native features, detailing configuration strategies, permission requirements, and emergency protocols for complex workflow scenarios.
The Shift to Native Concurrency Controls
For years, the community standard for preventing duplicate workflow runs was the installation of third-party actions, such as styfle/cancel-workflow-action. These actions functioned by capturing the current branch and SHA (Secure Hash Algorithm) upon a git push event. They would then query the GitHub Workflow Runs API to identify previous runs that matched the branch but did not match the current SHA. Any runs with a status of queued or in_progress were subsequently canceled, ensuring that only the latest run proceeded.
GitHub has since deprecated the need for such custom implementations by introducing native concurrency properties. Developers are now strongly advised to use the concurrency configuration within their workflow files. This native approach is more efficient, requires no additional steps or dependencies, and is managed directly by the GitHub Actions runner infrastructure.
The core configuration involves two parameters: group and cancel-in-progress. The group defines a unique key for the concurrency group, typically combining the workflow name and the reference branch. The cancel-in-progress parameter determines whether pending or running workflows in the same group should be canceled.
yaml
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
In this example, the group ensures that pushes to the same branch are grouped together. The cancel-in-progress logic uses a conditional expression to cancel previous runs for all branches except main. This prevents accidental cancellation of critical production deployments while still allowing efficient cleanup of feature branch builds. For workflows triggered by pull requests, a similar logic applies, though the reference handling may differ slightly depending on the event type.
Legacy Third-Party Action Configuration
While native concurrency is the recommended standard, understanding the mechanics of legacy actions like styfle/cancel-workflow-action remains relevant for maintaining older repositories or handling specific edge cases not covered by native concurrency. This action requires specific permissions and configuration to function correctly.
The action operates by executing a job that queries the API for non-completed runs. To execute this, the action requires write access to the actions scope. It is considered a best practice to set repository permissions to read-only by default and elevate permissions only for specific jobs that require them.
yaml
jobs:
test:
runs-on: ubuntu-latest
permissions:
actions: write
steps:
- name: Cancel Previous Runs
uses: styfle/cancel-workflow-action
with:
access_token: ${{ github.token }}
In this configuration, the permissions block restricts the actions: write scope to the test job only. The access_token input passes the default github.token to the action, allowing it to authenticate with the API. Because this action must run to cancel other workflows, it is typically placed as the first step in the job. If the pipeline is saturated and no runners are available, the action cannot execute, rendering the cancellation attempt ineffective until a runner becomes free.
Advanced Cancellation Scenarios
Certain workflow events require specialized cancellation strategies that differ from standard push-based cancellation. For instance, workflows triggered by workflow_run events or those needing to cancel runs when a pull request is closed present unique challenges.
When dealing with workflow_run triggers, which can also be triggered by push events in certain configurations, a dedicated workflow file is often created to handle cancellation. This workflow listens for the requested event of a specific workflow, such as "CI", and then cancels the previous runs associated with that workflow ID.
yaml
name: Cancel
on:
workflow_run:
workflows: ["CI"]
types:
- requested
jobs:
cancel:
runs-on: ubuntu-latest
steps:
- uses: styfle/cancel-workflow-action
with:
workflow_id: ${{ github.event.workflow.id }}
Another common scenario is the cancellation of workflows when a pull request is closed. Since closing a PR does not change the SHA of the commit, the standard SHA-matching logic fails to identify the runs as "previous." In this case, the ignore_sha option is utilized to force cancellation regardless of the commit hash.
yaml
on:
pull_request:
types: [closed]
jobs:
cleanup:
name: 'Cleanup After PR Closed'
runs-on: ubuntu-latest
timeout-minutes: 3
steps:
- name: Cancel build runs
uses: styfle/cancel-workflow-action
with:
ignore_sha: true
workflow_id: 479426
Additionally, the all_but_latest flag can be used to cancel the current workflow and all subsequently scheduled workflows, leaving only the latest one running. This is useful for ensuring that no stray runs persist after a rapid series of pushes.
yaml
name: Cancel
on: [push]
jobs:
cancel:
name: 'Cancel Previous Runs'
runs-on: ubuntu-latest
timeout-minutes: 3
steps:
- uses: styfle/cancel-workflow-action
with:
all_but_latest: true
It is crucial to note that some workflows may be dangerous to cancel if they are in progress, particularly those performing stateful operations or deployments. Careful consideration of workflow logic is required before implementing automatic cancellation.
Handling Stuck Workflows with Force Cancel
Despite best practices, workflows can occasionally become stuck in a state where they do not respond to standard cancellation requests. This can block other workflows from executing and typically required contacting GitHub Support for resolution. To address this, GitHub introduced a force-cancel feature via the REST API.
This feature allows customers to bypass conditions that would otherwise prevent a workflow from being canceled. It is intended for use only when a workflow fails to respond to the standard POST /repos/{owner}/{repo}/actions/runs/{run_id}/cancel endpoint.
Because GitHub does not provide a user interface button for force-canceling, users must invoke this feature manually via the API. This process requires creating a Personal Access Token (PAT) and making a direct API call. This lack of a UI element suggests that GitHub intends this as a last-resort measure for debugging or incident resolution, rather than a routine operational tool.
bash
curl -X POST \
-H "Authorization: Bearer YOUR_PAT" \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/{owner}/{repo}/actions/runs/{run_id}/force-cancel
This capability ensures that administrators have a way to clear blocked pipelines without relying on external support, provided they have the necessary permissions and API access.
IDE Integration for Workflow Management
For developers using integrated development environments (IDEs) that support GitHub Actions, such as those with a dedicated GitHub Actions tool window, canceling workflows can be performed directly from the interface.
The process typically involves opening the GitHub Actions tab, selecting the specific workflow run from the left pane, and clicking the cancel button. Upon execution, the workflow run is canceled, and a notification balloon appears in the bottom right corner to confirm the status change. This method provides a quick, visual way to manage active runs without navigating to the GitHub website or using the command line.
Conclusion
The management of workflow cancellations in GitHub Actions has matured from a reliance on third-party scripts to a sophisticated suite of native features and emergency API endpoints. The native concurrency property offers a clean, efficient solution for most use cases, eliminating the need for additional action steps and reducing configuration complexity. However, for complex scenarios involving workflow_run triggers, pull request closures, or stuck workflows, understanding the underlying mechanics of legacy actions and the REST API remains essential. Developers must balance the efficiency of automatic cancellation with the safety of critical operations, ensuring that stateful tasks are not interrupted prematurely. As GitHub continues to evolve its Actions platform, the integration of these tools into IDEs and the availability of force-cancel mechanisms provide a comprehensive toolkit for robust CI/CD pipeline management.