Consumer conventions

These shared actions and workflows are deliberately thin — they assume the consuming repo follows the FSH conventions below. If a repo diverges, override the relevant input or keep a local definition for that one piece.

Repo-wide

  • Org / default branch. All repos live under FSHTech and use main as the default branch (release, docs, and sibling clones all target main).

  • Pin to @v1. Consumers reference everything at the moving major tag (…@v1), updated in this repo via git tag -f v1 && git push -f origin v1.

  • Thin callers. Each repo keeps its own .github/workflows/*.yml, but those files only own the on: trigger + inputs and delegate to the reusable workflows / composite actions here. Job orchestration that is genuinely repo-specific (the lint job graph) stays local but is built from these actions.

  • actions/checkout first. Every composite action assumes the repo is already checked out and (for lint/test/build actions) the language toolchain action has already run.

Everything runs through just

Lint, type-check, test, build and generate all run via just-run (just <recipe>). The language-specific part is only the install that runs first (setup-python + uv-sync, or setup-node). So every repo exposes its CI steps as just recipes in a root justfile — the canonical names are lint, type-check, coverage-ci (CI test gate), docs, and for app/template repos gen / bootstrap / validate. This is what lets one generic runner serve both the Python and the Node repos.

Python repos (setup-python → uv-sync → just-run, plus pre-commit)

  • uv project with a committed uv.lock at the repo root (the setup-python cache keys on it). Python is pinned to 3.14 unless python-version is overridden.

  • Dependency groups. dev (tests + general dev) and lint (ruff, zuban, pre-commit, and anything the local hooks import). Jobs pass these to uv-sync via args: --group dev --group lint (lint), --group lint (pre-commit’s default sync), --group dev (tests). Monorepos add --all-packages.

  • Justfile with at least lint, type-check, coverage-ci recipes (run by just-run), and docs if the repo publishes Sphinx docs.

  • .pre-commit-config.yaml at the repo root. ruff / ruff-format are skipped by pre-commit (the lint job covers them); list any other hooks that can’t run in CI via the skip input (e.g. js-format, check-control-blank-lines when that tree isn’t materialised).

  • Coverage configured in pyproject.toml; the coverage-ci recipe runs coverage run -m pytest + a report. DB-backed suites attach a postgres service in the calling job and pass DATABASE_URL via env.

Node repos (setup-node → just-run)

  • .nvmrc at the repo root pins the Node version.

  • Yarn Classic (v1). setup-node runs yarn install --frozen-lockfile; use cache: yarn layout and a committed yarn.lock.

  • Yarn workspaces with @fsh/* scoped package names.

  • Justfile exposing the same recipe names (lint, type-check, build, test) that wrap the underlying yarn workspace … calls, so just-run drives Node the same way it drives Python. (A repo that still calls yarn directly in its workflow hasn’t adopted the runner yet — give it a justfile.)

  • LINT_IMPORT_CYCLES is honored by the shared eslint flat-config preset (turns on import/no-cycle); set it in the lint recipe or the job env.

Sibling path-deps (clone-siblings)

Why clone instead of installing from CodeArtifact? These deps are published CodeArtifact packages — [tool.uv.sources] (and the JS file: links) just override them to point at sibling source. The integration harnesses (codegen-example-app, sales-pipeline, codegen-targets, the templates) clone siblings so CI validates against HEAD of the whole constellation, not the last release — a breaking change in codegen is caught by the example app’s generate/lint/test gates before it’s published. Pure consumers of stable libs don’t need this and should just resolve from CodeArtifact.

Repos that do use the sibling layout follow the “checked out next to each other” convention:

  • [tool.uv.sources] paths are ../../<repo> and JS file: links are ../../<repo>/packages/<pkg> — i.e. siblings sit one directory above $GITHUB_WORKSPACE. clone-siblings clones into $(dirname $GITHUB_WORKSPACE) to match.

  • Per-repo deploy keys. Each sibling has its own read-only deploy key (provisioned by the infra source-code stack). The consumer must be granted those keys (the stack’s ci_consumers entry) and expose them as Actions secrets named DEPLOY_KEY_<REPO> — repo name uppercased with hyphens turned into underscores (codegen-database → DEPLOY_KEY_CODEGEN_DATABASE). The caller passes them through on the step’s env:.

PR titles (pr-title.yml)

  • PR titles follow Conventional Commits. Each repo passes its allowed scopes (always include deps, ci, release). requireScope defaults to false.

Releases (release-python.yml, release-npm.yml)

  • release-please configured in-repo: release-please-config.json + .release-please-manifest.json. Single-package repos emit release_created; monorepos emit releases_created (+ paths_released for npm).

  • Optional RELEASE_TOKEN secret (a PAT so release-please PRs re-trigger CI); falls back to GITHUB_TOKEN. Pass via secrets: inherit.

  • CodeArtifact via OIDC — infra provides these as repo/org variables: CODEARTIFACT_PUBLISH_ROLE_ARN, CODEARTIFACT_REGION, CODEARTIFACT_DOMAIN, CODEARTIFACT_DOMAIN_OWNER, and the repo URL (CODEARTIFACT_PYPI_REPOSITORY_URL for python, CODEARTIFACT_NPM_REPOSITORY_URL for npm). The publish job requests id-token: write and assumes the publisher role — no static credentials.

  • Build system. Python repos build with uv build (pyproject build-system); npm repos build only the buildable @fsh/* workspaces (the build-command input — @fsh/eslint-config has no build script and publishes source as-is).

Docs (docs.yml)

  • A Cloudflare Pages project is pre-provisioned by infra, which supplies the CLOUDFLARE_API_TOKEN secret (pass via secrets: inherit) and the CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_PAGES_PROJECT variables, with the custom domain bound to the main (production) branch.

  • Python docs: just docs builds Sphinx into docs/_build/html. Node docs: a Storybook build assembled into a site dir. The caller passes the runtime, build-command, and output-dir.

  • A docs build needing a service container (codegen-database’s Sphinx build talks to postgres) can’t use docs.yml — services: can’t pass through workflow_call — so it keeps a local docs workflow.

Tooling versions

  • OPA / Regal are pinned (setup-opa defaults 1.16.2 / 0.34.1) — bump deliberately, since OPA’s --schema typechecker and Regal’s lint rules evolve and can surface new failures.