Publish snapshot (2026-08-04)

Author: legendko

.github/workflows/publish-images.yml

@@ -0,0 +1,146 @@
+# Builds the three RAMP service images and publishes them to the GitHub
+# Container Registry.
+#
+# WHAT STARTS IT. A tag whose name begins with "v", pushed to this repository,
+# or a manual run from the Actions tab. Publishing source and publishing images
+# are deliberately separate acts: a source snapshot on its own builds nothing,
+# so a documentation-only update never reissues the images.
+#
+# A manual run must select a TAG as its ref, not a branch. The version comes from
+# the tag and there is nowhere else to get it; a branch produces no version at
+# all, and the first step below stops the run rather than letting it fail later
+# with something less obvious.
+#
+# AUTHENTICATION. The per-run GITHUB_TOKEN and nothing else. No personal access
+# token is created, stored or rotated for this workflow.
+#
+# TAGS. Exactly one per build: the version from the git tag with the leading "v"
+# removed. There is no "latest" and no moving major or minor pointer, so a
+# published tag names one build for ever. Production should pin by digest
+# (@sha256:...), which every image carries whether or not it is tagged.
+#
+# ARCHITECTURE. linux/amd64 only. The Broker and the Identity service are pure
+# Go and would need no more than the extra platform here, but the Exchange links
+# a C library for the ledger client, so an x86 runner cannot build its arm64
+# variant. Adding ARM means an arm64 runner and a manifest merge.
+#
+# Third-party actions are pinned by commit rather than by tag, because whoever
+# owns an action can repoint its tags at any time.
+
+name: Publish container images
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+concurrency:
+  # One publish per ref at a time, and never cancel a run that is under way. A
+  # half-finished release leaves some of the three images published and some
+  # not, which is worse than a slow queue.
+  group: publish-images-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-24.04
+    strategy:
+      # The three build independently. One failure must not hide the other two
+      # results, which is exactly what you need when a release breaks.
+      fail-fast: false
+      matrix:
+        include:
+          - service: exchange
+            dockerfile: src/exchange/Dockerfile
+          - service: broker
+            dockerfile: src/broker/Dockerfile
+          - service: identity
+            dockerfile: src/identity/Dockerfile
+
+    steps:
+      - name: Check out the source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+
+      - name: Sign in to the registry
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Derive the image tag
+        id: meta
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+        with:
+          # Lower case throughout: the registry refuses a mixed-case name.
+          images: ghcr.io/ramp-protocol/${{ matrix.service }}
+          # This list REPLACES the action's default rules. Keep it to the single
+          # entry: a default rule would publish tags that move.
+          tags: |
+            type=semver,pattern={{version}}
+          # Needed as well. The "latest" flavour defaults to "auto", which adds
+          # a latest tag on its own as soon as the ref is a version tag.
+          flavor: |
+            latest=false
+
+      - name: Refuse a run that has no version to publish
+        # A manual run can select any ref. On a branch the semver rule above
+        # matches nothing, so the tag list comes out empty. Without this step the
+        # build compiles all the way through and then fails inside the push, and
+        # the message it fails with does not say "you picked a branch".
+        #
+        # The ref reaches the script through the environment, never through an
+        # expression. GitHub substitutes an expression into the script TEXT
+        # before bash reads it, so at that point a ref name is command text.
+        # A ref name may hold $, backticks, parentheses, ; & and |. git does
+        # reject some characters — spaces, backslashes, control characters, and
+        # the revision syntax it needs for itself, : ? * [ ~ ^ — but not one of
+        # those omissions closes this hole. The job holds a token with
+        # packages: write for all three images.
+        #
+        # The message names no version. The tag is the only source of one, so an
+        # example here would be a second place to edit at release time, and the
+        # last one anybody would think to check.
+        if: steps.meta.outputs.tags == ''
+        env:
+          TRIGGER_REF: ${{ github.ref }}
+        run: |
+          echo "::error::No version tag was derived from ${TRIGGER_REF}. The version comes from the tag name and nowhere else: run this workflow against a tag whose name is the version to publish, with a leading v."
+          exit 1
+
+      - name: Build and push
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          # The repository root, because every service Dockerfile also copies
+          # the shared internal/ tree.
+          context: .
+          file: ${{ matrix.dockerfile }}
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          # Only the two labels that cannot be known until the build runs. The
+          # rest — source, licenses, title, description — are baked into each
+          # Dockerfile, and passing the metadata action's full label set here
+          # would overwrite the per-service title and description with this
+          # repository's own name for all three images. There is no created
+          # label because the image config already records a creation time.
+          labels: |
+            org.opencontainers.image.version=${{ steps.meta.outputs.version }}
+            org.opencontainers.image.revision=${{ github.sha }}
+          # Off on purpose. With provenance on, the pushed tag resolves to an
+          # image index carrying an extra attestation entry, which is a
+          # multi-platform manifest in everything but name. One platform is
+          # published, so the tag should resolve straight to that one image.
+          provenance: false
+          # Without a cache every run recompiles Go from cold, several minutes
+          # per service. The scope keeps the three from evicting each other.
+          cache-from: type=gha,scope=${{ matrix.service }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.service }}

