agiledancers/specs/in_progress/S4_create-build-pipeline-at-gitea

# S4 — Build and publish pipelines in Gitea

Status: IN_PROGRESS

Agreed after the grill-me review; shared understanding confirmed.

## User story

As a maintainer, I want every branch push to build and test the application,
so that broken changes are detected and successful main-branch builds provide
identifiable Docker images in our own registry.

## Agreed environment and feasibility

- Gitea and its container registry run on the existing Synology.
- The existing development mini-PC runs the Gitea Actions runner, separately from
  Gitea. No additional hardware is available or required.
- Gitea supports push-triggered Actions workflows and a runner on a separate
  machine. Codex can implement the repository configuration and assist with the
  installation and configuration required on the existing machines.
- Gitea was inspected as version 1.25.4. Match the runner and workflow setup to
  the installed version rather than assuming newer documentation applies.
- The mini-PC was inspected as Linux x86_64 with a Docker client installed, but
  without a reachable Docker daemon. Configuring a working daemon is part of S4.
- The current internal Gitea/registry endpoint is `http://192.168.2.28:3000`.
  Use that endpoint over the trusted internal network and explicitly configure
  Docker clients that need registry access to trust this particular HTTP registry.
  Introducing HTTPS is outside S4.
- The runner and job containers need access to Gitea, the registry and dependency
  download sources. The runner connects to Gitea; it needs no public incoming port.
- The mini-PC must be on, awake and running the runner. Jobs wait while it is
  unavailable; S4 does not promise unattended availability when the PC is off.

References:

