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 suite 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 Manual Distributed Task Execution (DTE) or with dynamic Nx agents. Note that additional configuration is required when using Manual DTE.

How to Define an Assignment Rule

Each assignment rule has 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 the tasks 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 above 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 5 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 agents and up to 10 tasks can be executed in parallel by agents of that type.

You can mix and match any of the criteria in an assignment rule provided that you follow the 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 runs-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 (linux-medium, linux-large)
• 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 comma delimited 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)

Configuring Parallelism through Assignment Rules

You can specify how many tasks of a certain type can run in parallel on a particular agent. Each agent object within the run-on list can have the parallelism property. Configuring parallelism through your assignment rules will override the other parallelism configurations in your workspace. For a given command run with DTE, parallelism is determined by in the following order:

1. Parallelism defined in the assignment rules
2. Parallelism defined in the --parallel flag in your command
3. Parallelism defined in your nx.json file (parallel: 3)

If none of these methods of configuring parallelism are used, the parallelism of executed tasks will default to 1.

Note that there are two special cases for parallelism with assignment rules where the behaviour may differ.

1. All tasks that are marked as non-cacheable (they are configured with cache: false) will be run with a parallelism of 1 regardless of the parallelism defined in the assignment rules or execution. This is usually the case with tasks such as e2e-ci which may requires each process to have its own environment or resources to run.
2. Assignment rules only apply to distributed executions (DTE). If you want to run multiple tasks in parallel without DTE (via the --no-dte flag), you will need to use the --parallel flag in your commands.

Assignment Rules Parallelism Example

In the above example, the lint and test targets will run on linux-medium agents with a parallelism of 4 as defined within the rules. The build target will run on linux-large agents, but note that there is no parallelism defined for that target. The parallelism for build tasks will then use the value provided by the --parallel flag, which is 3.

Setting Default Parallelism for Multiple Tasks

Putting globs and parallelism together, you can set a default parallelism for all tasks within your executions. Take the following statement:

Only e2e-ci tasks should run on large agents. All other tasks should run on medium agents with a parallelism of 5.

This can be represented as the following yaml config.

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 take priority, a rule of thumb is that 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.

If two rules have the same priority based on the below chart, the rule that appears first in the assignment-rules list will take precedence.

Rule Precedence Example

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

Using Assignment Rules with Manual DTE

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

Deprecated Assignment Rules

Assignment rules used to be defined with the following schema. However, this schema did not support multi-glob matching, nor parallelism. Rules defined in this format will still work, but we recommend updating them to the new schema.