Assignment Rules

Assignment rules allow you to control which tasks can run on which agents.

• Save on agent costs by provisioning different sizes of agents to suit the individual needs of your tasks.
• Ensure resource intensive targets like e2e-ci and build have what they need by using larger agents and with a specified parallelism.
• Lighter tasks like lint and test can run on smaller agents.

Assignment rules are defined in yaml files within your workspace's .nx/workflows directory. You can use assignment rules with self-hosted agents or with dynamic Nx agents. Note that additional configuration is required when using self-hosted agents.

How to Define an Assignment Rule

Each assignment rule has at least one of the following properties that it matches against tasks: projects, targets, and/or configurations. You can provide a list of globs to match against any of these properties in your workspace. It also has a list of possible agent types that tasks with the matching properties can run on. Rules are defined in yaml like the following:

The first rule will match any task that has a project named app1, any targets that begin with e2e-ci, and a configuration named production. Any tasks that match this rule will only be allowed to run on agents with linux-medium-js launch templates. Agents assigned these tasks will also be able to execute up to five tasks in parallel.

The second rule above will match any task that has a lint or build target. These tasks only run on linux-large-js agents and up to ten tasks can be executed in parallel by agents of that type.

You can mix and match any of the properties in an assignment rule provided that you follow these constraints:

• At least one of the following properties is defined: projects, targets, configurations.
• There is at least one agent type specified in the run-on field. If no parallelism is specified, the parallelism of the executed command will be used instead. If that is not specified, then the parallelism will default to 1
• For assignment rules with Nx Agents, every changeset in your distribute-on field must include at least one agent that matches each agent type specified in the run-on field across all assignment rules. For example, if your rules distribute tasks on linux-small-js, linux-medium-js, and linux-large-js, then at least one agent of each type must be available. Otherwise, tasks associated with those rules cannot be executed.

Assignment Rule Property Reference

projects

A list of string globs that matches against projects in your workspace.

targets

A list of string globs that matches against targets in your workspace.

configurations

A list of string globs that matches against configurations in your workspace.

run-on

Specification of which agent and how to run your tasks:

• agent: the type of agent to run on (i.e. linux-medium-js, linux-large-js)
• parallelism: the number of parallel executions allowed for agents of a given type

Glob Reference

You can use globs for better control over how to define your assignment rules.

* matches zero or more characters

• ✅ lint* matches lint-js, linting-test
• ✅ *test* matches business-test-2, test-12, 10-test
• ❌ lint* does not match eslint, lin-test, lin

? matches exactly one character

• ✅ app? matches app1, app3, apps
• ❌ app? does not match app10, apps1, bus-app1

! at start negates the pattern

• ✅ !prod matches development, staging
• ❌ !prod does not match prod

List delimited globs

If you provide a list of globs to an individual rule property (projects, targets, configurations), it will match any of the patterns for that given property.

The following rule will match the following tasks:

• starts with e2e-ci (i.e e2e-ci--playwright-button-test)
• starts with lint (i.e lint-js)

Comma delimited globs

Within each list entry, you can define a list of globs. This notation will match a given property only if all globs match.

The following rule will match the following tasks:

• starts with e2e-ci and ends with server-test (i.e e2e-ci--playwright-server-test)
• starts with lint (i.e lint-js)

Assignment Rule Precedence

Having multiple assignment rules means that often rules may overlap or apply to the same tasks. For a given task, only one rule will ever be applied. To determine which rule takes priority, more specific rules take precedence over more general rules. You can consult our precedence chart for a full list of rule priorities. A checkmark indicates that a rule has a particular property defined.

Rule Precedence Example

In this example, the task defined below can match multiple assignment rules. However, since the first rule specifies all three properties (project, target, and configuration) rather than just two (project and target), it takes precedence, and we automatically apply the second rule when distributing the task.

Using Assignment Rules with Self-Hosted Agents

A typical assignment-rules.yaml file might look like this:

Note that the agent types supplied in the run-on property will be used to determine which agents will have rules applied to them. You can choose to name your agent types anything you want, but they must be set on your agents via the NX_AGENT_LAUNCH_TEMPLATE environment variable.

You can then reference your assignment rules file within your start-ci-run command:

The following is an example of what this looks like within a Github Actions pipeline:

Using Assignment Rules with Dynamic Nx Agents

A typical distribution-config.yaml file might look like this:

You can then reference your distribution configuration in your CI pipeline configuration:

More Examples of Assignment Rules with Dynamic Agents

Invalid Assignment Rules Example

Valid Assignment Rules Example