devx/docs/decisions/0003-composite-actions.md

# ADR-0003: Composite Actions for CI Workflow Reuse

Date: 2026-08-12
Status: Accepted

## Context

The devx repository's Gitea Actions workflows (`.gitea/workflows/ci.yml`,
`post-merge.yml`, `build-images.yml`) repeated multi-step
sequences across jobs:

1. **Set up environment** — `make setup-image` (optionally with `EXTRAS=`).
   Appeared verbatim in 4 jobs across `ci.yml` and `post-merge.yml`, each
   with the same `CI_GITEA_API_TOKEN` env wiring.

2. **Notify on failure** — `python3 -m devx.ci.notify_failure ... --auto-login`
   with venv activation, PATH export, and 5 fixed CLI args. Appeared in
   4 jobs (`ci/validate`, `post-merge/detect-and-configure`,
   `post-merge/release-and-maintain`, `build-images/build-and-push`),
   each differing only in the `--workflow` string.

3. **Quality checks** — a 6-step sequence (lint-all, pytest-cov,
   check-test-speed, devx-docs-check, check-translations, pip-audit)
   with venv activation boilerplate on every step. Appeared once in
   `ci.yml` validate job, but the same sequence is needed by `grm` and
   `infra` (Phase 2b/2c of the cross-repo refactoring plan).

This duplication had the following costs:

- **Drift risk**: a fix to notify-failure (for example, new flag,
  different env var) had to be applied to 4 places; missing one caused
  inconsistent failure notifications.
- **Workflow YAML noise**: the 6-step quality block obscured the
  validate job's actual structure (detect-changes, pr-review,
  release-dry-run).
- **Cross-repo reuse blocked**: `grm` and `infra` could not adopt the
  same quality-checks sequence without copy-pasting the inline steps,
  which would amplify the drift problem across 3 repos.
- **Gitea 1.27 constraints**: every `run` step needs explicit `shell:`;
  composite actions cannot access `secrets` directly (only `env:`).
  These constraints had to be re-discovered and re-applied per step.

## Decision

Introduce three Gitea composite actions in `.gitea/actions/`:

### 1. `setup-env/action.yml`

Wraps the `make setup-image` call. Single input `extras` (default empty)
forwarded to `make setup-image EXTRAS=`. Reads `CI_GITEA_API_TOKEN` and
`CI_GITEA_USERNAME` from the calling workflow's `env:` context.

### 2. `notify-failure/action.yml`

Wraps the `devx.ci.notify_failure` invocation. Single required input
`workflow` (the workflow/job name for the Gitea issue title). Step is
gated by `if: failure()` so it only runs on job failure. Reads
`CI_GITEA_API_TOKEN` from the calling workflow's `env:` context.

### 3. `quality-checks/action.yml`

Wraps the 6-step quality sequence. Inputs:

- `package` (default empty) — sets `DEVX_DOC_VERSIONS_PKG` for doc
  version checks (for example, `devx`, `grm`).
- `test-speed-max` (default `15`) — total test seconds threshold.
- `test-speed-max-single` (default `0.5`) — per-test seconds threshold.
- `translations-file` (default empty) — path to `translations.json`
  for repos whose translations live outside `src/devx/`.

Each step activates the venv defensively
(`. .venv/bin/activate 2>/dev/null || true`) so the action works with
both pre-built CI images (which symlink `/opt/venv` to `.venv`) and
fresh `make setup-image` runs.

### Adoption Scope

- **`ci.yml` validate job**: `setup-env` + `quality-checks` +
  `notify-failure`.
- **`ci.yml` auto-merge job**: `setup-env` only (no quality checks,
  no notify-failure — auto-merge failure is surfaced by the validate
  job's notify-failure).
- **`post-merge.yml` detect-and-configure**: `setup-env` +
  `notify-failure`.
- **`post-merge.yml` release-and-maintain**: `setup-env` (with
  `extras: "release"`) + `notify-failure`.
- **`build-images.yml` build-and-push**: `notify-failure` only. The
  setup steps use `make setup-release` and `make setup-ci` (not
  `make setup-image`), so `setup-env` does not apply. The cleanup job
  has no notify-failure step (it only runs on build-and-push success).

### Same-Repo Copies (No Cross-Repo References)

Each consumer repo (`devx`, `grm`, `infra`) gets its own copy of the
composite actions under its `.gitea/actions/` directory. There is no
`uses: oblachno-oss/devx/.gitea/actions/...@vX.Y.Z` reference.

This avoids a single-point-of-failure where a bad `devx` master commit
would break all three repos' CI simultaneously. The cost is three
copies of ~30 lines of YAML each, updated manually when a composite
action changes. Given the stability of these patterns (the inline
versions were unchanged for months), this cost is acceptable.

## Consequences

### Positive

- **Workflow YAML is shorter and clearer**: the validate job's
  quality block collapses from 32 lines to 5 lines. The intent
  (`uses: ./.gitea/actions/quality-checks`) is more legible than
  6 individually wrapped steps.
- **Drift eliminated**: a change to notify-failure (new flag, different
  env var) is applied in one file. All 4 calling sites pick it up.
- **Cross-repo reuse enabled**: Phase 2b (`grm`) and Phase 2c (`infra`)
  copy the same `action.yml` files and adopt the same `uses:` pattern.
  The quality-checks sequence is now portable.
- **Gitea 1.27 constraints centralized**: the `shell: bash` and
  `env:` (not `secrets`) patterns are encoded once per action, not
  re-derived per step.
- **No release triggered**: changes to `.gitea/**` are classified as
  workflow-only by `devx.ci.classify_changes`. Phase 2a does not
  produce a new devx version. `grm`/`infra` bump to the Phase 1
  release (v0.50.4), not a Phase 2a version.

### Negative

- **Three copies of each action**: when a composite action changes,
  the change must be applied to `devx`, `grm`, and `infra`
  independently. This is intentional (see Same-Repo Copies preceding)
  but is a maintenance cost.
- **Composite action debugging is harder**: Gitea's log output for
  composite action steps is nested under the action name. Finding the
  failing step requires reading one more level of indentation.
- **`env:` propagation is implicit**: the calling workflow's top-level
  `env:` block must define `CI_GITEA_API_TOKEN` for the composite
  action to read it. A workflow that omits this will see an empty
  token at runtime, not at lint time. actionlint does not catch this.
- **`quality-checks` is devx-shaped**: the `package` and
  `translations-file` inputs exist because consumer repos (for example,
  `grm`) have translations files outside the default
  `src/devx/translations.json` location and need doc version checks
  targeting their own package name.
  A repo with a different translations path or package layout would need
  a new input or a different action. This is acceptable for the current
  3-repo scope.

### Neutral

- **`if: failure()` is preserved**: the `notify-failure` composite
  action's step has `if: failure()`, which is evaluated in the
  calling workflow's job-status context. This is the standard Gitea
  Actions pattern for post-failure notification.
- **Venv activation is defensive**: `. .venv/bin/activate 2>/dev/null
  || true` does not fail if the venv is missing (pre-built image path)
  or already active. This matches the inline pattern's behavior.