Creating Custom Steps
While Nx Cloud provides several pre-built steps, you can create custom steps to suit your specific needs. Custom steps are defined by creating a new YAML file.
Defining a Custom Step
To create a custom step, follow these steps:
1. Create a New YAML File: Create a new YAML file in your .nx/workflows directory (e.g., custom-step.yaml)
Custom steps do not need to be in the .nx/workflows directory. However, they must be available on a public GitHub repository. You have a few options for organizing your custom steps:
- Same Repository as your Nx Workspace: Ideal for open-source projects where the Nx workspace is publicly accessible.
- Create a Dedicated Repository: Create a separate repository to store a collection of custom steps. This is useful for sharing steps across multiple projects or teams, or if your main Nx workspace is not on GitHub or is private.
2. Define the Step Template: Below is an example of a custom step definition:
1name: 'Custom Step'
2description: 'This is a custom step that does XYZ.'
3definition:
4 using: 'node'
5 main: './scripts/custom-script.js'
6 post: './scripts/post-custom-script.js'
7inputs:
8 - name: 'input1'
9 description: 'Description for input1'
10 default: 'default_value'
11 required: true
12 - name: 'input2'
13 description: 'Description for input2'
14 required: false
15Explanation of Fields
name:
- The name of the custom step.
description:
- A description of what the custom step does.
definition:
- using: The runtime environment. Supported values are
nodeandaggregate.- node: If
usingis set tonode, then onlymainandpostcan be used. - aggregate: If
usingis set toaggregate, then onlystepscan be used.
- node: If
- main: Path to the main script to run (only if
usingisnode). - post: Path to the post script to run (only if
usingisnode).- runs before the agent is cleaned up
- steps: A list of sub-steps to be executed (only if
usingisaggregate). Steps follow the same definition as launch templates.
- using: The runtime environment. Supported values are
inputs:
- name: The name of the input.
- description: A description of the input.
- default: Default value for the input.
- required: Whether the input is required.
Using Inputs in Scripts
If your custom step has inputs, they can be accessed in scripts or JavaScript files using environment variables. Each input is prefixed with NX_CLOUD_INPUT_. For example, if you have an input called input1, you can access it in a JavaScript file like this:
1const input1 = process.env.NX_CLOUD_INPUT_input1;
2console.log(`The value of input1 is: ${input1}`);
3Using Custom Steps in Launch Templates
Once you've defined your custom step, you can use it in your launch templates by referencing the custom step file. Here's an example:
Custom Step locationWhen specifying the location for the custom step, you must include a branch or tag (e.g., main). Using a direct URL to the repository without a branch or tag will not work.
1launch-templates:
2 custom-template:
3 resource-class: 'docker_linux_amd64/medium'
4 image: 'ubuntu22.04-node20.11-v7'
5 init-steps:
6 - name: Custom Step
7 uses: 'your-org/your-repo/main/.nx/workflows/custom-steps.yaml'
8 env:
9 CUSTOM_VAR: 'custom_value'
10 inputs:
11 input1: 'value1'
12 input2: 'value2'
13While you can use both env and inputs to pass values to custom steps, it is recommended to use inputs as they offer validation support, whereas env does not.
Validating Custom Steps
Just like launch templates, you should validate your custom steps to ensure they are defined correctly. In your CI pipeline, use the nx-cloud validate command with the --step-file flag to ensure nobody merges in invalid changes to your step:
❯
nx-cloud validate --workflow-file=./.nx/workflows/custom-steps.yaml --step-file
Ensure your custom steps are committed to your source control repository before running the validation.
By defining and organizing custom steps in this way, you can create highly tailored workflows that meet the specific needs of your projects and CI/CD pipelines.