114 lines
10 KiB
Markdown
114 lines
10 KiB
Markdown
# 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 `corp-v1-<code>-delivery/` under the active user's working root:
|
|
|
|
```text
|
|
corp-v1-<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, Playwright browsers, Nginx binaries, and package-manager download caches. 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
|
|
|
|
When an authorized task requires login to a Corp v1 system being built or operated, follow the shared policy in `corp-v1-main` and use only the Bitwarden-injected runtime secrets named:
|
|
|
|
```text
|
|
HL_V1_SSO_EMAIL
|
|
HL_V1_SSO_PASSWORD
|
|
```
|
|
|
|
Secret availability is capability, not authorization. Verify the destination origin and task purpose before login. Never print, inspect, log, hash, serialize, paste, screenshot, or persist either value; never place a value in a command line, URL, file, repository, prompt, Discord message, browser console, test fixture, CI output, or generated artifact. Never ask a human to paste a value into chat. If a variable is unavailable, report only its missing name and request Bitwarden/gateway injection. Login does not authorize account recovery, MFA or credential changes, permission changes, billing, spending, destructive operations, or access outside the approved project task.
|
|
|
|
|
|
## Delivery Responsibilities
|
|
|
|
### Coding
|
|
|
|
- implement only human-approved Features and their authorized tasks;
|
|
- load applicable project engineering skills before changing code;
|
|
- preserve project structure, conventions, and environment namespace;
|
|
- keep changes small, reviewable, and traceable to requirements/issues;
|
|
- avoid unrelated refactors during failure repair;
|
|
- never fabricate command, test, CI, or deployment results.
|
|
|
|
### Unit testing
|
|
|
|
- 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
|
|
|
|
Monitor local builds and Gitea Actions for:
|
|
|
|
- compile/type failures;
|
|
- unit/integration test failures;
|
|
- lint/format failures;
|
|
- dependency, packaging, container, or chart failures;
|
|
- workflow/configuration defects;
|
|
- missing or stale artifacts;
|
|
- branch/head-SHA mismatch.
|
|
|
|
A green local build is not proof that CI or delivery succeeded. Verify the actual remote branch and matching CI task/run.
|
|
|
|
### 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 smoke contract.
|
|
- 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 smoke-test without registry credentials on pull requests. Publish only from the trusted `test` branch using a narrowly scoped Harbor robot secret.
|
|
- 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, runtime smoke test, Harbor publication, digest readback, and a consumer workflow at the exact PR-head SHA as separate acceptance layers.
|
|
- 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.
|
|
- CI may orchestrate exact-head validation, but it must not start application runtime-resource service containers or receive application-resource credentials. Harmless process-local test doubles and build tools are not runtime resources. Run resource-dependent tests through a restricted trigger as private in-cluster Jobs/Workflows; 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.
|