Files
channel-delivery-skic/references/runtime-and-ci.md

10 KiB

the adopted project Runtime and CI

Load this reference before login, toolchain execution, CI work, image publication, or Gondor resource work.

Channel-owned workspace

Resolve the channel root as <code>-delivery/ under the active user's working root:

<code>-delivery/
├── cache/                 # reusable channel toolchains and technical dependencies
├── uploads/
└── workspace/
    └── <TASK_ID>/
        ├── application/       # always: repository clone
        ├── documentation/     # always: repository clone
        ├── review/            # optional: only when separate review files are needed
        ├── cache/             # optional: only when a Task-specific cache is needed
        ├── tmp/               # optional: only when temporary Task files are needed
        ├── logs/              # optional: only when logs must be retained
        └── artifacts/         # optional: only when outputs must be retained
  • cache/ contains reusable technical dependencies installed by Delivery, including pinned Node/pnpm toolchains, Nginx binaries, and package-manager download caches. Browser/Playwright dependencies for non-unit suites belong to the UAT workspace and E2E repository. Reuse verified entries across Tasks instead of reinstalling them. Version or digest cache paths when compatibility matters, verify the resolved executable and version in every execution context, and never store credentials, Task evidence, repository content, or mutable application state there.
  • uploads/ contains files supplied through this channel. It is not a repository checkout or build directory.
  • Create one workspace/<TASK_ID>/ directory per Task.
  • During GATE_001_PREP, create only the required repository clones: application/ and documentation/. If a Task genuinely needs another repository, clone it as another clearly named child.
  • Do not create Task-local review/, cache/, tmp/, logs/, or artifacts/ speculatively. Create each folder only when a concrete activity for that Task needs it.
  • Use Task-local review/ only for a separate review checkout or review output. Use Task-local cache/ only for non-reusable data bound to that Task; reusable installed technical dependencies belong in the channel-level cache/. Use tmp/, logs/, and artifacts/ only for their named Task-local purpose.
  • Run dependency installation, generation, tests, and builds inside the applicable repository clone using that repository's normal paths. Copy or export outputs to artifacts/ only when they must be retained separately.
  • Keep every optional folder inside the selected Task directory. Never share it between Tasks or place it at the channel root.
  • Before every local repository command, resolve the real working directory and require it to be inside the selected Task directory. A command running elsewhere is invalid evidence and must stop before mutation.
  • Do not reuse another Task's clone or support folder as a shortcut. Resume only from the selected Task's own workspace after fetching and matching its visible PR head.

Shared Corp v1 System Login

Before login, load channel-board-skic and follow its complete Corp v1 System SSO Credential Use policy through Delivery's source/authority binding. Stop if unavailable; secret access grants no additional authority.

Delivery Responsibilities

Coding

Load development-monorepo-pnpm for pnpm/TypeScript implementation and development-scripts for Taskfile, shell, environment and Devbox work, using their source links and project-overlay precedence. Preserve project structure/namespace; implement only approved Features and authorized Tasks with small, traceable changes, no unrelated refactors and no fabricated results.

Unit testing

Load development-method-ttd before behavior changes, fixes or refactors using its source link. Its reusable mechanics do not replace the Task gate's unit/UAT boundary or resolve local-discard versus forward-repair policy.

  • add or update tests with behavioral changes;
  • reproduce defects before fixing when practical;
  • cover normal, edge, and failure cases proportional to risk;
  • run the narrowest relevant tests first, then required broader validation;
  • record exact commands and real results.

Build and continuous integration

Use Delivery's build/CI responsibilities for the required failure classes and UAT remediation boundary. Before reporting CI, load development-integrity through status-and-reporting.md; a local build is not remote CI evidence. Task gate job inventory and exact-head checks still apply.

Execution-context toolchain preflight

