Pipe Inspector

Detect which components changed between semver tags in monorepo CI pipelines.

In a monorepo with multiple components (each in its own directory), CI pipelines triggered by version tags have no reliable way to know which components actually changed. GitLab's rules: changes: doesn't work on tag pipelines, and GitHub Actions has similar limitations. Pipe Inspector fills this gap by comparing the current tag against the previous one using git diff, reporting exactly which paths have changes.

Designed to work alongside AgileFlow but compatible with any tag-based release workflow.

Installation

npm install -g @logickernel/pipe-inspector

Or run directly in CI without installing:

npx @logickernel/pipe-inspector component-a/ component-b/

Requires Node.js >= 14.0.0. No runtime dependencies.

Usage

pipe-inspector [options] <path> [<path>...]

Check if specific directories changed between the last two semver tags:

pipe-inspector component-a/ component-b/ component-c/

component-a/  changed
component-b/  unchanged
component-c/  unchanged

Options

| Option | Description | |---|---| | --tag <tag> | Set the current tag explicitly (default: auto-detect from CI_COMMIT_TAG, GITHUB_REF_NAME, or git describe) | | --format <fmt> | Output format: text (default), json, dotenv | | --version | Print the version | | -h, --help | Show help |

Exit codes

| Code | Meaning | |---|---| | 0 | At least one specified path has changes | | 1 | None of the specified paths have changes | | 2 | Error (bad arguments, not a git repo, shallow clone, etc.) |

Output formats

json — machine-readable, includes tag info and the list of changed files:

pipe-inspector --format json component-a/ component-b/

{"changed":true,"currentTag":"v0.9.0","previousTag":"v0.8.0","paths":{"component-a/":true,"component-b/":false},"files":["component-a/main.py"]}

dotenv — one variable per path plus version info, suitable for GitLab dotenv artifacts:

pipe-inspector --format dotenv component-a/ component-b/

CHANGED_COMPONENT_A=true
CHANGED_COMPONENT_B=false
CURRENT_VERSION=0.9.0
PREV_VERSION=0.8.0

The CURRENT_VERSION and PREV_VERSION variables (without v prefix) are included automatically, so downstream CI jobs can use them for retagging without additional shell logic.

CI Examples

GitLab CI — skip build when unchanged

The || exit 0 pattern makes the job succeed immediately when no changes are detected, skipping all subsequent script lines:

build-component-a:
  stage: build
  image: node:20
  script:
    - npx @logickernel/pipe-inspector component-a/ || exit 0
    - echo "Building component-a..."
  rules:
    - if: '$CI_COMMIT_TAG =~ /^v/'

GitLab CI — kaniko build with crane retag

For Docker image builds using kaniko, a detect-changes job runs pipe-inspector once and exports dotenv variables. Build jobs then either compile with kaniko or retag the previous image with crane (a manifest-level operation that skips downloading image layers entirely):

stages:
  - detect
  - build

detect-changes:
  stage: detect
  image: node:20-alpine
  before_script:
    - apk add --no-cache git
  script:
    - npx @logickernel/pipe-inspector --format dotenv component-a/ component-b/ | tee changes.env || true
    - cat changes.env
    - wget -qO- "https://github.com/google/go-containerregistry/releases/latest/download/go-containerregistry_Linux_x86_64.tar.gz" | tar xz crane
    - chmod +x crane
  artifacts:
    reports:
      dotenv: changes.env
    paths:
      - crane
  rules:
    - if: '$CI_COMMIT_TAG =~ /^v/'

.build-component:
  stage: build
  image:
    name: gcr.io/kaniko-project/executor:debug
    entrypoint: [""]
  needs:
    - detect-changes
  script:
    - VERSION=${CI_COMMIT_TAG#v}
    - IMAGE=${CI_REGISTRY_IMAGE}/${COMPONENT}
    - CHANGE_VAR="CHANGED_$(echo "${COMPONENT}" | tr '[:lower:]' '[:upper:]' | tr '-/./' '____' | sed 's/_*$//')"
    - eval "IS_CHANGED=\${${CHANGE_VAR}:-false}"
    - |
      build_image() {
        echo "Building ${COMPONENT}..."
        /kaniko/executor \
          --context "${CI_PROJECT_DIR}/${COMPONENT}" \
          --dockerfile "${CI_PROJECT_DIR}/${COMPONENT}/Dockerfile" \
          --build-arg VERSION=${VERSION} \
          --destination "${IMAGE}:${VERSION}" \
          --cache=true \
          --cache-repo="${IMAGE}/cache"
      }
    - |
      mkdir -p /kaniko/.docker
      echo "{\"auths\":{\"${CI_REGISTRY}\":{\"auth\":\"$(printf '%s:%s' "${CI_REGISTRY_USER}" "${CI_REGISTRY_PASSWORD}" | base64)\"}}}" > /kaniko/.docker/config.json
    - |
      if [ "${IS_CHANGED}" = "true" ]; then
        build_image
      elif [ -n "${PREV_VERSION}" ]; then
        echo "No changes in ${COMPONENT}, retagging ${PREV_VERSION} as ${VERSION}..."
        ${CI_PROJECT_DIR}/crane auth login -u "${CI_REGISTRY_USER}" -p "${CI_REGISTRY_PASSWORD}" "${CI_REGISTRY}"
        ${CI_PROJECT_DIR}/crane tag "${IMAGE}:${PREV_VERSION}" "${VERSION}" || build_image
      else
        build_image
      fi
  rules:
    - if: '$CI_COMMIT_TAG =~ /^v/'

build-component-a:
  extends: .build-component
  variables:
    COMPONENT: component-a

build-component-b:
  extends: .build-component
  variables:
    COMPONENT: component-b

GitHub Actions

jobs:
  build:
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npx @logickernel/pipe-inspector component-a/ || exit 0
      - run: echo "Building component-a..."

CI Requirements

• Full git history is required. Shallow clones cannot diff between tags. Set GIT_DEPTH: 0 in GitLab CI or fetch-depth: 0 in GitHub Actions.
• Tag auto-detection reads CI_COMMIT_TAG (GitLab) or GITHUB_REF_NAME (GitHub Actions). Use --tag to override.

Development

git clone https://code.logickernel.com/tools/pipe-inspector.git
cd pipe-inspector
npm install
npm test

License

ISC