- [Gitea 1.25 Actions quickstart](https://docs.gitea.com/1.25/usage/actions/quickstart/)
- [Gitea 1.25 Actions design](https://docs.gitea.com/1.25/usage/actions/design/)
- [Gitea container registry](https://docs.gitea.com/usage/packages/container/)

## Scope

### In scope

- Version-controlled Gitea Actions workflows and supporting build configuration.
- Enable Actions as needed at instance and repository level, configure Docker on
  the mini-PC, and install, register and configure its runner.
- Build and test both backend and frontend for every push to every branch,
  including newly created branches. Separate tag and pull-request event workflows
  are not required; branch pushes also check changes used in pull requests.
- Build two runnable Docker images: backend and frontend.
- Run end-to-end tests against those built containers before publication.
- Publish both images only from successful builds of the `main` branch to the
  container registry on the Synology.
- Configure registry authentication and the necessary secrets outside Git.
- Preserve failure diagnostics and document operation and recovery.
- Demonstrate a real successful pipeline and images that can be pulled back.

### Out of scope

- Automatic deployment, starting application containers on the Synology, and OTAP.
  Starting temporary containers for pipeline tests is in scope.
- New linting or static-analysis gates, such as ESLint or Sonar. Existing tests,
  including architecture tests, remain mandatory.
- Merge or release policies, separate tag/release workflows, and automatic image
  deletion or retention cleanup. Published images remain available for now.
- Multi-architecture images, HTTPS setup, new hardware or provisioning additional
  infrastructure.

## Build and verification behavior

1. Every branch push runs backend and frontend builds and their existing tests.
2. Backend verification includes the existing unit, integration/system and
   architecture tests. Current entry point: `mvn clean verify` using Java 25.
3. Frontend verification uses the lockfile (`npm ci`), unit tests (`npm test`) and
   production build (`npm run build`) with a supported Node version.
4. Build both Docker images on every branch, including branches that cannot
   publish. The current Dockerfile only covers the backend; frontend packaging
   must be added as part of implementation.
5. The frontend image serves the production Angular build, supports direct SPA
   route navigation, and forwards `/api` requests to the backend container.
   Container addressing/configuration is an implementation choice.
6. Run the existing Playwright end-to-end suite with Chromium against the built
   frontend/backend containers, through the frontend's API forwarding. Adapt the
   existing development-server test configuration as necessary: the acceptance
   run must exercise the actual images, not development servers.
7. Determine the intended server's CPU architecture during implementation. Build
   for that single target architecture and run the end-to-end tests on that same
   architecture. Do not infer the Synology's architecture from the mini-PC.
   Any architecture mismatch must be resolved and tested on the existing hardware
   before claiming acceptance.
8. A failed build or test fails the pipeline and prevents publication. Test
   containers are temporary and are cleaned up after the run, including failure.

## Publication and image identity

- Publish separate backend and frontend images under the repository owner's
  namespace in the existing Gitea container registry. Document the exact names.
- Feature branches must not publish application images.
- Both images from a main-branch commit use the full Git commit SHA as their tag.
  This identifies the matching pair independently of moving tags.
- Once both commit images have been successfully published, reruns verify/reuse
  them without overwriting either commit tag.
- Publication succeeds only when both images are published and can be pulled
  back from the registry. A partial publication fails the pipeline; one image may
  already exist. A rerun preserves that image and may publish the missing image.
- After both commit images are available, update the moving `main` tags only if
  the commit is still the current main-branch head. Serialize/coordinate that
  operation so an older, slower pipeline cannot move `main` backwards.
- The two moving tags are not an atomic pair. Use the same commit SHA on both
  images when an exact matching pair is needed. A failure updating a moving tag
  must be visible as a pipeline failure and recoverable through a rerun.
- No automatic deletion of published images is introduced in S4.

## Failure diagnostics and operation

- Failed pipelines retain available test reports, container logs, and Playwright
  traces and screenshots for fourteen days. Collect available diagnostics even
  when a preceding step fails; do not hide the original failure.
- Provide a short management guide covering:
  - Docker/runner installation, registration, startup and required access.
  - Gitea instance/repository Actions settings and registry configuration.
  - Required credentials, permissions and secret names, without secret values.
  - Which settings exist outside Git and how to reproduce them.
  - Trigger behavior, mini-PC availability and queued jobs.
  - Image names, tags and commands to pull a matching image pair.
  - Finding diagnostics, rerunning failed jobs and completing partial publication.
  - The target architecture and how it was established.
- Keep registry credentials and registration tokens out of repository files and
  logs; use the relevant secret settings.

## Acceptance criteria

- [ ] A push to any branch, including a new branch, starts a pipeline.
- [ ] Backend and frontend build and all existing tests, including architecture
      and Playwright end-to-end tests, pass before publication is permitted.
- [ ] Every branch builds both Docker images; end-to-end tests exercise those
      images through the frontend and its `/api` forwarding.
- [ ] A failing build or test fails the pipeline without publishing images.
- [ ] A successful feature-branch pipeline publishes no application images.
- [ ] A successful `main` pipeline publishes both images to the Synology registry
      with the full commit SHA; both images can be pulled back.
- [ ] Published commit images are preserved on rerun; partial publication can be
      completed without overwriting an existing commit image.
- [ ] Moving `main` tags are updated only after both commit images are available,
      and an older pipeline cannot move them backwards.
- [ ] Publication or pull-verification failure makes the pipeline fail, even if
      some images have already been uploaded.
- [ ] Available failure diagnostics are retained for fourteen days, and temporary
      test containers are cleaned up on success and failure.
- [ ] The runner operates on the existing mini-PC, with Gitea and the registry on
      the existing Synology; no additional hardware is needed.
- [ ] The single target architecture is established and the images are tested on
      that architecture using the existing hardware.
- [ ] A management guide records setup, external settings, secrets, image usage
      and recovery, including the need to keep the mini-PC/runner available.
- [ ] Actual pipeline runs demonstrate successful main-branch publication,
      feature-branch checks without publication, and failure blocking publication.

## Implementation handoff

This specification captures the agreed design. It does not install the runner,
change server settings or implement the pipeline. S4 is complete only when the
configuration, documentation and operational acceptance evidence are delivered;
workflow files alone are insufficient.


## Implementation progress

Repository implementation and local Docker verification are available. See
[management instructions](../../docs/gitea-ci.md) and
[validation evidence](../../docs/s4-validation.md).

Backend verification (20 tests), frontend verification (14 tests), both runtime
image builds and both Playwright tests against the containers passed. Eleven
isolated CI publication/configuration tests pass. The runner binary and user-service
configuration are installed on the mini-PC.

Operational acceptance is still pending: authenticated Synology architecture
verification, Gitea credentials/secrets, runner registration/startup and real
feature/failure/main pipeline runs with registry pullback evidence. The spec stays
IN_PROGRESS until those requirements are met.