docs(prd): scaffold PRD 0002 — Test pipeline on Gitea Actions

Assisted-by: Claude Code
2026-05-08 20:06:09 -04:00
parent 97aabd3d75
commit 3d969e7d27
1 changed files with 75 additions and 0 deletions
@@ -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.