# Build and dev delivery ## Current delivery flow (maintainer confirmed 2026-10-19) Pushing to Git runs Actions, which builds and publishes to Harbor; ArgoCD picks up the deployment and delivers it to Kubernetes. Workload manifests are under `deploy/`. Use this configured flow for development delivery. The manual-sync and image-pinning instructions below describe earlier setup and must not be treated as a request to replace the current automation. DEV workloads use `evolution-dev`, run on worker nodes rather than the control plane, and retain the existing PostgreSQL server, network structure and URLs. Qualification data must remain isolated from existing worlds. Immediately before each push refresh `REGION_SESSION_WINDOW` in `kubernetes/region/dev-session-route/listener.yaml` with a unique activation and an absolute UTC expiry four hours ahead. Record actual pipeline/deployment results separately: a push alone does not prove build success or reachability. World0 deployment, reset and pruning remain outside routine development. ## Historical setup and verification notes The maintainer has configured Gitea, Harbor and Argo. Gitea run [1399](https://git.aeternalisgames.com/dingo/AEvolution/actions/runs/1399) successfully built, tested and published commit `8ab48d3`. This repository adds broader checks and a bounded **stateless proof Job**. It is not a region server. Cluster execution must be recorded separately from image publication. The expanded [run 1402](https://git.aeternalisgames.com/dingo/AEvolution/actions/runs/1402) passed all checks and published `4c2cc04`. The maintainer's later GitOps commit `20e609d` pins the verified run 1399 image instead; M1.6 preserves that selection. The maintainer confirms Argo is ready to pick up deployment additions. Bootstrap examples still need the actual application namespace and destination; do not apply examples unchanged. ## Gitea and Harbor The single workflow is `.gitea/workflows/build.yaml`. The existing runner label is `ubuntu-22.04`; this does not imply its compiler version. Checks use explicit Ubuntu 24.04 Docker stages with GCC14 and LLVM19. The runner needs Git, Node20 for checkout, Bash and a working Docker builder. | Setting | Kind | Value / purpose | |---|---|---| | HARBOR_HOST | Existing variable | registry.aeternalisgames.com; publishing is scoped to this host | | HARBOR_PROJECT | Existing variable | aeternalis | | HARBOR_USERNAME / HARBOR_PASSWORD | Existing secrets | Harbor push robot; values never belong in Git | | HARBOR_REPOSITORY | Optional variable | Defaults to aevolution | | CI_RUNNER_LABEL | Optional variable | Defaults to the verified ubuntu-22.04 label | | UBUNTU_IMAGE | Optional variable | Defaults to ubuntu:24.04; prefer a reviewed base digest | Checks include Debug/Release CTest, format, clang-tidy, ASan/UBSan, a million synthetic ticks and bounded seeded libFuzzer. TSan runs separately. No failure is ignored. Windows MSVC checks use `tools/windows-check.ps1`. The image job waits for checks and executes a restricted runtime smoke test. Only main push/manual runs publish, using a temporary Docker credential directory. Published tags use `sha--run--` to distinguish rebuilds. This replaces the original commit-only tag convention. The job prints the registry digest in its logs/summary. GitOps references the digest, never latest. CI does not receive cluster credentials or automatically commit/sync GitOps. Use isolated runners for untrusted pull requests; Docker access is privileged. ## Local container checks ```sh docker build --progress=plain -f deploy/docker/Dockerfile --target ci-checks . docker build --progress=plain -f deploy/docker/Dockerfile --target ci-tsan . docker build -f deploy/docker/Dockerfile -t aeternalis-evo:dev . docker run --rm --network none --read-only --cap-drop ALL \ --security-opt no-new-privileges aeternalis-evo:dev \ --seed 123456 --entities 8 --ticks 1000 --verify-replay ``` Runtime UID/GID is 10001; JSON goes to stdout. Builder package versions are in `/usr/share/evo/build-packages.txt`; file output needs an explicit writable mount. Source COPY operations exclude local chat logs, `.git` and credentials. Ubuntu security packages move: production promotion still needs pinned provenance, SBOM, scan/signature and retention. TSan on this sequential proof validates instrumentation, not future concurrency. Record actual results in VALIDATION.md. ## Argo settings and promotion Reuse the maintainer's confirmed application. The following are bootstrap settings for an application watching this repository directly, not an inspection of the live application's configuration: | Field | Value | |---|---| | Repository | https://git.aeternalisgames.com/dingo/AEvolution.git | | Revision | main; review the resolved commit before syncing | | Path | deploy/kubernetes/dev | | Destination namespace | evolution-dev | | Project | aevolution-dev, or an equivalently restricted project | | Sync | Manual full sync; no automated prune/self-heal (recommended) | Inventory (2026-09-29, docs/infrastructure/INVENTORY.md): the live `aevolution-dev` application has no automated sync, which matches this guidance. Other projects' applications do auto-sync with prune. Keep AEvolution durable resources out of any automated-prune application. Bootstrap examples in `deploy/argocd/*.yaml.example` are outside the workload path. Replace the Argo namespace and registered cluster API URL, or use its UI. Create evolution-dev separately. Configure Argo's private Git read credential and a **pull-only** harbor-pull Secret in that namespace. Neither is the CI push credential. The project allows only Job, ServiceAccount and NetworkPolicy there. Before syncing: 1. Wait for successful checks and publication of the intended commit. 2. Update `deploy/kubernetes/dev/kustomization.yaml` to the published `sha256:<64 hex>` digest, review and commit it. It currently pins run 1399; no floating tag or fallback image is used. 3. Run `kubectl kustomize deploy/kubernetes/dev`. Check exactly three resources, all in evolution-dev, the selected digest and no unresolved marker. 4. Full-sync the dev app. Selective sync skips hooks. 5. Verify Job aevolution-dev-proof completes with exit 0 and JSON `replay_verified: true`, seed 123456, 8 entities and 100000 ticks. Record the digest, source commit and result in the validation report. The Job has a five-minute deadline, no retries, token mount, network access or writable root, and bounded resources. NetworkPolicy requires CNI enforcement; node-level image pulling is separate from pod egress. No Service, port, PVC or persistent world is included. BeforeHookCreation retains the latest Job until the next full sync replaces it; collect logs first. Kubernetes can execute a Job more than once: harmless here, not an exactly-once persistence mechanism. World0 is unchanged. Persistent deployment follows [infrastructure architecture](../docs/architecture/INFRASTRUCTURE_ARCHITECTURE.md) and [operations gates](../docs/infrastructure/OPERATIONS.md). TSan requires execution outside the Docker build sandbox on this runner. The ci-tsan target now builds its tests; the Gitea workflow runs them in a non-root, read-only, networkless container with tmpfs test-output directories. Its pinned Moby seccomp profile adds only personality(0x40000). No host security settings change. See ADR-0020 for the source, integrity hash and removal policy. Building the ci-tsan image alone is NOT a TSan test pass; use the workflow's docker run command with the generated profile to execute it locally. The TSan run requires writable tmpfs mounts for `build/tsan/Testing`, `build/tsan/cli-integration` and `build/tsan/world-proof`, plus `/tmp`. Each is bounded to 16 MiB in the workflow. The world restart test retains generated snapshots, journals and JSON reports beneath its own random run directory; it cannot create that directory on the read-only image filesystem. Any new file-producing CTest must declare its scratch directory in this container invocation as well. ## PostgreSQL migration tooling The `postgres` CI matrix builds and tests the isolated adapter in Release, clang-tidy and ASan/UBSan against private PostgreSQL clusters. The `postgres-tools` Docker target contains pinned psql plus checked-in migrations, not a database server. Set Gitea variable `HARBOR_POSTGRES_REPOSITORY=aevolution-postgres-tools` to enable publishing that image using existing HARBOR_PROJECT and robot secrets. Leave it unset for build/smoke only. Use the reported immutable digest in the Job example. Do not reuse the simulation image repository for this entrypoint. [Secret and role setup](../docs/infrastructure/POSTGRESQL.md) describes the separate migrator/runtime credentials. The example is outside active Argo resources until an operator supplies the database endpoint, role, Secret and egress rules. No region server or world-state migration is deployed by M7.2. Schema v2 (M7.3) additionally requires `EVO_PG_RUNTIME_ROLE`, naming an operator-created NOLOGIN runtime group role. ## Region server image (M7.8) The `server-image` job builds the Docker target `server-runtime` (`evo-server` plus the pinned libpq, UID 10001, no credentials). It smoke-tests the image with `tools/ci/server-image-smoke.sh` and publishes only when Gitea variable `HARBOR_SERVER_REPOSITORY` is set. The region host is deployed from `kubernetes/region/` (M8.4, ADR-0071), included in each environment's Argo path. It replaces the former `region-server` example. Probes: `/readyz` means authority, and `/livez` means only that the process is alive. Without a gateway, the region receives no inputs. ## Environments and World0 protection (M8.2) `kubernetes/platform/` holds each environment's namespace, quota, limit range, default-deny policies and service accounts. `kubernetes/platform/admission` holds the World0 admission policy. Since the M8.3 amendment they are delivered by the `aevolution-platform` Argo Application (`kubernetes/platform/cluster`), which self-heals and never prunes. Originally a cluster administrator applied them by hand; they are never part of an Argo Application. The stage and World0 Argo projects and applications are in `argocd/stage` and `argocd/world0` as examples. See docs/infrastructure/ENVIRONMENTS.md for the runbook, and ADR-0069. The CI `deploy` suite runs `tools/ci/deploy-policy-check.py` over every manifest.