Skip to content
Agon ĀtriumAgon Ātrium

Source code

Open source page

CI and package delivery guidance

  • Read CI and package releases before changing pipeline rules, jobs, artifacts, credentials, or publication.
  • Treat .gitlab/ci/*.gitlab-ci.yml as the pipeline source of truth. Follow the sibling stage-based includes. Place Docker image verification and publication in build.gitlab-ci.yml, release downloads in publish.gitlab-ci.yml, and manual deployment in deploy.gitlab-ci.yml. Keep Bake and image configuration under resources/infrastructure/.docker/, and Coolify Compose under resources/infrastructure/.deploy/. Preserve the Agon workflow markers, stages, runner tags, shared runtime/cache definitions, manual release gate, and release-before-publish dependency chain.
  • Follow publica-negotia for Docker jobs and Bake: use the runner-provided Docker tools, the shared Harbor login template, and a direct Bake invocation. Keep image names, tags, platforms, outputs, and OCI metadata in HCL. Never install a Docker client in a Node job or introduce Docker-in-Docker for these jobs. Local image checks must explicitly select Docker-only output and local tags.
  • Keep maintained helper code under src/. Reserve src/scripts/ci/helpers/ for entry points named directly in GitLab job configuration, and put shared implementation under src/scripts/ci/lib/.
  • Use node:24-trixie for Node jobs and keep the dedicated Playwright image for browser jobs. Both environments use glibc so the warmup and consumers share one compatible Yarn download cache. Keep the yarn-cache-node24-glibc prefix distinct from earlier musl caches. Resolve Yarn through Corepack from the root packageManager declaration and verify that Yarn version before immutable installation. Keep the images compatible with the Node engine range. Treat .nvmrc as the optional local version selection, not an exact CI patch requirement. Use Git and GNU tar supplied by the Debian image without reinstalling them in jobs.
  • Cache only dependency downloads. Pass built applications, package archives, integrity metadata, and reports through declared job artifacts. Keep all downstream dependencies mandatory for delivery.
  • Follow the Agon skeleton’s local CI pattern: .gitlab-ci-local.yml includes the hosted pipeline, the ignored variables file is owner-only, and yarn ci:local is the sole local executor entry point. Use CI_LOCAL_PIPELINE=true. Reserve CI_MANUAL_PIPELINE for hosted manual workflows.
  • Keep the runner’s exact emulator version, explicit job allowlist, command-specific options, active-target checks, and dependency validation synchronized with pipeline changes. Refuse unknown or active delivery jobs before execution. Default to one concurrent job and require a positive explicit override for more.
  • Execute composite prerequisites once, preserve declared artifact transfers, request scoped cleanup, and retain useful ignored reports. Never mount the Docker socket into ordinary verification jobs or copy developer environment files into executor workspaces.
  • Keep V8 coverage scoped to maintained source, including unimported files. Preserve GitLab’s percentage extraction, Cobertura annotations, and retained reports. Document scope and thresholds without implying browser coverage is included.
  • Never execute release, publish, deployment, tag, upload, or registry-write jobs locally. Isolated unit tests of delivery helper logic are permitted only with every filesystem, network, and subprocess boundary mocked. Read-only configuration expansion and these unit contracts do not invoke delivery jobs or contact registries.
  • Keep npm and release-download publication restricted to hosted protected-main push release candidates after explicit manual release creation. Site images may publish from verified protected-branch push or UI pipelines for unreleased playground deployments. Production deployments must verify a stable release and its attached image digest. Never add a tag, merge-request, scheduled, or local delivery path.
  • Publish the synchronized @agon/atrium, @agon/atrium-publisher, @agon/atrium-starter, and @agon/atrium-showcase packages to the current GitLab project’s registry using its job token. Keep the root private. Preflight every archive and registry version before uploading in dependency order. Never commit credentials, print tokens, or use public npm as a fallback.
  • Verify archive integrity and an independently installed consumer before release. Preserve source/archive comparison, release-commit verification, and duplicate-version refusal during publication.
  • Keep changelog entries under UNRELEASED during development. Before release, require a committed English long date such as 20 September 2026 matching the publication day in Europe/Zurich. Release preparation validates and extracts the notes without changing their date or the source changelog. Recheck the date in the manual creation job before creating the tag and release. The GLab image must include tzdata to resolve the Zurich day correctly. The job checks this prerequisite without installing packages.
  • Report local checks separately from hosted validation and actual external delivery. Never claim a package was published from static or local verification.

Author

Laurent Declercq l.declercq@agon-innovation.ch

License

Unless otherwise stated all source code is licensed under LGPL 2.1 and has the following copyright:

© 2026, Agon Partners Innovation AG, All rights reserved.

The design material and the “Agon Ātrium” trademark is the property of their authors. Reuse of them without prior consent of their respective authors is strictly prohibited.

Version

Version: 20260921