HWLAB Code Queue
78 lines
3.5 KiB
Markdown
78 lines
3.5 KiB
Markdown
# HWLAB Artifact Catalog Contract
|
|
|
|
The artifact catalog is the DEV-only MVP contract for interpreting deployment
|
|
artifacts. It pins which HWLAB service image, commit, profile, namespace, and
|
|
health path a static deploy manifest is claiming for acceptance review.
|
|
|
|
This file is not a CI publish record. It does not prove that an image exists in a
|
|
registry, that a digest was produced, or that a deployment happened. Real CI
|
|
publish evidence must come from the future publishing workflow and registry
|
|
metadata. Until that exists, the catalog can only validate that the local
|
|
skeleton files agree with each other and do not drift into PROD.
|
|
|
|
## Scope
|
|
|
|
- Environment: DEV only.
|
|
- Namespace: `hwlab-dev`.
|
|
- Public DEV endpoint: `http://74.48.78.17:6667`.
|
|
- Profile: `dev`.
|
|
- Health path: `/health/live`.
|
|
- Artifact state: contract skeleton only.
|
|
- PROD deployment, PROD smoke, secret reads, force push, real image publish, and
|
|
UniDesk runtime substitution are forbidden.
|
|
|
|
## Files
|
|
|
|
| File | Role |
|
|
| --- | --- |
|
|
| `deploy/artifact-catalog.dev.json` | Machine-readable DEV artifact catalog sample and static source of truth for the skeleton. |
|
|
| `deploy/deploy.json` | DEV deploy manifest skeleton that the catalog explains. |
|
|
| `CI.json` | Lightweight command and forbidden-action skeleton. |
|
|
| `scripts/validate-artifact-catalog.mjs` | Local static validator for the catalog, deploy manifest, and CI forbidden list. |
|
|
|
|
## Pin Rules
|
|
|
|
Every service entry in `deploy/artifact-catalog.dev.json` must satisfy these
|
|
rules:
|
|
|
|
| Field | Rule |
|
|
| --- | --- |
|
|
| `serviceId` | Must be one of the frozen HWLAB service IDs and must appear exactly once. |
|
|
| `commitId` | Must match the catalog and `deploy/deploy.json` commit ID. Short or full lowercase Git SHA is allowed. |
|
|
| `image` | Must match `ghcr.io/pikastech/<serviceId>:<imageTag>` and the matching `deploy/deploy.json` service image. |
|
|
| `imageTag` | Must be the first seven characters of `commitId`. Mutable tags such as `latest`, `dev`, or `main` are forbidden. |
|
|
| `profile` | Must be `dev`. |
|
|
| `namespace` | Must be `hwlab-dev`. |
|
|
| `healthPath` | Must be `/health/live` and match the DEV health contract. |
|
|
| `publishState` | Must be `skeleton-only` until real CI publish evidence exists. |
|
|
| `digest` | Must be `not_published` in the skeleton catalog; CI must replace this with a registry digest only after publishing. |
|
|
|
|
The current skeleton commit and tag values intentionally mirror
|
|
`deploy/deploy.json`. They are traceability placeholders for static acceptance
|
|
work, not a statement that GHCR already contains those images.
|
|
|
|
## Relationship To `deploy/deploy.json`
|
|
|
|
`deploy/deploy.json` remains the deploy manifest skeleton. The artifact catalog
|
|
does not replace it and must not be consumed as proof that a release was built.
|
|
The catalog explains the artifact identity that `deploy/deploy.json` currently
|
|
claims, then adds stricter DEV-only rules around commit pinning, image tags,
|
|
health paths, forbidden profiles, and publish state.
|
|
|
|
If a future CI workflow publishes real images, it should update or generate a
|
|
publish result that includes registry digests and provenance. That publish
|
|
result may be compared with this contract, but it must not be inferred from this
|
|
contract.
|
|
|
|
## Validation
|
|
|
|
Run the local static validator:
|
|
|
|
```sh
|
|
node --check scripts/validate-artifact-catalog.mjs
|
|
node scripts/validate-artifact-catalog.mjs
|
|
```
|
|
|
|
The validator reads only local repository files. It does not contact a registry,
|
|
read secrets, build images, push images, deploy to DEV, or deploy to PROD.
|