Update docs for concurrency group queueing and APIs (#60953)

Co-authored-by: sunbrye <sunbrye@github.com>
Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Sunbrye Ly <56200261+sunbrye@users.noreply.github.com>

Author: 3 people

content/actions/concepts/workflows-and-actions/concurrency.md

@@ -14,4 +14,10 @@ By default, {% data variables.product.prodname_actions %} allows multiple jobs w
 
 {% data variables.product.prodname_actions %} also allows you to disable concurrent execution. This can be useful for controlling your account’s or organization’s resources in situations where running multiple workflows or jobs at the same time could cause conflicts or consume more Actions minutes and storage than expected. For example, you might want to prevent multiple deployments from running at the same time, or cancel linters checking outdated commits.
 
+{% ifversion actions-nga %}
+
+When you limit concurrency, by default only one run can be pending in a concurrency group—any additional pending runs cancel the previous one. If you need runs to execute sequentially without being canceled, you can opt in to queuing, which allows multiple runs to wait in line and execute in order.
+
+{% endif %}
+
 To start controlling concurrency in your own workflows with the `concurrency` keyword, see [AUTOTITLE](/actions/how-tos/writing-workflows/choosing-when-your-workflow-runs/control-the-concurrency-of-workflows-and-jobs).

content/actions/get-started/continuous-deployment.md

@@ -32,7 +32,7 @@ You can set up a {% data variables.product.prodname_actions %} workflow to deplo
 
 You can configure your CD workflow to run when an event occurs (for example, when new code is pushed to the default branch of your repository), on a set schedule, manually, or when an external event occurs using the repository dispatch webhook. For more information about when your workflow can run, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows).
 
-{% data variables.product.prodname_actions %} provides features that give you more control over deployments. For example, you can use environments to require approval for a job to proceed, restrict which branches can trigger a workflow, or limit access to secrets. You can use concurrency to limit your CD pipeline to a maximum of one in-progress deployment and one pending deployment. For more information about these features, see [AUTOTITLE](/actions/deployment/about-deployments/deploying-with-github-actions) and [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment).
+{% data variables.product.prodname_actions %} provides features that give you more control over deployments. For example, you can use environments to require approval for a job to proceed, restrict which branches can trigger a workflow, or limit access to secrets. You can use concurrency to limit your CD pipeline to a maximum of one in-progress deployment{% ifversion actions-nga %}{% else %} and one pending deployment{% endif %}. For more information about these features, see [AUTOTITLE](/actions/deployment/about-deployments/deploying-with-github-actions) and [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment).
 
 ## Workflow templates and third-party actions
 

content/actions/how-tos/deploy/configure-and-manage-deployments/control-deployments.md

@@ -52,7 +52,7 @@ You can configure environments with protection rules and secrets. When a workflo
 
 ## 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. For more information about concurrency, see [AUTOTITLE](/actions/using-jobs/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{% ifversion actions-nga %}{% else %} and one deployment pending{% endif %} at a time. For more information about concurrency, see [AUTOTITLE](/actions/using-jobs/using-concurrency).
 
 {% ifversion actions-environments-without-deployments %}
 

content/actions/reference/limits.md

@@ -32,6 +32,9 @@ These limits are subject to change.
 | Workflow execution limit | Re-run | 50 re-runs | A workflow run can be re-run a maximum of 50 times. This limit includes both full re-runs and re-runs of a subset of jobs. | {% octicon "check" aria-label="Yes" %} Support ticket |
 | Workflows queuing | Workflow trigger event rate limit | 1500 events / 10 seconds / repository | Each repository is limited to events triggering a workflow run. | {% octicon "check" aria-label="Yes" %} Support ticket |
 | Workflows queuing | Workflow run queued | 500 workflow runs / 10 seconds | When the limit is reached, the workflow runs that were supposed to be triggered by the webhook events will be blocked and will not be queued. Reusable workflows are viewed as a single entity. For example, a run with 30 reusable workflows counts as 1 in this instance. | {% octicon "x" aria-label="No" %} |
