stella/.github

Organization-wide GitHub configurations, reusable workflows, and templates.

Contents

Reusable Workflows

Workflow	Description
pr-lint.yml	PR linting: conventional commits, labels, auto-assign
base-checks.yml	Composite workflow calling pr-lint
audit-branch-protection.yml	Drift detection for GitHub rulesets (compliance evidence)
provenance-update.yml	Reusable nightly/manual provenance refresh that opens a PR when provenance/ drifts

Composite Actions

Action	Description
typescript-checks	Setup pnpm, install deps, run lint + format + typecheck
notify-failure	Send failure notification to Google Chat webhook
provenance-check	Install stella/provenance and verify committed provenance artifacts

Templates

• PULL_REQUEST_TEMPLATE.md - Standard PR template
• ISSUE_TEMPLATE/ - Bug report, epic, feature request, other

Label Definitions

• labels.yml - Standardized labels (reference for manual setup)

---

Usage

Base Checks (Recommended)

Use this composite workflow to run all standard checks:

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]

permissions: write-all

jobs:
  checks:
    uses: stella/.github/.github/workflows/base-checks.yml@main
    secrets: inherit

PR Lint

# .github/workflows/pr-lint.yml
name: PR Lint

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]
    branches-ignore:
      - "dependabot/**"

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions: write-all

jobs:
  pr-lint:
    uses: stella/.github/.github/workflows/pr-lint.yml@main
    secrets: inherit

Branch Protection Scripts

Script	Description
apply-ruleset.sh	Idempotent create/update of a GitHub ruleset from JSON

---

Audit Branch Protection

Compares live GitHub rulesets against a checked-in expected config and uploads the result as a compliance artifact (365-day retention). Detects drift and fails if the live config diverges from the expected state.

# .github/workflows/audit-branch-protection.yml
name: Audit Branch Protection

on:
  schedule:
    - cron: "0 8 * * 1" # Monday 08:00 UTC
  workflow_dispatch:

jobs:
  audit:
    uses: stella/.github/.github/workflows/audit-branch-protection.yml@main
    with:
      expected-config-path: .github/branch-protection/ruleset-main.json
    secrets:
      BRANCH_PROTECTION_APP_ID: ${{ secrets.BRANCH_PROTECTION_APP_ID }}
      BRANCH_PROTECTION_APP_KEY: ${{ secrets.BRANCH_PROTECTION_APP_KEY }}

Secrets required:

• BRANCH_PROTECTION_APP_ID — GitHub App ID with Administration: Read and write
• BRANCH_PROTECTION_APP_KEY — GitHub App private key (PEM)

Inputs:

• expected-config-path — path to the expected ruleset JSON (default: .github/branch-protection/ruleset-main.json)

Provenance Update

Runs provenance generate in the calling repository and opens or updates a pull request when checked-in provenance/ artifacts drift. This workflow never pushes directly to main.

The schedule must live in the calling repository.

# .github/workflows/provenance-nightly.yml
name: Provenance Nightly

on:
  schedule:
    - cron: "0 2 * * *"
  workflow_dispatch:

jobs:
  provenance-update:
    permissions:
      contents: write
      pull-requests: write
    uses: stella/.github/.github/workflows/provenance-update.yml@<commit-sha>
    with:
      install-command: bun install --frozen-lockfile
      provenance-version: v0.1.2
    secrets: inherit

Inputs:

• root — repository root to scan (default: .)
• node-version — Node.js version used to install cdxgen (default: 22)
• cdxgen-version — pinned @cyclonedx/cdxgen version (default: 12.1.5)
• install-syft — install Syft before generation (default: false)
• syft-version — pinned Syft release tag (default: v1.42.4)
• provenance-version — GitHub release tag in stella/provenance to install (default: v0.1.2)
• provenance-repository — provenance repository slug (default: stella/provenance)
• install-command — optional dependency install command run before generation (default: bun install --frozen-lockfile)
• branch — branch used for refresh PRs (default: chore/provenance-update)
• commit-message — commit message for generated refreshes (default: chore: refresh provenance artifacts)
• pr-title — pull request title for generated refreshes (default: chore: refresh provenance artifacts)
• pr-body — pull request body for generated refreshes (default: Automated provenance refresh generated by the shared nightly updater.)

Optional secrets:

• auth_token — token for updater PR creation when downstream CI should run; if omitted, the workflow falls back to github.token

Apply Ruleset

Create or update a GitHub ruleset from a JSON file. Idempotent: looks up by name, creates if missing, updates if found.

# Basic usage (from repository root)
.github/branch-protection/apply-ruleset.sh stella/stella \
  .github/branch-protection/ruleset-main.json

# With github-actions[bot] bypass (for SBOM workflow etc.)
.github/branch-protection/apply-ruleset.sh --github-actions-bypass \
  stella/stella .github/branch-protection/ruleset-main.json

---

Composite Actions

typescript-checks

Setup pnpm, install dependencies with caching, and run lint + format + typecheck.

jobs:
  ci:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: TypeScript Checks
        uses: stella/.github/actions/typescript-checks@main

Inputs:

• run-lint - Run pnpm lint (default: true)
• run-format - Run pnpm format (default: true)
• run-typecheck - Run pnpm typecheck (default: true)
• run-codespell - Run codespell spell checker (default: true)
• working-directory - Working directory (default: .)
• node-version-file - Node version file (default: .nvmrc)

notify-failure

Send failure notification to Google Chat webhook.

steps:
  - name: Build
    run: ./build.sh

  - name: Notify on failure
    if: failure()
    uses: stella/.github/actions/notify-failure@main
    with:
      webhook-url: ${{ secrets.GOOGLE_CHAT_WEBHOOK }}
      message: 'Failed to build service-name in production.'

provenance-check

Install a pinned stella/provenance release binary and fail if committed provenance/ artifacts are stale.

steps:
  - uses: actions/checkout@v6

  - name: Provenance
    uses: stella/.github/actions/provenance-check@main
    with:
      provenance-version: v0.1.2

Inputs:

• root - Repository root to scan (default: .)
• node-version - Node.js version used to install cdxgen (default: 22)
• cdxgen-version - Pinned @cyclonedx/cdxgen version (default: 12.1.5)
• install-syft - Install Syft for container provenance checks (default: false)
• syft-version - Pinned Syft release tag (default: v1.42.4)
• provenance-version - GitHub release tag in stella/provenance to install (default: v0.1.2)
• provenance-repository - Provenance repository slug (default: stella/provenance)
• show-diff-on-failure - Print provenance diff output on failure (default: true)