# Ecosystem CI — reusable workflows

Shared CI building blocks for Olsitec projects on the foundation forge
(`documentation/999_testing.md`). Downstream repos call them as **reusable
workflows** (`on: workflow_call`) at **job** level:

```yaml
# .forgejo/workflows/ci.yml in any project repo
name: ci
on: [push]
jobs:
  build:
    runs-on: docker   # ← REQUIRED on Forgejo 11 (see "Forgejo 11 quirk" below)
    uses: olsitec/foundation/.forgejo/workflows/reusable-node-build.yml@master
    with: { package-manager: bun, build: "bun run build" }
```

## Forgejo 11 quirk (IMPORTANT)

Our forge runs **Forgejo 11.0.15**, where reusable-workflow support is the
**pre-v15 "limited" implementation**. Two rules differ from GitHub / Forgejo ≥ v15:

1. **The calling job MUST declare `runs-on`** (e.g. `runs-on: docker`). On standard
   GitHub you omit `runs-on` on a `uses:` job — do that here and Forgejo **silently
   schedules no run at all** (no error). This was verified live: a caller without
   `runs-on` produced zero runs; the same caller with `runs-on` ran green.
2. **Cross-repo references use the SHORT form** `owner/repo/.forgejo/workflows/x.yml@ref`
   — the **full-URL** form (`https://forge.olsitec.net/...`) fails for reusable
   workflows (it is, conversely, the form composite *actions* require).

Also pre-v15: the called workflow's logs collapse into a single "Set up job" entry
in the UI. **Forgejo v15.0** (LTS, Apr 2026) reworks this — omit `runs-on` and Forgejo
expands the reusable workflow into its inner jobs with separate logs. On a future v15
upgrade, drop the `runs-on` from callers and these notes become obsolete.

## Workflows

| Workflow | Purpose | Key inputs |
|----------|---------|------------|
| `reusable-node-build.yml` | install + build npm/bun/none | `package-manager`, `build`, `workdir` |
| `reusable-docker-build.yml` | `docker build` via the host socket | `image`, `dockerfile`, `context`, `build-args`, `push` |
| `reusable-lint.yml` | eslint + yamllint gate (error → non-zero) | `eslint-paths`, `yamllint-paths`, `package-manager` |
| `reusable-semantic-release.yml` | dry-run next-version probe (conventionalcommits) | `branch` → output `version` |

All run in the baked `foundation-ci:latest` image. `reusable-semantic-release`
checks out with `fetch-depth: 0` (full history + tags). Real Forgejo release
publishing is deferred (no `@semantic-release/forgejo` analogue yet) — it computes
+ outputs the version, faithful to the GitLab `generate-release-version` job.

## Candidate coverage (999_testing)

| Candidate | Shape | Workflow | Status |
|-----------|-------|----------|--------|
| olsicrypto | npm package (tsc) | `reusable-node-build` (npm) | self-contained ✓ |
| document-engine | bun package (tsc) | `reusable-node-build` (bun) | self-contained ✓ |
| olsitrack/api | no-artifact / versioned | `reusable-node-build` (empty build) | self-contained ✓ |
| seaspots-homepage | docker, dep `@olsitec/svelte-common` | `reusable-docker-build` | blocked on the package registry (Stage-2) |
| token-service | docker, dep `@olsitec/olsicrypto` | `reusable-docker-build` | blocked on the package registry (Stage-2) |

The semantic-release bump sequence and the eslint/yamllint gates are continuously
proven by `ecosystem-selftest.yml` on the foundation's own runner.