Controlling serial execution across your organization

CircleCI identifies jobs that belong to the same serial group by the string value you provide. When multiple jobs across your organization use identical serial group values, they enter a shared queue. This queue operates on a first-in, first-out basis but with special priority rules.

CircleCI uses a distributed locking system to control execution order. When a job with a serial group starts, it attempts to acquire a "lock" for that specific serial group value. If no other job holds the lock, the job proceeds. If another job already holds the lock, subsequent jobs must wait in the queue.

CircleCI uses pipeline numbers to determine execution priority. Jobs from newer pipelines (higher pipeline numbers) take precedence over jobs from older pipelines within the same project. If a job from an older pipeline tries to run while a newer pipeline’s job is waiting or running, the older job is automatically skipped.

Jobs in a serial group move through several states:

To prevent indefinite waits, jobs can remain in the queue for up to five hours. After this time, CircleCI automatically cancels the waiting job and removes it from the queue.

This architecture provides a robust system for coordinating work across your organization while maintaining execution order integrity and preventing deployment conflicts or race conditions in shared environments.

Serial group jobs are displayed in the CircleCI web app in workflow graphs with the following visual elements:

From the CircleCI web app there are two ways to move a serial group along to the next job in the queue:

Each method is described in the following sections:

Add a job-groups key at the top level of your config. Each group has a name and a jobs list that follows the same format as workflow job entries, including internal requires dependencies:

Reference the group by name in a workflow’s jobs list, just like a regular job. Jobs downstream of the group can depend on it using requires:

When invoked without serial-group, the compiler expands the group inline and wraps it with no-op boundary jobs.

Add the serial-group key to a group invocation to serialize the entire group as an atomic unit. No other serial group with the same serial-group key across your organization can start until all jobs in the group complete:

You can invoke the same job group more than once in a workflow by adding a name: attribute to each invocation. Each name: value must be unique within the workflow and is used as a prefix for the expanded job names:

When CircleCI processes a job group invocation, it inlines all jobs from the group definition and adds synthetic boundary jobs at each end:

The group invocation’s requires and branch/tag filters are applied to the entry job. Jobs in the workflow that depend on the group invocation using requires are rewired to depend on the exit job.

If your job is skipped with a "not run" status, check the following:

If jobs are running concurrently when you expected them to run in sequence, check the following:

If your jobs are being canceled after waiting in the queue, check the following:

If you are experiencing deployment order problems, check the following:

If your pipeline fails to compile after adding a job group, check for the following configuration errors:

If a downstream job configured to run on failure does not trigger after a job group fails, it may be waiting on the group’s exit job rather than the individual job that failed. Downstream jobs that depend on a job group invocation observe the exit job’s status, not the status of individual jobs inside the group.

To react to a failure inside the group, add a failure-handling job inside the group definition itself.

If you are still experiencing resource conflicts despite using serial groups, check the following:

Serial groups can be applied at the job or job group invocation level. You cannot configure an entire workflow to run as a serial group. To serialize a collection of jobs as an atomic unit using a single serial-group declaration, see Job groups.

Using identical serial group values multiple times within the same workflow can result in unexpected behavior due to the way the jobs join the queue. Each serial group key within a workflow must be unique to prevent conflicts in the execution order.

Serial groups always release their lock upon job completion, regardless of the outcome. You cannot configure a serial group to maintain its lock if a job fails. This means you cannot prevent subsequent jobs from running if a critical job fails without implementing additional control mechanisms.

Jobs waiting in the queue longer than five hours will be automatically canceled. This five-hour wait limit for serial groups is fixed and cannot be adjusted.

Serial groups work within a single organization only. You cannot use them to orchestrate jobs across different CircleCI organizations, even if they belong to the same company.

You cannot lock only a portion of a job’s execution. The entire job is considered part of the serial group, which means you cannot have parallel sections within a serially grouped job.

The pipeline number priority system cannot be overridden. This means you cannot prioritize an older pipeline over a newer one.