Merge pull request #30058 from github/repo-sync

Repo sync

content/actions/deployment/about-deployments/deploying-with-github-actions.md

@@ -14,7 +14,7 @@ topics:
   - Deployment
 shortTitle: Deploy with GitHub Actions
 ---
- 
+
 {% data reusables.actions.enterprise-github-hosted-runners %}
 
 ## Introduction
@@ -60,7 +60,7 @@ For more information, see "[AUTOTITLE](/actions/using-workflows/events-that-trig
 
 ## Using concurrency
 
-Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. You can use concurrency so that an environment has a maximum of one deployment in progress and one deployment pending at a time.
+Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. 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 about concurrency, see "[AUTOTITLE](/actions/using-jobs/using-concurrency)."
 
 {% note %}
 

content/actions/using-jobs/using-concurrency.md

@@ -8,11 +8,19 @@ versions:
   ghae: '*'
   ghec: '*'
 ---
- 
+
 {% data reusables.actions.enterprise-github-hosted-runners %}
 
 ## Overview
 
+By default, {% data variables.product.prodname_actions %} allows multiple jobs within the same workflow, multiple workflow runs within the same repository, and multiple workflow runs across a repository owner's account to run concurrently. This means that multiple workflow runs, jobs, or steps can run at the same time.
+
+{% data variables.product.prodname_actions %} also allows you to control the concurrency of workflow runs, so that you can ensure that only one run, one job, or one step runs at a time in a specific context. This can be useful for controlling your account's or organization's resources in situations where running multiple workflows, jobs, or steps at the same time could cause conflicts or consume more Actions minutes and storage than expected.
+
+For example, the ability to run workflows concurrently means that if multiple commits are pushed to a repository in quick succession, each push could trigger a separate workflow run, and these runs will execute concurrently.
+
+## Using concurrency in different scenarios
+
 {% data reusables.actions.jobs.section-using-concurrency-jobs %}
 
 {% ifversion github-runner-dashboard %}

data/reusables/actions/actions-group-concurrency.md

@@ -9,19 +9,74 @@ When a concurrent job or workflow is queued, if another job or workflow using th
 
 {% endnote %}
 
-### Examples: Using concurrency and the default behavior
+### Example: Using concurrency and the default behavior
+
+The default behavior of {% data variables.product.prodname_actions %} is to allow multiple jobs or workflow runs to run concurrently. The `concurrency` keyword allows you to control the concurrency of workflow runs.
+
+For example, you can use the `concurrency` keyword immediately after where trigger conditions are defined to limit the concurrency of entire workflow runs for a specific branch:
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: {% raw %}${{ github.workflow }}-${{ github.ref }}{% endraw %}
+  cancel-in-progress: true
+```
+
+You can also limit the concurrency of jobs within a workflow by using the `concurrency` keyword at the job level:
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  job-1:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: example-group
+      cancel-in-progress: true
+```
+
+### Example: Concurrency groups
+
+Concurrency groups provide a way to manage and limit the execution of workflow runs or jobs that share the same concurrency key.
+
+The `concurrency` key is used to group workflows or jobs together into a concurrency group. When you define a `concurrency` key, {% data variables.product.prodname_actions %} ensures that only one workflow or job with that key runs at any given time. If a new workflow run or job starts with the same `concurrency` key, {% data variables.product.prodname_actions %} will cancel any workflow or job already running with that key. The `concurrency` key can be a hard-coded string, or it can be a dynamic expression that includes context variables.
+
+It is possible to define concurrency conditions in your workflow so that the workflow or job is part of a concurrency group.
+
+This means that when a workflow run or job starts, GitHub will cancel any workflow runs or jobs that are already in progress in the same concurrency group. This is useful in scenarios where you want to prevent parallel runs for a certain set of a workflows or jobs, such as the ones used for deployments to a staging environment, in order to prevent actions that could cause conflicts or consume more resources than necessary.
+
+In this example, `job-1` is part of a concurrency group named `staging_environment`. This means that if a new run of `job-1` is triggered, any runs of the same job in the `staging_environment` concurrency group that are already in progress will be cancelled.
 
 {% raw %}
 
 ```yaml
-concurrency: staging_environment
+jobs:
+  job-1:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: staging_environment
+      cancel-in-progress: true
 ```
 
 {% endraw %}
 
+Alternatively, using a dynamic expression such as `{% raw %}concurrency: ci-${{ github.ref }}{% endraw %}` in your workflow means that the workflow or job would be part of a concurrency group named `ci-` followed by the reference of the branch or tag that triggered the workflow. In this example, if a new commit is pushed to the main branch while a previous run is still in progress, the previous run will be cancelled and the new one will start:
+
 {% raw %}
 
 ```yaml
+on:
+  push:
+    branches:
+      - main
+
 concurrency: ci-${{ github.ref }}
 ```
 
@@ -29,6 +84,8 @@ concurrency: ci-${{ github.ref }}
 
 ### Example: Using concurrency to cancel any in-progress job or run
 
+To use concurrency to cancel any in-progress job or run in {% data variables.product.prodname_actions %}, you can use the `concurrency` key with the `cancel-in-progress` option set to `true`:
+
 {% raw %}
 
 ```yaml
@@ -39,6 +96,8 @@ concurrency:
 
 {% endraw %}
 
+Note that in this example, without defining a particular concurrency group, {% data variables.product.prodname_actions %} will cancel _any_ in-progress run of the job or workflow.
+
 ### Example: Using a fallback value
 
 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.