docs(deploy): name the registry each agent-image path publishes to

The pinning section said CI republished ghcr.io on every push to main. CI
publishes git.catlow.cloud, and only for a release tag; ghcr is where the
hand-run tools/publish.sh writes, which is the reference the default names.

A release zip pins a digest on a registry an anonymous pull cannot reach, and
[containers].registry_auth -- the setting that fixes it -- was documented
nowhere. Documented there, beside the pin.

Also corrected: every shipped profile does not pin the image, and the section
link omitted its number so it matched no heading.
This commit is contained in:
sam committed 2026-10-31 00:35:49 +11:00
1 parent d07a56ff6e
commit 590bf12e26
6 files changed
+60 -23

No files matched your search

+7 -4
View File
@@ -101,10 +101,13 @@ move nothing, which looks like success.
Tagging one version produces, from a single `deploy` run:
- **Container images** — `ghcr.io/samcharles93/archied:latest` and
`ghcr.io/samcharles93/archie-agent:latest`. The runtime image is rebuilt by
the release, so runtime commits merged to `main` do not reach a running
sandbox until the host pulls the new image.
- **Container images** — `git.catlow.cloud/sam/archied:latest` and, on a
release tag, `git.catlow.cloud/sam/archie-agent:latest`. The runtime image is
rebuilt by the release, so runtime commits merged to `main` do not reach a
running sandbox until the host pulls the new image. The hand-run
`tools/publish.sh` publishes the same two images to
`ghcr.io/samcharles93` instead, which is the registry the binary's default
`[containers].image` names.
- **`:latest` names the newest release, not the newest commit.** A push to
`main` that is not a release publishes `archied:edge` (mutable, tracking
`main`) and `archied:sha-<commit>` (immutable) instead, so a release's
+6 -2
View File
@@ -21,8 +21,12 @@ of its own (`deployments/systemd-user-service.md`).
`archie-agent` (the per-task sandboxed runtime) has no unit of its own: it
ships beside `archied` because a Kit run mounts it from that directory. The
agent image `ghcr.io/samcharles93/archie-agent` is a separate thing, pulled by
digest for the containers `archied` spawns per task.
agent image is a separate thing, pulled for the containers `archied` spawns
per task: `[containers].image` defaults to
`ghcr.io/samcharles93/archie-agent:latest`, while this archive's `release.json`
pins the digest the release published. Set `[containers].registry_auth` when
that reference is on a registry that needs a login -- see
`deployments/systemd-user-service.md#6-pinning-the-archie-agent-image`.
## Quickstart
+2 -2
View File
@@ -61,8 +61,8 @@ url = "nats://172.19.0.1:4222"
network = "archie-core_default"
# Pin your own registry's tag/digest -- never deploy against a bare
# ":latest" reference, which can change under a running deployment with no
# warning. See deployments/systemd-user-service.md#pinning-the-archie-agent-image
# for the pinning convention this repo follows for its own GHCR image.
# warning. See deployments/systemd-user-service.md#6-pinning-the-archie-agent-image
# for the pinning convention this repo follows for its own agent image.
image = "git.example.com/you/archie-agent:v1.21.0" # or "@sha256:..." for a production digest pin
max_concurrency = 4
# Must outlast the whole-task limit (default 4h), or the reaper ends a run the
+2 -2
View File
@@ -53,8 +53,8 @@ mode = "embedded"
[containers]
# Pinned to a verified digest -- archie-agent has no published semver tag
# yet (CI only pushes :latest). See
# deployments/systemd-user-service.md#pinning-the-archie-agent-image.
# yet (a release publishes :latest and :sha-<commit>). See
# deployments/systemd-user-service.md#6-pinning-the-archie-agent-image.
image = "ghcr.io/samcharles93/archie-agent@sha256:870f1b1357979cfea23fccacb24166ebeb9ab321708ef2c2b218a763ed99b090"
pull_policy = "missing"
+42 -12
View File
@@ -134,9 +134,10 @@ Compose service or host `archie-agent` binary is required.
Docker must be installed and reachable by the service user. With no explicit
broker or container settings, Archie defaults `containers.image` to
`ghcr.io/samcharles93/archie-agent:latest`. Every profile shipped in
`deployments/` overrides that default with a pinned reference -- see
[Pinning the archie-agent image](#pinning-the-archie-agent-image) below. An
`ghcr.io/samcharles93/archie-agent:latest`. `single-forge-github.toml` and
`docker-nats-stack.toml` override that default with a pinned reference
(`standalone.toml` and `dev.toml` leave it) -- see
[Pinning the archie-agent image](#6-pinning-the-archie-agent-image) below. An
explicit equivalent, pinned the same way, is:
```toml
@@ -168,16 +169,26 @@ fall back to a host model loop.
## 6. Pinning the archie-agent Image
`ghcr.io/samcharles93/archie-agent:latest` is a moving target: every push to
`main` that touches the runtime's package closure re-publishes it
(`.github/workflows/deploy.yml`), so `latest` can change under a running
deployment with no warning and no way to reproduce a prior build.
`archie-agent:latest` is a moving target: every release re-publishes it, so it
can change under a running deployment with no warning and no way to reproduce a
prior build. Two paths publish it, to different references:
As of this writing, `archie-agent` has **no published semantic-version tag**
-- CI only pushes `:latest` to GHCR (`archied` is versioned independently per
`RELEASING.md`, but that versioning is not yet reflected as a registry tag for
the agent image). Until CI publishes one, the only reproducible reference is
a content digest, resolved once and pinned explicitly:
- `.github/workflows/deploy.yml` publishes `git.catlow.cloud/sam/archie-agent`
as `:latest` and `:sha-<commit>` when the commit carries a release tag; an
ordinary push to `main` publishes nothing for the agent image.
- `tools/publish.sh`, run by hand for a release, publishes
`ghcr.io/samcharles93/archie-agent` as `:latest` and `:sha-<commit>`, which is
the registry the shipped default above names.
A distribution zip pins whichever one its own release published, by digest, in
`release.json`; `archied update install` then pulls exactly that.
As of this writing, `archie-agent` has **no published semantic-version tag** --
both paths publish only `:latest` and an immutable `:sha-<commit>` (`archied`
is versioned independently per `RELEASING.md`, but that versioning is not yet
reflected as a registry tag for the agent image). Until one publishes it, the
only reproducible reference is a content digest, resolved once and pinned
explicitly:
```toml
[containers]
@@ -199,6 +210,25 @@ that need byte-for-byte reproducibility guarantees a tag alone cannot give
(tags are mutable pointers; a compromised or accidentally-overwritten tag
still resolves, a digest cannot).
A reference on a registry that needs a login needs the credential in
`[containers].registry_auth` -- the release's own
`git.catlow.cloud/sam/archie-agent` digest is one, since an anonymous pull
cannot reach it:
```toml
[containers]
registry_auth = {engine = "env", key = "ARCHIE_REGISTRY_AUTH"}
```
The secret resolves to a Docker `AuthConfig` JSON document: the object
`docker login` stores under `auths`, without the surrounding map, and with a
personal access token that can read the package as the password --
`{"username":"<user>","password":"<token>"}`. Put it in
`~/.config/archie/env` as `ARCHIE_REGISTRY_AUTH` so it stays out of
`config.toml`. The field is file-owned and settled at boot, so a change takes
effect on restart; a value that cannot be read logs a warning and pulls
anonymously, which is the failure the task reports as a capability error.
The bundled update adapter snapshots the configured `[containers].image` before
rebuilding it and restores that image if the restarted daemon fails its health
check. A custom image reference is therefore supported directly in
+1 -1
View File
@@ -94,7 +94,7 @@ services:
# A tag, not the digest: Compose refuses to build an image it is told to
# name by digest. The digest a task container actually runs is pinned in
# the daemon's own [containers] image, so nothing here decides it. See
# deployments/systemd-user-service.md#pinning-the-archie-agent-image.
# deployments/systemd-user-service.md#6-pinning-the-archie-agent-image.
image: ghcr.io/samcharles93/archie-agent:latest
# ── example agent profile image ─────────────────────────────────────