Concurrency Pools

RWX supports concurrency pools to limit the number of simultaneous runs that are executing based on a specified pool id.

You can configure:

  • an id that identifies the concurrency pool
  • an if expression that controls whether the pool should apply to the run
  • a capacity for how many runs are permitted to execute concurrently within the pool
  • an on-overflow value that indicates what should happen when more than capacity runs are in the pool

Note that concurrency-pools takes an array so that you can use a different pool depending on the context of the run. For example, you might use cancel-running on feature branches and queue on your main branch. Only one concurrency pool can apply to a run, so ensure your if conditions are mutually exclusive.

id is global to your organization and is not scoped to a repository, so be sure to choose a value that will not collide with values used in your other repositories. A good way to avoid an incidental conflict is by including the repository name in the id.

Overflow Behavior

The three possible values for on-overflow:

  • queue will result in the runs queuing, waiting to execute until there is capacity available in the pool
  • cancel-running will cancel any runs that are currently running, so that the new run can start executing immediately
  • cancel-waiting will cancel any runs that are currently in the queue, but it will not cancel any runs that are currently running

It's common to use cancel-running on pushes to feature branches, since the new push usually makes the run results from the previous push irrelevant.

It's common to use cancel-waiting on runs for Continuous Deployment. Although you only want to run one deployment at a time, if multiple are in the queue, it's reasonable to skip the waiting runs and go straight to the most recent one.

Feature Branch Example

For feature branches, it's common to cancel existing runs on new pushes.

on:
  github:
    push:
      init:
        branch: ${{ event.git.branch }}

concurrency-pools:
  - id: your-org/your-repo:branch-${{ init.branch }}
    if: ${{ init.branch != 'main' }}
    capacity: 1
    on-overflow: cancel-running

Or if you are running on the pull request trigger:

on:
  github:
    pull_request:
      init:
        pr-number: ${{ event.github.pull_request.number }}

concurrency-pools:
  - id: your-org/your-repo:pr-${{ init.pr-number }}
    capacity: 1
    on-overflow: cancel-running

Continuous Deployment Example

on:
  github:
    push:
      if: ${{ init.branch == 'main' }}
      init:
        branch: ${{ event.git.branch }}

concurrency-pools:
  - id: your-org/your-repo:main
    capacity: 1
    on-overflow: cancel-waiting

Example with CI and CD in the same file

If your CI and CD tasks are in the same file, you may want to use if conditions on concurrency pools to control which pool applies.

on:
  github:
    push:
      init:
        branch: ${{ event.git.branch }}

concurrency-pools:
  - id: your-org/your-repo:main
    if: ${{ init.branch == 'main' }}
    capacity: 1
    on-overflow: cancel-waiting

  - id: your-org/your-repo:${{ init.branch }}
    if: ${{ init.branch != 'main' }}
    capacity: 1
    on-overflow: cancel-running