This page contains common configuration examples for launch templates. For the full reference of available fields, see the launch templates reference page.
Full example
Section titled “Full example”This is an example of a launch template using all pre-built features:
# Define common setup steps that can be reused across templatescommon-js-init-steps: &common-js-init-steps # using a reusable step in an external GitHub repo, # this step is provided by Nx Cloud: https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps - name: Checkout uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/checkout/main.yaml' - name: Restore Node Modules Cache uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/cache/main.yaml' # the cache step requires configuration via env vars # https://github.com/nrwl/nx-cloud-workflows/tree/main/workflow-steps/cache#options inputs: # Include patches directories to ensure cache is busted when patches change # If you use a custom patches directory, add it to the key as well key: 'package-lock.json|yarn.lock|pnpm-lock.yaml|patches/**|.yarn/patches/**' paths: | ~/.npm # or ~/.cache/yarn # or ~/.local/share/pnpm/store base-branch: 'main' - name: Restore Browser Binary Cache uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/cache/main.yaml' inputs: key: 'package-lock.json|yarn.lock|pnpm-lock.yaml|"browsers"' paths: | '~/.cache/Cypress' base-branch: 'main' - name: Install Node Modules uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-node-modules/main.yaml' - name: Install Browsers (if needed) uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-browsers/main.yaml' # You can also run a custom script to configure various things on the agent machine - name: Run a custom script script: | git config --global user.email test@test.com git config --global user.name "Test Test" - name: Define Step Env Var # this env var will be available to all future steps using these 'common-init-steps' reusable steps # persist env vars between steps by writing to the $NX_CLOUD_ENV file script: | echo "MY_STEP_ENV=step-env-var" >> $NX_CLOUD_ENV
common-rust-init-steps: &common-rust-init-steps - name: Checkout uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/checkout/main.yaml'
# add Rust-specific steps - name: Install Rust script: | curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh -s -- -y source "$HOME/.cargo/env" rustup toolchain install stable # persist cargo bin into PATH echo "PATH=$HOME/.cargo/bin:$PATH" >> $NX_CLOUD_ENV
launch-templates: # Custom template name, the name is referenced in a worker count such as '3 my-linux-medium-js' # You can define as many templates as you need, commonly used to make different sizes or toolchains depending on your workspace needs my-linux-medium-js: resource-class: 'docker_linux_amd64/medium' image: 'ubuntu22.04-node24.14-v1' # Define environment variables shared among all steps in this launch template env: MY_ENV_VAR: shared # list out steps to run on the agent before accepting tasks # the agent will need a copy of the source code and dependencies installed # note we are using yaml anchors to reduce duplication with the below launch-template (they have the same init-steps) init-steps: *common-js-init-steps
# another template which does the same as above, but with a large resource class # You're not required to define a template for every resource class, only define what you need! my-linux-large-js: resource-class: 'docker_linux_amd64/large' image: 'ubuntu22.04-node24.14-v1' env: MY_ENV_VAR: shared # note we are using yaml anchors to reduce duplication with the above launch-template (they have the same init-steps) init-steps: *common-js-init-steps
# template that installs rust my-linux-rust-large: resource-class: 'docker_linux_amd64/large' image: 'ubuntu22.04-node24.14-v1' init-steps: *common-rust-init-stepsUse these templates by setting the number of agents desired and the template name on a worker-templates entry in the same file. Pick whichever template suits the job, swapping my-linux-medium-js for my-linux-large-js or my-linux-rust-large.
worker-templates: default: 4 my-linux-medium-jsYour main CI job then starts the agents with nx-cloud start-workers. With one entry, the command takes no flags.
npx nx-cloud start-workersPass environment variables
Section titled “Pass environment variables”nx-cloud start-workers forwards variables prefixed with NX_ from the main job to your agents. Set other values on the launch template:
launch-templates: my-linux-medium-js: env: VAR1: value1 VAR2: value2To use a secret, read it in the template's env with ${{ secrets.NAME }}, or ${{ vars.NAME }} for a value that isn't secret:
- If it's on the Environment variables page of your workspace settings, that's all you need.
- If it's in your CI provider, put it in the env of the
start-workersstep and list it:npx nx-cloud start-workers --forward-secrets API_TOKEN,OTHER_TOKEN. Values from the main job's env are sent for that run only, and--forward-secretsvalues are masked in logs.
Pass values between steps
Section titled “Pass values between steps”If you need to pass a value from one step to another step, such as assigning the value to an existing or new environment variable. You can write to the NX_CLOUD_ENV environment file.
Commonly used for redefining the PATH or setting options for tooling. For the other files a step can write to, such as $NX_CLOUD_OUTPUT, see variables and files in each step.
launch-templates: my-template-name: init-steps: - name: Set PATH script: echo "PATH=$HOME/.cargo/bin:$PATH" >> $NX_CLOUD_ENV - name: Check PATH script: | # now contains $HOME/.cargo/bin echo $PATH # can invoke cargo directly because it's in the PATH now. cargo --versionPrivate npm registry
Section titled “Private npm registry”If your project consumes packages from a private registry, you'll have to set up an authentication step in a custom launch template and authenticate like you normally would, usually this is via a .npmrc or .yarnrc file. Add SOME_AUTH_TOKEN on the Environment variables page of your workspace settings, then map it in the template's env with ${{ secrets.SOME_AUTH_TOKEN }}.
launch-templates: my-linux-medium-js: resource-class: 'docker_linux_amd64/medium' image: 'ubuntu22.04-node24.14-v1' env: SOME_AUTH_TOKEN: ${{ secrets.SOME_AUTH_TOKEN }} init-steps: - name: Checkout uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/checkout/main.yaml' - name: Auth to Registry script: | # we recommend add to the 'user' level npmrc file # create .npmrc with @myorg scoped packages pointing to GH npm registry # or yarn config set -l user if you use yarn npm config set -L user "@myorg:registry" "https://npm.pkg.github.com" npm config set -L user "//npm.pkg.github.com/:_authToken" "${SOME_AUTH_TOKEN}" - name: Install Node Modules uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-node-modules/main.yaml'Custom node version
Section titled “Custom node version”Workers come with node LTS installed. If you want to enforce a different version, add a step to install the desired node version. To keep local development, CI, and Workers on the same version, commit the version to your repository and let the install step read it, rather than hardcoding a version in the launch template.
Which file the step reads depends on which step you use:
- The
install-nodestep reads a.nvmrcfile or thevolta.nodefield inpackage.json. - The mise step reads a
mise.tomlfile.
You can use mise to manage node versions alongside other toolchains.
launch-templates: node-22: resource-class: 'docker_linux_amd64/medium' image: 'ubuntu22.04-node24.14-v1' init-steps: - name: Checkout uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/checkout/main.yaml' - name: Install mise uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-mise/main.yaml' inputs: # you can also define a mise.toml in your repo instead of inline tools tools: | node=22 - name: Install Node Modules uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-node-modules/main.yaml'Nx Cloud provides a pre-built install-node step to install a custom node version within your workflow. This step is available as of v4 of the workflow steps and requires the minimum image version to be ubuntu22.04-node20.11-v9 or later.
The step resolves the node version in this order, using the first source it finds:
- The
node_versioninput, if provided - A
.nvmrcfile in the root of the repository - The
volta.nodefield in your rootpackage.json
If none of these are set, the agent keeps the node version that ships with the image.
launch-templates: node-22: resource-class: 'docker_linux_amd64/medium' # note the image version of v9, # earlier versions of the base image will not work image: 'ubuntu22.04-node24.14-v1' init-steps: - name: Checkout uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/checkout/main.yaml' - name: Install Node # note the step is only released as of v4 of the workflow steps uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-node/main.yaml' inputs: # omit this input to read the version from a '.nvmrc' # file or the 'volta.node' field in package.json node_version: '22'Here is a simplified launch template manually installing nvm to manage different node version. Feel free to use your preferred tool, other popular options are volta or fnm. The steps follow the general pattern of:
- install tool
- install node with tool
- persist any environment variable changes for future steps
launch-templates: node-22: resource-class: 'docker_linux_amd64/medium' image: 'ubuntu22.04-node24.14-v1' init-steps: - name: Checkout uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/checkout/main.yaml' - name: Install nvm script: | # run nvm install script curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # source the updated profile to get the nvm command available source ~/.profile # install the needed version of node via nvm nvm install 22.23.2 # echo the current path (which now includes the nvm-provided version of node) to NX_CLOUD_ENV echo "PATH=$PATH" >> $NX_CLOUD_ENV - name: Print node version # confirm that the node version has changed script: node -v - name: Install Node Modules uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-node-modules/main.yaml' # Continue setup steps as neededSpecific package manager version
Section titled “Specific package manager version”Workers have corepack enabled by default, allowing you to define the yarn or pnpm version via the package.json.
{ "packageManager": "yarn@4.1.1"}Installing packages
Section titled “Installing packages”You can use apt to install popular linux packages. This is helpful in streamlining setting up various toolchains needed for your workspace.
For example, you can install the GitHub CLI on the agents if needed.
launch-templates: my-linux-medium-js: resource-class: 'docker_linux_amd64/medium' image: 'ubuntu22.04-node24.14-v1' init-steps: - name: Install Extras script: | sudo apt install gh unzip zip -yInstall tools with mise
Section titled “Install tools with mise”mise is a polyglot version manager that can install and manage multiple tools and runtimes (node, Rust, Python, Go, and more) in a single step. Nx Cloud provides a pre-built step to install mise and configure tools on your agents.
If your repo already has a mise.toml file, mise automatically installs the tools defined there.
launch-templates: my-linux-medium-js: resource-class: 'docker_linux_amd64/medium' image: 'ubuntu22.04-node24.14-v1' init-steps: - name: Checkout uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/checkout/main.yaml' - name: Install mise uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-mise/main.yaml' - name: Install Node Modules uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-node-modules/main.yaml'You can define tools inline using the tools input. Each line specifies a tool and version separated by =, @, or a space.
launch-templates: my-linux-medium-js: resource-class: 'docker_linux_amd64/medium' image: 'ubuntu22.04-node24.14-v1' init-steps: - name: Checkout uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/checkout/main.yaml' - name: Install mise uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-mise/main.yaml' inputs: tools: | node=22 rust=1.90 python=3.12 - name: Install Node Modules uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-node-modules/main.yaml'AWS CLI
Section titled “AWS CLI”First, add the environment variables on the Environment variables page of your workspace settings, then map them in the template's env.
Minimally the AWS_REGION (or AWS_DEFAULT_REGION), AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY environment variables are required.
Using the pre-built step simplifies and provides debugging checks to make sure the AWS CLI is properly authenticated to AWS before continuing. The step is recommended for most use cases.
launch-templates: my-linux-medium-js: resource-class: 'docker_linux_amd64/medium' image: 'ubuntu22.04-node24.14-v1' env: AWS_REGION: ${{ vars.AWS_REGION }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} init-steps: - name: Install AWS CLI uses: 'nrwl/nx-cloud-workflows/v6/workflow-steps/install-aws-cli/main.yaml' # no additional inputs required, as all configuration is via environment variablesManual installation follows installing the AWS CLI using the official directions. In order to decompress the installation archive, you'll need to install the unzip package in your step. Manual installation is helpful if a custom installation setup is required. It is helpful to run aws sts get-caller-identity command to make sure you're properly authenticated to AWS before proceeding
launch-templates: my-linux-medium-js: resource-class: 'docker_linux_amd64/medium' image: 'ubuntu22.04-node24.14-v1' env: AWS_REGION: ${{ vars.AWS_REGION }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} init-steps: - name: Install AWS CLI script: | # unzip is required to unzip the AWS CLI installer sudo apt install gh unzip -y curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" unzip awscliv2.zip # run installer, default location is already in the PATH # if installing in a custom location, # then update the $PATH like `PATH=$PATH:[extra-path-items] >> $NX_CLOUD_ENV` sudo ./aws/install # print AWS CLI version to verify command is avaiable aws --version # verify credentials to AWS is working aws sts get-caller-identitySize Workers by workload
Section titled “Size Workers by workload”Nx Cloud can size your Workers by the work each run has to do, picking a size from the remaining work after cache hits. Set small, medium, and large on a worker entry:
worker-templates: default: small: 3 linux-medium-js medium: 8 linux-medium-js large: 12 linux-medium-jsDebugging
Section titled “Debugging”You can add steps to your template which print information about your workspace, toolchains, or any other needs. Below are some common steps people use for debugging such as running nx commands, printing file contents and/or listing directory contents.
launch-templates: my-linux-medium-js: resource-class: 'docker_linux_amd64/medium' image: 'ubuntu22.04-node24.14-v1' env: # enable verbose logging for all steps NX_VERBOSE_LOGGING: true init-steps: - name: 'Debug: Print Nx Report' script: | nx report - name: 'Debug: List Directory Contents' script: | echo $HOME ls -la $HOME output_dir=$HOME/dist # if output directory exists list it's contents if [ -d output_dir ]; then ls -la $output_dir else echo "$output_dir does not exist" fi - name: 'Debug: Show File Contents' script: | cat $HOME/.profile - name: 'Debug: Check For Checkout Files' script: | git diff - name: 'Debug: Print Versions' script: | # note if you use yarn and try to run pnpm, corepack might throw an error at you # saying you're using the wrong package manager, in that case just remove the usage of pnpm echo "Versions:" echo "Node: $(node -v)" echo "NPM: $(npm -v)" echo "Yarn: $(yarn -v)" echo "PNPM: $(pnpm -v)" echo "Golang: $(go version)" echo "Java: $(javac --version)" # add any other toolchain you want - name: 'Debug: Print env' script: | # !!! DO NOT RUN THIS IF YOU HAVE PASSWORD/ACCESS TOKENS IN YOUR ENV VARS !!! # this will print your env as plain text values to the terminal env # This is a safer approach to prevent leaking tokens/passwords echo "SOME_VALUE: $SOME_VALUE"Nx workspace in a subdirectory
Section titled “Nx workspace in a subdirectory”If your Nx workspace is in a subdirectory of your repository, set NX_WORKING_DIRECTORY in your launch template:
launch-templates: my-template: resource-class: 'docker_linux_amd64/medium' image: 'ubuntu22.04-node24.14-v1' env: NX_WORKING_DIRECTORY: './client' init-steps: # ...The install-node-modules step automatically respects this variable (but can be overridden at the step level if your lockfile is hosted at the root). For other steps, set the working directory manually.