Files
clean-architecture-backend-…/.github/workflows/release.yml
T
DongHyeonka 34565130e0 fix!: 성숙도 리뷰의 High·P1 결함 19건을 고친다
문제: 2026-11-01 성숙도 리뷰에서 High 21건·P1 25건이 나왔다. 결과를
모르는 일을 "확실함"으로 기록했다(발송 중 죽은 알림 재발송, 커밋 중
끊긴 쓰기를 재시도 가능으로 응답, 재시도 가능한 거부를 DEAD로). 중복을
DB가 아니라 코드 순서로 막았다(정산 job, 포스터 제목). 짝 프론트와
wire 계약이 달랐고(처리 중 409, Envelope null), JWT audience 검증이
기본으로 꺼져 있었고, 트레이스가 나가지 않았고, CI가 strict lane 14개를
한 번도 돌리지 않았다.

방법: 발견마다 실패하는 테스트를 먼저 쓰고 고쳤다. 주요 선택:
- 알림 attempt는 처음부터 "시작 여부 모름"으로 쓴다(호출 직전 갱신은
  쓰기가 하나 늘어 버림).
- 정산 job claim은 lease·fence를 갱신하는 UPDATE 한 문장(처리 전체를
  트랜잭션으로 감싸는 안은 외부 호출 동안 잠금을 잡아 버림).
- 커밋 단계 연결 끊김은 DB_COMPLETION_UNKNOWN(재시도 불가).
- 처리 중 409는 retryable=true + Retry-After: 2, Envelope null 필드는
  web Jackson mixin으로 생략(shared-contract는 stdlib only).
- 트레이싱은 자체 Tracer를 지우고 Boot 4 tracing·OTLP로.
- strict lane을 단계에 연결하고 verifyStrictLaneStages가 고아를 막는다.
발견별 RED·GREEN·버린 대안은 리뷰 README 13절 표에 있다.

위험·한계: JWT 모드는 APP_SECURITY_JWT_AUDIENCE가 없으면 기동하지
않는다. 짝 프론트는 409 retryable과 Envelope 키 규칙을 맞춰야 한다.
이 커밋 시점에는 MinIO 공식 이미지가 사라져 MinIO 2 lane이 실패한다
(다음 커밋에서 대체 이미지로 해결).

검증: ci 통과. mainCheck·integrationCheck는 MinIO 2 lane만 실패(이미지
pull 거부). -p optional-platforms ci integrationCheck, performanceCheck,
releaseCheck(-PgitRevision) 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 2·13절
BREAKING CHANGE: JWT 모드에서 APP_SECURITY_JWT_AUDIENCE가 필수가 되고 role은
audience client와 realm 것만 읽는다. IDEMPOTENT_IN_FLIGHT가 retryable=true,
Retry-After: 2로 바뀌고 Envelope는 null 필드를 보내지 않는다.
2026-11-03 19:52:06 +09:00

753 lines
38 KiB
YAML

