# FSH github-actions

Centrally-managed GitHub Actions for the FSH org: **composite actions**
(reusable step bundles) and **reusable workflows** (callable jobs). Consumer
repos reference these instead of carrying their own copies, so a change is made
once here and rolled out everywhere via the moving `@v1` tag.

```{toctree}
:maxdepth: 2
:hidden:

getting-started
reference/index
conventions
changelog
```

## What's here

**Composite actions** — drop into a job's `steps:`

| Action | Purpose |
|--------|---------|
| [`setup-python`](reference/actions/setup-python) | uv + pinned Python, with `uv.lock` caching |
| [`setup-node`](reference/actions/setup-node) | Node from `.nvmrc` + `yarn install` |
| [`uv-sync`](reference/actions/uv-sync) | install project deps (`uv sync <args>`) |
| [`just-run`](reference/actions/just-run) | generic task runner — `just <recipes>` |
| [`clone-siblings`](reference/actions/clone-siblings) | clone FSH sibling repos for editable / `file:` path deps |
| [`setup-opa`](reference/actions/setup-opa) | install pinned `opa` + `regal` |
| [`pre-commit`](reference/actions/pre-commit) | cache + sync + `pre-commit run --all-files` |

**Reusable workflows** — call from a job's `uses:`

| Workflow | Purpose |
|----------|---------|
| [`pr-title`](reference/workflows/pr-title) | Conventional-Commit PR-title validation |
| [`release-python`](reference/workflows/release-python) | release-please + build + publish to CodeArtifact (pypi) |
| [`release-npm`](reference/workflows/release-npm) | release-please + build + publish `@fsh/*` to CodeArtifact (npm) |
| [`docs`](reference/workflows/docs) | build a static site and deploy to Cloudflare Pages |

New here? Start with **[Getting started](getting-started)**. The full list of
repo expectations these bake in is in **[Conventions](conventions)**.

## What's *not* centralised

Some things are deliberately left in each repo because they're too
repo-specific to share cleanly:

- **`lint.yml` as a whole workflow.** Every repo's lint job graph differs
  (simple python lint; multi-side `be`/`fe`/`opa`/`render` app gates; template
  `bootstrap` gates), so the orchestration stays per-repo — but it's *built
  from* the actions above: a python repo's lint job is `setup-python` →
  `uv-sync` → `just-run` (plus a `pre-commit` job); a node repo is `setup-node`
  → `just-run`; app gates add `clone-siblings` + `setup-opa`. The recipes
  themselves live in each repo's `justfile`.
- **A docs build that needs a service container** (e.g. codegen-database's
  Sphinx build talks to postgres) keeps a local docs workflow, since `services:`
  can't pass through `workflow_call`.