@e-square/nx-affected-matrix

Summary

A GitHub Action that outputs a matrix of NX targets (with some other useful outputs.
This action enables CI level parallelism by splitting the affected projects into multiple parallel jobs.

It is recommended to use this action's outputs with @e-square/nx-distributed-task, check out the monorepo's README for a full usage example of both actions.

Usage

Inputs

name	description	default	required
targets	Comma-delimited targets to run	-	✓
maxDistribution	Maximum distribution of jobs per target. Can be number that will be used for all targets, or an array/object that matches the targets input	3	✗
workingDirectory	Path to the Nx workspace, needed if not the repository root	-	✗
main-branch	nx-set-shas action input. The 'main' branch of your repository (the base branch which you target with PRs)	'main'	✗
workflow-id	The ID of the github action workflow to check for successful run or the name of the file name containing the workflow	-	✗
checkout	Should the action do git checkout	true	✗
args	Space-delimited args to add to nx affected command	-	✗

Outputs

name	description
matrix	The affected matrix to be consumed
apps	A comma-delimited list of the affected apps
libs	A comma-delimited list of the affected libs (including non buildable libs)
hasChanges	boolean that will be true when there is at least one job in the affected matrix

jobs:
  setup:
    runs-on: ubuntu-latest
    name: Affected Matrix
    outputs:
      hasChanges: ${{ steps.affected.outputs.hasChanges }}
      matrix: ${{ steps.affected.outputs.matrix }}
    steps:
      - name: Calculate affected projects
        uses: e-square-io/nx-affected-matrix@v2
        id: affected
        with:
          targets: 'test,build'
          maxDistribution: 3

For each supplied target, the action will slice the list of affected projects into multiple groups.
So the output matrix from the example above will be:

{
  "include": [
    {
      "target": "test",
      "projects": "project1,project2"
    },
    {
      "target": "test",
      "projects": "project3,project4"
    },
    ...
  ]
}

Control distribution per target

In some cases it might be useful to change the distribution only for a particular target.
maxDistribution input can receive an object with keys matching to the supplied targets or an array that will match by index. e.g:

- name: Calculate affected projects
  uses: e-square-io/nx-affected-matrix@v2
  id: affected
  with:
    targets: 'test,build'
    maxDistribution: '[2,1]' # or '{"test": 2, "build": 1}'

will produce 2 jobs for test target and one for build target.
Note: The action allows to set a partial distribution config, any target that isn't specified in the config will receive the default distribution value (3)

FAQ

Q: Can I use this action without any prior actions? (checkout, npm ci, etc)
A: Yes! The action is already bundled with everything needed to run NX's affected command.
Also, the action will do the checkout for you with clean: false & fetch-depth: 0 (which is required in order to calculate the changes).

Known Issues

1. Cannot read properties of undefined (reading 'endsWith')
   Workaround: make sure all of your projects has root defined in their project.json config file