From 231635f906a58d833dde6581f08fa9d56d0705c8 Mon Sep 17 00:00:00 2001 From: Sarah Edwards Date: Mon, 19 Apr 2021 06:49:59 -0700 Subject: [PATCH] Revert "Revert "[April 13] serialization feature doc"" (#18742) --- content/actions/reference/environments.md | 3 ++ .../workflow-syntax-for-github-actions.md | 34 ++++++++++++++++++- .../actions/actions-group-concurrency.md | 25 ++++++++++++++ data/reusables/actions/concurrency-beta.md | 5 +++ 4 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 data/reusables/actions/actions-group-concurrency.md create mode 100644 data/reusables/actions/concurrency-beta.md diff --git a/content/actions/reference/environments.md b/content/actions/reference/environments.md index 779a70ad24a1..aa3570397f44 100644 --- a/content/actions/reference/environments.md +++ b/content/actions/reference/environments.md @@ -71,6 +71,9 @@ For more information on syntax to reference environments in workflows, see "[Wor When a workflow references an environment, the environment will appear in the repository's deployments. For more information about viewing current and previous deployments, see "[Viewing deployment history](/developers/overview/viewing-deployment-history)." +### Using concurrency to serialize deployments in an environment +You can use concurrency so that an environment has a maximum of one deployment in progress and one deployment pending at a time. For more information, see "[Workflow syntax for GitHub Actions](/actions/reference/workflow-syntax-for-github-actions#concurrency)." + ### Deleting an environment {% data reusables.github-actions.permissions-statement-environment %} diff --git a/content/actions/reference/workflow-syntax-for-github-actions.md b/content/actions/reference/workflow-syntax-for-github-actions.md index 9e2de6816c46..db1e7f8bdf3a 100644 --- a/content/actions/reference/workflow-syntax-for-github-actions.md +++ b/content/actions/reference/workflow-syntax-for-github-actions.md @@ -221,6 +221,18 @@ defaults: working-directory: scripts ``` +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" or currentVersion == "github-ae@next" %} +### `concurrency` + +{% data reusables.actions.concurrency-beta %} + +Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can only use the `github` context. For more information about expressions, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)." + +You can also specify `concurrency` at the job level. For more information, see [`jobs..concurrency`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#jobsjob_idconcurrency). + +{% data reusables.actions.actions-group-concurrency %} + +{% endif %} ### `jobs` A workflow run is made up of one or more jobs. Jobs run in parallel by default. To run jobs sequentially, you can define dependencies on other jobs using the `jobs..needs` keyword. @@ -347,10 +359,11 @@ The environment that the job references. All environment protection rules must p You can provide the environment as only the environment `name`, or as an environment object with the `name` and `url`. The URL maps to `environment_url` in the deployments API. For more information about the deployments API, see "[Deployments](/rest/reference/repos#deployments)." ##### Example using a single environment name - +{% raw %} ```yaml environment: staging_environment ``` +{% endraw %} ##### Example using environment name and URL @@ -372,6 +385,25 @@ environment: {% endraw %} {% endif %} + +{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" or currentVersion == "github-ae@next" %} +### `jobs..concurrency` + +{% data reusables.actions.concurrency-beta %} + +{% note %} + +**Note:** When concurrency is specified at the job level, order is not guaranteed for jobs or runs that queue within 5 minutes of each other. + +{% endnote %} + +Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the `secrets` context. For more information about expressions, see "[Context and expression syntax for {% data variables.product.prodname_actions %}](/actions/reference/context-and-expression-syntax-for-github-actions)." + +You can also specify `concurrency` at the workflow level. For more information, see [`concurrency`](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#concurrency). + +{% data reusables.actions.actions-group-concurrency %} + +{% endif %} ### `jobs..outputs` A `map` of outputs for a job. Job outputs are available to all downstream jobs that depend on this job. For more information on defining job dependencies, see [`jobs..needs`](#jobsjob_idneeds). diff --git a/data/reusables/actions/actions-group-concurrency.md b/data/reusables/actions/actions-group-concurrency.md new file mode 100644 index 000000000000..493e81cb45d6 --- /dev/null +++ b/data/reusables/actions/actions-group-concurrency.md @@ -0,0 +1,25 @@ +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`. + +##### Examples using concurrency and the default behavior + +{% raw %} +```yaml +concurrency: staging_environment +``` +{% endraw %} + +{% raw %} +```yaml +concurrency: ci-${{ github.ref }} +``` +{% endraw %} + +##### Example using concurrency to cancel any in-progress job or run + +{% raw %} +```yaml +concurrency: + group: ${{ github.head_ref }} + cancel-in-progress: true +``` +{% endraw %} diff --git a/data/reusables/actions/concurrency-beta.md b/data/reusables/actions/concurrency-beta.md new file mode 100644 index 000000000000..c3f2c9a831f1 --- /dev/null +++ b/data/reusables/actions/concurrency-beta.md @@ -0,0 +1,5 @@ +{% note %} + +**Note:** Concurrency is currently in beta and subject to change. + +{% endnote %} \ No newline at end of file