Monarchic Meta GitHub Defaults

Shared GitHub Actions workflows and organization defaults for Monarchic repositories.

Reusable Workflows

Nix CI

Use .github/workflows/nix-ci.yml from repositories with a Nix flake:

name: Nix CI

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

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

jobs:
  nix-ci:
    uses: OmnisGenomics/.github/.github/workflows/nix-ci.yml@main
    with:
      publish_cache: ${{ github.ref == 'refs/heads/main' }}
    secrets:
      MONARCHIC_GITHUB_PAT: ${{ secrets.MONARCHIC_GITHUB_PAT }}

The reusable workflow runs on the self-hosted Monarchic-local NixOS runner labels, builds every packages.${system} output, builds every checks.${system} output, runs nix flake check, and optionally signs and uploads built store paths to the Monarchic Nix binary cache. It is intended to run for trusted pushes to main, including merges, and for manual dispatches. If the caller repository has a MONARCHIC_GITHUB_PAT secret, the workflow uses it for private flake inputs.

Release

Use .github/workflows/release.yml as a preflight job from repository release workflows before publishing packages, images, deployments, or GitHub releases:

jobs:
  release-preflight:
    uses: OmnisGenomics/.github/.github/workflows/release.yml@main
    secrets: inherit

The reusable workflow runs on the self-hosted Monarchic-local NixOS runner labels, requires a tag ref, checks that the tag matches v*.*.* by default, verifies that the tag points at origin/main, and verifies that the caller repository already has a successful Nix CI workflow run for the tagged commit. It performs no publishing or deployment itself; caller workflows keep repo-specific release steps behind this preflight job.

NPM Publish

Use .github/workflows/npm-publish.yml for tag-driven npm package publishing after the release preflight has verified the tag and required Nix CI run:

name: Publish CLI

on:
  push:
    tags:
      - "cli-v*"

jobs:
  publish:
    uses: OmnisGenomics/.github/.github/workflows/npm-publish.yml@main
    with:
      tag_pattern: '^cli-v[0-9]+[.][0-9]+[.][0-9]+$'
      tag_prefix: cli-v
      required_workflow: Nix CI
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

The reusable workflow runs the shared release preflight, checks that the version encoded in the tag matches package.json, installs dependencies, builds the package, and publishes with npm provenance. Callers can override the package directory, Node.js version, install command, build command, and publish arguments when the package is not a root npm ci && npm run build project.

Maintenance

Use .github/workflows/maintenance.yml from scheduled or manual caller workflows that should produce a report before any automation becomes mutating:

name: Maintenance

on:
  workflow_dispatch:
  schedule:
    - cron: "17 9 * * 1"

jobs:
  maintenance:
    uses: OmnisGenomics/.github/.github/workflows/maintenance.yml@main
    with:
      check_flake: true
      maintenance_command: nix run .#maintenance-report
    secrets: inherit

The reusable workflow runs on the self-hosted Monarchic-local NixOS runner labels, optionally evaluates nix flake check --no-build, optionally runs a repo-local maintenance command, writes a Markdown report to the job summary, and uploads it as an artifact. It does not push commits, open pull requests, deploy, publish, or mutate external systems by default.

Pages

Use .github/workflows/pages.yml from repositories whose static site is built as a Nix flake package:

name: Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  pages:
    uses: OmnisGenomics/.github/.github/workflows/pages.yml@main
    with:
      package_attr: docs
    secrets: inherit

The reusable workflow runs on the self-hosted Monarchic-local NixOS runner labels, builds the requested flake package, uploads the resulting static site artifact, and deploys it to GitHub Pages.

CLA

Use .github/workflows/cla.yml from repositories that require maintainer approval before merging external public-core contributions:

name: CLA

on:
  pull_request_target:
    types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled, edited]
  workflow_dispatch:

permissions:
  pull-requests: read

jobs:
  CLA:
    name: CLA
    uses: OmnisGenomics/.github/.github/workflows/cla.yml@main

The reusable workflow runs on the self-hosted Monarchic-local NixOS runner labels. It passes for repository members, owners, collaborators, draft pull requests, or pull requests labeled cla-approved; otherwise it fails with the repository's inbound licensing reminder. It is a policy gate, not a build or test workflow.

CodeQL

Use .github/workflows/codeql.yml for trusted default-branch CodeQL analysis. Move manual build commands into flake apps so the caller stays a thin policy wrapper:

name: CodeQL

on:
  push:
    branches: [main]
    tags-ignore:
      - "v*"
  workflow_dispatch:

permissions:
  contents: read
  security-events: write

jobs:
  analyze:
    uses: OmnisGenomics/.github/.github/workflows/codeql.yml@main
    with:
      matrix: >-
        {"include":[
          {"language":"c-cpp","build-mode":"manual","build-command":"nix run .#codeql-cpp-build"},
          {"language":"javascript","build-mode":"none","build-command":""},
          {"language":"rust","build-mode":"none","build-command":""}
        ]}
    secrets:
      MONARCHIC_GITHUB_PAT: ${{ secrets.MONARCHIC_GITHUB_PAT }}

The reusable workflow runs on the self-hosted Monarchic-local NixOS runner labels. Matrix entries with a non-empty build-command install Nix and execute that command after CodeQL initialization; entries without a build command use CodeQL's none build mode.

OpenSSF Scorecard

Use .github/workflows/scorecard.yml for trusted default-branch, scheduled, or branch-protection Scorecard analysis:

name: OpenSSF Scorecard

on:
  branch_protection_rule:
  push:
    branches: [main]
  schedule:
    - cron: "22 14 * * 2"
  workflow_dispatch:

permissions:
  contents: read
  security-events: write
  id-token: write

jobs:
  scorecard:
    uses: OmnisGenomics/.github/.github/workflows/scorecard.yml@main

The reusable workflow runs OpenSSF Scorecard on the self-hosted Monarchic-local NixOS runner labels and uploads the SARIF result to code scanning.

Docker CI

Use .github/workflows/docker-ci.yml only for repositories where Docker is still an explicit build or runtime contract:

name: Docker CI

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  docker-ci:
    uses: OmnisGenomics/.github/.github/workflows/docker-ci.yml@main
    with:
      runner_labels: '["self-hosted","Linux","X64","monarchic-local","docker"]'
      context: .
      dockerfile: Dockerfile
      image_name: example-docker-ci
      smoke_command: docker run --rm example-docker-ci --version

The reusable workflow requires a Docker-capable runner label set, verifies Docker availability, builds the requested image, and optionally runs a smoke command. It can also push explicitly supplied image tags when Docker image publishing is part of a tag-driven release contract:

jobs:
  docker:
    uses: OmnisGenomics/.github/.github/workflows/docker-ci.yml@main
    with:
      image_name: ghcr.io/omnisgenomics/example:${{ github.ref_name }}
      image_tags: |
        ghcr.io/omnisgenomics/example:latest
      push: true

Prefer moving build, test, lint, smoke, and security behavior into flake checks and using nix-ci.yml when Docker is not part of the repo's real contract.