From 3d969e7d278ddc60f03b4ac685edbda525158ded Mon Sep 17 00:00:00 2001 From: didericis Date: Fri, 8 May 2026 20:06:09 -0400 Subject: [PATCH] =?UTF-8?q?docs(prd):=20scaffold=20PRD=200002=20=E2=80=94?= =?UTF-8?q?=20Test=20pipeline=20on=20Gitea=20Actions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Assisted-by: Claude Code --- .../0002-test-pipeline-on-gitea-actions.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/prds/0002-test-pipeline-on-gitea-actions.md diff --git a/docs/prds/0002-test-pipeline-on-gitea-actions.md b/docs/prds/0002-test-pipeline-on-gitea-actions.md new file mode 100644 index 0000000..bee9d50 --- /dev/null +++ b/docs/prds/0002-test-pipeline-on-gitea-actions.md @@ -0,0 +1,75 @@ +# PRD 0002: Test pipeline on Gitea Actions + +- **Status:** Draft +- **Author:** didericis +- **Created:** 2026-05-08 + +## Summary + +Run the project's test suite on every push to a PR via Gitea Actions, and gate merges to `main` on the check being green. + +## Problem + +There is no automated test run today — tests only run when the author remembers to invoke them locally before pushing or merging. That's the whole CI loop missing: nothing reruns tests on each push, and nothing prevents a tired or distracted author from merging a branch whose tests don't pass. + +## Goals / Success Criteria + +- A failing test on a branch blocks the merge button on `main`. +- Every PR shows a passing/failing tests check from Gitea Actions, updated per push. +- Pushing a fix to a red PR re-runs the workflow automatically and turns it green without manual re-trigger. +- The workflow file is committed in-tree and the branch-protection rules are documented so the setup is reproducible from the repo alone. + +## Non-goals + +- Pipeline speed / wall-clock optimization. +- Matrix testing across Python versions or operating systems. +- Notifications (Slack, email, etc.) on failure. +- Caching dependencies between runs. + +## Scope + +### In scope + +- A Gitea Actions workflow that runs `tests/run_tests.py` (full suite — unit + integration) on every push event affecting a PR, plus pushes to `main`. +- Branch-protection rules on `main` requiring the test check before the merge button is enabled. +- A one-time end-to-end demo: a deliberately-failing test on a throwaway branch shows the merge button disabled, proving the gate is wired correctly. The demo branch is deleted after the proof. +- A short README section + status badge so contributors can read CI state and know what to do when it's red. +- Whatever dependency-manifest changes are needed to make the runner install pytest and run `tests/run_tests.py` cleanly. + +### Out of scope + +- Deploy / release pipeline (publishing images, tagging releases, etc.). +- Coverage reporting or quality gates. +- Lint / format checks beyond the test suite. + +## Proposed Design + +### New services / components + +- `.gitea/workflows/test.yml` — workflow definition. Triggers on `pull_request` and `push` to `main`. Runs `tests/run_tests.py` (the full suite, which exercises both unit and integration tests; integration tests require Docker on the runner). +- A small contract demo (a deliberately-failing test on a throwaway branch) used once to verify the merge gate, then deleted. Not a permanent file in the repo. + +### Existing code touched + +- `tests/` — no code edits expected, just executed by CI. If the existing suite isn't currently green on the runner's environment, fix-up is in scope. +- `README.md` — add a CI status badge and a short section explaining how to read the check and what to do when it's red. +- Existing dependency manifests (e.g. `pyproject.toml` or `requirements*.txt`, whatever is in tree) — adjusted as needed so the runner can install pytest and the project's dev dependencies. + +### Data model changes + +None. + +### External dependencies + +- Relies on the already-configured Gitea Actions runner on `gitea.dideric.is`. No new runner is provisioned as part of this PRD. +- The runner must have Docker available (integration tests in this repo spin up containers). + +## Open questions + +- Does the configured runner on `gitea.dideric.is` have Docker available and permissions to run integration tests? If not, the implementer needs to either (a) coordinate with the host to enable it, or (b) reduce CI scope to `tests/run_tests.py unit` and reopen this PRD for the integration half. +- How are branch-protection rules captured in the repo for reproducibility? Gitea applies them via API/UI, not in-tree — a `docs/` note pointing at the exact setting path is probably enough, but the format is up to the implementer. + +## References + +- `tests/run_tests.py` — the runner CI will invoke. +- PRD 0001 (`docs/prds/0001-per-agent-egress-proxy-via-pipelock.md`) — prior PRD for repo numbering reference.