Reusable GitHub Workflows

Reusable GitHub Workflows

All nself-org repositories share a set of reusable GitHub Actions workflows hosted in the nself-org/.github repository. Calling these templates keeps CI/CD configuration consistent and reduces duplication.

Available Templates

Template	Purpose	Key Inputs
test	Run the test suite with pnpm	node-version, working-directory, test-command
build	Build the package and upload an artifact	node-version, working-directory, build-command
release	Build, test, and publish to npm	node-version, working-directory, publish-command
doc-sync	Verify documentation is in sync with source	node-version, working-directory, check-command
clean-root	Enforce clean repository root (no stray Markdown)	allowed-markdown
security	Audit dependencies, licenses, and secrets	node-version, working-directory, fail-on-severity

All inputs have sensible defaults so minimal configuration is required for standard pnpm packages.

Prerequisites

• pnpm is the required package manager (pnpm-lock.yaml must be present)
• Node.js ≥ 18 (templates default to Node 20)
• For the release template: add NPM_TOKEN as a repository or organization secret

Basic Usage

Reference a template with uses: nself-org/.github/.github/workflows/<name>.yml@v1:

.github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    uses: nself-org/.github/.github/workflows/test.yml@v1
    with:
      node-version: "22"

  build:
    needs: test
    uses: nself-org/.github/.github/workflows/build.yml@v1
    with:
      node-version: "22"

Full Example

A complete workflow using all six templates:

.github/workflows/ci.yml

name: CI / CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  release:
    types: [published]

jobs:
  test:
    uses: nself-org/.github/.github/workflows/test.yml@v1
    with:
      node-version: "22"
      working-directory: "apps/my-package"
      test-command: "pnpm run test:ci"

  build:
    uses: nself-org/.github/.github/workflows/build.yml@v1
    with:
      node-version: "22"
      working-directory: "apps/my-package"

  doc-sync:
    uses: nself-org/.github/.github/workflows/doc-sync.yml@v1
    with:
      working-directory: "apps/my-package"

  clean-root:
    uses: nself-org/.github/.github/workflows/clean-root.yml@v1

  security:
    uses: nself-org/.github/.github/workflows/security.yml@v1
    with:
      working-directory: "apps/my-package"
      fail-on-severity: "high"

  release:
    if: github.event_name == 'release'
    needs: [test, build]
    uses: nself-org/.github/.github/workflows/release.yml@v1
    with:
      node-version: "22"
      working-directory: "apps/my-package"
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Versioning

Templates are pinned to @v1. Breaking changes create a new major version tag (@v2). Improvements that do not break existing callers are applied in-place on the current major tag.

Source

Templates live in workflow-templates/ in the nself-org/.github repository. Each template has a matching .properties.json file that enables discovery via the GitHub Actions UI (“Actions → New workflow”).