docs(ci): document reusable workflows and hosted-first self-hosted fallback (PR #48)

Author: polyipseity

docs/ci.md

@@ -1,11 +1,17 @@
 # CI workflows (overview)
 
-The repository uses GitHub Actions. The active workflows are in `.github/workflows/` — check those files for exact steps. High-level:
+The repository uses GitHub Actions. The active workflows live in `.github/workflows/` — check those files for exact steps. Recent CI changes extract common logic into reusable workflows to allow a hosted-first runner strategy with a self-hosted fallback. High-level:
 
-- `check.yml` — runs lint, commitlint, and the test suite on pushes and PRs.
-- `docker.yml` — builds and pushes container images for PRs and pushes.
-- `release.yml` — run by `release-please` on `main` to automate releases and production image publishing.
+- `check.yml` — top-level caller that invokes the reusable workflow in `check-reusable.yml`; runs lint, commitlint, and the test suite on pushes and PRs. The caller prefers GitHub-hosted runners and will fall back to a self-hosted runner only if the hosted job fails.
+- `docker.yml` — top-level caller that invokes `docker-reusable.yml` to build and push container images.
+- `release.yml` — caller for `release-reusable.yml`; invoked by `release-please` on `main` to automate releases and image publishing.
 
-When a check fails, open the corresponding workflow run in GitHub (Actions tab) to see job logs.
+Key notes about the hosted-first / self-hosted fallback:
+
+- The top-level workflow will try a hosted runner first and, if that job fails, run a fallback job targeting `self-hosted` runners. This improves reliability when hosted runners are unavailable or hit capacity.
+- The fallback uses a `failure()` condition so it only runs when the primary (hosted) job fails; this can cause duplicated checks to appear in the PR UI and may show cosmetic failures for the fallback run — this is expected and documented in the workflow comments.
+- `continue_on_error` is exposed as an input and applied at the reusable workflow job level when requested.
+
+When a check fails, open the corresponding workflow run in GitHub (Actions tab) to see job logs. Prefer inspecting the primary (hosted) job logs first.
 
 Avoid committing generated artifacts — have CI produce and publish them instead.

docs/docker-and-deployment.md

@@ -1,10 +1,11 @@
 # Docker & Deployment
 
+
 This guide explains how to build and run the project's Docker image and where CI builds/publishes images.
 
 ## Provided Dockerfile
 
-A `Dockerfile` exists at the repository root. It is used by the CI workflow `.github/workflows/docker.yml` to build multi-tag images and push them to the configured registry (default: `ghcr.io`).
+A `Dockerfile` exists at the repository root. CI image build/publish logic has been extracted into a reusable workflow (`.github/workflows/docker-reusable.yml`) and is invoked by a small top-level caller (`.github/workflows/docker.yml`) that prefers hosted runners and falls back to `self-hosted` when the hosted job fails.
 
 ## Local build & run
 
@@ -22,14 +23,15 @@ Replace `--env-file .env.example` with your `.env` file or explicit `-e` flags f
 
 ## CI image publishing
 
-The repository's `docker.yml` workflow builds and pushes images to the registry. The workflow:
+
+The repository's `docker.yml` top-level caller invokes the reusable workflow to build and push images to the registry. The reusable workflow:
 
 - sets up QEMU and Buildx
 - logs into the registry using the workflow token
 - generates metadata tags (sha, branch/ref, test)
 - builds and pushes the image(s)
 
-If you need to change the target registry or image name, update the `REGISTRY` and `IMAGE_NAME` environment variables in the workflow.
+If you need to change the target registry or image name, update the `REGISTRY` and `IMAGE_NAME` environment variables in the reusable workflow or the top-level caller as appropriate.
 
 ## Deployment notes
 

docs/release.md

@@ -1,10 +1,11 @@
 # Release automation (summary)
 
-Releases are produced by `googleapis/release-please-action` in `.github/workflows/release.yml`.
 
-- Trigger: push to `main`.
+Releases are produced by `googleapis/release-please-action`. The release workflow now uses a reusable workflow (`.github/workflows/release-reusable.yml`) and a small top-level caller (`.github/workflows/release.yml`) that prefers GitHub-hosted runners and falls back to a `self-hosted` runner when necessary.
+
+- Trigger: push to `main` (via `release-please` outputs).
 - Behavior: `googleapis/release-please-action` parses Conventional Commits and will open/update Release PRs or create a release when appropriate; it also generates/updates the changelog (`CHANGELOG.md`) and exposes outputs such as `release_created`, `major`, `minor`, `patch`, `tag_name`, and `body`.
-- CI integration: the workflow uses those outputs to tag versions and to build/push container images (see the repo's workflow for the exact steps).
+- CI integration: the reusable workflow consumes those outputs to tag versions and to build/push container images (see the repository workflows for exact steps). The hosted-first / self-hosted fallback may cause duplicate PR checks to appear when the fallback runs — this is cosmetic.
 
 ## Notes for maintainers