Makefile

@@ -2,6 +2,7 @@
 .PHONY: go-fmt go-fmt-check go-lint go-typecheck go-test test-integration test-zitadel test-e2e-collect
 .PHONY: db-up db-down db-logs dev-keys adr-001-check adr-008-d3-check sdk-pin-check
 .PHONY: stale-proto-names-check published-refs-check published-secrets-check test-terraform
+.PHONY: image-version-check
 .PHONY: zitadel-up zitadel-creds zitadel-logs zitadel-down
 .PHONY: edge-%
 .PHONY: test-e2e e2e-keys e2e-up e2e-down e2e-logs e2e-demo
@@ -33,15 +34,15 @@ help:
 	@echo ""
 	@echo "Per-subproject: make edge-<target> (e.g. edge-lint, edge-test)"
 
-quality: fmt lint typecheck test-fast jscpd file-length adr-001-check adr-008-d3-check sdk-pin-check stale-proto-names-check published-refs-check published-secrets-check
+quality: fmt lint typecheck test-fast jscpd file-length adr-001-check adr-008-d3-check sdk-pin-check stale-proto-names-check published-refs-check published-secrets-check image-version-check
 	@echo "All quality gates passed!"
 
 # CI variant of `quality`: formatting is CHECKED, never written. CI must not
 # mutate the tree, and a check FAILS on violations instead of the local `fmt`
 # silently auto-fixing them. (Go + edge formatting is also enforced by their
 # linters; tests/e2e Python formatting is enforced ONLY here.) Local
 # `make quality` keeps auto-formatting via `fmt`.
-quality-ci: fmt-check lint typecheck test-fast jscpd file-length adr-001-check adr-008-d3-check sdk-pin-check stale-proto-names-check published-refs-check published-secrets-check
+quality-ci: fmt-check lint typecheck test-fast jscpd file-length adr-001-check adr-008-d3-check sdk-pin-check stale-proto-names-check published-refs-check published-secrets-check image-version-check
 	@echo "All quality gates passed (CI, check-only fmt)!"
 
 file-length:
@@ -90,6 +91,13 @@ published-refs-check:
 published-secrets-check:
 	@scripts/check-published-secrets.sh
 
+# Keeps the published image version declared once per deployment document and
+# identical across the three. A release edits one line per document; a partial
+# edit would otherwise leave a document naming a tag nobody published, which
+# reads as correct right up to the "not found".
+image-version-check:
+	@scripts/check-image-version.sh
+
 fmt: go-fmt
 	@$(MAKE) -C src/edge fmt
 	@$(MAKE) -C tests/e2e fmt

docker-compose.e2e.yml

@@ -919,6 +919,13 @@ services:
       # installing the CLI keeps the runner image small and avoids pinning a
       # client version against whatever daemon the host happens to run.
       - /var/run/docker.sock:/var/run/docker.sock
