bot-bottle/docs/prds/0002-test-pipeline-on-gitea-actions.md

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.