+| {% ifversion actions-nga %} |
+| Workflows queuing | Concurrency group queue | 100 workflow runs / concurrency group | When using `queue: max` in the `concurrency` section, up to 100 jobs or workflow runs can be queued per concurrency group. Runs beyond this limit will be rejected. | {% octicon "x" aria-label="No" %} |
+| {% endif %} |
 | Self-hosted | Runner registrations | 1500 runners / 5 minutes / repository/org/enterprise | Runners can be registered per repository/organization/enterprise. | {% octicon "check" aria-label="Yes" %} Support ticket |
 | Self-hosted | Runners per runner group | 10,000 runners | Runners registered at the same time per runner group. | {% octicon "x" aria-label="No" %} |
 | Self-hosted | Job execution time | 5 days | Each job in a workflow can run for up to 5 days of execution time. If a job reaches this limit, the job is terminated and fails. | {% octicon "x" aria-label="No" %} |

content/rest/actions/concurrency-groups.md

@@ -11,4 +11,8 @@ category:
   - Automate CI/CD workflows
 ---
 
-<!-- Content after this section is automatically generated -->
+## About concurrency groups in {% data variables.product.prodname_actions %}
+
+You can use the REST API to read the state of {% data variables.product.prodname_actions %} concurrency groups, which ensure that only a single job or workflow using the same group will run at a time while additional runs are pending or canceled depending on configuration. For more information, see [AUTOTITLE](/actions/using-jobs/using-concurrency).
+
+<!-- Content after this section is automatically generated -->

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

@@ -1,10 +1,29 @@
+{% ifversion actions-nga %}
+
+This means that there can be at most one running job or workflow in a concurrency group at any 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`. By default, any existing `pending` job or workflow in the same concurrency group will be canceled and the new queued job or workflow will take its place.
+
+{% else %}
+
 This means that there can be at most one running and one pending job in a concurrency group at any 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 existing `pending` job or workflow in the same concurrency group, if it exists, will be canceled and the new queued job or workflow will take its place.
 
+{% endif %}
+
 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.
 
+{% ifversion actions-nga %}
+
+To allow more than one `pending` job or workflow run to wait in the same concurrency group, use the optional `queue` property. The `queue` property accepts the following values:
+
+* `single` (default): At most one job or workflow run can be `pending` in the concurrency group. When a new job or workflow run is queued, any existing `pending` job or workflow run in the same group is canceled and replaced.
+* `max`: Up to 100 jobs or workflow runs can be `pending` in the concurrency group. When the queue is full, any additional jobs or workflow runs are canceled.
+
+The combination of `queue: max` and `cancel-in-progress: true` is not allowed and will result in a workflow validation error.
+
+{% endif %}
+
 > [!NOTE]
 > * The concurrency group name is case insensitive. For example, `prod` and `Prod` will be treated as the same concurrency group.
-> * Ordering is not guaranteed for jobs or workflow runs using concurrency groups. Jobs or workflow runs in the same concurrency group are handled in an arbitrary order.
+> * Jobs or workflow runs in the same concurrency group are processed in first-in-first-out (FIFO) order according to the time each one started waiting on the concurrency group, not the time each workflow was dispatched. Since the actual start time of a job or run may vary, ordering is not guaranteed.
 
 ### Example: Using concurrency and the default behavior
 
@@ -81,6 +100,33 @@ concurrency:
 
 {% endraw %}
 
+{% ifversion actions-nga %}
+
+### Example: Queueing multiple pending runs
+
+By default, only one job or workflow run can be `pending` in a concurrency group at a time. To allow multiple runs to queue instead of being canceled, set `queue: max`. With `queue: max`, up to 100 jobs or workflow runs can wait in the concurrency group; once the queue is full, any additional runs are canceled.
+
+For example, the following workflow queues deployments to the `production` environment, processing them one at a time in order based on when each run started waiting on the concurrency group:
+
+{% raw %}
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: production-deploy
+  queue: max
+```
+
+{% endraw %}
+
+Note that `queue: max` cannot be combined with `cancel-in-progress: true`, because the two options describe conflicting behaviors for handling in-progress runs.
+
+{% endif %}
+
 ### 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`: