> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# nrwl/nx

A Orb which includes helpful commands for running Nx commands in the CI


## Commands

### set-shas

Derives SHAs for base and head for use in `nx affected` commands in CI


| Parameter | Type | Default | Description |
|---|---|---|---|
| `allow-not-run-workflow` | boolean | false | By default, only workflows with CircleCI status of "success" will be detected for the main branch.
Enable this option to also detect workflows with CircleCI status of "not_run" in case your workflow requires manual approvals.
 |
| `allow-on-hold-workflow` | boolean | false | By default, only workflows with CircleCI status of "success" will be detected for the main branch.
Enable this option to also detect workflows with CircleCI status of "on_hold" in case your workflow requires manual approvals.
 |
| `error-on-no-successful-workflow` | boolean | false | By default, if no successful workflow is found on the main branch to determine the SHA,
we will log a warning and use HEAD~1. Enable this option to error and exit instead.
 |
| `main-branch-name` | string | main | The name of the main branch in your repo, used as the target of PRs. E.g. main, master etc.
 |
| `skip-branch-filter` | boolean | false | By default, the workflow runs will be filtered by `main` branch. This works fine with standard `push` event. If you
want to use the orb for non-push events (e.g. tag, label etc.) you need to disable branch filtering.
 |
| `workflow-name` | string |  | By default, the script is looking for the last successful job across all workflows.
Set this param to search for the last successful job within a specific workflow.
 |

## Examples

### custom

You need to specify `main-branch-name` if different than `main`. If last successful workflow run was not found, by default we report warning and fallback to HEAD~1. You can instead make this a hard error by settting 'error-on-no-successful-workflow' to true. If you need to find the last successful job within a specific workflow, set the value of 'workflow-name'. By default we check for `success` state of the workflow. If you would like to include also `on_hold` states, you can do so by enabling `allow-on-hold-workflow`.


```yaml
version: '2.1'
orbs:
  nx: nrwl/nx@1.7.0
jobs:
  build:
    docker:
      - image: cimg/node:14.17-browsers
    environment:
      MAIN_BRANCH_NAME: master
    steps:
      - checkout
      - run:
          command: yarn install --frozen-lockfile
          name: Install dependencies
      - nx/set-shas:
          allow-on-hold-workflow: true
          error-on-no-successful-workflow: true
          main-branch-name: master
          workflow-name: nx-pipeline
      - run:
          command: yarn nx affected --target=build --base=$NX_BASE
          name: Run Builds
      - run:
          command: yarn nx affected --target=test --base=$NX_BASE
          name: Run Unit Tests
workflows: null
```

### default

You can use `set-shas` without parameters using the default values provided. Check API for more information.


```yaml
version: '2.1'
orbs:
  nx: nrwl/nx@1.7.0
jobs:
  build:
    docker:
      - image: cimg/node:14.17-browsers
    steps:
      - checkout
      - run:
          command: yarn install --frozen-lockfile
          name: Install dependencies
      - nx/set-shas
      - run:
          command: >-
            yarn nx affected --target=build --base=$NX_BASE --parallel
            --max-parallel=3
          name: Run Builds
      - run:
          command: >-
            yarn nx affected --target=test --base=$NX_BASE --parallel
            --max-parallel=2
          name: Run Unit Tests
workflows: null
```

### private

To use this orb with a private repository on your main branch, you need to grant the orb access to your CircleCI API. You can do this by creating an environment variable called `CIRCLE_API_TOKEN` in the context or the project. The remaining usage code is intentionally omitted, since it does not differ from the normal usage.
Note: It should be a user token, not project token.


```yaml
version: '2.1'
orbs:
  nx: nrwl/nx@1.7.0
workflows: null
```

### tags

You can use `set-shas` also for non-push events, but you need to skip the branch check in that case.


```yaml
version: '2.1'
orbs:
  nx: nrwl/nx@1.7.0
jobs:
  build:
    docker:
      - image: cimg/node:14.17-browsers
    steps:
      - checkout
      - run:
          command: yarn install --frozen-lockfile
          name: Install dependencies
      - nx/set-shas:
          skip-branch-filter: true
      - run:
          command: >-
            yarn nx affected --target=build --base=$NX_BASE --parallel
            --max-parallel=3
          name: Run Builds
      - run:
          command: >-
            yarn nx affected --target=test --base=$NX_BASE --parallel
            --max-parallel=2
          name: Run Unit Tests
workflows:
  my-workflow:
    jobs:
      - build:
          filters:
            branches:
              ignore: /.*/
            tags:
              only: /^v[0-9]+(\.[0-9]+)*$/
```