GitHub Action: Plan

Relevant source files

The following files were used as context for generating this wiki page:

• actions/plan/src/plan.ts
• actions/plan/README.md
• actions/plan/package.json
• actions/plan/project.json
• actions/run-many/src/utils/generate-summary.ts
• README.md

The GitHub Action: Plan analyzes an Nx workspace to determine which projects require execution based on tags and affected status. It generates a build matrix that allows subsequent CI steps to deploy or test only the necessary projects, effectively disabling those not ready for deployment.

This action integrates with the broader nx-extend ecosystem, specifically intended to provide outputs for the run-many action. By using project tags, it facilitates complex deployment logic such as environment-specific filtering or conditional service activation.

Sources: actions/plan/README.md:1-7, README.md:104-118

Core Logic and Architecture

The Plan action identifies projects through the Nx CLI and filters them against project-specific tags. It reads the workspace's project graph to validate target availability and tag conditions before calculating the optimal number of parallel jobs.

Execution Flow

The following diagram illustrates how the action processes workspace data to generate a plan:

The action first retrieves projects using npx nx show projects --json. If affectedOnly is enabled, it appends the --affected flag to this command. It then uses readCachedProjectGraph() to access project metadata, including tags and defined targets.

Sources: actions/plan/src/plan.ts:16-56

Project Filtering logic

Projects are excluded if they contain the tag ci=off. For each requested target, the action verifies if the project defines that target and if it meets the required targetTag conditions.

Inputs and Configuration

The action accepts several inputs to customize how it plans the execution matrix. Many inputs are dynamic, prefixed by the target name (e.g., buildTag, testMaxJobs).

Standard Inputs

Input	Type	Description
targets	Multiline String	The list of Nx targets to plan for (e.g., build, test, e2e).
affectedOnly	Boolean	If true, only considers projects affected by changes.
workingDirectory	String	The directory where the Nx workspace is located.

Dynamic Target Inputs

For every target defined in the targets input, the following options are available:

Option Pattern	Description
<target>Tag	Tags required for a project to be included for this target. Supports conditional logic (e.g., service!=vercel).
<target>MaxJobs	The maximum number of parallel jobs to create for this target.
<target>Parallel	The number of projects Nx can run in parallel within a single job.
<target>PreTargets	Targets to run before the main target.
<target>PostTargets	Targets to run after the main target.
<target>Config	Specific Nx configuration to use for the target.

Sources: actions/plan/src/plan.ts:12-15, actions/plan/src/plan.ts:60-66, actions/plan/README.md:46-60

Matrix Generation

The action generates a matrix output containing an include array. This array is formatted for use in a GitHub Actions strategy.matrix field.

Job Calculation Logic

The action calculates maxJobCount to ensure work is distributed efficiently. It ensures that each job runs at least 2 projects if possible, up to the limit defined by <target>MaxJobs.

// actions/plan/src/plan.ts:100-107
      let maxJobCount = 1
      for (let i = maxJobs; i > 0; i--) {
        // Each job needs to at-least run 2 projects
        if ((amountOfProjectsWithTarget.length / i) >= 2) {
          maxJobCount = i
          break
        }
      }

Sources: actions/plan/src/plan.ts:100-107

Output Structure

The matrix output contains objects with the following properties:

• target: The Nx target to execute.
• tag: The tag conditions used for filtering.
• index: The current job index (1-based).
• count: Total jobs for this target.
• parallel: Parallelism setting for the Nx command.
• preTargets / postTargets: Concatenated strings of secondary targets.

Sources: actions/plan/src/plan.ts:109-119, actions/plan/src/plan.ts:128-131

Integration Example

The Plan action is typically used in a setup job to provide the matrix for a subsequent distributed-task job.

jobs:
  setup:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.plan.outputs.matrix }}
    steps:
      - name: Plan
        id: plan
        uses: tripss/nx-extend/actions/plan@master
        with:
          targets: build
          buildMaxJobs: 3

  distributed-task:
    needs: setup
    strategy:
      matrix: ${{ fromJSON(needs.setup.outputs.matrix) }}
    steps:
      - name: Execute
        uses: tripss/nx-extend/actions/run-many@master
        with:
          target: ${{ matrix.target }}
          index: ${{ matrix.index }}
          count: ${{ matrix.count }}

Sources: actions/plan/README.md:11-85

Summary of Capabilities

The GitHub Action: Plan provides a sophisticated way to manage CI/CD scaling within Nx monorepos. By leveraging the project graph and custom tags, it minimizes redundant computations and allows for highly granular control over which parts of the workspace are processed during a pipeline run.

Sources: actions/plan/README.md:1-5, actions/plan/src/plan.ts:125-135