Treat every foreground shell, detached worktree, background process, Hermes main-session review command, and CI job as a separate execution context. Before any repository command or operation runs in an execution context, complete the applicable preflight for that exact context. For a Node/pnpm repository—or any command that may invoke Node or pnpm—the following checks are mandatory:

  1. resolve the repository-required Node and pnpm versions from its committed toolchain contract;
  2. run command -v node, node --version, command -v pnpm, and pnpm --version inside the exact context, then compare the observed versions with the committed required versions;
  3. verify required non-secret environment variable names are present, including disposable-test database markers when applicable, without reading or printing their values;
  4. verify the actual working directory, linked branch/PR identity, and clean or intentionally staged repository state; and
  5. start the repository command only after every applicable preflight check passes.

Never assume a background process inherits PATH, shell activation, Devbox state, Corepack activation, database variables, or other exports from a foreground terminal. A missing pnpm executable is always an execution-context/toolchain failure, never an application-code or test failure. Repair the exact context by providing the required toolchain path or activation, repeat the complete preflight there, and rerun the original command before making any claim about repository code.

Per-project reusable CI base images

the adopted project owns corp-v1-<code>/corp-v1-<code>-base-images as the reusable CI-image repository. Use it when stable runtimes or operating-system tools would otherwise be downloaded repeatedly in application jobs.

  • Keep one folder per image, with its Dockerfile, machine-readable version/platform metadata, usage documentation, build helper, and static publication contract. Runtime smoke belongs to UAT.
  • Pin the upstream base by digest and assert exact runtime/tool versions, architecture, numeric non-root identity, writable workspace, CA trust, Git, shell, and other required tools.
  • Build and perform static/unit validation without registry credentials on pull requests. Publish only from the trusted test branch using a narrowly scoped Harbor robot secret; UAT validates the published digest at runtime.
  • Publish immutable full-source-SHA tags, read back the Harbor artifact digest, and consume the image from the adopted project workflows by digest—not latest, a mutable version tag, or an unverified local name.
  • Extend fail-closed tests to reject broad publication triggers, mutable tags, secret access from PR paths, shell interpolation, wrong digests, and reintroduced runtime setup actions.
  • Prefer the verified job image over repeated actions/setup-node or package-manager bootstrap steps. Keep pnpm install --frozen-lockfile --ignore-scripts in the application repository for lockfile parity; do not bake project dependencies into a generic base image.
  • Treat the first real Gitea build, Harbor publication, digest readback, and consumer workflow at the exact PR-head SHA as separate Delivery layers. Runtime smoke is a separate UAT layer.
  • Repair image or publication failures forward only. Preserve the last known-good digest for consumers until the replacement image and consuming workflow pass exact-head CI.

Gondor runtime-resource placement

The adopted project CI jobs and developer workstations must not provision PostgreSQL, queues, object stores, caches, brokers, or other application runtime services. Load development-gitops-argo-cd-gondor-v1 before defining or changing Gondor desired state. Render the committed project template separately into one repository per environment; Delivery may update only the repository assigned to its non-production environment, while production remains outside Delivery authority unless an explicit project overlay says otherwise.

  • Keep every non-production the adopted project environment—including development, integration, test, staging, and preview—and all of its resources isolated from production and from other non-production environments. Destructive or concurrent validation requires a per-run database/schema/role or explicit serialization; it must not reset shared data.
  • Delivery CI may orchestrate exact-head unit/build validation, but it must not start application runtime-resource service containers or receive application-resource credentials. Harmless process-local unit-test doubles and build tools are not runtime resources. UAT owns resource-dependent tests and their restricted execution; Delivery only provisions an approved development dependency and hands its exact identity to UAT. Do not expose PostgreSQL or another internal resource through Ingress, NodePort, LoadBalancer, or a runner-accessible public endpoint.
  • Persistent Gondor storage must follow home-v1--truenas. For durable the adopted project data, create a purpose-specific TrueNAS dataset and NFS share restricted to Gondor node networks, then bind a static PV/PVC with persistentVolumeReclaimPolicy: Retain and storageClassName: "". Do not use the default dynamic truenas-csi StorageClass for durable data because its Delete reclaim policy can remove the backing dataset with the PVC.
  • Use only External Secrets backed by the existing Bitwarden ClusterSecretStore; never commit connection strings or credentials.
  • Provision and verify required Gondor resources before deploying dependent the adopted project code. Resource-independent implementation may proceed, but deployment remains blocked until the dependency is healthy and consumed by the application.