name: release
# Stage 3: produce a deployable artifact.
#
# One workflow, because there is one deployable unit. `app-bootstrap` is the composition root and
# the only thing a cluster runs; the adapters are leaves of that artifact, not independently
# shippable services. Eight files used to answer a release tag — web-release, web-advanced-release,
# websocket-release, httpclient-release, container-release, jpa-release, fileserver-certification
# and one more — and between them they ran `verifyCleanArchitectureDependencies` six times and the
# composition root's unit tests four times for one release, on separate runners, with no job in any
# of them able to wait on a job in another.
#
# Tag scheme: `v*` only. The adapter-scoped patterns (`web-v*`, `websocket-v*`, `fileserver-v*`) are
# gone. They were the namespace-split bug: tagging `v1.2.3` and tagging `web-v1.2.3` ran different
# sets of gates, so a release could choose which gate it cleared, and the adapter-scoped half could
# not build an image because there is no per-adapter image to build.
#
# The JPA release gates and the fileserver certification used to stand outside this file
# (jpa-release.yml, fileserver-certification.yml), so the image job could not wait on them. They are
# jobs here now (review 2026-09-24 BUILD-계획-B2): JpaReleaseRenderingTest reads this file's JPA
# matrix and promotion list, and FileserverDocumentationCoverageTest reads its fileserver job ids.
#
# The image job waits on every evidence job in this file: `needs:` does not reach across
# workflows, so a gate in another file could still be running, or already red, when the image
# published.
on:
push:
tags:
- "v*"
permissions:
contents: read
# Never cancel a release in flight. A half-pushed manifest is worse than a slow one, and two runs
# for the same tag would race for the same registry tags.
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false
jobs:
# The tag-only checks. releaseCheck no longer re-runs `ci`: a release tag is cut from a main
# commit that ci-quality-gates.yml (the pull-request gate) and integration-main.yml (`mainCheck`)
# already ran on, and running the whole PR gate a third time was the repeat review BUILD-중복-6
# asked to remove.
architecture-and-surface:
runs-on: ubuntu-latest
timeout-minutes: 90
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the repository release contract
working-directory: src
run: ./gradlew :releaseCheck --stacktrace
# Every web lane that `check` cannot reach: the servlet system contract on Tomcat (systemTest)
# and Jetty (webJettyCompatTest), and the Advanced lane.
#
# webAdvancedTest is here rather than in a nightly of its own. Its tests run inside
# `:adapter:inbound:web-advanced:test` by design, so the lane adds exactly one thing: it fails closed when
# the `web-advanced` tag selects nothing. That is worth asserting at a release and is not worth a
# workflow file and a runner every night.
web-stable-release-gate:
runs-on: ubuntu-latest
timeout-minutes: 90
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run every web lane, Stable and Advanced
working-directory: src
run: >-
./gradlew
:adapter:inbound:web:systemTest
:adapter:inbound:web:webJettyCompatTest
:adapter:inbound:web-advanced:webAdvancedTest
--stacktrace
- name: Publish the release evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: web-release-evidence
path: |
src/adapter/inbound/web/build/reports/tests/
src/adapter/inbound/web-advanced/build/reports/tests/
if-no-files-found: error
websocket-stable-release-gate:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run every websocket lane
working-directory: src
run: >-
./gradlew
:adapter:inbound:websocket:test
:adapter:inbound:websocket:systemTest
:adapter:inbound:websocket:websocketJettyTest
:adapter:inbound:websocket:websocketNginxTest
:adapter:inbound:websocket:websocketTransportQualificationTest
--stacktrace
- name: Publish the release evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: websocket-release-evidence
path: src/adapter/inbound/websocket/build/reports/tests/
if-no-files-found: error
# The three gRPC certification lanes. Their tests already run on every pull request — the
# `grpc-inprocess`, `grpc-netty` and `grpc-fault` tags are NOT excluded from
# `:grpc:grpc-testkit:test` (only `grpc-performance` is), and that task runs inside the root
# `check`. So this job adds exactly what the web Advanced lane above adds: the lane
# fails closed when its tag selects nothing, which is the one thing a tag-filtered suite inside
# `test` cannot tell you. A renamed or deleted @Tag would otherwise leave the in-process,
# transport and fault evidence grades claiming coverage that stopped existing.
#
# Release rather than nightly, for the same reason web-stable-release-gate is: these lanes need no
# container and no fixed cadence — grpcNettyContractTest opens an ephemeral socket, not a broker —
# so the guard is worth asserting once per tag and is not worth a runner every night.
#
# grpcPerformanceTest is deliberately absent. The leaf excludes it from `test` and says why: "a
# measurement in the release gate is a flaky test on a shared CI runner; it runs when somebody asks
# for it, by name." It is recorded as a manual entrypoint in the repository README instead.
grpc-stable-release-gate:
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the gRPC Stable certification lanes
working-directory: src
run: >-
./gradlew -p optional-platforms
:grpc:grpc-testkit:grpcInProcessContractTest
:grpc:grpc-testkit:grpcNettyContractTest
:grpc:grpc-testkit:grpcFaultTest
--stacktrace
# The operation ledger's real-PostgreSQL lane ran only on main and nightly
# (integration-main.yml), so a tag could be cut from a main whose ledger lane was red. It needs
# Docker, which a release runner has (review 2026-11-01 03-12).
- name: Certify the gRPC operation ledger against real PostgreSQL
working-directory: src
env:
TESTCONTAINERS_REUSE_ENABLE: "false"
run: ./gradlew -p optional-platforms integrationCheck --stacktrace
- name: Publish the gRPC release evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: grpc-release-evidence
path: |
src/grpc/grpc-testkit/build/reports/tests/
src/grpc/grpc-operation-ledger-jpa/build/reports/tests/
if-no-files-found: warn
# Each gate runs as its own single-line `./gradlew <task>` step so that a failure names the gate
# rather than a folded command. The architecture dependency gate that used to end this list is now
# architecture-and-surface above; it was the fourth copy of the same invocation.
httpclient-release-gate:
runs-on: ubuntu-latest
timeout-minutes: 60
defaults:
run:
working-directory: src
env:
# A project property rather than a command-line flag, so each run command stays a plain,
# verifiable task invocation while the machine-dependent bounds are still asserted.
GRADLE_OPTS: -Dorg.gradle.project.performance.assertions.enabled=true
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the HTTP client release qualification graph
run: >-
./gradlew
:adapter:outbound:httpclient:test
:adapter:outbound:httpclient:spring62ApiSurfaceScan
:adapter:outbound:httpclient:spring70CompatibilityTest
:adapter:outbound:httpclient:httpClientStableContractTest
:adapter:outbound:httpclient:httpClientSecurityTest
:adapter:outbound:httpclient:httpClientFailureInjectionTest
:adapter:outbound:httpclient:httpClientPerformanceTest
--stacktrace
httpclient-documentation:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # actions/setup-python@v5.6.0
with:
python-version: '3.12'
- name: Verify documentation matches the code
run: python3 scripts/verify-httpclient-docs.py
# ---------------------------------------------------------------------------------------------
# JPA release gates (were jpa-release.yml). One job per PostgreSQL major, because one job for
# three majors was one job for one major: `-Pjpa.matrix.versions=16,17,18` reached
# JpaPlatformContractSupport.start(), which started only the first selected version, while
# docs/jpa/support-matrix.md recorded all three as covered. start() now fails closed on a
# multi-version selection, so this matrix is the only way the Stable majors get covered.
#
# config/jpa/release-registry.json is the gate-task source: jpaReleaseQualification (persistence-jpa
# build.gradle) depends on its blocking gates, so a gate naming a missing task fails when the task
# graph is built, and JpaReleaseRenderingTest holds this matrix and the promotion list below to the
# registry's Stable majors. Editing one without the other fails the persistence-jpa unit lane.
jpa-release-gate:
runs-on: ubuntu-latest
timeout-minutes: 90
strategy:
fail-fast: false
matrix:
postgresql: ["16", "17", "18"]
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the JPA database qualification set on PostgreSQL ${{ matrix.postgresql }}
working-directory: src
run: >-
./gradlew
jpaReleaseQualification
-Pjpa.matrix.versions=${{ matrix.postgresql }}
--stacktrace
- name: Record which major this evidence covers
if: always()
working-directory: src
run: |
mkdir -p build/jpa-release-evidence
{
echo "sha=${{ github.sha }}"
echo "ref=${{ github.ref }}"
echo "postgresql-major=${{ matrix.postgresql }}"
echo "task-set=jpa-database-qualification"
} > "build/jpa-release-evidence/manifest-${{ matrix.postgresql }}.properties"
- name: Upload the release evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: jpa-release-evidence-pg${{ matrix.postgresql }}
path: |
src/build/jpa-release-evidence/manifest-${{ matrix.postgresql }}.properties
src/adapter/outbound/persistence-jpa/build/test-results/**/*.xml
retention-days: 30
if-no-files-found: error
# The promotion decision. Every Stable major's evidence, all from this SHA — an aggregate that
# accepted a re-run artifact from another commit would promote a release on evidence produced by
# different code.
jpa-release-promotion:
runs-on: ubuntu-latest
timeout-minutes: 15
needs: jpa-release-gate
steps:
- name: Download every major's evidence
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # actions/download-artifact@v4.3.0
with:
pattern: jpa-release-evidence-pg*
path: evidence
- name: Require every Stable major, all from this SHA
run: |
set -euo pipefail
missing=0
for major in 16 17 18; do
manifest=$(find evidence -name "manifest-${major}.properties" -print -quit)
if [ -z "${manifest}" ]; then
echo "::error::no release evidence for PostgreSQL ${major}"
missing=1
continue
fi
sha=$(sed -n 's/^sha=//p' "${manifest}")
if [ "${sha}" != "${{ github.sha }}" ]; then
echo "::error::PostgreSQL ${major} evidence is from ${sha}, not ${{ github.sha }}"
missing=1
fi
done
if [ "${missing}" -ne 0 ]; then
echo "::error::the release gate covers every Stable PostgreSQL major; promotion needs all of them"
exit 1
fi
echo "Every Stable PostgreSQL major's evidence is present and from ${{ github.sha }}."
jpa-registry-and-docs:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Verify the release registry, the readiness cards and the support matrix
working-directory: src
run: >-
./gradlew
:adapter:outbound:persistence-jpa:test
--tests '*JpaReleaseManifestTest'
--tests '*JpaReleaseRenderingTest'
--tests '*JpaReadinessRegistryTest'
--stacktrace
# ---------------------------------------------------------------------------------------------
# Fileserver certification (was fileserver-certification.yml). Its job list is the same shape as
# docs/fileserver/support-matrix.md: nothing is advertised at a support level whose evidence job
# is absent. FileserverDocumentationCoverageTest reads the job ids from this file and from
# `.github/workflows/fileserver-*.yml`. "Certification" rather than "release" on purpose: these
# jobs prove a storage topology, a support matrix and a telemetry redaction claim, and deploy
# nothing (docs/ci-cd/boundary.md).
fileserver-full-verification:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the complete fileserver suite across every leaf
working-directory: src
run: >-
./gradlew
:application-fileserver:check
:adapter:inbound:web-fileserver:check
:adapter:outbound:fileserver:check
:adapter:outbound:persistence-fileserver:check
:composition:fileserver-platform:check
--stacktrace
fileserver-documentation-gate:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Prove every support claim maps to a job and every endpoint is documented
working-directory: src
run: >-
./gradlew
:composition:fileserver-platform:test --tests '*FileserverDocumentationCoverageTest'
--stacktrace
fileserver-pvc-certification:
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
# This job checks the manifest, and only the manifest; it applies nothing to a cluster. The
# cluster result comes from an operator running infra/fileserver/kubernetes/
# pvc-certification-job.yaml and recording it in docs/fileserver/storage-certification.md,
# where the absence of a cluster result is stated rather than hidden behind a green check.
- name: Check the certification manifest still says what the claim depends on
run: |
set -euo pipefail
manifest=infra/fileserver/kubernetes/pvc-certification-job.yaml
test -f "$manifest"
grep -q 'kind: PersistentVolumeClaim' "$manifest"
grep -q 'kind: Job' "$manifest"
# ReadWriteMany is explicitly not claimed; a manifest that quietly widened the access
# mode would certify a topology the support matrix says is uncertified.
grep -q 'ReadWriteOnce' "$manifest"
! grep -q 'ReadWriteMany' "$manifest"
fileserver-sensitive-telemetry-scan:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Prove telemetry carries no filename, path, or raw identifier
working-directory: src
run: >-
./gradlew
:application-fileserver:test --tests '*FileserverObservabilityTest'
--stacktrace
app-image-release:
needs:
- architecture-and-surface
- web-stable-release-gate
- websocket-stable-release-gate
- grpc-stable-release-gate
- httpclient-release-gate
- httpclient-documentation
- jpa-release-promotion
- jpa-registry-and-docs
- fileserver-full-verification
- fileserver-documentation-gate
- fileserver-pvc-certification
- fileserver-sensitive-telemetry-scan
# Job-level, because a job that declares `permissions:` replaces the workflow set entirely: this
# job and app-image-signing are the only ones that write anything anywhere, and
# `packages: write` stops at their boundary. No OIDC token here: this job runs the repository's
# Gradle build inside the Dockerfile, and the signing identity stays out of that.
permissions:
contents: read
packages: write
# The signing job below reads the digest from here. It is the digest, not a tag, that is signed.
outputs:
pinned_reference: ${{ steps.push.outputs.pinned_reference }}
runs-on: ubuntu-latest
timeout-minutes: 90
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
# The builder stage inside src/Dockerfile runs this repository's Gradle wrapper to produce the
# JAR that becomes the image. Validating the wrapper here checks the thing that is about to
# execute, before it executes, rather than after an image already exists.
# The tag is the release identity; everything below derives from it. A tag that does not parse
# stops the release here, rather than producing an image named after whatever ref happened to
# be checked out.
#
# GHCR rejects an uppercase path, and this repository's owner is mixed case — the naive
# `ghcr.io/${{ github.repository }}` fails at push time with a message about the manifest
# rather than about the case, so the lowercasing is explicit and the result is asserted.
- name: Resolve the release coordinates
env:
CONFIGURED_IMAGE_NAME: ${{ vars.APP_IMAGE_NAME }}
run: |
set -euo pipefail
readonly REGISTRY='ghcr.io'
if [[ "${GITHUB_REF_TYPE}" != 'tag' ]]; then
echo "::error::container-release runs only for a release tag; ref type was ${GITHUB_REF_TYPE}"
exit 1
fi
release_tag="${GITHUB_REF_NAME}"
# Bare MAJOR.MINOR.PATCH, because src/build.gradle's release-version guard refuses a
# pre-release or build suffix and the image tag must be the same string the JAR reports.
if [[ ! "${release_tag}" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
echo "::error::release tag must be vMAJOR.MINOR.PATCH with no suffix; got '${release_tag}'"
exit 1
fi
release_version="${BASH_REMATCH[1]}"
owner_path="$(printf '%s' "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')"
image_name="${CONFIGURED_IMAGE_NAME:-${owner_path}/caskeleton}"
image_repository="${REGISTRY}/${image_name}"
if [[ "${image_repository}" != "${image_repository,,}" ]]; then
echo "::error::image repository must be lowercase; got '${image_repository}'"
exit 1
fi
if [[ "${image_repository}" =~ [[:space:]] || "${image_repository}" == *:* ]]; then
echo "::error::image repository must carry no tag and no whitespace; got '${image_repository}'"
exit 1
fi
{
printf 'REGISTRY=%s\n' "${REGISTRY}"
printf 'RELEASE_VERSION=%s\n' "${release_version}"
printf 'BUILD_VERSION=%s+%s\n' "${release_version}" "${GITHUB_SHA}"
printf 'IMAGE_REPOSITORY=%s\n' "${image_repository}"
printf 'IMAGE_VERSION_TAG=%s\n' "${release_version}"
printf 'IMAGE_REVISION_TAG=sha-%s\n' "${GITHUB_SHA}"
printf 'SOURCE_URL=%s/%s\n' "${GITHUB_SERVER_URL}" "${GITHUB_REPOSITORY}"
} >> "${GITHUB_ENV}"
printf 'container-release: %s -> %s:%s and %s:sha-%s\n' \
"${release_tag}" "${image_repository}" "${release_version}" \
"${image_repository}" "${GITHUB_SHA}"
# Byte-identical to the install in dependency-vulnerability.yml, deliberately: the same
# checksum-pinned binary at the same version scans the filesystem and the image, so the two
# gates cannot disagree because one of them silently moved to a newer database schema.
#
# This repository installs its scanner rather than calling a scanner action, which is why no
# third-party action appears in this workflow: a pinned tarball with an asserted SHA-256 is a
# supply-chain claim that can be checked offline, and an action pinned to a commit is not.
- name: Install pinned Trivy under RUNNER_TEMP
env:
TRIVY_DOWNLOAD_BASE_URL: ${{ vars.TRIVY_DOWNLOAD_BASE_URL }}
run: |
set -euo pipefail
readonly TRIVY_VERSION='0.71.2'
readonly TRIVY_SHA256_AMD64='0510e71e2fd39bf863856d499c8dc19feb4e7336546394c502a8f5cc7ab27460'
readonly TRIVY_SHA256_ARM64='fe1c7106e15a5365d485b098a8c338f91e3b7ba71cb0e4963b98a3a098763cfc'
readonly DOWNLOAD_BASE_URL="${TRIVY_DOWNLOAD_BASE_URL:-https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}}"
case "${RUNNER_ARCH:-X64}" in
X64)
asset_arch='64bit'
expected_sha256="${TRIVY_SHA256_AMD64}"
;;
ARM64)
asset_arch='ARM64'
expected_sha256="${TRIVY_SHA256_ARM64}"
;;
*)
echo "::error::unsupported runner architecture: ${RUNNER_ARCH:-unknown}"
exit 1
;;
esac
install_dir="${RUNNER_TEMP}/trivy-${TRIVY_VERSION}"
archive="${RUNNER_TEMP}/trivy-${TRIVY_VERSION}.tar.gz"
mkdir -p "${install_dir}"
curl --fail --show-error --silent --location --retry 3 \
--proto '=https' --tlsv1.2 \
"${DOWNLOAD_BASE_URL}/trivy_${TRIVY_VERSION}_Linux-${asset_arch}.tar.gz" \
--output "${archive}"
printf '%s %s\n' "${expected_sha256}" "${archive}" | sha256sum -c -
tar -xzf "${archive}" -C "${install_dir}" trivy
chmod 0755 "${install_dir}/trivy"
printf '%s\n' "${install_dir}" >> "${GITHUB_PATH}"
# SOURCE_DATE_EPOCH is the commit time, not the wall clock, so the image metadata is a function
# of the commit rather than of when the runner happened to pick the job up. Verified locally,
# and worth stating exactly because it is easy to overclaim: BuildKit uses it for the image
# config `created` field and for every history timestamp — both came back as the commit time —
# and it does NOT rewrite file mtimes inside the layers. Those still carry the build time, so
# two builds of the same commit agree on metadata but their layer digests still differ.
# Byte-identical layers additionally need `--output type=image,rewrite-timestamp=true`, which
# needs the containerd image store; that is a runner-capability change, not a flag to add
# untested to the one job that publishes releases.
#
# The OCI `created` label comes from the same commit for the same reason: `date -u` there would
# have made every rebuild a different image for no reason anybody could see.
#
# Both base images are already digest-pinned inside src/Dockerfile, and so is the Dockerfile
# frontend in its `# syntax` directive, so nothing in this build resolves a floating tag.
- name: Build the release image
run: |
set -euo pipefail
SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"
export SOURCE_DATE_EPOCH
created="$(git log -1 --format=%cI)"
printf 'SOURCE_DATE_EPOCH=%s (%s)\n' "${SOURCE_DATE_EPOCH}" "${created}"
DOCKER_BUILDKIT=1 docker build \
--file src/Dockerfile \
--tag "${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}" \
--tag "${IMAGE_REPOSITORY}:${IMAGE_REVISION_TAG}" \
--build-arg RELEASE_VERSION="${RELEASE_VERSION}" \
--build-arg BUILD_VERSION="${BUILD_VERSION}" \
--build-arg GIT_SHA="${GITHUB_SHA}" \
--build-arg SOURCE_URL="${SOURCE_URL}" \
--label org.opencontainers.image.created="${created}" \
src
docker image inspect \
--format 'built {{.Id}} ({{.Size}} bytes, {{len .RootFS.Layers}} layers)' \
"${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}"
# Generated before the blocking scan, and uploaded before it too, so the inventory of what is
# in the image survives the run that refuses to publish it. An SBOM you only get on a green
# build is an SBOM you cannot use to answer "what was in the one that failed".
- name: Generate the image SBOM
run: |
set -euo pipefail
trivy image \
--format cyclonedx \
--scanners license \
--output image-sbom.cdx.json \
"${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}"
test -s image-sbom.cdx.json
- name: Upload the image SBOM
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # actions/upload-artifact@v7.0.1
with:
name: container-release-sbom
path: image-sbom.cdx.json
if-no-files-found: error
retention-days: 90
# The same policy dependency-vulnerability.yml applies to the filesystem, applied to the thing
# that actually ships: CRITICAL and HIGH block, everything else is reported. The filesystem
# scan cannot see the base image's OS packages, which is most of an image's attack surface, so
# a green trivy-fs has never been evidence about the artifact.
#
# --ignorefile is mandatory here as everywhere: .trivyignore.yaml is the single suppression
# source. Each entry carries a rationale and an expiry by policy, reviewed through CODEOWNERS
# (.github/dependency-vulnerability-policy.md); an inline --skip or a second ignore file would
# be a suppression nobody reviews.
#
# This step is the reason `docker push` is further down. A vulnerable image that was pushed and
# then reported is already pullable by everything that watches the tag.
- name: Block High and Critical vulnerabilities in the release image
run: |
set -euo pipefail
trivy image \
--scanners vuln,license \
--severity CRITICAL,HIGH \
--exit-code 1 \
--ignorefile .trivyignore.yaml \
"${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}"
- name: Report Medium and Low vulnerabilities in the release image
run: |
set -euo pipefail
trivy image \
--scanners vuln,license \
--severity MEDIUM,LOW \
--exit-code 0 \
--ignorefile .trivyignore.yaml \
"${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}"
- name: Sign in to the container registry
env:
REGISTRY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
set -euo pipefail
printf '%s' "${REGISTRY_TOKEN}" \
| docker login "${REGISTRY}" --username "${GITHUB_ACTOR}" --password-stdin
# Two tags, one digest. The semver tag is what a human reads and what a release note cites; the
# sha- tag is the one that can never be moved to different content, because the git SHA it
# names is the only commit that can produce it.
#
# Neither is what a manifest should pin. Both are mutable names in a registry: a later push can
# point `1.2.3` at something else, and nothing about a tag tells a cluster it did not. The
# digest recorded below is immutable by construction, and it is the field the GitOps repository
# pins — the tags exist so a person can find the digest, not so a cluster can resolve one.
- name: Push the release and revision tags
id: push
run: |
set -euo pipefail
docker push "${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}"
docker push "${IMAGE_REPOSITORY}:${IMAGE_REVISION_TAG}"
# awk rather than `grep | head`, deliberately. Under `set -e` with `pipefail`, a grep that
# matches nothing exits 1 and kills the step right here — so the explicit check below,
# and its message, would never run and the failure would surface as a bare exit code.
# awk exits 0 whether or not it matched, which leaves the empty case for us to report.
pinned_reference="$(
docker image inspect \
--format '{{range .RepoDigests}}{{println .}}{{end}}' \
"${IMAGE_REPOSITORY}:${IMAGE_VERSION_TAG}" \
| awk -v prefix="${IMAGE_REPOSITORY}@sha256:" \
'index($0, prefix) == 1 { print; exit }'
)"
if [[ -z "${pinned_reference}" ]]; then
echo "::error::no registry digest for ${IMAGE_REPOSITORY} after push"
exit 1
fi
printf 'PINNED_REFERENCE=%s\n' "${pinned_reference}" >> "${GITHUB_ENV}"
printf 'pinned_reference=%s\n' "${pinned_reference}" >> "${GITHUB_OUTPUT}"
printf 'container-release: pushed %s\n' "${pinned_reference}"
# The handoff to the GitOps repository, in a form a person and a script can both read. It is
# written to the job summary as well as to an artifact because the summary is where somebody
# looks first and the artifact is what survives the ninety days a release audit asks about.
- name: Record the immutable image reference
run: |
set -euo pipefail
digest="${PINNED_REFERENCE#*@}"
{
printf 'release_tag: %s\n' "${GITHUB_REF_NAME}"
printf 'git_sha: %s\n' "${GITHUB_SHA}"
printf 'image_repository: %s\n' "${IMAGE_REPOSITORY}"
printf 'version_tag: %s\n' "${IMAGE_VERSION_TAG}"
printf 'revision_tag: %s\n' "${IMAGE_REVISION_TAG}"
printf 'digest: %s\n' "${digest}"
printf 'pinned_reference: %s\n' "${PINNED_REFERENCE}"
} > image-release.txt
{
printf '### container-release\n\n'
printf 'Pin this in the GitOps manifest as the container image:\n\n'
printf '```\n%s\n```\n\n' "${PINNED_REFERENCE}"
printf -- '- release tag: `%s`\n' "${GITHUB_REF_NAME}"
printf -- '- version tag: `%s:%s`\n' "${IMAGE_REPOSITORY}" "${IMAGE_VERSION_TAG}"
printf -- '- revision tag: `%s:%s`\n' "${IMAGE_REPOSITORY}" "${IMAGE_REVISION_TAG}"
} >> "${GITHUB_STEP_SUMMARY}"
cat image-release.txt
- name: Upload the immutable image reference
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # actions/upload-artifact@v7.0.1
with:
name: container-release-image-reference
path: image-release.txt
if-no-files-found: error
retention-days: 90
# Keyless signature of the pushed digest (owner decision 31). A job of its own so that
# `id-token: write` — the GitHub OIDC token Fulcio turns into a short-lived signing certificate
# naming this workflow and tag — exists only here, in a job that checks nothing out and builds
# nothing. The signature goes to the registry beside the image (hence `packages: write`) and the
# transparency-log entry to Rekor; there is no key to store or rotate.
#
# The digest is signed, never a tag: a tag can be moved to other content, a digest cannot.
# Verification runs right after signing with the identity a deployment should require, so a
# release whose signature a cluster would reject fails here instead of at admission.
#
# Local limit: signing needs the tag run's OIDC token and a pushed GHCR image, so it is exercised
# only by a real release. DeveloperExperienceContractTest pins the structure of this job.
app-image-signing:
needs:
- app-image-release
permissions:
contents: read
packages: write
id-token: write
runs-on: ubuntu-latest
timeout-minutes: 30
env:
PINNED_REFERENCE: ${{ needs.app-image-release.outputs.pinned_reference }}
steps:
# Same policy as Trivy above: a pinned release binary with an asserted SHA-256, no action.
# The two hashes are the cosign-linux-{amd64,arm64} lines of the official v3.1.3
# cosign_checksums.txt, which was itself verified against its Sigstore bundle
# (identity keyless@projectsigstore.iam.gserviceaccount.com, issuer https://accounts.google.com)
# when they were pinned. The checksum file is fetched again here and must still carry the
# pinned line, so a re-published release asset fails the job instead of passing silently.
- name: Install pinned cosign under RUNNER_TEMP
run: |
set -euo pipefail
readonly COSIGN_VERSION='3.1.3'
readonly COSIGN_SHA256_AMD64='4629c757b7618056f8ddd7e2625ae9fdd94c0372a65049520bc7d9df9efc7f71'
readonly COSIGN_SHA256_ARM64='c5d324e091826b0d7a78eb16fef316450b4eb9aaec045611c08ba06f5e73220a'
readonly DOWNLOAD_BASE_URL="https://github.com/sigstore/cosign/releases/download/v${COSIGN_VERSION}"
case "${RUNNER_ARCH:-X64}" in
X64)
asset='cosign-linux-amd64'
expected_sha256="${COSIGN_SHA256_AMD64}"
;;
ARM64)
asset='cosign-linux-arm64'
expected_sha256="${COSIGN_SHA256_ARM64}"
;;
*)
echo "::error::unsupported runner architecture: ${RUNNER_ARCH:-unknown}"
exit 1
;;
esac
install_dir="${RUNNER_TEMP}/cosign-${COSIGN_VERSION}"
mkdir -p "${install_dir}"
curl --fail --show-error --silent --location --retry 3 \
--proto '=https' --tlsv1.2 \
"${DOWNLOAD_BASE_URL}/cosign_checksums.txt" \
--output "${RUNNER_TEMP}/cosign_checksums.txt"
if ! grep -qxF "${expected_sha256} ${asset}" "${RUNNER_TEMP}/cosign_checksums.txt"; then
echo "::error::cosign_checksums.txt no longer lists the pinned ${asset} hash"
exit 1
fi
curl --fail --show-error --silent --location --retry 3 \
--proto '=https' --tlsv1.2 \
"${DOWNLOAD_BASE_URL}/${asset}" \
--output "${install_dir}/cosign"
printf '%s %s\n' "${expected_sha256}" "${install_dir}/cosign" | sha256sum -c -
chmod 0755 "${install_dir}/cosign"
printf '%s\n' "${install_dir}" >> "${GITHUB_PATH}"
- name: Check the reference to sign
run: |
set -euo pipefail
if [[ ! "${PINNED_REFERENCE}" =~ ^ghcr\.io/[a-z0-9._/-]+@sha256:[0-9a-f]{64}$ ]]; then
echo "::error::app-image-release handed over no digest reference; got '${PINNED_REFERENCE}'"
exit 1
fi
printf 'CERTIFICATE_IDENTITY=%s/%s\n' "${GITHUB_SERVER_URL}" "${GITHUB_WORKFLOW_REF}" \
>> "${GITHUB_ENV}"
- name: Sign in to the container registry
env:
REGISTRY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
set -euo pipefail
printf '%s' "${REGISTRY_TOKEN}" \
| docker login ghcr.io --username "${GITHUB_ACTOR}" --password-stdin
- name: Sign the image digest (keyless)
run: |
set -euo pipefail
cosign sign --yes "${PINNED_REFERENCE}"
# The identity a deployment admission policy should require: this workflow file at this tag,
# issued by GitHub's OIDC provider. Anything else — another workflow, another repository, a
# branch run — does not verify.
- name: Verify the signature with the release identity
run: |
set -euo pipefail
cosign verify \
--certificate-identity "${CERTIFICATE_IDENTITY}" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
"${PINNED_REFERENCE}" > cosign-verify.json
{
printf '### container-release signature\n\n'
printf -- '- signed: `%s`\n' "${PINNED_REFERENCE}"
printf -- '- certificate identity: `%s`\n' "${CERTIFICATE_IDENTITY}"
printf -- '- issuer: `https://token.actions.githubusercontent.com`\n'
} >> "${GITHUB_STEP_SUMMARY}"