deploy-standard

Files (4)

• SKILL.md
• environments.md · references/
• target-conventions.md · references/
• validation.md · references/

SKILL.md (first lines)

# Deployment standard

Build once. Distribute without modification. Run with configuration owned by
the environment.

## Required references by task

Reference files beside this skill are normative under it; load them by
task before working:

| Work touches | Must also read |
| --- | --- |
| Compose, local modes, tags, development hosts, environments | [`references/environments.md`](references/environments.md) |
| Bazel image, fixture, or release target names | [`references/target-conventions.md`](references/target-conventions.md) |
| Architecture or release validation | [`references/validation.md`](references/validation.md) |

## Execution pipeline

1. Source
2. Bazel
3. OCI image
4. Distribution adapter — `oci_load` to the local container runtime, or
   `oci_push` to an OCI registry
5. Runtime orchestrator

| Boundary | Responsibility |
| --- | --- |
| Source | Declares application or fixture content and build inputs |
| Bazel | Builds executable artifacts, deterministic layers, and repository-owned images |
| OCI image | Carries environment-independent runtime content |
| Distribution adapter | Makes an existing image available without rebuilding it |
| Runtime orchestrator | Runs the supplied image and injects runtime configuration |

Do not move construction into distribution or orchestration.

## Build authority

Bazel is the build authority for project application images, repository-owned
fixture images under `deploy/images/`, deterministic image layers, and
test-consumable OCI archives. Docker, Compose, registry tooling, deployment
scripts, tests, and cloud runtimes consume completed images; they do not
build or modify them. `oci_load` and `oci_push` are distribution, not
construction.

Do not introduce:

* a Dockerfile as an alternate application-image definition;
* a Compose `build:` stanza for a project application;
* a Compose build path for a repository-owned fixture;
* a second image path for a particular environment;
* a script that reproduces Bazel image assembly;
* a test-only image that diverges from the canonical image target.

## Artifact classes

**Application image** — a project executable plus required runtime
dependencies. Canonical targets: `<service>_image`, `<service>_load`.

**Repository-owned fixture image** — an infrastructure runtime whose derived
artifact contract the repository maintains. Canonical targets:
`<service>_fixture_image`, `<service>_fixture_load`,
`<service>_fixture_test_tar`.

A fixture is repository-owned when the repository controls material
characteristics. These include required packages, deterministic configuration,
architecture support, extension availability, runtime files, test behaviour,
security defaults, or compatibility behaviour relied upon by the repository.

Repository-owned fixtures follow the same build discipline as application images.

**Direct third-party fixture** — consumed directly when the upstream image
itself is the intended dependency and satisfies the runtime contract without
a repository-owned derivation. Verify: the upstream project is maintained;
the selected artifact is supported; required architectures are published; the
image satisfies the fixture contract; normal execution needs no emulation or
forced architecture pin.

**Compose-built fixture wrapper** — a narrow wrapper under
`deploy/dev/images/` adapting a third-party local fixture. It must not
contain project application binaries, become an alternate application build
path, replace a canonical image target, become an undeclared test dependency,
or expand beyond its local fixture purpose. Once a canonical fixture exists
under `deploy/images/`, Compose and tests consume it rather than rebuilding
or pulling an alternate version.

## Third-party dependency discipline

Do not rely on an obsolete, abandoned, architecture-limited, or unmaintained
image merely because it already exists on a public registry. When an upstream
preassembled image is unsuitable, prefer maintained upstream components
assembled through Bazel.

Repository-owned images should use, where supported: base images pinned by
digest; declared package manifests; committed package locks;
architecture-specific package resolution; deterministic filesystem layers;
explicit OCI metadata.

A mutable package repository is permitted only through a resolution process
that records the exact selected artifacts in a committed lock.

Replacing one use of a stale image is not sufficient: Compose, tests,
scripts, and other consumers converge on the approved artifact. Do not
preserve stale dependencies because tests already use them, they work on one
CPU architecture, the runtime can emulate them, or a local override hides
the problem.

## Deployment fixtures in tests

Tests using a repository-owned fixture image consume the canonical Bazel
artifact. The fixture must be supplied as a declared build input and must be
available as a loadable OCI archive. Load it under an isolated test tag before
the container starts.

The fixture must require no manual developer preload or direct pull of a
replacement image. It must derive from the same canonical image used by local
orchestration.

Prerequisite status is test-specific. A test that requires a local
Docker-compatible daemon for real container behaviour must declare that

From iamthenop/infurnet-skills, MIT.

More from iamthenop/infurnet-skills