From c5c59f08c94e8f7d621d67a81f7dcfe736c49933 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Machist=C3=A9=20N=2E=20Quintana?= Date: Sun, 17 Oct 2021 14:23:22 -0400 Subject: [PATCH 1/4] Update docs on using concurrency to auto-cancel in-progress runs --- .../actions/actions-group-concurrency.md | 50 ++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/data/reusables/actions/actions-group-concurrency.md b/data/reusables/actions/actions-group-concurrency.md index 85aece27b2b8..75b4e6921cba 100644 --- a/data/reusables/actions/actions-group-concurrency.md +++ b/data/reusables/actions/actions-group-concurrency.md @@ -14,7 +14,7 @@ concurrency: ci-${{ github.ref }} ``` {% endraw %} -## Example: Using concurrency to cancel any in-progress job or run +## Example: Using concurrency to cancel any in-progress job or run on a pull request {% raw %} ```yaml @@ -23,3 +23,51 @@ concurrency: cancel-in-progress: true ``` {% endraw %} + +{% note %} + +**Note:** `github.head_ref` is only defined on `pull_request` events. If you have a workflow that responds to other events in addition to `pull_request` events, you will need to provide a fallback to avoid a syntax error. + +{% endnote %} + +### Example: With fallback + +To cancel in-progress jobs or runs on `pull_request` events only, but not on other events the workflow responds to: + +{% raw %} +```yaml +concurrency: + group: ${{ github.head_ref || github.run_id }} + cancel-in-progress: true +``` +{% endraw %} + +If `github.head_ref` is undefined, the concurrency group will fallback to the run ID, which is guaranteed to be both unique and defined for the run. + +### Only cancel in-progress jobs or runs for the current workflow + +{% note %} + +**Note:** If you have multiple workflows in the same repository, concurrency group names must be unique to avoid canceling in-progress jobs or runs from independent workflows. Otherwise, any previously in-progress or pending job will be canceled, regardless of the workflow that triggered it, leading to potentially confusing behavior if that wasn't your intent. + +{% endnote %} + +To only cancel in-progress runs on a per-workflow basis: + +{% raw %} +```yaml +concurrency: + group: ${{github.workflow}}-${{ github.head_ref }} + cancel-in-progress: true +``` +{% endraw %} + +With fallback: + +{% raw %} +```yaml +concurrency: + group: ${{github.workflow}}-${{ github.head_ref || github.run_id }} + cancel-in-progress: true +``` +{% endraw %} From 382d53fed17c745059f0745c7464a327a18413b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Machist=C3=A9=20N=2E=20Quintana?= Date: Mon, 1 Nov 2021 19:02:50 -0400 Subject: [PATCH 2/4] Fix spacing in examples --- data/reusables/actions/actions-group-concurrency.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data/reusables/actions/actions-group-concurrency.md b/data/reusables/actions/actions-group-concurrency.md index 75b4e6921cba..84af44397776 100644 --- a/data/reusables/actions/actions-group-concurrency.md +++ b/data/reusables/actions/actions-group-concurrency.md @@ -57,7 +57,7 @@ To only cancel in-progress runs on a per-workflow basis: {% raw %} ```yaml concurrency: - group: ${{github.workflow}}-${{ github.head_ref }} + group: ${{ github.workflow }}-${{ github.head_ref }} cancel-in-progress: true ``` {% endraw %} @@ -67,7 +67,7 @@ With fallback: {% raw %} ```yaml concurrency: - group: ${{github.workflow}}-${{ github.head_ref || github.run_id }} + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true ``` {% endraw %} From 68261cac546a3304166a8d10cdb14ba3e5dc5446 Mon Sep 17 00:00:00 2001 From: Sarah Edwards Date: Thu, 13 Jan 2022 11:01:57 -0800 Subject: [PATCH 3/4] Apply suggestions from code review --- .../actions/actions-group-concurrency.md | 32 ++++--------------- 1 file changed, 6 insertions(+), 26 deletions(-) diff --git a/data/reusables/actions/actions-group-concurrency.md b/data/reusables/actions/actions-group-concurrency.md index cfa10460c6ec..911325c7510d 100644 --- a/data/reusables/actions/actions-group-concurrency.md +++ b/data/reusables/actions/actions-group-concurrency.md @@ -14,7 +14,7 @@ concurrency: ci-${{ github.ref }} ``` {% endraw %} -## Example: Using concurrency to cancel any in-progress job or run on a pull request +## Example: Using concurrency to cancel any in-progress job or run {% raw %} ```yaml @@ -24,15 +24,9 @@ concurrency: ``` {% endraw %} -{% note %} +### Example: Using a fallback value -**Note:** `github.head_ref` is only defined on `pull_request` events. If you have a workflow that responds to other events in addition to `pull_request` events, you will need to provide a fallback to avoid a syntax error. - -{% endnote %} - -### Example: With fallback - -To cancel in-progress jobs or runs on `pull_request` events only, but not on other events the workflow responds to: +If you build the group name with a property that is only defined for specific events, you can use a fallback value. For example, `github.head_ref` is only defined on `pull_request` events. If your workflow responds to other events in addition to `pull_request` events, you will need to provide a fallback to avoid a syntax error. The following concurrency group cancels in-progress jobs or runs on `pull_request` events only; if `github.head_ref` is undefined, the concurrency group will fallback to the run ID, which is guaranteed to be both unique and defined for the run. {% raw %} ```yaml @@ -42,32 +36,18 @@ concurrency: ``` {% endraw %} -If `github.head_ref` is undefined, the concurrency group will fallback to the run ID, which is guaranteed to be both unique and defined for the run. ### Only cancel in-progress jobs or runs for the current workflow -{% note %} + If you have multiple workflows in the same repository, concurrency group names must be unique across workflows to avoid canceling in-progress jobs or runs from other workflows. Otherwise, any previously in-progress or pending job will be canceled, regardless of the workflow. -**Note:** If you have multiple workflows in the same repository, concurrency group names must be unique to avoid canceling in-progress jobs or runs from independent workflows. Otherwise, any previously in-progress or pending job will be canceled, regardless of the workflow that triggered it, leading to potentially confusing behavior if that wasn't your intent. - -{% endnote %} - -To only cancel in-progress runs on a per-workflow basis: +To only cancel in-progress runs of the same workflow, you can use the `github.workflow` property to build the concurrency group: {% raw %} ```yaml concurrency: - group: ${{ github.workflow }}-${{ github.head_ref }} + group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true ``` {% endraw %} -With fallback: - -{% raw %} -```yaml -concurrency: - group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} - cancel-in-progress: true -``` -{% endraw %} From a3d9c374509de90023fa32037928d9f99b6caa0e Mon Sep 17 00:00:00 2001 From: Sarah Edwards Date: Thu, 13 Jan 2022 11:33:11 -0800 Subject: [PATCH 4/4] Apply suggestions from code review --- 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 911325c7510d..7a666d419ffc 100644 --- a/data/reusables/actions/actions-group-concurrency.md +++ b/data/reusables/actions/actions-group-concurrency.md @@ -37,7 +37,7 @@ concurrency: {% endraw %} -### Only cancel in-progress jobs or runs for the current workflow +### Example: Only cancel in-progress jobs or runs for the current workflow If you have multiple workflows in the same repository, concurrency group names must be unique across workflows to avoid canceling in-progress jobs or runs from other workflows. Otherwise, any previously in-progress or pending job will be canceled, regardless of the workflow.