Concurrency

Limit how many strategy instances run simultaneously when a stage or step uses a matrix, for loop, or while loop strategy.

Concurrency controls how many instances run at the same time when a strategy is applied to a stage or step. Without a concurrency limit, all instances start simultaneously. Setting a limit queues the remaining instances and releases them as running ones complete.

Use concurrency to:

• Avoid overwhelming a downstream service with simultaneous deploys

• Respect infrastructure quotas or rate limits

• Roll out changes progressively across environments or regions

What you will learn

• What the max-parallel setting does and how it limits simultaneous strategy instances

• How to configure a concurrency limit in YAML alongside a matrix or loop strategy

• The behavioral difference between no limit, serial (max-parallel: 1), and N-parallel execution

---

YAML

Set max-parallel inside the strategy block:

stages:
  - name: deploy
    id: deploy
    strategy:
      matrix:
        region: [us-east-1, eu-west-1, ap-southeast-1, ap-northeast-1]
      max-parallel: 2
    steps:
      - name: deploy-region
        id: deploy_region
        run:
          script: echo "Deploying to ${{ matrix.region }}"

With max-parallel: 2, the four regions deploy in two waves: the first two start immediately, and the remaining two start only after one of the first two finishes.

---

Behavior

max-parallel value	Effect
Not set	All instances start at the same time
1	Instances run one at a time (fully sequential)
N	At most N instances run simultaneously; others are queued

max-parallel applies within a single stage's strategy. It does not affect concurrency between different stages in the pipeline.

---

Next steps

• Go to Strategy to define matrix, repeat, or parallelism for a stage.

• Go to Pipelines overview to review the pipeline model.