GitHub Action: Set SHAs

Relevant source files

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

• actions/set-shas/src/set-shas.ts
• actions/set-shas/project.json
• actions/plan/README.md
• README.md
• actions/set-shas/CHANGELOG.md

The Set SHAs action identifies and exports the correct Git commit identifiers (SHAs) required for Nx "affected" commands within a GitHub Actions workflow. By determining the appropriate base and head SHAs, it enables Nx to calculate exactly which projects changed between two points in Git history, preventing unnecessary builds or tests of unchanged code.

This action is typically utilized as a setup step before executing high-level orchestration actions such as Plan or Run Many. It integrates with the tripss/nx-extend ecosystem to provide a streamlined CI/CD experience for monorepos.
Sources: README.md:144-146, actions/plan/README.md:41-45

Functional Logic

The action performs different logic based on the GitHub event type. It extracts the head SHA from the current GitHub context and calculates the base SHA through one of three primary paths: Pull Requests, Tagged commits, or Branch history.

SHA Derivation Flow

The following diagram illustrates the decision logic used to determine the baseSha and headSha.

The logic prioritizes specific Git references provided by the GitHub API for pull requests and falls back to manual Git command execution for other events.
Sources: actions/set-shas/src/set-shas.ts:6-46

Base SHA Determination Logic

The action determines the baseSha using these specific rules:

1. Pull Requests: Uses the sha from the base branch reference in the pull request payload.
2. Tagged Repositories: If tags exist, it identifies the most recent tag using git describe --tags --abbrev=0 and resolves it to a commit SHA using git rev-parse {tag}^{commit}.
3. Untagged Repositories: If no tags are found, it resolves the base SHA from the parent of the specified main branch using git rev-parse origin/{main-branch-name}~1.

Sources: actions/set-shas/src/set-shas.ts:11-37, actions/set-shas/CHANGELOG.md:46-47

Configuration and Outputs

The action requires minimal configuration but provides several mechanisms to pass the derived data to subsequent workflow steps.

Inputs

Input Name	Description	Required	Default
main-branch-name	The name of the primary branch (e.g., master or main) used when no tags are found.	No	master

Sources: actions/set-shas/src/set-shas.ts:25

Outputs and Variables

The action provides the derived SHAs in two formats: GitHub Action outputs for step-to-step referencing, and environment variables for direct consumption by Nx.

Name	Type	Description
base	Output	The calculated base commit SHA.
head	Output	The calculated head commit SHA.
NX_BASE	Env Var	Environment variable set for Nx CLI compatibility.
NX_HEAD	Env Var	Environment variable set for Nx CLI compatibility.

Sources: actions/set-shas/src/set-shas.ts:41-44

Technical Implementation

The action is implemented in TypeScript and compiled into a standalone JavaScript file using @vercel/ncc. This ensures all dependencies are bundled, allowing the action to run without a separate npm install step in the runner.

Build Process

The project configuration defines a compile target that executes the bundling process.

{
  "targets": {
    "compile": {
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "npx ncc build ./actions/set-shas/src/set-shas.ts --out ./actions/set-shas/dist"
        ]
      }
    }
  }
}

Sources: actions/set-shas/project.json:7-14

Component Interaction

The action utilizes the following internal and external components:

• @actions/core: Used for logging, setting outputs, and exporting environment variables.
• @actions/github: Used to access the workflow context and pull request payloads.
• execCommand Utility: A local helper used to execute Git CLI commands synchronously and capture their output.

Sources: actions/set-shas/src/set-shas.ts:1-4, actions/set-shas/src/set-shas.ts:18-34

Summary

The Set SHAs action acts as the foundation for efficient CI in Nx monorepos by automating the Git history analysis required for affected commands. It ensures that the base SHA is accurately retrieved from pull request metadata or Git tags, falling back to branch history when necessary. This precision allows developers to significantly reduce CI execution time by only targeting modified projects.
Sources: actions/plan/README.md:41-45, actions/set-shas/src/set-shas.ts:6-40