From f6bd7d6da10c23d4c92b5cddb39082b8515bd030 Mon Sep 17 00:00:00 2001 From: Rob Vesse Date: Wed, 13 Dec 2023 09:48:53 +0000 Subject: [PATCH 1/3] Clarify concurrency cancel-in-progress behaviour The section on GitHub Actions concurrency did not cover whether cancel-in-progress could use an expression and several discussions exists expressing confusion around this. This commit aims to clarify this part of the documentation and include an explicit example of using an expression for cancel-in-progress. It also adds clarifying language so that it is clear that even when cancel-in-progress is, or evaluates to, false, that there can still only be at most 1 running and 1 pending job in any given concurrency group. --- .../actions/actions-group-concurrency.md | 22 ++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/data/reusables/actions/actions-group-concurrency.md b/data/reusables/actions/actions-group-concurrency.md index 793f49b8abee..d258a307cefe 100644 --- a/data/reusables/actions/actions-group-concurrency.md +++ b/data/reusables/actions/actions-group-concurrency.md @@ -1,4 +1,6 @@ -When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be `pending`. Any previously pending job or workflow in the concurrency group will be canceled. To also cancel any currently running job or workflow in the same concurrency group, specify `cancel-in-progress: true`. +When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be `pending`. Any previously pending job or workflow in the concurrency group will be canceled. This means that there can be at most 1 running and 1 pending job in a concurrency group at any one time. + +To also cancel any currently running job or workflow in the same concurrency group, specify `cancel-in-progress: true`. You may also specify `cancel-in-progress` as an expression subject to the restrictions on available contexts outlined above. {% note %} @@ -129,3 +131,21 @@ concurrency: ``` {% endraw %} + +### Example: Only cancel in-progress jobs on specific branches + + In some scenarios it may be desireable to cancel in-progress jobs on certain branches but not others e.g. development versus release branches. You can use conditional expressions with `cancel-in-progress` to achieve this. + +To only cancel in-progress runs of the same workflow when not running on a release branch you could do the following: + +{% raw %} + +```yaml +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ !contains(github.ref, 'release/')}} +``` + +{% endraw %} + +So multiple pushes to a `release/1.2.3` branch would not cancel in-progress runs, whereas pushes to another branch e.g. `main` would cancel in-progress runs. From f921a9266519aed07c6a83333b8daf0d6b3be1a4 Mon Sep 17 00:00:00 2001 From: Siara <108543037+SiaraMist@users.noreply.github.com> Date: Tue, 27 Feb 2024 13:00:25 -0800 Subject: [PATCH 2/3] Apply suggestions from code review --- data/reusables/actions/actions-group-concurrency.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/data/reusables/actions/actions-group-concurrency.md b/data/reusables/actions/actions-group-concurrency.md index eb99b20a3370..ab547ec0ba92 100644 --- a/data/reusables/actions/actions-group-concurrency.md +++ b/data/reusables/actions/actions-group-concurrency.md @@ -1,6 +1,6 @@ -When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be `pending`. Any pending job or workflow in the concurrency group will be canceled. This means that there can be at most 1 running and 1 pending job in a concurrency group at any one time. +When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be `pending`. Any pending job or workflow in the concurrency group will be canceled. This means that there can be at most one running and one pending job in a concurrency group at any time. -To also cancel any currently running job or workflow in the same concurrency group, specify `cancel-in-progress: true`. You may also specify `cancel-in-progress` as an expression subject to the restrictions on available contexts outlined above. +To also cancel any currently running job or workflow in the same concurrency group, specify `cancel-in-progress: true`. To conditionally cancel currently running jobs or workflows in the same concurrency group, you can specify `cancel-in-progress` as an expression if you use any of the following allowed expression contexts: [`github`](/actions/learn-github-actions/contexts#github-context), [`inputs`](/actions/learn-github-actions/contexts#inputs-context), [`vars`](/actions/learn-github-actions/contexts#vars-context), [`needs`](/actions/learn-github-actions/contexts#needs-context), [`strategy`](/actions/learn-github-actions/contexts#strategy-context), and [`matrix`](/actions/learn-github-actions/contexts#matrix-context). {% note %} @@ -134,9 +134,9 @@ concurrency: ### Example: Only cancel in-progress jobs on specific branches - In some scenarios it may be desireable to cancel in-progress jobs on certain branches but not others e.g. development versus release branches. You can use conditional expressions with `cancel-in-progress` to achieve this. +If you would like to cancel in-progress jobs on certain branches but not on others, you can use conditional expressions with `cancel-in-progress`. For example, you can do this if you would like to cancel in-progress jobs on development branches but not on release branches. -To only cancel in-progress runs of the same workflow when not running on a release branch you could do the following: +To only cancel in-progress runs of the same workflow when not running on a release branch, you can set `cancel-in-progress` to an expression similar to the following: {% raw %} @@ -148,4 +148,4 @@ concurrency: {% endraw %} -So multiple pushes to a `release/1.2.3` branch would not cancel in-progress runs, whereas pushes to another branch e.g. `main` would cancel in-progress runs. +In this example, multiple pushes to a `release/1.2.3` branch would not cancel in-progress runs. Pushes to another branch, such as `main`, would cancel in-progress runs. From b51eee911494e867e488124443a336f3c721feb7 Mon Sep 17 00:00:00 2001 From: Siara <108543037+SiaraMist@users.noreply.github.com> Date: Tue, 27 Feb 2024 13:23:50 -0800 Subject: [PATCH 3/3] Update data/reusables/actions/actions-group-concurrency.md --- data/reusables/actions/actions-group-concurrency.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/reusables/actions/actions-group-concurrency.md b/data/reusables/actions/actions-group-concurrency.md index ab547ec0ba92..c494cae99ff6 100644 --- a/data/reusables/actions/actions-group-concurrency.md +++ b/data/reusables/actions/actions-group-concurrency.md @@ -1,6 +1,6 @@ When a concurrent job or workflow is queued, if another job or workflow using the same concurrency group in the repository is in progress, the queued job or workflow will be `pending`. Any pending job or workflow in the concurrency group will be canceled. This means that there can be at most one running and one pending job in a concurrency group at any time. -To also cancel any currently running job or workflow in the same concurrency group, specify `cancel-in-progress: true`. To conditionally cancel currently running jobs or workflows in the same concurrency group, you can specify `cancel-in-progress` as an expression if you use any of the following allowed expression contexts: [`github`](/actions/learn-github-actions/contexts#github-context), [`inputs`](/actions/learn-github-actions/contexts#inputs-context), [`vars`](/actions/learn-github-actions/contexts#vars-context), [`needs`](/actions/learn-github-actions/contexts#needs-context), [`strategy`](/actions/learn-github-actions/contexts#strategy-context), and [`matrix`](/actions/learn-github-actions/contexts#matrix-context). +To also cancel any currently running job or workflow in the same concurrency group, specify `cancel-in-progress: true`. To conditionally cancel currently running jobs or workflows in the same concurrency group, you can specify `cancel-in-progress` as an expression with any of the allowed expression contexts. {% note %}