From e9b0d07286131900ce7d59e590cbf4cb7732bc7c Mon Sep 17 00:00:00 2001 From: lourw <56288712+lourw@users.noreply.github.com> Date: Mon, 23 Dec 2024 16:03:41 -0500 Subject: [PATCH 1/7] docs(nx-cloud): add docs for assignment rules on manual dte --- docs/nx-cloud/reference/assignment-rules.md | 151 ++++++++++++-------- 1 file changed, 92 insertions(+), 59 deletions(-) diff --git a/docs/nx-cloud/reference/assignment-rules.md b/docs/nx-cloud/reference/assignment-rules.md index 5d96816ecae8a..6cc806ced1f9c 100644 --- a/docs/nx-cloud/reference/assignment-rules.md +++ b/docs/nx-cloud/reference/assignment-rules.md @@ -2,16 +2,13 @@ Assignment rules allow you to control which tasks can run on which agents. Save on agent costs by provisioning different sizes of agents all with the confidence that your tasks will be run on the agents that are best suited for them. 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 your workspaces `distribution-config.yaml` file. This file should be created in the `.nx/workflows` directory of your repository. Note that this means that you must have [dynamic agents](/ci/features/dynamic-agents) also configured in your `distribution-config.yaml` file. +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](/ci/features/dynamic-agents). Note that the 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](/ci/reference/launch-templates) that tasks with the matching properties can run on. Rules are defined in yaml like the following: -```yaml {% fileName=".nx/workflows/distribution-config.yaml" %} -distribute-on: - default: 3 linux-small-js, 2 linux-medium-js, 1 linux-large-js - +```yaml {% fileName=".nx/workflows/assignment-rules.yaml" %} assignment-rules: - project: app1 target: build @@ -29,56 +26,6 @@ You can mix and match any of the criteria in an assignment rule provided that yo - There is at least one [agent type](/ci/reference/launch-templates) specified in the `run-on` field. - 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. -### Invalid Assignment Rules Example - -```yaml {% fileName=".nx/workflows/distribution-config.yaml" %} -distribute-on: - # Invalid changeset that is missing `linux-large-js`. Tasks assigned to large agents won't be able to execute. - small-changeset: 1 linux-small-js, 2 linux-medium-js - medium-changeset: 2 linux-small-js, 2 linux-medium-js, 3 linux-large-js - large-changeset: 3 linux-small-js, 3 linux-medium-js, 4 linux-large-js - -assignment-rules: - # Missing one of `project`, `target`, `configuration` - - runs-on: - - linux-medium-js - - linux-large-js - - # Missing `runs-on` - - target: lint - configuration: production - - # Agent type not found in any of the `distribute-on` changesets - - project: lib1 - target: test - runs-on: - - linux-extra-large-js -``` - -### Valid Assignment Rules Example - -```yaml {% fileName=".nx/workflows/distribution-config.yaml" %} -distribute-on: - default: 3 linux-small-js, 2 linux-medium-js, 1 linux-large-js - -# All rules below are valid assignment rules -assignment-rules: - - project: app1 - runs-on: - - linux-medium-js - - linux-large-js - - - target: lint - configuration: production - runs-on: - - linux-large-js - - - project: lib1 - target: test - runs-on: - - linux-medium-js -``` - ## 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. @@ -106,9 +53,6 @@ In this example, the task defined below can match multiple assignment rules. How ``` ```yaml {% fileName=".nx/workflows/distribution-config.yaml" %} -distribute-on: - default: 10 linux-medium-js, 8 linux-large-js - assignment-rules: - project: app1 target: build @@ -122,7 +66,44 @@ assignment-rules: - linux-large-js ``` -## Using Assignment Rules in your CI Pipeline +## Using Assignment Rules with Self-Hosted Agents + +A typical `assignment-rules.yaml` file might look like this: + +```yaml +assignment-rules: + - project: app1 + target: build + configuration: production + runs-on: + - linux-large-js + - linux-medium-js + + - target: lint + runs-on: + - linux-medium-js + + - configuration: development + runs-on: + - linux-medium-js + - linux-large-js +``` + +Note that the labels supplied in the `runs-ons` property will be used to determine which agents will have rules applied to them. When using self-hosted agents, you must supply these labels to your agents via an environment variable: `NX_AGENT_LAUNCH_TEMPLATE`. + +You can then reference your assignment rules file within your `start-ci-run` command: + +```shell +npx nx-cloud start-ci-run --assignment-rules='.nx/workflows/assignment-rules.yaml' +``` + +The following is an example of what this looks like within a github actions pipeline: + +```angular2html + +``` + +## Using Assignment Rules with Dynamic Nx Agents A typical `distribution-config.yaml` file might look like this: @@ -162,3 +143,55 @@ jobs: - run: npx nx-cloud start-ci-run --distribute-on=".nx/workflows/distribution-config.yaml" --stop-agents-after="e2e-ci" - .. ``` + +### More Examples of Assignment Rules with Dynamic Agents + +#### Invalid Assignment Rules Example + +```yaml {% fileName=".nx/workflows/distribution-config.yaml" %} +distribute-on: + # Invalid changeset that is missing `linux-large-js`. Tasks assigned to large agents won't be able to execute. + small-changeset: 1 linux-small-js, 2 linux-medium-js + medium-changeset: 2 linux-small-js, 2 linux-medium-js, 3 linux-large-js + large-changeset: 3 linux-small-js, 3 linux-medium-js, 4 linux-large-js + +assignment-rules: + # Missing one of `project`, `target`, `configuration` + - runs-on: + - linux-medium-js + - linux-large-js + + # Missing `runs-on` + - target: lint + configuration: production + + # Agent type not found in any of the `distribute-on` changesets + - project: lib1 + target: test + runs-on: + - linux-extra-large-js +``` + +#### Valid Assignment Rules Example + +```yaml {% fileName=".nx/workflows/distribution-config.yaml" %} +distribute-on: + default: 3 linux-small-js, 2 linux-medium-js, 1 linux-large-js + +# All rules below are valid assignment rules +assignment-rules: + - project: app1 + runs-on: + - linux-medium-js + - linux-large-js + + - target: lint + configuration: production + runs-on: + - linux-large-js + + - project: lib1 + target: test + runs-on: + - linux-medium-js +``` From 9c883d6734d8704e95bf93d97e717e292c6bc6e1 Mon Sep 17 00:00:00 2001 From: lourw <56288712+lourw@users.noreply.github.com> Date: Mon, 30 Dec 2024 07:48:25 -0800 Subject: [PATCH 2/7] docs(nx-cloud): add example for manual assignment rules --- docs/nx-cloud/reference/assignment-rules.md | 61 ++++++++++++++++++--- 1 file changed, 54 insertions(+), 7 deletions(-) diff --git a/docs/nx-cloud/reference/assignment-rules.md b/docs/nx-cloud/reference/assignment-rules.md index 6cc806ced1f9c..f9f9e0aa72fc9 100644 --- a/docs/nx-cloud/reference/assignment-rules.md +++ b/docs/nx-cloud/reference/assignment-rules.md @@ -70,23 +70,23 @@ assignment-rules: A typical `assignment-rules.yaml` file might look like this: -```yaml +```yaml {% fileName=".nx/workflows/assignment-rules.yaml" %} assignment-rules: - project: app1 target: build configuration: production runs-on: - - linux-large-js - - linux-medium-js + - linux-large + - linux-medium - target: lint runs-on: - - linux-medium-js + - linux-medium - configuration: development runs-on: - - linux-medium-js - - linux-large-js + - linux-medium + - linux-large ``` Note that the labels supplied in the `runs-ons` property will be used to determine which agents will have rules applied to them. When using self-hosted agents, you must supply these labels to your agents via an environment variable: `NX_AGENT_LAUNCH_TEMPLATE`. @@ -99,8 +99,55 @@ npx nx-cloud start-ci-run --assignment-rules='.nx/workflows/assignment-rules.yam The following is an example of what this looks like within a github actions pipeline: -```angular2html +```yaml {% fileName=".github/workflows/ci.yaml" %} +... +jobs: + main: + displayName: Main Job + ... + steps: + ... + - run: npx nx-cloud start-ci-run --assignment-rules=.nx/workflows/assignment-rules.yaml --stop-agents-after="e2e-ci" + - .. + + medium-agents: + displayName: Agents ${{ matrix.agent }} + runs-on: + group: medium-agents + strategy: + matrix: + agent: [1, 2, 3] + steps: + - name: Checkout + uses: actions/checkout@v4 + + ... + + - name: Start Agent ${{ matrix.agent }} + run: npx nx-cloud start-agent + env: + NX_AGENT_NAME: ${{ matrix.agent }} + NX_AGENT_LAUNCH_TEMPLATE: "linux-medium" # This value needs to match one of the 'runs-on' values defined in the assignment rules + + large-agents: + displayName: Agents ${{ matrix.agent }} + runs-on: + group: large-agents + strategy: + matrix: + agent: [1, 2, 3] + + steps: + - name: Checkout + uses: actions/checkout@v4 + + ... # other setup steps + - name: Start Agent ${{ matrix.agent }} + run: npx nx-cloud start-agent + env: + NX_AGENT_NAME: ${{ matrix.agent }} + NX_AGENT_LAUNCH_TEMPLATE: "linux-large" # This value needs to match one of the 'runs-on' values defined in the assignment rules ``` ## Using Assignment Rules with Dynamic Nx Agents From df86252b92d92c5d4be5fd5ba3b1861b56119b9c Mon Sep 17 00:00:00 2001 From: lourw <56288712+lourw@users.noreply.github.com> Date: Mon, 6 Jan 2025 09:57:28 -0800 Subject: [PATCH 3/7] docs(nx-cloud): use correct yaml field for job name github --- docs/nx-cloud/features/dynamic-agents.md | 4 ++-- docs/nx-cloud/reference/assignment-rules.md | 14 ++++++++++---- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/nx-cloud/features/dynamic-agents.md b/docs/nx-cloud/features/dynamic-agents.md index 43ee22a0b1cd9..05520f920bd82 100644 --- a/docs/nx-cloud/features/dynamic-agents.md +++ b/docs/nx-cloud/features/dynamic-agents.md @@ -10,7 +10,7 @@ By default, when you set up [Nx Agents](/ci/features/distribute-task-execution) ... jobs: - job: main - displayName: Main Job + name: Main Job ... steps: ... @@ -68,7 +68,7 @@ You can then reference your distribution configuration in your CI pipeline confi ... jobs: - job: main - displayName: Main Job + name: Main Job ... steps: ... diff --git a/docs/nx-cloud/reference/assignment-rules.md b/docs/nx-cloud/reference/assignment-rules.md index f9f9e0aa72fc9..bb92aaeffbb4d 100644 --- a/docs/nx-cloud/reference/assignment-rules.md +++ b/docs/nx-cloud/reference/assignment-rules.md @@ -103,7 +103,7 @@ The following is an example of what this looks like within a github actions pipe ... jobs: main: - displayName: Main Job + name: Main Job ... steps: ... @@ -111,7 +111,7 @@ jobs: - .. medium-agents: - displayName: Agents ${{ matrix.agent }} + name: Agents ${{ matrix.agent }} runs-on: group: medium-agents strategy: @@ -121,6 +121,9 @@ jobs: - name: Checkout uses: actions/checkout@v4 + - name: Install dependencies + run: npm ci + ... - name: Start Agent ${{ matrix.agent }} @@ -130,7 +133,7 @@ jobs: NX_AGENT_LAUNCH_TEMPLATE: "linux-medium" # This value needs to match one of the 'runs-on' values defined in the assignment rules large-agents: - displayName: Agents ${{ matrix.agent }} + name: Agents ${{ matrix.agent }} runs-on: group: large-agents strategy: @@ -141,6 +144,9 @@ jobs: - name: Checkout uses: actions/checkout@v4 + - name: Install dependencies + run: npm ci + ... # other setup steps - name: Start Agent ${{ matrix.agent }} @@ -183,7 +189,7 @@ You can then reference your distribution configuration in your CI pipeline confi ... jobs: - job: main - displayName: Main Job + name: Main Job ... steps: ... From 3ec949e7f3496d3cf206627975e81f07f8700546 Mon Sep 17 00:00:00 2001 From: lourw <56288712+lourw@users.noreply.github.com> Date: Mon, 6 Jan 2025 10:28:46 -0800 Subject: [PATCH 4/7] docs(nx-cloud): adjust quotes for consistency --- docs/nx-cloud/reference/assignment-rules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/nx-cloud/reference/assignment-rules.md b/docs/nx-cloud/reference/assignment-rules.md index bb92aaeffbb4d..2e8cbfbb5e3e8 100644 --- a/docs/nx-cloud/reference/assignment-rules.md +++ b/docs/nx-cloud/reference/assignment-rules.md @@ -94,7 +94,7 @@ Note that the labels supplied in the `runs-ons` property will be used to determi You can then reference your assignment rules file within your `start-ci-run` command: ```shell -npx nx-cloud start-ci-run --assignment-rules='.nx/workflows/assignment-rules.yaml' +npx nx-cloud start-ci-run --assignment-rules=".nx/workflows/assignment-rules.yaml" ``` The following is an example of what this looks like within a github actions pipeline: @@ -107,7 +107,7 @@ jobs: ... steps: ... - - run: npx nx-cloud start-ci-run --assignment-rules=.nx/workflows/assignment-rules.yaml --stop-agents-after="e2e-ci" + - run: npx nx-cloud start-ci-run --assignment-rules=".nx/workflows/assignment-rules.yaml" --stop-agents-after="e2e-ci" - .. medium-agents: From 66e357bde4a952e19f961a11349d3f3b7b46a7f5 Mon Sep 17 00:00:00 2001 From: lourw <56288712+lourw@users.noreply.github.com> Date: Thu, 16 Jan 2025 14:44:57 -0800 Subject: [PATCH 5/7] docs(nx-cloud): clean up assignment rules docs --- docs/nx-cloud/reference/assignment-rules.md | 65 +++++++++++++-------- 1 file changed, 42 insertions(+), 23 deletions(-) diff --git a/docs/nx-cloud/reference/assignment-rules.md b/docs/nx-cloud/reference/assignment-rules.md index 2e8cbfbb5e3e8..e7d83e6d21051 100644 --- a/docs/nx-cloud/reference/assignment-rules.md +++ b/docs/nx-cloud/reference/assignment-rules.md @@ -1,8 +1,8 @@ # 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 all with the confidence that your tasks will be run on the agents that are best suited for them. 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 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](/ci/features/dynamic-agents). Note that the additional configuration is required when using self-hosted 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](/ci/features/dynamic-agents). Note that additional configuration is required when using self-hosted agents. ## How to Define an Assignment Rule @@ -14,8 +14,8 @@ assignment-rules: target: build configuration: production runs-on: - - linux-large-js - linux-medium-js + - linux-large-js ``` The 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. @@ -23,8 +23,13 @@ The above rule will match any task that has a project named `app1`, a target nam 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](/ci/reference/launch-templates) specified in the `run-on` field. -- 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. +- There is at least one [agent type](/ci/reference/launch-templates) specified in the `runs-on` field. +- 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. + +{% callout type="note" title="If you are using self-hosted agents, you must define your own agent types" %} +You can 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](#using-assignment-rules-with-selfhosted-agents) of how to define your own agent types when using self-hosted agents. +{% /callout %} ## Assignment Rule Precedence @@ -42,7 +47,7 @@ Having multiple assignment rules means that often rules may overlap or apply to ### 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 apply the second rule when distributing the task. +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. ```json {% fileName="A task from your workspace" %} { @@ -54,6 +59,7 @@ In this example, the task defined below can match multiple assignment rules. How ```yaml {% fileName=".nx/workflows/distribution-config.yaml" %} assignment-rules: + # A task for app1:build:production will use this rule because it is more specific (matches all three properties instead of just two) - project: app1 target: build configuration: production @@ -76,8 +82,8 @@ assignment-rules: target: build configuration: production runs-on: - - linux-large - linux-medium + - linux-large - target: lint runs-on: @@ -89,26 +95,29 @@ assignment-rules: - linux-large ``` -Note that the labels supplied in the `runs-ons` property will be used to determine which agents will have rules applied to them. When using self-hosted agents, you must supply these labels to your agents via an environment variable: `NX_AGENT_LAUNCH_TEMPLATE`. +Note that the agent types supplied in the `runs-ons` 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: ```shell -npx nx-cloud start-ci-run --assignment-rules=".nx/workflows/assignment-rules.yaml" +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: +The following is an example of what this looks like within a Github Actions pipeline: ```yaml {% fileName=".github/workflows/ci.yaml" %} -... +--- jobs: main: name: Main Job - ... + runs-on: ubuntu-latest steps: - ... - - run: npx nx-cloud start-ci-run --assignment-rules=".nx/workflows/assignment-rules.yaml" --stop-agents-after="e2e-ci" - - .. + - ... # setup steps for your main job + + - run: npx nx-cloud start-ci-run --distribute-on="manual" --assignment-rules=".nx/workflows/assignment-rules.yaml" --stop-agents-after="e2e-ci" + + - ... # Nx commands you want to distribute medium-agents: name: Agents ${{ matrix.agent }} @@ -121,16 +130,21 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Install dependencies - run: npm ci + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: 'npm' - ... + - ... # other setup steps you may need + + - name: Install dependencies + run: npm ci --legacy-peer-deps - name: Start Agent ${{ matrix.agent }} run: npx nx-cloud start-agent env: NX_AGENT_NAME: ${{ matrix.agent }} - NX_AGENT_LAUNCH_TEMPLATE: "linux-medium" # This value needs to match one of the 'runs-on' values defined in the assignment rules + NX_AGENT_LAUNCH_TEMPLATE: 'linux-medium' # This value needs to match one of the 'runs-on' values defined in the assignment rules large-agents: name: Agents ${{ matrix.agent }} @@ -144,16 +158,21 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Install dependencies - run: npm ci + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: 'npm' - ... # other setup steps + - ... # other setup steps you may need + + - name: Install dependencies + run: npm ci --legacy-peer-deps - name: Start Agent ${{ matrix.agent }} run: npx nx-cloud start-agent env: NX_AGENT_NAME: ${{ matrix.agent }} - NX_AGENT_LAUNCH_TEMPLATE: "linux-large" # This value needs to match one of the 'runs-on' values defined in the assignment rules + NX_AGENT_LAUNCH_TEMPLATE: 'linux-large' # This value needs to match one of the 'runs-on' values defined in the assignment rules ``` ## Using Assignment Rules with Dynamic Nx Agents From 49df41f50a2dafa6434837632f191ed5799d4eb8 Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Thu, 16 Jan 2025 18:43:59 -0500 Subject: [PATCH 6/7] docs(core): update docs/nx-cloud/reference/assignment-rules.md --- docs/nx-cloud/reference/assignment-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/nx-cloud/reference/assignment-rules.md b/docs/nx-cloud/reference/assignment-rules.md index e7d83e6d21051..80c1f5f7f7333 100644 --- a/docs/nx-cloud/reference/assignment-rules.md +++ b/docs/nx-cloud/reference/assignment-rules.md @@ -95,7 +95,7 @@ assignment-rules: - linux-large ``` -Note that the agent types supplied in the `runs-ons` property will be used to determine which agents will have rules applied to them. +Note 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: From 9bc0cfa017363c662ae1ae5d3b811e01f2314806 Mon Sep 17 00:00:00 2001 From: lourw <56288712+lourw@users.noreply.github.com> Date: Thu, 16 Jan 2025 23:07:55 -0800 Subject: [PATCH 7/7] docs(nx-cloud): edit grammar --- docs/nx-cloud/reference/assignment-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/nx-cloud/reference/assignment-rules.md b/docs/nx-cloud/reference/assignment-rules.md index 80c1f5f7f7333..0dcd2feea73b0 100644 --- a/docs/nx-cloud/reference/assignment-rules.md +++ b/docs/nx-cloud/reference/assignment-rules.md @@ -27,7 +27,7 @@ You can mix and match any of the criteria in an assignment rule provided that yo - 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. {% callout type="note" title="If you are using self-hosted agents, you must define your own agent types" %} -You can 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. +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](#using-assignment-rules-with-selfhosted-agents) of how to define your own agent types when using self-hosted agents. {% /callout %}