DEVX-157: docs: add ADR-0003 and update docs for composite actions

2026-08-12 19:32:28 +00:00
parent ad98d76c1f
commit f5d3b72a38
12 changed files with 504 additions and 133 deletions
@@ -58,6 +58,74 @@ The pre-commit hook runs actionlint automatically when workflow files change.
 The CI `validate` job runs `make setup-image` then `make lint-all`.
 CI also runs a best-effort `make workflow-dryrun` step (skipped if act_runner is not installed in the CI Docker image).

+## Composite Actions (`.gitea/actions/`)
+
+Reusable Gitea composite actions eliminate repeated multi-step sequences
+across workflows. Each action lives in its own directory under
+`.gitea/actions/<name>/action.yml` and is referenced via
+`uses: ./.gitea/actions/<name>`.
+
+### Available Composite Actions
+
+| Action | Purpose | Inputs |
+|--------|---------|--------|
+| `setup-env` | Run `make setup-image` (with optional `EXTRAS=`) | `extras` (default: `""`) |
+| `notify-failure` | Create a Gitea issue on job failure via `devx.ci.notify_failure` | `workflow` (required) |
+| `quality-checks` | 6-step quality sequence: lint, tests, speed, docs, translations, security | `package`, `test-speed-max`, `test-speed-max-single`, `translations-file` |
+
+### Gitea 1.27 Constraints
+
+- Every `run` step in a composite action MUST have explicit `shell:`.
+- Composite actions CANNOT access `secrets` directly. They read from
+  the calling workflow's `env:` context (for example, `${{ env.CI_GITEA_API_TOKEN }}`).
+  The calling workflow's top-level `env:` block must define the required
+  env vars.
+- `if: failure()` in a composite action step is evaluated in the
+  calling workflow's job-status context.
+
+### Usage Pattern
+
+```yaml
+jobs:
+  validate:
+    env:
+      CI_GITEA_API_TOKEN: ${{ secrets.CI_GITEA_API_TOKEN }}
+      CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.gitea/actions/setup-env
+      - uses: ./.gitea/actions/quality-checks
+        with:
+          package: devx
+      - uses: ./.gitea/actions/notify-failure
+        with:
+          workflow: "ci/validate"
+```
+
+### Same-Repo Copies (No Cross-Repo References)
+
+Each 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 repos' CI simultaneously. See ADR-0003 for the full
+rationale.
+
+### When NOT to Use Composite Actions
+
+- **`make setup-release` / `make setup-ci`**: the `setup-env` action
+  only wraps `make setup-image`. Workflows that use other setup targets
+  (for example, `build-images.yml` uses `make setup-release`) keep the inline
+  setup step.
+- **Deploy-specific setup**: infra deploy workflows have additional
+  steps (`install-collections`, `setup-vault`, `setup_ssh_key`) that
+  are NOT part of the common setup. The `setup-env` action only
+  replaces the `make setup-image` step; deploy-specific steps stay
+  inline.
+- **Custom notification**: `security-scan.yml` uses a Mattermost
+  webhook, not `devx.ci.notify_failure`. The `notify-failure` action
+  does not apply.
+
 ## Architecture

 devx is a reusable Python package providing development and CI/CD tools for oblachno-oss projects.