docs(ci): update workflow docs for shared-step try→fallback pattern and runner defaults

Author: polyipseity

docs/ci.md

@@ -1,16 +1,16 @@
 # CI workflows (overview)
 
-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:
+The repository uses GitHub Actions. The active workflows live in `.github/workflows/` — check those files for exact steps. CI logic has been refactored into local shared-step workflows (named `*-shared-steps.yml`) that are invoked via `workflow_call` by small top-level callers. This implements a hosted-first → self-hosted fallback pattern.
 
-- `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.
+- `check.yml` — top-level caller that invokes `.github/workflows/check-shared-steps.yml` and runs lint, commitlint, and the test suite on pushes and PRs. The caller uses `ubuntu-22.04` for the primary try job and falls back to `self-hosted` only when the try job fails.
+- `docker.yml` — caller that invokes `.github/workflows/docker-shared-steps.yml` to build and push container images (primary: `ubuntu-latest`, fallback: `self-hosted`).
+- `release.yml` — caller that invokes `.github/workflows/release-shared-steps.yml` (primary: `ubuntu-latest`, fallback: `self-hosted`).
 
-Key notes about the hosted-first / self-hosted fallback:
+Notes about the shared-step / fallback pattern:
 
-- 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.
+- The shared-step files are internal to this repository (named `*-shared-steps.yml`) and are not intended as cross-repo reusable workflows; they expose inputs such as `runs_on` and `continue_on_error` to the caller.
+- Each top-level caller runs a primary job on a hosted runner and conditionally runs a fallback job on `self-hosted` using `if: ${{ failure() }}`. This makes CI more resilient but can cause duplicated or expanded sections in the GitHub PR UI when the fallback executes — this is cosmetic and documented in the workflow comments.
+- `continue_on_error` is passed from the caller into the shared-step workflow and applied at the job level inside the shared workflow.
 
 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.
 

docs/docker-and-deployment.md

@@ -1,11 +1,10 @@
 # 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. 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.
+A `Dockerfile` exists at the repository root. CI image build/publish logic has been extracted into an internal shared-step workflow (`.github/workflows/docker-shared-steps.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
 
@@ -23,15 +22,16 @@ Replace `--env-file .env.example` with your `.env` file or explicit `-e` flags f
 
 ## CI image publishing
 
-
-The repository's `docker.yml` top-level caller invokes the reusable workflow to build and push images to the registry. The reusable workflow:
+The repository's `docker.yml` top-level caller invokes the internal shared-step workflow to build and push images to the registry. The shared-step 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 reusable workflow or the top-level caller as appropriate.
+If you need to change the target registry or image name, update the `REGISTRY` and `IMAGE_NAME` environment variables in the shared-step workflow or the top-level caller as appropriate.
+
+Note: the top-level caller uses `ubuntu-latest` for the primary try job; when that job fails the fallback runs on `self-hosted`. This is intended to improve reliability while keeping hosted runner usage first.
 
 ## Deployment notes
 

docs/release.md

@@ -1,11 +1,10 @@
 # Release automation (summary)
 
+Releases are produced by `googleapis/release-please-action`. The release workflow has been refactored so release steps are defined in `.github/workflows/release-shared-steps.yml` and invoked by a small top-level caller (`.github/workflows/release.yml`) which prefers hosted runners and falls back to `self-hosted` when the top-level try job fails.
 
-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).
+- Trigger: push to `main`.
 - 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 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.
+- CI integration: the shared-step 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