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:

jobs:
  nix-ci:
    uses: monarchic-langs/.github/.github/workflows/nix-ci.yml@main
    with:
      publish_cache: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
    secrets: inherit

The reusable workflow runs on vars.CI_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.

CodeQL

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

name: CodeQL

on:
  push:
    branches: [monarchic]
  schedule:
    - cron: "20 18 * * 2"
  workflow_dispatch:

permissions:
  contents: read
  security-events: write

jobs:
  codeql:
    uses: monarchic-langs/.github/.github/workflows/codeql.yml@main
    with:
      matrix: >-
        {"include":[
          {"language":"java-kotlin","build-mode":"manual","build-command":"nix build .#default"},
          {"language":"javascript","build-mode":"none","build-command":""},
          {"language":"python","build-mode":"none","build-command":""}
        ]}
    secrets:
      MONARCHIC_GITHUB_PAT: ${{ secrets.MONARCHIC_GITHUB_PAT }}

The reusable workflow runs on the shared self-hosted 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.

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: monarchic-langs/.github/.github/workflows/release.yml@main
    secrets: inherit

The reusable workflow runs on vars.CI_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 from Node package repositories whose release is an npm publish from a semantic version tag:

name: Release

on:
  push:
    tags: [v*.*.*]

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

jobs:
  npm-publish:
    uses: monarchic-langs/.github/.github/workflows/npm-publish.yml@main
    with:
      default_branch: monarchic
      publish_command: npm publish --provenance
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

The reusable workflow first runs the shared release preflight, which verifies the semantic version tag, target branch, and successful Nix CI run for the tagged commit. It then installs dependencies, builds, and publishes with the caller-provided command.

GitHub Release Draft

Use .github/workflows/github-release-draft.yml when a repository creates a draft GitHub release from a semantic version tag after Nix CI has passed:

name: Prepare Release

on:
  push:
    tags: [v*.*.*]

permissions:
  actions: read
  contents: write

jobs:
  draft:
    uses: monarchic-langs/.github/.github/workflows/github-release-draft.yml@main
    with:
      default_branch: monarchic
      release_notes_command: node ./scripts/release-notes.mjs "$GITHUB_REF_NAME"

The reusable workflow runs the shared release preflight first, then checks out the caller repository, resolves release notes with the caller-provided command, and creates a draft GitHub release for the tag.

Release Command

Use .github/workflows/release-command.yml when a repository needs a custom publish or deploy command, but should still share the standard release gate:

name: Release

on:
  release:
    types: [published]

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

jobs:
  release:
    uses: monarchic-langs/.github/.github/workflows/release-command.yml@main
    with:
      default_branch: monarchic
      pnpm_version: 9.6.0
      install_command: pnpm install --frozen-lockfile
      build_command: pnpm -r run build
      release_command: pnpm publish --provenance
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

The reusable workflow verifies the tag, target branch, and prior Nix CI success before installing dependencies, building release artifacts when requested, and running the caller-provided release command.

Manual Command

Use .github/workflows/manual-command.yml for trusted manual jobs that must mutate external systems, such as legacy deploy scripts, while keeping runner selection and setup centralized:

name: Deploy

on:
  workflow_dispatch:

permissions:
  contents: write
  id-token: write

jobs:
  deploy:
    uses: monarchic-langs/.github/.github/workflows/manual-command.yml@main
    with:
      node_version: "22"
      pnpm_version: "10"
      command: nix run .#deploy
    secrets: inherit

Keep build, test, lint, smoke, and security gates in flake checks. Use this workflow for explicit manual operations that should not run automatically from pull requests or ordinary pushes.

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: monarchic-langs/.github/.github/workflows/maintenance.yml@main
    with:
      check_flake: true
      maintenance_command: nix run .#maintenance-report
    secrets: inherit

The reusable workflow runs on vars.CI_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.

Maintenance PR

Use .github/workflows/maintenance-pr.yml when scheduled or manual maintenance should update checked-in files through a pull request:

name: Update Generated Files

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

permissions:
  contents: write
  pull-requests: write

jobs:
  update-generated-files:
    uses: monarchic-langs/.github/.github/workflows/maintenance-pr.yml@main
    with:
      maintenance_command: nix run .#update-generated-files
      add_paths: |
        generated/
      branch: maintenance/update-generated-files
      title: Update generated files
      commit_message: chore: update generated files
    secrets: inherit

The reusable workflow runs on the self-hosted Monarchic-local NixOS runner, optionally evaluates nix flake check --no-build, runs the repo-local command, and opens a pull request only when files changed. Keep repo-specific generation, upgrade, and validation logic in flake apps or checks.

Issue Translate

Use .github/workflows/issue-translate.yml from repositories that want issue and issue-comment translation automation:

name: Issue Translate

on:
  issue_comment:
    types: [created]
  issues:
    types: [opened]

permissions:
  issues: write

jobs:
  issue-translate:
    uses: monarchic-langs/.github/.github/workflows/issue-translate.yml@main
    with:
      custom_bot_note: Example translate bot

The reusable workflow runs on vars.CI_RUNNER_LABELS and delegates translation to usthe/issues-translate-action.

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: monarchic-langs/.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. 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.