Assignment Rules (beta)
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. You can ensure resource intensive targets like e2e-ci and build have what they need by using larger agents. 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 one of the following properties that it matches against tasks: project, target, and/or configuration. 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:
1assignment-rules:
2 - project: app1
3 target: build
4 configuration: production
5 runs-on:
6 - linux-medium-js
7 - linux-large-js
8The above rule will match any task that has a project named app1, a target named build, and a configuration named production. Any tasks that match this rule will only be allowed to run on agents with the linux-large-js and linux-medium-js launch templates.
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:
project,target,configuration. - There is at least one agent type specified in the
runs-onfield. - Every changeset in your
distribute-onfield must include at least one agent that matches each agent type specified in theruns-onfield across all assignment rules. For example, if your rules distribute tasks onlinux-small-js,linux-medium-js, andlinux-large-js, then at least one agent of each type must be available; otherwise, tasks associated with those rules cannot be executed.
You must define your own agent types and attach them to your self-hosted agents using the NX_AGENT_LAUNCH_TEMPLATE environment variable. Ensure that for each runs-on field in your assignment rules, you have corresponding agents in your agent pool that have the same agent type. See below for an example of how to define your own agent types when using self-hosted agents.
Assignment Rule Precedence
Having multiple assignment rules means that often rules may overlap or apply to the same tasks. 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.
| Priority | Configuration | Target | Project |
|---|---|---|---|
| 1 | ✅︎ | ✅︎ | ✅︎ |
| 2 | ✅︎ | ✅︎ | |
| 3 | ✅︎ | ✅︎ | |
| 4 | ✅︎ | ✅︎ | |
| 5 | ✅︎ | ||
| 6 | ✅︎ | ||
| 7 | ✅ |
Rule Precedence Example
In this example, the task defined below can match multiple assignment rules. However, since the second 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.
1{
2 "project": "app1",
3 "target": "build",
4 "configuration": "production"
5}
61assignment-rules:
2 # A task for app1:build:production will use this rule because it is more specific (matches all three properties instead of just two)
3 - project: app1
4 target: build
5 configuration: production
6 runs-on:
7 - linux-medium-js
8
9 - project: app1
10 target: build
11 runs-on:
12 - linux-large-js
13Using Assignment Rules with Self-Hosted Agents
A typical assignment-rules.yaml file might look like this:
1assignment-rules:
2 - project: app1
3 target: build
4 configuration: production
5 runs-on:
6 - linux-medium
7 - linux-large
8
9 - target: lint
10 runs-on:
11 - linux-medium
12
13 - configuration: development
14 runs-on:
15 - linux-medium
16 - linux-large
17Note that the agent types supplied in the runs-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:
❯
npx nx-cloud start-ci-run --distribute-on="manual" --assignment-rules=".nx/workflows/assignment-rules.yaml"
The following is an example of what this looks like within a Github Actions pipeline:
1
2jobs:
3 main:
4 name: Main Job
5 runs-on: ubuntu-latest
6 steps:
7 - ... # setup steps for your main job
8
9 - run: npx nx-cloud start-ci-run --distribute-on="manual" --assignment-rules=".nx/workflows/assignment-rules.yaml" --stop-agents-after="e2e-ci"
10
11 - ... # Nx commands you want to distribute
12
13 medium-agents:
14 name: Agents ${{ matrix.agent }}
15 runs-on:
16 group: medium-agents
17 strategy:
18 matrix:
19 agent: [1, 2, 3]
20 steps:
21 - name: Checkout
22 uses: actions/checkout@v4
23
24 - uses: actions/setup-node@v4
25 with:
26 node-version: 20
27 cache: 'npm'
28
29 - ... # other setup steps you may need
30
31 - name: Install dependencies
32 run: npm ci --legacy-peer-deps
33
34 - name: Start Agent ${{ matrix.agent }}
35 run: npx nx-cloud start-agent
36 env:
37 NX_AGENT_NAME: ${{ matrix.agent }}
38 NX_AGENT_LAUNCH_TEMPLATE: 'linux-medium' # This value needs to match one of the 'runs-on' values defined in the assignment rules
39
40 large-agents:
41 name: Agents ${{ matrix.agent }}
42 runs-on:
43 group: large-agents
44 strategy:
45 matrix:
46 agent: [1, 2, 3]
47
48 steps:
49 - name: Checkout
50 uses: actions/checkout@v4
51
52 - uses: actions/setup-node@v4
53 with:
54 node-version: 20
55 cache: 'npm'
56
57 - ... # other setup steps you may need
58
59 - name: Install dependencies
60 run: npm ci --legacy-peer-deps
61
62 - name: Start Agent ${{ matrix.agent }}
63 run: npx nx-cloud start-agent
64 env:
65 NX_AGENT_NAME: ${{ matrix.agent }}
66 NX_AGENT_LAUNCH_TEMPLATE: 'linux-large' # This value needs to match one of the 'runs-on' values defined in the assignment rules
67Using Assignment Rules with Dynamic Nx Agents
A typical distribution-config.yaml file might look like this:
1distribute-on:
2 small-changeset: 3 linux-medium-js, 2 linux-large-js
3 medium-changeset: 6 linux-medium-js, 4 linux-large-js
4 large-changeset: 10 linux-medium-js, 8 linux-large-js
5
6assignment-rules:
7 - project: app1
8 target: build
9 configuration: production
10 runs-on:
11 - linux-large-js
12
13 - target: lint
14 runs-on:
15 - linux-medium-js
16
17 - configuration: development
18 runs-on:
19 - linux-medium-js
20 - linux-large-js
21You can then reference your distribution configuration in your CI pipeline configuration:
1...
2jobs:
3 - job: main
4 name: Main Job
5 ...
6 steps:
7 ...
8 - run: npx nx-cloud start-ci-run --distribute-on=".nx/workflows/distribution-config.yaml" --stop-agents-after="e2e-ci"
9 - ..
10More Examples of Assignment Rules with Dynamic Agents
Invalid Assignment Rules Example
1distribute-on:
2 # Invalid changeset that is missing `linux-large-js`. Tasks assigned to large agents won't be able to execute.
3 small-changeset: 1 linux-small-js, 2 linux-medium-js
4 medium-changeset: 2 linux-small-js, 2 linux-medium-js, 3 linux-large-js
5 large-changeset: 3 linux-small-js, 3 linux-medium-js, 4 linux-large-js
6
7assignment-rules:
8 # Missing one of `project`, `target`, `configuration`
9 - runs-on:
10 - linux-medium-js
11 - linux-large-js
12
13 # Missing `runs-on`
14 - target: lint
15 configuration: production
16
17 # Agent type not found in any of the `distribute-on` changesets
18 - project: lib1
19 target: test
20 runs-on:
21 - linux-extra-large-js
22Valid Assignment Rules Example
1distribute-on:
2 default: 3 linux-small-js, 2 linux-medium-js, 1 linux-large-js
3
4# All rules below are valid assignment rules
5assignment-rules:
6 - project: app1
7 runs-on:
8 - linux-medium-js
9 - linux-large-js
10
11 - target: lint
12 configuration: production
13 runs-on:
14 - linux-large-js
15
16 - project: lib1
17 target: test
18 runs-on:
19 - linux-medium-js
20