These tests run against a throwaway Gitea 28.1.0 started in Docker. They are opt-in: without AEGIS_INTEGRATION=1 every test here is skipped and Docker is never touched, so the default uv run pytest stays fast.

AEGIS_INTEGRATION=1 uv run pytest tests/integration -m integration -v

An integration-only run covers little of src/, so the unit-test coverage gate is lowered to 0 for runs that collect nothing but tests/integration. If Docker is unavailable while AEGIS_INTEGRATION=1 is set, the session fails with a clear message instead of skipping.

What the harness does

Image: GITEA_IMAGE in harness.py (digest-pinned, single constant).
One container and one network per run, both named aegis-it-<8 hex>. No host bind mounts, no image builds, no docker prune.
Gitea is configured through GITEA__section__KEY env vars (sqlite3, INSTALL_LOCK, random SECRET_KEY/INTERNAL_TOKEN/OAuth2 JWT secret, Actions, packages and OAuth2 enabled, mailer off, webhook allowed host list *, MAX_RESPONSE_ITEMS=50).
Readiness: polls GET /api/v1/version for up to 90 s. On failure the last 100 log lines of the container are written to stderr.
Seeding: admin aegis-admin (random password) via gitea admin user create, plus a full-scope token. All data is fake and random per run. Passwords and tokens are kept out of repr and error messages.
Cleanup: docker rm -f -v <container> and docker network rm <net> from the session fixture finalizer, an atexit hook, and SIGTERM/SIGHUP handlers.

Reachability modes

Local (default): a free loopback port is chosen, published as 127.0.0.1:<port>:3000, and ROOT_URL is set to match. Base URL http://127.0.0.1:<port>.
CI (AEGIS_IT_NETWORK_MODE=container): for test runs inside a job container that shares the host Docker socket. No port is published. Gitea joins the per-run network, the job container ($HOSTNAME) is connected to the same network with docker network connect, and tests reach Gitea at http://aegis-it-<id>:3000. On cleanup the job container is disconnected again before the network is removed.

Fixtures and helpers

gitea (session): a GiteaInstance with base_url, admin_login, admin_token, api(method, path, token=None, **kw) (defaults to the admin token, anonymous=True sends no credentials), create_user, mint_token, create_org, create_repo, unique.
regular_user (session): non-admin user with its own full-scope token.
unique_name (function): a unique name derived from the test name.