+      # The revocation e2e writes revocations.json through the harness tree, and
+      # the broker service above reads THE SAME host directory at /revocations
+      # (BROKER_REVOCATION_FILE). The mount is what makes the write cross the
+      # container boundary. Without it the path resolves inside the runner
+      # image's own layer — the directory is there, because COPY brought
+      # .gitkeep in, so the write succeeds and the Broker never sees a byte.
+      - ./tests/e2e/harness/revocations:/runner/harness/revocations
     depends_on:
       exchange:
         condition: service_started

docs/architecture/adr-024-container-image-distribution.md

@@ -0,0 +1,161 @@
+# ADR-024 — Container Image Distribution
+
+**Status:** Accepted (2026-08-03)
+**Relates to:** ADR-020 (RAMP SDK layered libraries) — the same question asked about library packages rather than container images.
+
+---
+
+## Context
+
+Three services of this implementation ship as containers: the Exchange, the Broker
+and the Identity service. Each has a Dockerfile under `src/<service>/` and a
+deployment document that tells an operator how to run it.
+
+Until this decision, nothing was published anywhere. Two of those three deployment
+documents nonetheless stated that the image was available from a public registry,
+and named one we do not use. The image names they printed were unqualified, so a
+reader who copied them resolved a registry we have never pushed to and got "not
+found". The documents promised an artifact that did not exist, in a place it would
+never have been.
+
+Two things are deliberately outside this decision:
+
+- **The Edge worker.** It deploys as a Cloudflare Worker, not a container. Its
+  Dockerfile is a local test harness for the e2e stack and is not a deliverable.
+- **Postgres, Redis, TigerBeetle, Vault and the identity provider.** These are
+  upstream images pulled from their own publishers, pinned by us, built by them.
+
+Two other push paths for these same three images already exist, and neither is what
+this decision governs. `scripts/ecr-push.sh` pushes to a private AWS registry to roll
+the demo deployment. `deploy/terraform/scripts/build-push-images.sh` pushes to
+whichever registry a staging stack is configured with. Both are deployment plumbing:
+one environment, one audience, a registry chosen per deployment. This decision is
+about the public artifacts of a reference implementation, where the audience is
+anyone and the guarantees have to hold without us being in the room. All three
+coexist and none shares a naming scheme with the others.
+
+## Decision
+
+### D1 — Images are published to the GitHub Container Registry, under flat names
+
+`ghcr.io/ramp-protocol/exchange`, `ghcr.io/ramp-protocol/broker`,
+`ghcr.io/ramp-protocol/identity`. Not nested under the repository name.
+
+The source already lives on GitHub, so the registry is part of the same account and
+the build needs no credential that anyone has to hold, store or rotate (see D4).
+Names are flat because the service is the unit an operator deploys; which repository
+it was built from is recorded in the image's `org.opencontainers.image.source` label
+instead. That label carries weight: it is what links the published package to its
+repository, and linking is what makes the package manageable and publishable at
+all.
+
+Registry names must be lower case, so the organisation appears as `ramp-protocol`.
+
+### D2 — One immutable version tag per build, and no `latest`
+
+Each build publishes exactly one tag: the version, with no leading `v`. No `latest`,
+and no moving major or minor pointer such as `1.0`. A published tag names one build
+and is never repointed.
+
+A `latest` may be introduced later, once there is a release history for it to point
+at. Nothing in this decision prevents that.
+
+The immediate consequence is intended: `docker pull ghcr.io/ramp-protocol/exchange`
+with no tag **fails**. An operator who omits the version finds out immediately,
+rather than silently running whatever was pushed most recently.
+
+Production should deploy the digest, not the tag. Every image has a `@sha256:...`
+address whether or not it is tagged. Our tags are written once and never moved, but
+that is a policy of ours; a digest is content-addressed and cannot be moved by
+anyone. Where the two disagree, the digest is the one that is a guarantee.
+
+### D3 — `linux/amd64` only
+
+No arm64 variant, and no multi-architecture manifest. The provenance attestation
+that the build tooling would otherwise attach is switched off for the same reason:
+it turns the published tag into an image index, which is a multi-platform manifest
+in all but name, and only one platform is published.
+
+What an ARM build would cost, for whoever revisits this. The Broker and the Identity
+service are pure Go with cgo disabled, and would need no more than the extra platform
+in the build. The Exchange is different: it links a C library for the TigerBeetle
+ledger client, and cgo cannot cross-compile without a cross toolchain, so an x86
+runner cannot produce its arm64 variant at all. The clean route is a native arm64
+runner plus a manifest merge. That is real work, and no target deployment needs it
+today.
+
+### D4 — The build runs in the public repository, authenticated by its per-run token
+
+`.github/workflows/publish-images.yml` builds all three images and pushes them,
+signing in to the registry with the token GitHub issues for the run. No personal
+access token is created, stored, or rotated for this purpose, and the workflow
+contains nothing secret.
+
+The workflow is authored **here**, in the source repository, and travels to the
+public repository through the publish allowlist in `scripts/published-paths.sh`. It
+cannot be authored on the public repository instead: the publish rebuilds that tree
+from the allowlist and deletes everything it does not reproduce, so a workflow
+created there would survive exactly until the next snapshot.
+
+### D5 — Publishing the source and publishing the images are separate acts
+
+A snapshot of the source builds nothing. The workflow listens for version tags only,
+and the publish pushes a branch. Pushing a version tag to the public repository is
+what produces images.
+
+The separation is the point. Documentation-only snapshots are frequent, and each one
+would otherwise reissue three images with a new build date and a new digest for
+unchanged code. Deciding to publish source and deciding to publish binaries are
+different decisions and should stay two commands.
+
+## Consequences
+
+**Positive.**
+
+- An operator pulls an artifact instead of compiling one, and needs no Go toolchain,
+  no C toolchain, and no copy of the source to run the platform.
+- Nothing to leak. There is no long-lived registry credential anywhere, so there is
+  none to rotate and none to lose.
+- The absence of `latest` removes a whole class of "which version is production
+  actually running" incidents, at the cost of making every example more verbose.
+- Every image is traceable back to the commit it was built from through the
+  `revision` and `version` labels the workflow stamps at build time.
+
+**Negative.**
+
+- Anyone on an ARM machine runs these under emulation. That is fine for inspection
+  and wrong for measurement, and every deployment document has to say so.
+- The allowlist entry that carries the workflow copies the whole `.github` subtree.
+  Anything added there later reaches the public repository with no further decision.
+  The allowlist file records this; per-file granularity would have to be built if it
+  ever matters.
+- Publishing stays ours. Whoever develops the protocol publishes the images, so a
+  third party who wants a different registry has to build their own.
+
+## Non-goals
+
+- **Signing and attestation.** Images are not signed, and no SBOM is published. Both
+  are reasonable next steps and neither is a prerequisite for a first release.
+- **A support or deprecation policy for published versions.** Nothing here commits to
+  keeping any version pullable for any period.
+- **Publishing the Edge worker as a container.** It is not deployed that way.
+
+## Rejected alternatives
+
+**A public Docker Hub organisation.** It is where the deployment documents already
+pointed, so it looked like the smallest change. It needs an organisation account, a
+credential stored as a repository secret, and someone to own rotating it — all to
+put the artifact somewhere other than where its source already is. Rate limits on
+anonymous pulls are a second, smaller reason against.
+
+**Reusing the private AWS registry.** It already builds and pushes these three
+images. It is private, tied to one cloud account, and the images it holds are named
+for a demo deployment. Making it public would mean publishing an operational
+registry, which conflates our environment with the reference implementation's
+artifacts.
+
+**Nesting the image names under the repository**
+(`ghcr.io/ramp-protocol/reference-implementation/exchange`). This is the registry's
+default shape and needs no decision. It reads as though the repository were part of
+the artifact's identity, and it makes every command in every deployment document
+longer for no gain to the reader.