Merge pull request 'ci!: workflow를 pr·main·release 셋으로 접고 Gitea runner에서 돌린다' (#7) from claude/t2a-backend-ci-451e3b into main
main / main (push) Successful in 17m8s
main / configuration-cache (push) Successful in 2m3s
main / integration (push) Failing after 17m27s
main / build-logic (push) Successful in 1m24s
main / links (push) Failing after 6s
main / vulnerabilities (push) Successful in 43s
main / http3-experimental (push) Successful in 1m59s
main / jpa-postgresql (16) (push) Skipped
main / jpa-postgresql (17) (push) Skipped
main / jpa-postgresql (18) (push) Skipped
main / httpclient-transport (apache) (push) Skipped
main / httpclient-transport (jdk) (push) Skipped
main / redis-topology (7.2, cluster) (push) Skipped
main / redis-topology (7.2, sentinel) (push) Skipped
main / redis-topology (7.2, standalone) (push) Skipped
main / redis-topology (7.4, cluster) (push) Skipped
main / redis-topology (7.4, sentinel) (push) Skipped
main / redis-topology (7.4, standalone) (push) Skipped
main / redis-topology (7.4, tls) (push) Skipped
main / redis-topology (8.2, cluster) (push) Skipped
main / redis-topology (8.2, sentinel) (push) Skipped
main / redis-topology (8.2, standalone) (push) Skipped
main / redis-topology (8.2, tls) (push) Skipped
main / fileserver-nfs-ambiguity (push) Skipped
main / notification-chaos (push) Skipped
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
main / object-storage-aws (push) Skipped
main / compose-smoke (push) Skipped
main / performance (push) Canceled after 0s

This commit was merged in pull request #7.
This commit is contained in:
2026-11-11 11:25:17 +00:00
88 changed files with 2226 additions and 8798 deletions
+8 -9
View File
@@ -5,13 +5,12 @@ description: 이 repo에서 Gradle·Docker·테스트·게이트·성능 측정
# desktop에서 게이트 돌리기
정본은 `docs/work/operate.md` 4.1절(실행 위치)·4.2절(기록)과 `docs/work/reference/gates.md`(무엇을 돌릴지)다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다. CI 재편에서 검증 진입점 스크립트(설계 이름 `verify.sh`)가 생기면 이 절차를 그 스크립트가 대신한다.
정본은 `docs/work/operate.md` 4.1절(실행 위치)·4.2절(기록)과 `docs/work/reference/gates.md`(무엇을 돌릴지)다. 이 스킬은 실행 순서표다. 둘이 다르면 정본이 맞다.
1. 돌릴 게이트를 고른다: 바꾼 것에 맞는 게이트는 `gates.md` 2절, PR·main 단계 묶음은 3절이다. leaf의 Gradle path는 registry `gradle_path`에서 읽는다.
2. 트리를 정한다. push가 허용됐으면 push한 브랜치, 아니면 4.1절 「push 전에 검증하기」대로 기준 커밋 + 패치를 보내고 노트북 `git write-tree`와 desktop `git write-tree`가 같은지 본다.
3. desktop에 따로 worktree를 만든다. 기존 checkout의 브랜치와 `stash@{0}`는 건드리지 않는다. 로그 폴더는 `~/<작업 이름>-logs/`다.
4. `uptime`을 적고, 게이트마다 `flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?"`로 하나씩 돌린다. 증거로 쓸 실행은 `--rerun`이나 `--no-build-cache`로 캐시 결과를 쓰지 않는다(`gates.md` 4절).
5. 테스트 수는 결과 XML 사본에서 센다(`gates.md` 4절). 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다(`operate.md` 7절).
6. 다른 세션이 잠금을 쥐고 있으면 기다린다. 기다리는 동안 다른 일을 하고, 잠금 대기는 완료나 첫 실패에서 끝나는 대기 하나로 둔다.
7. 끝나면 compose를 내리고(`docker compose … down`) worktree를 지운다. root 소유 폴더가 남으면 4.1절의 정리법을 쓴다.
8. 보고에는 게이트, rc, 직전 부하, 로그 경로, 대상 트리 해시, 캐시 여부를 적는다.
1. 돌릴 단계를 고른다: 바꾼 것에 맞는 게이트는 `gates.md` 2절, 단계 묶음은 1절의 `scripts/verify.sh` 단계(`leaf <gradle-path>`·`pr`·`main`·`nightly`·`release`·`round`)다. leaf의 Gradle path는 registry `gradle_path`에서 읽는다.
2. `scripts/verify.sh <단계> [--no-cache]`를 노트북 저장소 루트에서 돌린다. 스크립트가 커밋하지 않은 변경까지 패치로 desktop에 보내고, 기준 커밋에서 새 worktree를 만들어 트리 해시를 맞추고, 공유 잠금 `flock /tmp/claude-gates/heavy.lock` 아래에서 돌리고, 로그를 desktop `~/<브랜치 이름>-logs/<단계>.log`에 남기고, worktree를 지운다. 오래 걸리는 단계는 background로 두고 끝나면 알림을 받는다.
3. 증거로 쓸 실행은 `--no-cache`로 돌린다(`gates.md` 3절). 로그의 `FROM-CACHE`가 0인지 본다.
4. 테스트 수는 `verify.sh`가 worktree를 지우기 전에 결과 XML에서 세어 로그 끝에 남긴다(`verify: 테스트 tests=…`). 명령별로 나눈 수가 필요하면 단계 밖에서 손으로 돌려 `gates.md` 4절대로 센다. 실패하면 기준 커밋에서도 돌려 이번 변경 몫인지 가린다(`operate.md` 7절).
5. 다른 세션이 잠금을 쥐고 있으면 기다린다. 기다리는 동안 다른 일을 하고, 잠금 대기는 완료나 첫 실패에서 끝나는 대기 하나로 둔다.
6. 단계 밖의 명령(lane 하나, `spotlessApply`, 탐침)은 `operate.md` 4.1절 「절차」대로 손으로 하고, `--no-daemon`을 붙인다(오래 사는 daemon이 여러 worktree를 받으면 compiler worker가 쌓여 desktop 메모리를 채운다). desktop 기존 checkout의 브랜치와 `stash@{0}`는 건드리지 않는다.
7. 보고에는 단계, rc, 직전 부하(로그 첫 줄), 로그 경로, 대상 트리 해시, 캐시 여부를 적는다.
@@ -0,0 +1,26 @@
name: Set up Java and Gradle
description: >-
Installs the repository's pinned Temurin JDK, then configures Gradle through the official
setup-gradle action, which validates every checked-in wrapper jar and manages the Gradle cache.
# A Gradle job is two lines: checkout, then this action. `actions/checkout` cannot move in here: a
# `./.gitea/actions/...` reference is resolved from the checked-out working copy, so this file does
# not exist until checkout has run.
#
# Full URLs, because the runner resolves a bare `owner/name` against its own default action host,
# and a pinned commit SHA, the only immutable action reference. The JDK is the version in
# .tool-versions under the name Temurin publishes it (`+10.0.LTS`); setup-java rejects `+10`.
runs:
using: composite
steps:
- uses: https://github.com/actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # actions/setup-java@v4.7.1
with:
distribution: temurin
java-version: "21.0.11+10.0.LTS"
# Gradle's own caching, not setup-java's `cache: gradle`. The two cache the same directory with
# different keys, and running both is how a job restores one cache and saves the other.
- uses: https://github.com/gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # gradle/actions@v6
with:
build-scan-publish: false
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
+306
View File
@@ -0,0 +1,306 @@
# Main-branch stage: is the merged state healthy. It does not block a merge — the merge has already
# happened — but it fails loudly, after the change it reports on (owner decision 2026-09-16).
#
# On every push to main: the main stage, the container lanes, the build-logic tests, configuration
# cache, links and the dependency scan. Nightly (and on a manual run) also the jobs that need a matrix
# or an environment the stage tasks do not have, and last the performance lanes, which need a
# machine nothing else is using: the runner takes one job at a time, and `needs` puts them after
# every other heavy job (owner decision 2026-11-07).
#
# Which lanes a stage means is decided by its Gradle task (src/build.gradle). The stage jobs
# (`main`, `integration`, `performance`) run it as one line; `verifyStrictLaneStages` fails a pull
# request that changes that line, its condition, or adds a way for it to pass quietly.
name: main
on:
push:
branches: [main]
schedule:
# 04:00 KST. grpc-library runs at 03:00 and messaging-library at 03:30 on the same runner.
- cron: "0 19 * * *"
workflow_dispatch:
inputs:
run_protected_aws:
description: Also run the protected AWS object-storage lane (needs the sandbox secrets)
type: boolean
default: false
permissions:
contents: read
concurrency:
group: main-${{ github.ref }}
cancel-in-progress: false
defaults:
run:
working-directory: src
env:
# Reuse would hand one lane a container another lane had already faulted.
TESTCONTAINERS_REUSE_ENABLE: "false"
jobs:
# Environment contract, full-boot qualification, public-path baseline, transport and messaging
# qualification, document-contract lanes, test-code analysis, the feature generator round trip.
# `--continue`: one failed lane must not hide the others.
main:
runs-on: ubuntu-latest
timeout-minutes: 120
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :mainCheck --continue
# Every integration-category strict lane: real PostgreSQL, MongoDB, Kafka, MinIO, nginx, Toxiproxy.
# A lane joins by declaring `integration()`; no line here names it. Lanes that need an input this
# job does not have are explicitOnly and named in the output.
integration:
runs-on: ubuntu-latest
timeout-minutes: 240
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :integrationCheck --continue
# The included build's own tests (TestKit for the convention plugins). The main task graph does
# not reach them; `ci` already runs every plugin they test (owner decision 2026-11-07: main stage).
build-logic:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew -p build-logic test
configuration-cache:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: bash ../scripts/ci/verify-configuration-cache.sh
# Every committed Markdown link, external URLs included. A documentation check, so the main stage
# (owner decision 2026-09-16); scripts/check-docs.py checks the relative links on every pull request.
links:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Check committed documentation links
uses: https://github.com/lycheeverse/lychee-action@7cd0af4c74a61395d455af97419279d86aafaede # lycheeverse/lychee-action@v2.0.2
with:
args: >-
--no-progress
--root-dir .
README.md
src/README.md
'src/**/README.md'
'src/**/CLAUDE.md'
'docs/**/*.md'
'.github/**/*.md'
fail: true
# The dependency tree against today's vulnerability database: new advisories appear without a
# commit, so main and nightly scan again what the pull request scanned.
vulnerabilities:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: bash scripts/ci/trivy-scan.sh filesystem
working-directory: .
# Experimental by design: the result is reported, never used to block anything.
http3-experimental:
runs-on: ubuntu-latest
timeout-minutes: 30
continue-on-error: true
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true
# ---------------------------------------------------------------------------------------------
# Nightly and manual runs only.
# The platform contract on every Stable PostgreSQL major, one major per job: the integration stage
# runs the lane once, on the default major. JpaReleaseRenderingTest holds this list to the release
# registry's Stable majors (src/adapter/outbound/persistence-jpa/release/release-registry.json).
jpa-postgresql:
if: ${{ github.event_name != 'push' }}
runs-on: ubuntu-latest
timeout-minutes: 60
strategy:
fail-fast: false
matrix:
postgresql: ["16", "17", "18"]
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest -Pjpa.matrix.versions=${{ matrix.postgresql }}
# One HTTP transport per job, so a transport that stops satisfying the shared contract fails on its
# own row. `ci` runs the lane once over both.
httpclient-transport:
if: ${{ github.event_name != 'push' }}
runs-on: ubuntu-latest
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
transport: [apache, jdk]
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :adapter:outbound:httpclient:httpClientStableContractTest -Phttpclient.contract.transports=${{ matrix.transport }}
# Sentinel promotion, Cluster redirects and TLS against real servers, every supported version.
# docs/redis/support-matrix.md says which lane produced which evidence; the job log carries the
# commit, the server version and the image digest.
redis-topology:
if: ${{ github.event_name != 'push' }}
runs-on: ubuntu-latest
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
include:
- { topology: standalone, redis: "7.2" }
- { topology: standalone, redis: "7.4" }
- { topology: standalone, redis: "8.2" }
- { topology: sentinel, redis: "7.2" }
- { topology: sentinel, redis: "7.4" }
- { topology: sentinel, redis: "8.2" }
- { topology: cluster, redis: "7.2" }
- { topology: cluster, redis: "7.4" }
- { topology: cluster, redis: "8.2" }
- { topology: tls, redis: "7.4" }
- { topology: tls, redis: "8.2" }
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: bash scripts/ci/redis-topology.sh ${{ matrix.topology }} ${{ matrix.redis }}
working-directory: .
# The one fileserver environment a pull request cannot provide: a real NFSv4 server.
fileserver-nfs-ambiguity:
if: ${{ github.event_name != 'push' }}
runs-on: ubuntu-latest
timeout-minutes: 45
env:
FILESERVER_NFS_TESTS: "true"
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: docker compose -f adapter/outbound/fileserver/compose/nfs/compose.yml up -d --wait
- run: ./gradlew :adapter:outbound:fileserver:test --tests '*NfsAmbiguityIntegrationTest'
- if: ${{ always() }}
run: docker compose -f adapter/outbound/fileserver/compose/nfs/compose.yml down -v
# The notification fault, race and restart suites run again on their own: one green run says least
# about exactly these.
notification-chaos:
if: ${{ github.event_name != 'push' }}
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- name: Ambiguity and fault harness
run: ./gradlew :adapter:outbound:notification:test --tests '*ChaosSecurity*' --tests '*CrossProviderContractSuite*' --rerun
- name: Concurrency and rotation races
run: ./gradlew :adapter:outbound:notification:test --tests '*ConcurrencyTest' --tests '*ProviderRuntimeStateTest' --rerun
- name: Restart recovery and lease fencing (real PostgreSQL)
run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest :adapter:outbound:persistence-jpa:jpaPlatformFailureTest
# A filter that matches nothing passes. Each filter above names classes that exist today; if
# one is renamed the job fails rather than quietly stops covering it.
- name: Every named suite actually ran
run: |
for suite in ChaosSecurity CrossProviderContractSuite ConcurrencyTest ProviderRuntimeStateTest; do
find . -path '*/build/test-results/*' -name "*${suite}*.xml" | grep -q . || {
echo "no test results for ${suite}: the filter matched nothing" >&2
exit 1
}
done
# Advisory probes for the next JPA, Hibernate and PostgreSQL majors. The targets are not resolvable
# yet, so each records NOT_EXECUTABLE with its reason instead of implying compatibility evidence.
# JpaReleaseRenderingTest requires every Experimental PostgreSQL major to be the `target` here.
jpa-next:
if: ${{ github.event_name != 'push' }}
runs-on: ubuntu-latest
timeout-minutes: 60
continue-on-error: true
strategy:
fail-fast: false
matrix:
include:
- id: jakarta-persistence-4
target: Jakarta Persistence 4
test: "*Jpa4CompatibilityTest"
reason: the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it
- id: hibernate-8
target: Hibernate 8
test: "*Hibernate8CompatibilityTest"
reason: Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it
- id: postgresql-19
target: PostgreSQL 19
test: "*PostgreSql19CompatibilityTest"
reason: no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :adapter:outbound:persistence-jpa:test --tests '${{ matrix.test }}' --rerun
- if: ${{ always() }}
run: |
echo "${{ matrix.target }} compatibility is NOT_EXECUTABLE (${{ github.sha }}): ${{ matrix.reason }}"
# The protected AWS lane, only on a manual run that asks for it: it needs the sandbox secrets.
object-storage-aws:
if: ${{ github.event_name == 'workflow_dispatch' && inputs.run_protected_aws }}
runs-on: ubuntu-latest
timeout-minutes: 30
env:
OBJECT_STORAGE_AWS_QUALIFICATION_ENABLED: "true"
OBJECT_STORAGE_AWS_BUCKET: ${{ secrets.OBJECT_STORAGE_AWS_BUCKET }}
OBJECT_STORAGE_AWS_REGION: ${{ secrets.OBJECT_STORAGE_AWS_REGION }}
OBJECT_STORAGE_AWS_EXPECTED_OWNER: ${{ secrets.OBJECT_STORAGE_AWS_EXPECTED_OWNER }}
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :adapter:outbound:objectstorage:objectStorageAwsQualificationTest
# Every blocking Compose runtime lane, on the qualification image (src/Dockerfile
# COMPOSITION=qualification: every capability module present).
compose-smoke:
if: ${{ github.event_name != 'push' }}
runs-on: ubuntu-latest
timeout-minutes: 180
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
working-directory: .
# Load, slow-client, shutdown, pool and resource bounds. Last, after every other heavy job of the
# run, so the bounds are measured on a runner that is not building something else.
performance:
needs:
- main
- integration
- build-logic
- configuration-cache
- jpa-postgresql
- httpclient-transport
- redis-topology
- fileserver-nfs-ambiguity
- notification-chaos
- compose-smoke
if: ${{ !cancelled() && github.event_name != 'push' }}
runs-on: ubuntu-latest
timeout-minutes: 120
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :performanceCheck --continue
+66
View File
@@ -0,0 +1,66 @@
# Pull-request stage. Everything here blocks a merge, and the branch protection requires one check:
# `done`. Which leaves, lanes and checks the stage means is decided by the Gradle task `prCheck`
# (src/build.gradle), not here; `verifyStrictLaneStages` fails when this job stops running it as one
# line (docs/work/reference/gates.md).
#
# The adapter container lanes are not here: they run in main.yml on every push to main (owner
# decision 2026-11-07). A change that touches an adapter runs that leaf's strict lanes on the
# desktop before it merges (docs/work/reference/gates.md 2).
name: pr
on:
pull_request:
permissions:
contents: read
concurrency:
group: pr-${{ github.ref }}
cancel-in-progress: true
defaults:
run:
working-directory: src
env:
TESTCONTAINERS_REUSE_ENABLE: "false"
jobs:
gradle:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :prCheck
# Plans every stage (--dry-run: nothing executes), so it cannot be a dependency of prCheck.
- run: ./gradlew :verifyStrictLaneStages --dry-run
# Known High and Critical vulnerabilities and CISA KEV matches in the dependency tree.
vulnerabilities:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: bash scripts/ci/trivy-scan.sh filesystem
working-directory: .
# The one required check. A job added above joins `needs` here, and the branch protection does
# not change.
done:
needs: [gradle, vulnerabilities]
if: ${{ always() }}
runs-on: ubuntu-latest
steps:
- name: Require every job of this stage to have succeeded
working-directory: .
env:
RESULTS: ${{ needs.gradle.result }} ${{ needs.vulnerabilities.result }}
run: |
for result in ${RESULTS}; do
if [ "${result}" != success ]; then
echo "pr / done: a job of this stage ended with ${result}"
exit 1
fi
done
echo "pr / done: every job of this stage succeeded."
+299
View File
@@ -0,0 +1,299 @@
# Release stage: produce the deployable artifact. One workflow, because there is one deployable unit,
# `app-bootstrap`; CI does not deploy (docs/ci-cd/boundary.md).
#
# A `vMAJOR.MINOR.PATCH` tag runs everything and publishes the image to this Gitea's container
# registry, signed by digest. A manual run is the rehearsal: every gate, the image build, the SBOM
# and the image scan, and nothing that publishes or signs.
#
# Secrets (repository settings, created by the owner): PACKAGE_TOKEN, a personal access token with
# package read/write (the job token cannot publish packages); COSIGN_PRIVATE_KEY and COSIGN_PASSWORD,
# the release signing key pair's private half and its password (owner decision 2026-11-07: Gitea
# issues no OIDC token, so keyless signing cannot run here).
name: release
on:
push:
tags: ["v*"]
workflow_dispatch:
permissions:
contents: read
# Never cancel a release in flight. A half-pushed manifest is worse than a slow one.
concurrency:
group: release-${{ github.ref }}
cancel-in-progress: false
defaults:
run:
working-directory: src
env:
TESTCONTAINERS_REUSE_ENABLE: "false"
jobs:
# The tag-only checks: release provenance and the public path baseline. Not `ci` again: a tag is
# cut from a main commit the pull-request and main stages already ran on.
release:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :releaseCheck
# Every web lane `check` cannot reach. webAdvancedTest selects tests `:web-advanced:test` already
# runs; what it adds is failing closed when its tag selects nothing.
web-stable-release-gate:
runs-on: ubuntu-latest
timeout-minutes: 90
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :adapter:inbound:web:systemTest :adapter:inbound:web:webJettyCompatTest :adapter:inbound:web-advanced:webAdvancedTest
websocket-stable-release-gate:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: >-
./gradlew
:adapter:inbound:websocket:test
:adapter:inbound:websocket:systemTest
:adapter:inbound:websocket:websocketJettyTest
:adapter:inbound:websocket:websocketNginxTest
:adapter:inbound:websocket:websocketTransportQualificationTest
httpclient-release-gate:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- 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
httpclient-documentation:
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: python3 scripts/verify-httpclient-docs.py
working-directory: .
# One job per Stable PostgreSQL major: one job for three majors was one job for one major, because
# the platform starts only the first selected version. persistence-jpa's
# release/release-registry.json owns the gate tasks (jpaReleaseQualification depends on them), and
# JpaReleaseRenderingTest holds this list to the registry's Stable majors. The image job needs this
# job, so every major has passed, in this run and on this commit, before anything is published.
jpa-release-gate:
runs-on: ubuntu-latest
timeout-minutes: 90
strategy:
fail-fast: false
matrix:
postgresql: ["16", "17", "18"]
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew jpaReleaseQualification -Pjpa.matrix.versions=${{ matrix.postgresql }}
jpa-registry-and-docs:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: >-
./gradlew :adapter:outbound:persistence-jpa:test
--tests '*JpaReleaseManifestTest' --tests '*JpaReleaseRenderingTest' --tests '*JpaReadinessRegistryTest'
# Fileserver certification. docs/fileserver/support-matrix.md names these job ids as evidence, and
# FileserverDocumentationCoverageTest fails when a named job is missing.
fileserver-full-verification:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: >-
./gradlew
:application-fileserver:check
:adapter:inbound:web-fileserver:check
:adapter:outbound:fileserver:check
:adapter:outbound:persistence-fileserver:check
:composition:fileserver-platform:check
fileserver-documentation-gate:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :composition:fileserver-platform:test --tests '*FileserverDocumentationCoverageTest'
fileserver-sensitive-telemetry-scan:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :application-fileserver:test --tests '*FileserverObservabilityTest'
# Build, inventory and scan the image; on a tag also push it. It waits on every evidence job:
# `needs` does not reach across workflows, so a gate in another file could still be running.
app-image-release:
needs:
- release
- web-stable-release-gate
- websocket-stable-release-gate
- httpclient-release-gate
- httpclient-documentation
- jpa-release-gate
- jpa-registry-and-docs
- fileserver-full-verification
- fileserver-documentation-gate
- fileserver-sensitive-telemetry-scan
outputs:
pinned_reference: ${{ steps.push.outputs.pinned_reference }}
runs-on: ubuntu-latest
timeout-minutes: 90
defaults:
run:
working-directory: .
steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
# The tag is the release identity; a tag that does not parse stops the release here. A manual
# run is a rehearsal and builds version 0.0.0, which no release tag names.
- name: Resolve the release coordinates
run: |
set -euo pipefail
if [ "${GITHUB_REF_TYPE}" = tag ]; then
if [[ ! "${GITHUB_REF_NAME}" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
echo "release: the tag must be vMAJOR.MINOR.PATCH with no suffix; got '${GITHUB_REF_NAME}'" >&2
exit 1
fi
version="${BASH_REMATCH[1]}"
else
version=0.0.0
fi
registry="${GITHUB_SERVER_URL#https://}"
repository="${registry}/$(printf '%s' "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')/caskeleton"
{
echo "REGISTRY=${registry}"
echo "RELEASE_VERSION=${version}"
echo "BUILD_VERSION=${version}+${GITHUB_SHA}"
echo "IMAGE_REPOSITORY=${repository}"
echo "SOURCE_URL=${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}"
} >> "${GITHUB_ENV}"
echo "release: ${GITHUB_REF_NAME} -> ${repository}:${version} and :sha-${GITHUB_SHA}"
# SOURCE_DATE_EPOCH is the commit time, so the image config `created` field and every history
# timestamp are a function of the commit. It does not rewrite file mtimes inside the layers;
# byte-identical layers would need the containerd image store.
- name: Build the release image
run: |
set -euo pipefail
SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"
export SOURCE_DATE_EPOCH
DOCKER_BUILDKIT=1 docker build \
--file src/Dockerfile \
--tag "${IMAGE_REPOSITORY}:${RELEASE_VERSION}" \
--tag "${IMAGE_REPOSITORY}:sha-${GITHUB_SHA}" \
--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="$(git log -1 --format=%cI)" \
src
# The SBOM is printed and kept in the log before the blocking scan, so the inventory of an image
# that is refused still exists. A vulnerable image is never pushed: the push comes after.
- name: Inventory and scan the release image
run: |
set -euo pipefail
bash scripts/ci/trivy-scan.sh image "${IMAGE_REPOSITORY}:${RELEASE_VERSION}"
echo "release: SBOM image-sbom.cdx.json, $(wc -c < image-sbom.cdx.json) bytes, sha256 $(sha256sum image-sbom.cdx.json | cut -d' ' -f1)"
# Two tags, one digest. The digest recorded here is what a GitOps manifest pins; the tags exist
# so a person can find it.
- name: Push the release and revision tags
id: push
if: ${{ github.ref_type == 'tag' }}
env:
PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
run: |
set -euo pipefail
[ -n "${PACKAGE_TOKEN}" ] || { echo "release: PACKAGE_TOKEN is not set" >&2; exit 1; }
printf '%s' "${PACKAGE_TOKEN}" | docker login "${REGISTRY}" --username "${GITHUB_REPOSITORY_OWNER}" --password-stdin
docker push "${IMAGE_REPOSITORY}:${RELEASE_VERSION}"
docker push "${IMAGE_REPOSITORY}:sha-${GITHUB_SHA}"
pinned="$(docker image inspect --format '{{range .RepoDigests}}{{println .}}{{end}}' "${IMAGE_REPOSITORY}:${RELEASE_VERSION}" \
| awk -v prefix="${IMAGE_REPOSITORY}@sha256:" 'index($0, prefix) == 1 { print; exit }')"
[ -n "${pinned}" ] || { echo "release: no registry digest for ${IMAGE_REPOSITORY} after push" >&2; exit 1; }
echo "pinned_reference=${pinned}" >> "${GITHUB_OUTPUT}"
echo "release: pin this in the GitOps manifest: ${pinned}"
# Signs the pushed digest with the release key pair and verifies the signature before the release
# counts as done, so a signature a cluster would reject fails here rather than at admission. A job
# of its own, so the private key exists only in a job that checks nothing out and builds nothing.
app-image-signing:
needs:
- app-image-release
if: ${{ github.ref_type == 'tag' }}
runs-on: ubuntu-latest
timeout-minutes: 30
defaults:
run:
working-directory: .
env:
PINNED_REFERENCE: ${{ needs.app-image-release.outputs.pinned_reference }}
steps:
# A pinned release binary with an asserted SHA-256, no action: the cosign-linux-{amd64,arm64}
# lines of the official v3.1.3 cosign_checksums.txt. The checksum file is fetched again and must
# still carry the pinned line, so a re-published asset fails the job.
- name: Install pinned cosign
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 "$(uname -m)" in
x86_64) asset='cosign-linux-amd64'; expected="${COSIGN_SHA256_AMD64}" ;;
aarch64) asset='cosign-linux-arm64'; expected="${COSIGN_SHA256_ARM64}" ;;
*) echo "release: unsupported architecture $(uname -m)" >&2; 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"
grep -qxF "${expected} ${asset}" "${RUNNER_TEMP}/cosign_checksums.txt" \
|| { echo "release: cosign_checksums.txt no longer lists the pinned ${asset} hash" >&2; exit 1; }
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}" "${install_dir}/cosign" | sha256sum -c -
chmod 0755 "${install_dir}/cosign"
echo "${install_dir}" >> "${GITHUB_PATH}"
- name: Sign the image digest and verify the signature
env:
PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
COSIGN_PRIVATE_KEY: ${{ secrets.COSIGN_PRIVATE_KEY }}
COSIGN_PASSWORD: ${{ secrets.COSIGN_PASSWORD }}
run: |
set -euo pipefail
[[ "${PINNED_REFERENCE}" =~ ^[a-z0-9.-]+/[a-z0-9._/-]+@sha256:[0-9a-f]{64}$ ]] \
|| { echo "release: app-image-release handed over no digest reference; got '${PINNED_REFERENCE}'" >&2; exit 1; }
[ -n "${COSIGN_PRIVATE_KEY}" ] || { echo "release: COSIGN_PRIVATE_KEY is not set" >&2; exit 1; }
printf '%s' "${PACKAGE_TOKEN}" | cosign login "${PINNED_REFERENCE%%/*}" --username "${GITHUB_REPOSITORY_OWNER}" --password-stdin
cosign sign --yes --key env://COSIGN_PRIVATE_KEY "${PINNED_REFERENCE}"
cosign public-key --key env://COSIGN_PRIVATE_KEY > "${RUNNER_TEMP}/cosign.pub"
cosign verify --key "${RUNNER_TEMP}/cosign.pub" "${PINNED_REFERENCE}" > /dev/null
echo "release: signed and verified ${PINNED_REFERENCE} with:"
cat "${RUNNER_TEMP}/cosign.pub"
+2
View File
@@ -3,6 +3,8 @@
/.trivyignore.yaml @DongHyeonka
/.github/ @DongHyeonka
/.gitea/ @DongHyeonka
/scripts/ci/ @DongHyeonka
/renovate.json @DongHyeonka
# Public security and compatibility baselines require an explicit maintainer review.
@@ -1,41 +0,0 @@
name: Set up Java and Gradle
description: >-
Installs the repository's pinned Temurin JDK, then configures Gradle through the official
setup-gradle action — which validates every checked-in wrapper jar and manages the Gradle cache.
Every Gradle job used to carry the JDK block verbatim, so the JDK patch level lived in fifty-nine
places; every job also carried a separate three-line wrapper-validation step, so the pinned action
SHA lived in forty.
# Wrapper validation is INSIDE this action now.
#
# It could not be before, and the reason was not a GitHub limitation: .github/scripts/
# verify-gradle-wrapper.sh read every workflow job and required it to contain, literally and in this
# order, an `actions/checkout@` step, the exact three-field pinned wrapper-validation step, and then
# the Gradle invocation. That literalness was the whole guard — "this job validated the wrapper" had
# to be answerable from the workflow file alone — and it is what made the step uninlineable.
#
# That script is gone (it also byte-hashed all twelve workflow files, so a comment change needed a
# hash update, while an attacker with write access would simply have updated both). The guarantee it
# was protecting is now the official action's own: `gradle/actions/setup-gradle` validates all
# wrapper jars by default (`validate-wrappers`, default true), and the action is pinned to a full
# commit SHA here — which GitHub's own hardening guide calls the only immutable action reference.
#
# `actions/checkout` still cannot move here: a `./.github/actions/...` reference is resolved from the
# checked-out working copy, so this file does not exist until checkout has already run. A composite
# action cannot contain the step that makes itself readable.
#
# So a Gradle job is two lines — checkout, then this action.
runs:
using: composite
steps:
- uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # actions/setup-java@v4.7.1
with:
distribution: temurin
java-version: "21.0.11+10"
# Gradle's own caching, not setup-java's `cache: gradle`. The two cache the same directory with
# different keys, and running both is how a job restores one cache and saves the other.
- uses: gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # gradle/actions@v6
with:
build-scan-publish: false
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
-18
View File
@@ -1,18 +0,0 @@
# GitHub dependency-review configuration. The workflow guards this GitHub-only API so other forges
# use the platform-neutral Trivy filesystem snapshot instead.
fail-on-severity: high
fail-on-scopes:
- runtime
# Template legal posture: deny strong and network copyleft for newly introduced dependencies.
# Forks must have their legal/security owner review this organization-specific list.
deny-licenses:
- GPL-2.0-only
- GPL-2.0-or-later
- GPL-3.0-only
- GPL-3.0-or-later
- AGPL-3.0-only
- AGPL-3.0-or-later
comment-summary-in-pr: never
+12 -16
View File
@@ -1,28 +1,25 @@
# 의존성 취약점 정책
이 정책을 강제하는 것은
[`dependency-vulnerability.yml`](workflows/dependency-vulnerability.yml),
[`dependency-review-config.yml`](dependency-review-config.yml),
[`scripts/ci/trivy-scan.sh`](../scripts/ci/trivy-scan.sh)(pull request·main·nightly workflow의
`vulnerabilities` job과 release workflow의 이미지 job이 부른다),
[`../.trivyignore.yaml`](../.trivyignore.yaml), CODEOWNERS,
[`../renovate.json`](../renovate.json)이다.
## 실행 위치와 플랫폼 경계
정본 workflow 파일은 `.github/workflows` 아래에 있다. 지금 origin은 Gitea이고, 서버 쪽 Actions는 밖에서
꺼져 있다. 이 통제를 커밋해도 원격 실행이 켜지거나 증명되지 않는다. 관리자가 따로 Actions를 켜고, 맞는
runner를 주고, 필수 검사(required check)를 설정하고, code owner 리뷰를 필수로 해야 한다.
workflow는 `.gitea/workflows`의 `pr.yml`·`main.yml`·`release.yml`이고 Gitea Actions(desktop runner)에서 돈다.
`vulnerabilities` job은 pull request, `main` push, 매일 예약 실행, 손으로 부른 실행에서 돈다. pull request의
필수 검사 `pr / done`이 그 결과를 포함한다.
외부 action은 확인한 전체 커밋 SHA로만 실행한다. 리뷰를 위해 같은 줄 주석에 바뀌지 않는 릴리스 태그를
남긴다. GitHub dependency review는 검사 결과만 내고 PR 요약 댓글은 쓰지 않는다. 그래서 workflow 전체의
`contents: read` 권한이 유지된다.
남긴다. 스캐너는 action이 아니라 체크섬을 고정한 릴리스 실행 파일이다.
GitHub dependency review와 dependency submission은 GitHub.com API에 기댄다. 둘은
`github.server_url == 'https://github.com'` 조건으로 막혀 있고, Gitea에서는 일부러 건너뛴다. `trivy-fs`는
플랫폼에 묶이지 않는, 릴리스를 막는 전체 스냅숏 검사다. pull request, `main` push, 매일 예약 실행, 손으로
부른 실행에서 돈다.
GitHub dependency review와 dependency submission은 GitHub.com API에만 있어 2026-11-08 Gitea로 옮길 때
지웠다. Trivy 전체 스냅숏 검사가 플랫폼에 묶이지 않는, 병합을 막는 검사다.
이미지 빌드·스캔, SBOM, 서명, provenance, 태그 릴리스는 `workflows/release.yml`이 맡는다. 이 정책은 그
job을 다루지 않는다.
이미지 빌드·스캔, SBOM, 서명, 태그 릴리스는 `.gitea/workflows/release.yml`이 맡는다. 이미지 스캔도 같은
스크립트(`image` 모드)와 같은 예외 파일을 쓴다.
## 심각도와 대응
@@ -34,8 +31,7 @@ job을 다루지 않는다.
| Low | 알리기만 한다 | 가능한 대로 |
High/Critical이 이 템플릿의 릴리스 기준이다. 정확한 기준과 고칠 기한은 외부 규정이 아니라 팀 정책이다.
템플릿을 받아 쓸 때 다시 검토한다. GitHub dependency review도 새로 들어온 runtime 의존성에 같은 High
기준을 쓴다.
템플릿을 받아 쓸 때 다시 검토한다.
Trivy JSON 스냅숏은 CISA KEV(Known Exploited Vulnerabilities, 실제 악용이 확인된 취약점) 목록과도
대조한다. 겹치는 항목이 있으면 Trivy 심각도와 상관없이 막는다. 대조하기 전에 CI는 KEV 목록을 확인한다.
@@ -63,7 +59,7 @@ runner는 다음 곳으로 HTTPS로 나갈 수 있어야 한다.
- Trivy 취약점 DB(스캐너 기본값, 보통 OCI 레지스트리)
- jq 릴리스(`JQ_DOWNLOAD_BASE_URL`이 내부 mirror를 가리키면 그쪽)
- CISA KEV 목록(`KEV_FEED_URL`이 내부 mirror를 가리키면 그쪽)
- forge가 action을 mirror하지 않으면 GitHub action 출처
- workflow가 전체 URL로 부르는 GitHub action 출처(`https://github.com/...`)
닫힌 네트워크에서는 고정한 Trivy·jq 산출물과 체크섬을 mirror하고, `TRIVY_DOWNLOAD_BASE_URL`과
`JQ_DOWNLOAD_BASE_URL`을 설정하고, Trivy 문서에 있는 DB mirror 환경을 설정하고, `KEV_FEED_URL`을 설정한다.
-50
View File
@@ -1,50 +0,0 @@
#!/usr/bin/env bash
set -euo pipefail
readonly JQ_VERSION='1.8.1'
readonly JQ_SHA256_AMD64='020468de7539ce70ef1bceaf7cde2e8c4f2ca6c3afb84642aabc5c97d9fc2a0d'
readonly JQ_SHA256_ARM64='6bc62f25981328edd3cfcfe6fe51b073f2d7e7710d7ef7fcdac28d4e384fc3d4'
readonly DOWNLOAD_BASE_URL="${JQ_DOWNLOAD_BASE_URL:-https://github.com/jqlang/jq/releases/download/jq-${JQ_VERSION}}"
: "${RUNNER_TEMP:?RUNNER_TEMP must be set by the CI runner}"
: "${GITHUB_PATH:?GITHUB_PATH must be set by the CI runner}"
architecture="${RUNNER_ARCH:-$(uname -m)}"
case "${architecture}" in
X64 | x86_64 | amd64)
asset='jq-linux-amd64'
expected_sha256="${JQ_SHA256_AMD64}"
;;
ARM64 | aarch64 | arm64)
asset='jq-linux-arm64'
expected_sha256="${JQ_SHA256_ARM64}"
;;
*)
printf '::error::install-jq: unsupported runner architecture: %s\n' "${architecture}" >&2
exit 1
;;
esac
install_dir="${RUNNER_TEMP}/jq-${JQ_VERSION}/bin"
destination="${install_dir}/jq"
mkdir -p "${install_dir}"
temporary="$(mktemp "${RUNNER_TEMP}/jq-${JQ_VERSION}.XXXXXX")"
trap 'rm -f "${temporary}"' EXIT
curl --fail --show-error --silent --location --retry 3 \
--proto '=https' --tlsv1.2 \
"${DOWNLOAD_BASE_URL}/${asset}" \
--output "${temporary}"
printf '%s %s\n' "${expected_sha256}" "${temporary}" | sha256sum -c -
chmod 0755 "${temporary}"
mv "${temporary}" "${destination}"
trap - EXIT
printf '%s\n' "${install_dir}" >> "${GITHUB_PATH}"
installed_version="$("${destination}" --version)"
if [[ "${installed_version}" != "jq-${JQ_VERSION}" ]]; then
printf '::error::install-jq: expected jq-%s, got %s\n' "${JQ_VERSION}" "${installed_version}" >&2
exit 1
fi
printf 'install-jq: %s installed under RUNNER_TEMP\n' "${installed_version}"
-37
View File
@@ -1,37 +0,0 @@
name: build-logic
# The included build's own tests (TestKit for the convention plugins, unit tests for the verifiers).
# The main task graph does not reach them, so they run here — and only when a pull request touches
# the included build or the catalog it reads. build-tools was folded into build-logic (review
# 2026-09-24 BUILD-O3-6).
on:
pull_request:
paths:
- "src/build-logic/**"
- "src/gradle/**"
- ".github/workflows/build-logic.yml"
push:
branches: ["main"]
paths:
- "src/build-logic/**"
- "src/gradle/**"
- ".github/workflows/build-logic.yml"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
included-builds:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Test the build-logic convention plugins
working-directory: src
run: ./gradlew -p build-logic test --stacktrace
-85
View File
@@ -1,85 +0,0 @@
name: ci-quality-gates
# The pull-request gate. Everything here blocks a merge.
#
# The job list used to include `gate-matrix-lint`, which ran .github/scripts/verify-gate-matrix.sh
# against .github/ci-gate-matrix.yml: a 1,025-line register of all 107 CI controls, checked for
# consistency against the Gradle task graph and this workflow by a 568-line shell script, which was
# itself checked by contract tests in :app-bootstrap. Adding one check meant editing Gradle, a
# workflow, the matrix, the verifier's expectations and a Java test. The information was already in
# the task graph and the job graph; the matrix was a third copy that had to be kept equal to both.
on:
pull_request:
push:
branches: ["main"]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
TESTCONTAINERS_REUSE_ENABLE: "false"
jobs:
quality-gates:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Export the live Gradle verification task map
working-directory: src
run: ./gradlew tasks --group verification --console=plain > ../verification-tasks.txt
- name: Upload the Gradle verification task map
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # actions/upload-artifact@v7.0.1
with:
name: gradle-verification-task-map
path: verification-tasks.txt
if-no-files-found: error
# `ci`, not `check`. A leaf's `check` is that leaf's — compile, its tests, Spotless, Checkstyle
# and Error Prone — and the repository-wide gates are named tasks of their own:
# ci = every leaf check + architectureCheck + qualityCheck
# A leaf's `check` includes its API surface verification (owner decision 20). The main-branch
# stage (`mainCheck`: environment contract, full-boot qualification, public-path baseline,
# transport and messaging lanes, document-contract lanes) runs in integration-main.yml.
- name: Run the pull-request gate
working-directory: src
run: ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --stacktrace
# Plans every stage (`--dry-run`: nothing executes) and fails when a strict lane is in no stage
# a workflow executes, or a stage is executed by no workflow (review 2026-11-01 08-01). A new
# lane fails here, on its own pull request, instead of running nowhere after it merges.
- name: Require every strict lane to be in an executed stage
working-directory: src
run: ./gradlew :verifyStrictLaneStages --dry-run --stacktrace
- name: Verify Compose profile contracts render exactly as declared
run: bash scripts/verify-compose-profile-contracts.sh
# The repository root and src/ hold only the entries on the allow list (owner decision
# 2026-11-07): a new top-level folder is a decision, not a side effect of a feature commit.
- name: Refuse a top-level folder outside the allow list
run: python3 scripts/check-repo-layout.py
release-gate:
needs:
- quality-gates
if: always()
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Require every current blocking job to succeed
env:
QUALITY_RESULT: ${{ needs.quality-gates.result }}
run: |
set -euo pipefail
for result in \
"${QUALITY_RESULT}"; do
if [[ "${result}" != "success" ]]; then
echo "::error::release-gate: required job result was ${result}"
exit 1
fi
done
echo "release-gate: all current blocking quality jobs succeeded."
@@ -1,180 +0,0 @@
name: dependency-vulnerability
on:
pull_request:
push:
branches: ["main"]
schedule:
- cron: "0 6 * * *"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
# The compare API exists only on GitHub.com. Trivy remains the full-snapshot backstop elsewhere.
dependency-review:
if: github.event_name == 'pull_request' && github.server_url == 'https://github.com'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Review newly introduced dependencies
uses: actions/dependency-review-action@56339e523c0409420f6c2c9a2f4292bbb3c07dd3 # actions/dependency-review-action@v4.8.0
with:
config-file: ./.github/dependency-review-config.yml
# The submission API is also GitHub.com-only and is not required for the platform-neutral scan.
dependency-submission:
if: github.event_name == 'push' && github.server_url == 'https://github.com'
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Submit the resolved Gradle dependency graph
uses: gradle/actions/dependency-submission@748248ddd2a24f49513d8f472f81c3a07d4d50e1 # gradle/actions@v4.4.4
with:
build-root-directory: src
trivy-fs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- 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}"
- name: Install checksum-pinned jq
env:
JQ_DOWNLOAD_BASE_URL: ${{ vars.JQ_DOWNLOAD_BASE_URL }}
run: bash .github/scripts/install-jq.sh
- name: Block High and Critical vulnerabilities
run: |
trivy fs \
--scanners vuln,license \
--severity CRITICAL,HIGH \
--exit-code 1 \
--ignorefile .trivyignore.yaml \
.
- name: Report Medium and Low vulnerabilities
run: |
trivy fs \
--scanners vuln,license \
--severity MEDIUM,LOW \
--exit-code 0 \
--ignorefile .trivyignore.yaml \
.
- name: Produce the governed all-severity KEV input
run: |
trivy fs \
--scanners vuln \
--severity CRITICAL,HIGH,MEDIUM,LOW,UNKNOWN \
--exit-code 0 \
--ignorefile .trivyignore.yaml \
--format json \
--output trivy-kev.json \
.
- name: Fail closed on any CISA KEV match
env:
CONFIGURED_KEV_FEED_URL: ${{ vars.KEV_FEED_URL }}
run: |
set -euo pipefail
readonly DEFAULT_KEV_FEED_URL='https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json'
readonly KEV_FEED_URL="${CONFIGURED_KEV_FEED_URL:-${DEFAULT_KEV_FEED_URL}}"
if ! curl --fail --show-error --silent --location --retry 3 \
--proto '=https' --tlsv1.2 "${KEV_FEED_URL}" --output kev.json; then
echo "::error::KEV feed unavailable; configure KEV_FEED_URL to an approved internal mirror"
exit 1
fi
if ! jq -e '
(.catalogVersion | type == "string" and test("\\S"))
and (.dateReleased | type == "string" and test("\\S"))
and (.count | type == "number")
and (.count > 0)
and (.count == (.count | floor))
and (.vulnerabilities | type == "array")
and ((.vulnerabilities | length) > 0)
and (.count == (.vulnerabilities | length))
and (all(
.vulnerabilities[];
(.cveID | type == "string" and test("^CVE-[0-9]{4}-[0-9]{4,}$"))
))
and (([.vulnerabilities[].cveID] | unique | length) == .count)
' kev.json >/dev/null; then
echo "::error::KEV feed is malformed, empty, count-inconsistent, or contains invalid/duplicate cveID values"
exit 1
fi
if ! jq -e '
(type == "object")
and (.Results | type == "array")
and ((.Results | length) > 0)
and (all(.Results[]; type == "object"))
and (all(
.Results[];
(.Vulnerabilities == null) or (.Vulnerabilities | type == "array")
))
and (all(
.Results[];
all(
.Vulnerabilities[]?;
(type == "object")
and (.VulnerabilityID | type == "string" and test("\\S"))
)
))
' trivy-kev.json >/dev/null; then
echo "::error::Trivy KEV input is malformed, empty, or contains an invalid VulnerabilityID"
exit 1
fi
jq -r '[.Results[]?.Vulnerabilities[]?.VulnerabilityID | select(type == "string")] | unique[]?' \
trivy-kev.json | sort -u > found-cves.txt
jq -r '.vulnerabilities[]?.cveID | select(type == "string")' \
kev.json | sort -u > kev-cves.txt
# No `|| true`. comm exits non-zero only when it cannot read or order its inputs, and
# swallowing that would have turned an unreadable CVE list into an empty intersection and
# printed "no catalog match" — a KEV cross-check that passes because it never ran.
hits="$(comm -12 found-cves.txt kev-cves.txt)"
if [[ -n "${hits}" ]]; then
echo "::error::CISA KEV-listed vulnerability found regardless of CVSS:"
printf '%s\n' "${hits}"
exit 1
fi
echo "KEV cross-check: no catalog match."
-28
View File
@@ -1,28 +0,0 @@
name: docs-check
# Document language, record head blocks, references and copied numbers (scripts/check-docs.py).
# It runs on every pull request, not on a docs/** path filter: deleting a file or a Gradle project
# in code is exactly what makes a living document point at nothing, and that change touches no
# document. The checker is plain Python outside Gradle, because the build does not parse documents.
on:
pull_request:
push:
branches: ["main"]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Test the document checker
run: python3 -m unittest discover -s scripts/tests
- name: Check documents
run: python3 scripts/check-docs.py
-84
View File
@@ -1,84 +0,0 @@
name: fileserver-nightly
# The environments that cannot run on every pull request: a real network filesystem, a foreign
# filesystem, and the long-running fault matrices. They are nightly rather than skipped because a
# green pull-request run is not certification of any of them.
on:
workflow_dispatch:
schedule:
- cron: '0 18 * * *'
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}
cancel-in-progress: false
jobs:
fileserver-nfs-ambiguity:
runs-on: ubuntu-latest
timeout-minutes: 45
env:
FILESERVER_NFS_TESTS: "true"
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Start the NFSv4 certification environment
run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d --wait
- name: Run the network-filesystem ambiguity suite
working-directory: src
run: >-
./gradlew
:adapter:outbound:fileserver:test --tests '*NfsAmbiguityIntegrationTest'
--stacktrace
- name: Tear down the NFS environment
if: always()
run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml down -v
fileserver-process-kill-matrix:
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 crash matrix and reconciliation suites
working-directory: src
run: >-
./gradlew
:adapter:outbound:fileserver:test --tests '*CrashRecoveryMatrixTest'
:application-fileserver:test --tests '*FileReconciliationServiceTest'
--rerun-tasks
--stacktrace
fileserver-large-file-performance:
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 large-file and slow-client suites under a constrained heap
working-directory: src
env:
GRADLE_OPTS: -Xmx512m
run: >-
./gradlew
:adapter:outbound:fileserver:test --tests '*LargeFileBoundedMemoryTest'
:adapter:outbound:fileserver:test --tests '*LocalAppendMemoryTest'
--rerun-tasks
--stacktrace
fileserver-multi-instance-lease:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Prove no run commits bytes from a stale lease
working-directory: src
run: >-
./gradlew
:application-fileserver:test --tests '*MultiInstanceWriterLeaseTest'
--rerun-tasks
--stacktrace
-110
View File
@@ -1,110 +0,0 @@
name: fileserver-pr
# Every claim in docs/fileserver/support-matrix.md that says "Stable" is backed by a job here.
# A support level with no job behind it is a marketing claim, not an engineering one, and
# DocumentationCoverageTest fails the build when the two drift apart.
on:
workflow_dispatch:
pull_request:
paths:
- 'src/application-fileserver/**'
- 'src/adapter/inbound/web-fileserver/**'
- 'src/adapter/outbound/fileserver/**'
- 'src/adapter/outbound/persistence-fileserver/**'
- 'src/composition/fileserver-platform/**'
- 'src/adapter/outbound/persistence-jpa/src/**/fileserver/**'
- 'src/app-bootstrap/src/**/fileserver/**'
- 'docs/fileserver/**'
# The capability is not only its Java files. A change to the bound settings, the shipped
# environment, the registry that documents it, or the container that has to give it a
# writable volume changes how it behaves at runtime just as surely — and those were the
# exact files that could previously ship unverified.
- 'src/app-bootstrap/src/main/resources/application.yml'
- 'src/.env'
- 'docs/registries/env-keys.yaml'
- 'src/Dockerfile'
- 'compose.yaml'
- 'src/app-bootstrap/compose-lanes/fileserver.yaml'
- '.github/workflows/fileserver-pr.yml'
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
- '.github/actions/setup-gradle-java/action.yml'
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
fileserver-unit-and-architecture:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
# The architecture half of this claim is ci-quality-gates.yml's `architectureCheck`, which runs
# the whole ArchUnit suite on the same pull request; a filtered second run here was the repeat
# review BUILD-중복-6 removed.
- name: Run the fileserver application and assembly suites
working-directory: src
run: >-
./gradlew
:application-fileserver:test
:composition:fileserver-platform:test
--stacktrace
fileserver-local-ext4-contract:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Certify the local content store against the shared contract
working-directory: src
run: >-
./gradlew
:adapter:outbound:fileserver:test
--stacktrace
fileserver-http-contract:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the servlet transport contracts
working-directory: src
run: >-
./gradlew
:adapter:inbound:web-fileserver:test
--stacktrace
fileserver-security-suite:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the path, filename, range, and problem-detail hardening suite
working-directory: src
run: >-
./gradlew
:adapter:inbound:web-fileserver:test --tests '*FileserverHardeningContractTest'
:adapter:outbound:fileserver:test --tests '*PhysicalPathResolverTest'
--stacktrace
fileserver-bounded-memory:
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 transfer cost does not scale with file size
working-directory: src
run: >-
./gradlew
:adapter:outbound:fileserver:test --tests '*LargeFileBoundedMemoryTest'
--stacktrace
-249
View File
@@ -1,249 +0,0 @@
name: integration-main
# Stage 2: is the merged state healthy.
#
# The question this stage answers is different from stage 1's. Stage 1 asks whether a diff is safe
# and blocks a merge; stage 2 asks whether main is healthy and does not — the merge has already
# happened. That difference is the point, and it is what lets a control exist without being an
# obstacle: a gate here still fails loudly, it just fails after the thing it is reporting on.
#
# Two kinds of work live here.
#
# 1. The lanes that need a machine that is not simultaneously compiling something else — load,
# abuse, graceful shutdown, TCP fault injection, resource bounds. They were web-nightly.yml and
# httpclient-nightly.yml, two module-shaped files whose only real difference was the cadence they
# shared. They now run on every push to main as well as nightly, which is strictly more often
# than before.
#
# 2. The container-backed lanes, run as the root category aggregates `:integrationCheck` and
# `:performanceCheck` rather than one workflow line per lane. A lane nobody runs is not coverage;
# it is a file that looks like coverage — and naming lanes here one by one is how fourteen of
# them came to run nowhere (review 2026-11-01 08-01). The pull-request gate's
# `verifyStrictLaneStages` now fails when a strict lane is in no stage a workflow executes. They
# are here rather than in stage 1 because every one of them starts containers or real servers,
# and the pull-request budget is minutes for the whole gate.
#
# What is deliberately NOT here: the web "Advanced capability" nightly lane that used to exist as
# web-advanced-nightly.yml (websocket-advanced-nightly.yml went with the websocket Advanced code,
# deleted 2026-09-25). The web leaf's build file says it outright — "They also run inside `test`,
# deliberately ... excluding them from the PR gate to make this lane look meaningful would mean the
# PR gate stopped covering a fifth of the leaf" — so `webAdvancedTest` selects tagged tests that
# `:<leaf>:test` already runs, and `:<leaf>:test` runs inside the root `check` on every pull request
# and every push to main. The strict lane itself survives in release.yml, where its
# fail-on-nothing-discovered guard is worth a job.
on:
push:
branches: ["main"]
schedule:
# 03:00 UTC. Late enough that the day's merges are in, early enough that a failure is triaged
# before the next working day starts.
- cron: '0 3 * * *'
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false
# The documentation-drift gates that used to run here are gone rather than demoted.
#
# They were four hand-written parsers: README shell blocks compared against the Gradle task graph,
# runbook identifiers compared against every declared Java type, a leaf count written in prose
# compared against the registry, and a Markdown table compared against the declared source sets.
# Each was a custom parser for a file format nobody controls, and each made a documentation edit a
# precondition for a build. A stale sentence is a defect, but it is not one a build can be failed
# for, and link-check.yml already answers the one documentation question with a stable machine
# answer: does this link resolve.
jobs:
# The main-branch stage of the Gradle gates (`:mainCheck`): the environment contract, full-boot
# qualification, the public-path baseline, the conditional transport
# lanes, the messaging contract lanes and each leaf's document-contract lanes. API surfaces are
# in the pull-request `check` (owner decision 20). The rest left the pull-request gate (review
# 2026-09-24 BUILD, item 12); none of them is deleted.
main-check:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Require the committed public-path security baseline
run: |
set -euo pipefail
readonly snapshot='docs/security/public-paths-snapshot.txt'
if [[ ! -s "${snapshot}" ]] || ! git ls-files --error-unmatch "${snapshot}" >/dev/null 2>&1; then
echo "::error::${snapshot} is missing, empty or not committed; verifyPublicPathSnapshot must not create its own baseline."
exit 1
fi
- uses: ./.github/actions/setup-gradle-java
- name: Run the main-branch stage
working-directory: src
# `--continue`: one failed lane (an external image that cannot be pulled, say) must not stop
# the other main-stage gates from reporting (review 2026-11-01 08-04).
run: ./gradlew :mainCheck --continue --warning-mode=fail --stacktrace
# Storability only: the `--dry-run` below plans `integrationCheck` without running a lane. The
# lanes run in `integration-check`.
#
# Two questions. Can every task in the repository-wide gates be *stored* (a property of the task
# graph, so `--dry-run` answers it for all of them in seconds)? And is a stored entry *reused* while
# the build still executes its work (checked on the two core leaves)?
configuration-cache:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Require every repository-wide gate to be storable
working-directory: src
shell: bash
run: |
set -euo pipefail
for gate in ci mainCheck integrationCheck releaseCheck; do
echo "::group::${gate}"
./gradlew "${gate}" --dry-run \
--configuration-cache --configuration-cache-problems=fail --stacktrace
output="$({ ./gradlew "${gate}" --dry-run \
--configuration-cache --configuration-cache-problems=fail --stacktrace; } 2>&1)"
printf '%s\n' "${output}"
echo '::endgroup::'
grep -Fq 'Reusing configuration cache.' <<<"${output}" || {
echo "::error::Gradle did not reuse the configuration cache for ${gate}."
exit 1
}
done
- name: Store configuration cache for the everyday core build
working-directory: src
run: >-
./gradlew
:domain-core:check
:application-core:check
--configuration-cache
--configuration-cache-problems=fail
--stacktrace
- name: Require configuration-cache reuse
working-directory: src
shell: bash
run: |
set -euo pipefail
output="$({ ./gradlew :domain-core:check :application-core:check \
--configuration-cache --configuration-cache-problems=fail --stacktrace; } 2>&1)"
printf '%s\n' "${output}"
grep -Fq 'Reusing configuration cache.' <<<"${output}" || {
echo '::error::Gradle did not reuse the configuration cache on the second identical build.'
exit 1
}
# The integration stage: every integration-category strict lane (`:integrationCheck`).
#
# This job replaced six jobs that named lanes one by one — the MongoDB lanes, app-bootstrap's
# Testcontainers lane, the moved messaging/object-storage/sample contracts, six of the
# persistence-jpa PostgreSQL contracts and the httpclient fault injection. Naming lanes was how
# eleven persistence-jpa readiness lanes ended up running nowhere: a lane added to Gradle without a
# workflow line was declared, failed closed, and executed on no machine (review 2026-11-01 08-01).
# The aggregate is the list now. A lane joins it by declaring `integration()`, and the root
# `verifyStrictLaneStages` (pull-request gate) fails when a strict lane is in no stage a workflow
# executes.
#
# `--continue` so that one red lane does not hide the others: every failed lane is named in the
# same run. Lanes that need an input this job does not have (the Redis topology coordinates, the
# protected AWS sandbox) are `explicitOnly`; the aggregate prints which ones it left out.
# The container lanes take the build-wide `exclusiveRealServerLane` slot one at a time, so the
# job's length is the sum of the lanes. Split the aggregate across jobs when it outgrows its
# timeout rather than going back to naming lanes.
#
# Measured length (one local run of `:integrationCheck`, 2026-11-01, 37 lanes, images already
# pulled, machine load 24): 794 s for the command, of which the lanes' test JVMs took about 624 s
# in sum — mongoSecurityIntegrationTest 89, jpaPlatformContractTest 104, messagingCertificationTest
# 70, mongoCompatibilityTest 69, jpaPlatformMigrationTest 66, mongoFailoverTest 59, the eleven JPA
# readiness lanes 57 together, httpClientFailureInjectionTest 27, sample integrationTest 23,
# messaging starter integrationTest 21, the rest under 10 each — and the remainder was compilation
# and container start-up between lanes. A hosted runner adds cold image pulls (about 5 GB
# uncompressed across the PostgreSQL, MongoDB, Kafka, nginx, httpbin and Toxiproxy images) and a
# cold Gradle cache; expect 25 to 40 minutes (an estimate, not a measured hosted run). The 240-minute timeout is a ceiling for a hung container, not a budget.
# Since 2026-11-08 messagingCertificationTest and the messaging starter's integrationTest run in the
# messaging-library repository, not here; the measurement above predates that.
integration-check:
runs-on: ubuntu-latest
timeout-minutes: 240
env:
# Reuse would hand the failover lane a replica set another lane had already faulted.
TESTCONTAINERS_REUSE_ENABLE: "false"
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run every integration-category strict lane
working-directory: src
run: ./gradlew :integrationCheck --continue --stacktrace
- name: Publish the integration lane reports
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: integration-check-reports
path: src/**/build/reports/tests/
if-no-files-found: warn
# The performance stage: every performance-category strict lane (`:performanceCheck`) — Tomcat and
# Jetty load, slow-client and graceful shutdown, the Hikari pool contract, the httpclient pool,
# streaming, retry and rotation bounds, the MongoDB resource budget. They measure behaviour that
# degrades gradually rather than breaking outright, which is the kind of regression a per-PR gate
# never catches. This job replaced `web-load-abuse-and-shutdown`, which despite its name ran
# `:adapter:inbound:web:test` and `webJettyCompatTest` — two lanes the pull-request and main stages
# already run — and never the load lanes (review 2026-11-01 08-01), and `httpclient-performance`.
# No assertions switch: the strict-lane convention asserts every performance lane's bounds, so this
# job and a person on a workstation run the same command and get the same bounds.
performance-check:
runs-on: ubuntu-latest
timeout-minutes: 120
env:
TESTCONTAINERS_REUSE_ENABLE: "false"
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run every performance-category strict lane
working-directory: src
run: ./gradlew :performanceCheck --continue --stacktrace
- name: Publish the performance lane reports
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: performance-check-reports
path: src/**/build/reports/tests/
if-no-files-found: warn
httpclient-http3-experimental:
runs-on: ubuntu-latest
timeout-minutes: 30
# Experimental by design (D-08): the result is reported, never used to block a merge. Registered
# advisory so that "this job cannot fail the
# build" is written down rather than inferred from a field two hundred lines into a workflow.
continue-on-error: true
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Exercise the experimental HTTP/3 opt-in
working-directory: src
run: ./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true --stacktrace
# Dynamic half of the compose-profile contract. Every blocking lane the matrix declares runs on
# main and nightly; a partial lane run is reproduction only and cannot satisfy this job. The count
# is not written here on purpose — a number in prose drifts the moment a lane is added, and the
# matrix file is the thing this job reads.
#
# The lanes boot the qualification image (src/Dockerfile COMPOSITION=qualification: every
# capability module present). The script selects it; release.yml builds the default image.
compose-runtime-smoke:
runs-on: ubuntu-latest
timeout-minutes: 180
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Run every blocking Compose runtime lane
run: bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
- name: Publish sanitized runtime-smoke evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: compose-runtime-smoke-evidence
path: src/app-bootstrap/build/evidence/runtime-smoke
if-no-files-found: warn
-75
View File
@@ -1,75 +0,0 @@
name: jpa-next
# Advisory compatibility probes for future JPA/Hibernate/PostgreSQL majors. These targets are not
# resolved by the current build, so the artifact records NOT_EXECUTABLE rather than implying that a
# green policy test is compatibility evidence.
on:
workflow_dispatch:
schedule:
- cron: '0 5 * * 1'
permissions:
contents: read
jobs:
compatibility:
strategy:
fail-fast: false
matrix:
include:
- id: jakarta-persistence-4
target: Jakarta Persistence 4
coordinate: jakarta.persistence:jakarta.persistence-api:4.x
test: "*Jpa4CompatibilityTest"
reason: the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it
- id: hibernate-8
target: Hibernate 8
coordinate: org.hibernate.orm:hibernate-core:8.x
test: "*Hibernate8CompatibilityTest"
reason: Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it
- id: postgresql-19
target: PostgreSQL 19
coordinate: postgres:19-alpine
test: "*PostgreSql19CompatibilityTest"
reason: no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane
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 current-runtime policy probe
id: compatibility-probe
working-directory: src
run: >-
./gradlew
:adapter:outbound:persistence-jpa:test
--tests '${{ matrix.test }}'
--stacktrace
- name: Record what this lane did and did not execute
if: always()
env:
PROBE_OUTCOME: ${{ steps.compatibility-probe.outcome }}
TARGET: ${{ matrix.target }}
TARGET_COORDINATE: ${{ matrix.coordinate }}
REASON: ${{ matrix.reason }}
run: |
mkdir -p compatibility-evidence
{
echo "target=${TARGET}"
echo "target-coordinate=${TARGET_COORDINATE}"
echo "status=NOT_EXECUTABLE"
echo "probe-result=${PROBE_OUTCOME}"
echo "reason=${REASON}"
echo "what-ran=the current runtime's own version canary for this target"
echo "sha=${{ github.sha }}"
} > compatibility-evidence/status.properties
echo "::notice::${TARGET} compatibility is NOT_EXECUTABLE: ${REASON}"
- name: Upload the compatibility status
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: compatibility-status-${{ matrix.id }}
path: compatibility-evidence/status.properties
retention-days: 30
if-no-files-found: error
-86
View File
@@ -1,86 +0,0 @@
name: jpa-nightly
# The suites that are too slow, too Docker-heavy, or too machine-dependent for a PR, and the middle
# of the PostgreSQL matrix.
#
# The failure-injection lane is the one that matters most and is easiest to lose: it is the only
# place the commit-ambiguity scenarios run, and they are the only evidence that a lost commit
# acknowledgement produces completion-unknown rather than a retry.
on:
workflow_dispatch:
schedule:
# 02:30 UTC daily.
- cron: '30 2 * * *'
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}
cancel-in-progress: false
jobs:
jpa-full-matrix:
runs-on: ubuntu-latest
timeout-minutes: 60
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: Certify the platform against PostgreSQL ${{ matrix.postgresql }}
working-directory: src
run: >-
./gradlew
:adapter:outbound:persistence-jpa:jpaPlatformContractTest
-Pjpa.matrix.versions=${{ matrix.postgresql }}
--stacktrace
jpa-failure-injection:
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Reproduce deadlock, serialization, and commit-ambiguity scenarios
working-directory: src
run: >-
./gradlew
:adapter:outbound:persistence-jpa:jpaPlatformFailureTest
--stacktrace
jpa-query-plan-and-security:
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 query plan and database security suites
working-directory: src
run: >-
./gradlew
:adapter:outbound:persistence-jpa:jpaPlatformQueryPlanTest
:adapter:outbound:persistence-jpa:jpaPlatformSecurityTest
--stacktrace
jpa-pool-pressure:
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Verify pool saturation and REQUIRES_NEW connection behaviour
working-directory: src
# A behaviour contract, not a measurement. This step used to switch assertions off with an
# explicit property and call the result a certification, so the only threshold it ever
# asserted was that thresholds were not being asserted. What
# it checks now — that REQUIRES_NEW needs two connections per concurrent thread, that a
# saturated pool reports its pending count, that a caller waits rather than proceeding
# without a connection — is true on any runner, so there is nothing to switch off.
run: >-
./gradlew
:adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest
--stacktrace
-49
View File
@@ -1,49 +0,0 @@
name: link-check
on:
pull_request:
paths:
- "README.md"
- "src/README.md"
- "src/**/README.md"
- "src/**/CLAUDE.md"
- "docs/**/*.md"
- ".github/**/*.md"
- ".github/workflows/link-check.yml"
push:
branches: ["main"]
paths:
- "README.md"
- "src/README.md"
- "src/**/README.md"
- "src/**/CLAUDE.md"
- "docs/**/*.md"
- ".github/**/*.md"
- ".github/workflows/link-check.yml"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
lychee:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Check committed documentation links
uses: lycheeverse/lychee-action@7cd0af4c74a61395d455af97419279d86aafaede # lycheeverse/lychee-action@v2.0.2
with:
args: >-
--no-progress
--root-dir .
README.md
src/README.md
'src/**/README.md'
'src/**/CLAUDE.md'
'docs/**/*.md'
'.github/**/*.md'
fail: true
-144
View File
@@ -1,144 +0,0 @@
name: notification-platform
# Verification tiers for the Notification Delivery Platform.
#
# The PR tier is deliberately free of any external provider. A gate that depends on a third-party
# sandbox fails for reasons that have nothing to do with the change under review, and a gate people
# learn to re-run is not a gate. Real provider smoke tests live in the secret-protected tier, where
# a failure is an environment signal rather than a merge blocker.
#
# Every job that invokes Gradle validates the wrapper first with the repository's pinned action;
# the wrapper JAR is executable code fetched at build time, so validating it is what keeps a
# compromised wrapper from turning any workflow run into arbitrary code execution.
on:
pull_request:
paths:
# The filter used to stop at the four notification source trees, so a change to the
# composition root, the settings binding, the schema migrations, or the evidence manifest
# ran none of this — and those are exactly the surfaces that decide whether the platform
# assembles, binds and migrates at all.
- 'src/application-core/src/**/notification/**'
- 'src/adapter/outbound/notification/**'
- 'src/adapter/outbound/persistence-notification/**'
# The notification real-PostgreSQL qualifications still run in the JPA leaf's lane.
- 'src/adapter/outbound/persistence-jpa/src/**/notification/**'
- 'src/adapter/inbound/web-notification/**'
- 'src/composition/notification-platform/**'
- 'src/app-bootstrap/src/main/resources/application*.yml'
- 'src/gradle/notification-*.gradle'
- 'src/config/architecture/modules.json'
- 'src/.env'
- 'docs/notification/**'
- 'src/app-bootstrap/compose-lanes/smoke/notification-smoke.sh'
- '.github/workflows/notification-platform.yml'
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
- '.github/actions/setup-gradle-java/action.yml'
push:
branches: [ main ]
schedule:
# Nightly: the chaos tier, which is slower and inherently less deterministic than the PR tier.
- cron: '0 17 * * *'
workflow_dispatch:
permissions:
contents: read
concurrency:
group: notification-platform-${{ github.ref }}
cancel-in-progress: true
jobs:
pr:
name: contract (Java 21, no external provider)
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Compile and format check
working-directory: src
run: ./gradlew :application-core:compileJava :adapter:outbound:notification:compileJava --console=plain
- name: Application contracts
working-directory: src
run: ./gradlew :application-core:test --console=plain
- name: Provider contract suite
working-directory: src
run: ./gradlew :adapter:outbound:notification:test --console=plain
- name: Persistence and web
working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:test :adapter:inbound:web-notification:test :composition:notification-platform:test --console=plain
# The PR tier never touched a database, so every claim about migrations, claim atomicity and
# lease fencing rested on a fake. Docker is available on this runner; the lane fails closed
# when the container cannot start, because a skipped contract reports success for a database
# nobody tested.
- name: Notification schema and claim contracts (real PostgreSQL)
working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest --console=plain
- name: Notification migration upgrade (real PostgreSQL)
working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformMigrationTest --console=plain
# The architecture gates run in ci-quality-gates.yml on the same pull request; the evidence
# manifest (NotificationEvidenceVerifierTest) and the environment registry
# (NotificationEnvironmentRegistryTest) are leaf tests the steps above already ran.
# verifyNotificationApiSurface is part of the leaf's `check` (owner decision 20), so the step
# below runs it; a separate API surface step would run it twice.
- name: Static analysis and API surface
working-directory: src
run: ./gradlew :adapter:outbound:notification:check -x test --console=plain
nightly-chaos:
name: chaos (ambiguity, restart recovery, callback burst)
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
# This job is named for ambiguity, restart recovery and callback burst. It used to run a
# unit-test filter and then `test` — neither of which restarts anything or bursts anything —
# so the job name was the only place those three properties existed.
- name: Ambiguity and fault harness
working-directory: src
run: ./gradlew :adapter:outbound:notification:test --tests '*ChaosSecurity*' --tests '*CrossProviderContractSuite*' --console=plain
- name: Concurrency and rotation races
working-directory: src
run: ./gradlew :adapter:outbound:notification:test --tests '*ConcurrencyTest' --tests '*ProviderRuntimeStateTest' --console=plain
- name: Restart recovery and lease fencing (real PostgreSQL)
working-directory: src
run: ./gradlew :adapter:outbound:persistence-jpa:jpaPlatformContractTest :adapter:outbound:persistence-jpa:jpaPlatformFailureTest --console=plain
- name: Notification regression suite
working-directory: src
run: >-
./gradlew
:application-core:test
:adapter:outbound:notification:test
:adapter:outbound:persistence-jpa:test
:adapter:inbound:web-notification:test
:composition:notification-platform:test
--console=plain
# A filter that matches nothing passes. Each --tests filter above names a class that exists
# today; if one is renamed the job must fail rather than quietly stop covering it.
- name: Every named suite actually ran
working-directory: src
run: |
set -euo pipefail
for suite in ChaosSecurity CrossProviderContractSuite ConcurrencyTest ProviderRuntimeStateTest; do
if ! find . -path '*/build/test-results/*' -name "*${suite}*.xml" | grep -q .; then
echo "no test results for ${suite}: the filter matched nothing and the job passed vacuously" >&2
exit 1
fi
done
# There is no provider-sandbox job. It ran only on workflow_dispatch and could not succeed by
# any path: with no credentials its first step exit 1-ed, and with credentials the only test it
# ran was ProviderSandboxSmokeTest, whose body is an unconditional fail() saying a real sandbox
# call is not implemented. Its credential check read secrets.NOTIFICATION_SANDBOX_CREDENTIALS,
# which nothing in this repository consumes — the test reads NOTIFICATION_SANDBOX_ENABLED — so
# any non-empty string satisfied it and was then dropped.
#
# The unimplemented state is still stated in two places that do not depend on a workflow:
# ProviderSandboxSmokeTest itself, and the unsatisfied provider-wire-qualified claim in
# docs/notification/evidence-manifest.json, which NotificationEvidenceVerifierTest enforces in
# the notification leaf's tests. When a real sandbox call is implemented, the job comes back with it.
@@ -1,65 +0,0 @@
name: object-storage-qualification
# Only pull requests that touch object storage start the MinIO container (review BUILD-계획-B3). The
# MinIO lanes left the object storage leaf's `check`; they run in the root `integrationCheck` (main push
# and nightly, integration-main.yml) and here.
on:
pull_request:
paths:
- "src/application-objectstorage/**"
- "src/adapter/outbound/objectstorage/**"
- "src/gradle/**"
- ".github/workflows/object-storage-qualification.yml"
schedule:
- cron: "23 3 * * 2"
workflow_dispatch:
inputs:
run_protected_aws:
description: Run the protected AWS sandbox qualification lane
required: true
default: false
type: boolean
permissions:
contents: read
env:
TESTCONTAINERS_REUSE_ENABLE: "false"
jobs:
minio-managed-contract:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run exact-release MinIO managed contract
working-directory: src
run: ./gradlew :adapter:outbound:objectstorage:objectStorageMinioContractTest --stacktrace
minio-managed-fault:
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run digest-pinned MinIO and Toxiproxy fault contract
working-directory: src
run: ./gradlew :adapter:outbound:objectstorage:objectStorageMinioFaultTest --stacktrace
aws-managed-common-subset:
if: >-
github.event_name == 'workflow_dispatch'
&& inputs.run_protected_aws
environment: object-storage-aws-qualification
runs-on: ubuntu-latest
env:
OBJECT_STORAGE_AWS_QUALIFICATION_ENABLED: "true"
OBJECT_STORAGE_AWS_BUCKET: ${{ secrets.OBJECT_STORAGE_AWS_BUCKET }}
OBJECT_STORAGE_AWS_REGION: ${{ secrets.OBJECT_STORAGE_AWS_REGION }}
OBJECT_STORAGE_AWS_EXPECTED_OWNER: ${{ secrets.OBJECT_STORAGE_AWS_EXPECTED_OWNER }}
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run protected AWS common-subset qualification
working-directory: src
run: ./gradlew :adapter:outbound:objectstorage:objectStorageAwsQualificationTest --stacktrace
-262
View File
@@ -1,262 +0,0 @@
name: pr-adapters
# Stage 1, the adapter half: the lanes a pull request must clear that `ci-quality-gates.yml` cannot
# reach.
#
# It replaces web-pr.yml, websocket-pr.yml, httpclient-contract.yml and jpa-pr.yml, which were four
# files split by module rather than by stage. Splitting by module is what made the duplication
# invisible: each file opened with its own "unit and architecture" job running
# `:<leaf>:test verifyCleanArchitectureDependencies`, and all four of those were already inside the
# root `check` that ci-quality-gates.yml runs on every pull request with no path filter. Four jobs,
# four runners, four Gradle configurations, zero additional coverage. They are gone; what is left
# here is only what `check` does not run.
#
# What `check` does not run, and therefore what this file is for:
# * lanes with their own source set — the servlet system contract, a second servlet container,
# a real Nginx;
# * lanes parameterised per run — one PostgreSQL major per job, one HTTP transport per job.
# Each of those genuinely cannot run inside `check`, which is the test for whether a job belongs
# here at all.
#
# Path filtering is per job rather than per workflow. The four files it replaces each carried an
# `on.pull_request.paths` list, so the whole file was skipped or run as a unit; a change touching
# web and JPA started two workflows and a change touching neither still started none. Here one
# `changes` job computes the answer once from the pull request's own diff and every lane reads it.
# The filter is a plain `git diff` rather than a filter action: this repository pins every action by
# commit SHA and adding a third-party action to compute a boolean is a supply-chain decision, not a
# convenience.
on:
pull_request:
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
# One diff, read once. `workflow_dispatch` answers "everything changed", because a manual run is
# somebody asking for the lanes and there is no base ref to compare against.
changes:
runs-on: ubuntu-latest
timeout-minutes: 10
outputs:
web: ${{ steps.filter.outputs.web }}
websocket: ${{ steps.filter.outputs.websocket }}
httpclient: ${{ steps.filter.outputs.httpclient }}
jpa: ${{ steps.filter.outputs.jpa }}
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
with:
# Both endpoints of the pull request's diff have to be present locally; the default
# shallow fetch has neither the base commit nor the merge base.
fetch-depth: 0
- name: Decide which adapter lanes this diff can affect
id: filter
env:
BASE_SHA: ${{ github.event.pull_request.base.sha }}
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
run: |
set -euo pipefail
if [ "${GITHUB_EVENT_NAME}" != 'pull_request' ]; then
changed='ALL'
else
if [ -z "${BASE_SHA}" ] || [ -z "${HEAD_SHA}" ]; then
echo "::error::pull request diff endpoints are missing; refusing to report no lanes"
exit 1
fi
changed="$(git diff --name-only "${BASE_SHA}" "${HEAD_SHA}")"
fi
# Fail closed rather than reporting "nothing changed": an empty diff on a pull request
# means the comparison did not work, and a filter that answers false on a broken
# comparison silently turns every lane below off.
if [ "${changed}" != 'ALL' ] && [ -z "${changed}" ]; then
echo "::error::the pull request diff is empty; the comparison did not run"
exit 1
fi
printf 'changed files:\n%s\n' "${changed}"
emit() {
lane="$1"
shift
if [ "${changed}" = 'ALL' ]; then
printf '%s=true\n' "${lane}" >> "${GITHUB_OUTPUT}"
printf 'lane %s: true (manual run)\n' "${lane}"
return 0
fi
for pattern in "$@"; do
if printf '%s\n' "${changed}" | grep -qE -- "${pattern}"; then
printf '%s=true\n' "${lane}" >> "${GITHUB_OUTPUT}"
printf 'lane %s: true (%s)\n' "${lane}" "${pattern}"
return 0
fi
done
printf '%s=false\n' "${lane}" >> "${GITHUB_OUTPUT}"
printf 'lane %s: false\n' "${lane}"
}
# This workflow and the composite action every lane below uses are in every lane's path
# set: a change to either changes what the lanes do, and a gate that does not re-run when
# its own definition changes is a gate nobody has seen run in its current form.
common='^\.github/workflows/pr-adapters\.yml$|^\.github/actions/'
emit web \
'^src/adapter/inbound/web/' \
'^src/application-core/src/.*/operation/' \
'^src/application-core/src/.*/idempotency/' \
'^src/adapter/outbound/persistence-jpa/src/.*/operation/' \
'^docs/web/' \
"${common}"
emit websocket \
'^src/adapter/inbound/websocket/' \
'^docs/websocket/' \
"${common}"
emit httpclient \
'^src/adapter/outbound/httpclient/' \
'^src/app-bootstrap/src/.*/httpclient/' \
'^docs/httpclient/' \
'^scripts/verify-httpclient-docs\.py$' \
"${common}"
emit jpa \
'^src/adapter/outbound/persistence-jpa/' \
'^src/app-bootstrap/src/.*/jpa/' \
'^src/config/architecture/modules\.json$' \
'^docs/jpa/' \
'^docs/adr/ADR-JPA-' \
"${common}"
# The servlet system contract on both containers the template supports (Tomcat, Jetty). Real
# sockets, so neither lane is part of `check`.
web-servlet-containers:
needs: changes
if: needs.changes.outputs.web == 'true'
runs-on: ubuntu-latest
timeout-minutes: 40
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the servlet system contract on Tomcat and Jetty
working-directory: src
run: >-
./gradlew
:adapter:inbound:web:systemTest
:adapter:inbound:web:webJettyCompatTest
--stacktrace
- name: Publish the test reports
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: web-servlet-containers-reports
path: src/adapter/inbound/web/build/reports/tests/
if-no-files-found: warn
websocket-container-matrix:
needs: changes
if: needs.changes.outputs.websocket == 'true'
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the runtime contract on the second servlet container
working-directory: src
run: >-
./gradlew
:adapter:inbound:websocket:websocketJettyTest
--stacktrace
# Docker-gated, and the lane fails rather than skipping. Upgrade handling is the single most
# common WebSocket deployment failure and it is invisible from either side alone.
websocket-nginx-contract:
needs: changes
if: needs.changes.outputs.websocket == 'true'
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the upgrade and forwarded-header contract behind a real Nginx
working-directory: src
run: >-
./gradlew
:adapter:inbound:websocket:websocketNginxTest
--stacktrace
# One transport per job, so a transport that stops satisfying the shared contract fails on its own
# row instead of disappearing into an aggregate run. `check` runs this lane once, unparameterised.
httpclient-stable-contract:
needs: changes
if: needs.changes.outputs.httpclient == 'true'
runs-on: ubuntu-latest
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
transport: [apache, jdk]
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Certify one transport against the shared contract
working-directory: src
run: >-
./gradlew
:adapter:outbound:httpclient:httpClientStableContractTest
-Phttpclient.contract.transports=${{ matrix.transport }}
--stacktrace
# Only the Spring 7.0 lane. httpClientSecurityTest and spring62ApiSurfaceScan used to run here
# too; both are `dependsOn` of this leaf's `check`
# (src/adapter/outbound/httpclient/build.gradle), so ci-quality-gates.yml already ran them on the
# same pull request. spring70CompatibilityTest is deliberately outside `check` and is what is left.
httpclient-security-and-compatibility:
needs: changes
if: needs.changes.outputs.httpclient == 'true'
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the next-major Spring compatibility lane
working-directory: src
run: >-
./gradlew
:adapter:outbound:httpclient:spring70CompatibilityTest
--stacktrace
# 16 and 18 — the ends of the Stable matrix. 17 runs in the integration stage. What this does not
# do is skip the container lane on a runner without Docker: PostgreSqlContainerFactory throws,
# because a skipped contract reports success for a database nobody tested.
jpa-postgresql-contract:
needs: changes
if: needs.changes.outputs.jpa == 'true'
runs-on: ubuntu-latest
timeout-minutes: 45
strategy:
fail-fast: false
matrix:
postgresql: ["16", "18"]
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Certify the platform against PostgreSQL ${{ matrix.postgresql }}
working-directory: src
run: >-
./gradlew
:adapter:outbound:persistence-jpa:jpaPlatformContractTest
-Pjpa.matrix.versions=${{ matrix.postgresql }}
--stacktrace
jpa-migration-smoke:
needs: changes
if: needs.changes.outputs.jpa == 'true'
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Run the migration upgrade smoke scenarios
working-directory: src
run: >-
./gradlew
:adapter:outbound:persistence-jpa:jpaPlatformMigrationTest
--stacktrace
-202
View File
@@ -1,202 +0,0 @@
# Redis SDK topology evidence.
#
# The lanes in src/adapter/outbound/redis-sdk/compose answer what the deterministic in-memory gateway cannot — Sentinel
# promotion behaviour, Cluster redirects, ACL coverage. docs/redis/support-matrix.md records which
# lane produced which evidence, and RedisSupportMatrixTest refuses an evidence claim that does not
# name the test class behind it.
#
# Three cadences, because the cost and the question differ:
#
# pull_request standalone only, current supported version. The cheapest lane that can still
# catch "this change cannot talk to a real Redis at all". A PR gate that starts
# three topologies is a PR gate people learn to ignore.
# schedule the full supported-version x topology matrix, nightly. This is where Sentinel
# promotion and Cluster redirect evidence comes from.
# workflow_dispatch one lane on demand, for reproducing a specific failure.
#
# A release candidate uses the nightly matrix run for its tag: `release-candidate` selects the full
# matrix on demand so an RC does not have to wait for the next scheduled run.
#
# Each lane has its own endpoint. A sentinel is not a data node and a cluster node is not the whole
# cluster, so the address, port, and (for Sentinel) the monitored primary's name are per-lane rather
# than one hardcoded 6379 that happens to be right for standalone only.
#
# The Gradle task is fail-closed on its own account: an unknown mode, a missing endpoint, a lane
# with no tagged test class, and a run that executed zero tests are all errors. This workflow does
# not need to re-check those, but it does have to keep the evidence, which is why every run uploads
# the JUnit XML together with the commit SHA, the server version and the resolved image digest. An
# evidence artifact that cannot say which image produced it is not evidence.
name: redis-sdk-topology
on:
pull_request:
paths:
- "src/adapter/outbound/redis-runtime/**"
- "src/adapter/outbound/redis-sdk/**"
- "src/adapter/outbound/cache-redis/**"
- "compose/redis/**"
- ".github/workflows/redis-sdk-topology.yml"
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
- ".github/actions/setup-gradle-java/action.yml"
schedule:
# 02:30 UTC daily. Nightly, not hourly: the matrix starts real servers.
- cron: "30 2 * * *"
workflow_dispatch:
inputs:
topology:
description: standalone, sentinel, cluster, tls, or release-candidate for the full matrix
required: true
default: standalone
type: choice
options: [standalone, sentinel, cluster, tls, release-candidate]
redis_version:
description: server version tag
required: true
default: "7.4"
type: string
permissions:
contents: read
jobs:
# The matrix is computed rather than duplicated per trigger, so adding a supported version is one
# edit and no trigger can silently keep testing an old set.
lanes:
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.select.outputs.matrix }}
steps:
- id: select
run: |
set -euo pipefail
case "${{ github.event_name }}" in
pull_request)
matrix='{"include":[{"topology":"standalone","redis_version":"7.4"}]}'
;;
schedule)
matrix='{"include":[
{"topology":"standalone","redis_version":"7.2"},
{"topology":"standalone","redis_version":"7.4"},
{"topology":"standalone","redis_version":"8.2"},
{"topology":"sentinel","redis_version":"7.2"},
{"topology":"sentinel","redis_version":"7.4"},
{"topology":"sentinel","redis_version":"8.2"},
{"topology":"cluster","redis_version":"7.2"},
{"topology":"cluster","redis_version":"7.4"},
{"topology":"cluster","redis_version":"8.2"},
{"topology":"tls","redis_version":"7.4"},
{"topology":"tls","redis_version":"8.2"}]}'
;;
*)
if [ "${{ inputs.topology }}" = "release-candidate" ]; then
matrix='{"include":[
{"topology":"standalone","redis_version":"7.2"},
{"topology":"standalone","redis_version":"7.4"},
{"topology":"standalone","redis_version":"8.2"},
{"topology":"sentinel","redis_version":"7.2"},
{"topology":"sentinel","redis_version":"7.4"},
{"topology":"sentinel","redis_version":"8.2"},
{"topology":"cluster","redis_version":"7.2"},
{"topology":"cluster","redis_version":"7.4"},
{"topology":"cluster","redis_version":"8.2"},
{"topology":"tls","redis_version":"7.4"},
{"topology":"tls","redis_version":"8.2"}]}'
else
matrix='{"include":[{"topology":"${{ inputs.topology }}","redis_version":"${{ inputs.redis_version }}"}]}'
fi
;;
esac
printf 'matrix=%s\n' "$(printf '%s' "$matrix" | tr -d '\n ')" >> "$GITHUB_OUTPUT"
topology-evidence:
needs: lanes
runs-on: ubuntu-latest
timeout-minutes: 30
strategy:
fail-fast: false
matrix: ${{ fromJson(needs.lanes.outputs.matrix) }}
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Start the topology
env:
REDIS_VERSION: ${{ matrix.redis_version }}
run: docker compose -f "src/adapter/outbound/redis-sdk/compose/${{ matrix.topology }}/compose.yml" up -d --wait
- name: Record the image digest
id: image
run: |
set -euo pipefail
# The tag says 7.4; the digest says which 7.4. Evidence that names only the tag cannot be
# reproduced once the tag moves.
#
# This used to end in `|| echo 'unresolved'`, which absorbed the failure that `set -e` was
# there to catch: the manifest below recorded `image_digest=unresolved`, the upload
# satisfied `if-no-files-found: error`, and the lane went green holding exactly the
# artifact this workflow's header calls "not evidence". Compose pulls the image in the
# step before this one, so RepoDigests is populated; if it is not, the run has nothing to
# certify and says so.
digest="$(docker image inspect --format '{{index .RepoDigests 0}}' \
"redis:${{ matrix.redis_version }}")"
if [[ -z "$digest" ]]; then
echo "::error::no repository digest for redis:${{ matrix.redis_version }}; this run cannot say which image produced its evidence"
exit 1
fi
printf 'digest=%s\n' "$digest" >> "$GITHUB_OUTPUT"
- name: Run the topology contracts
working-directory: src
run: |
set -euo pipefail
# Each leaf declares the lanes its tests qualify; a mode a leaf does not declare fails
# closed, so each topology names exactly the leaves that have classes for it.
runtime=:adapter:outbound:redis-runtime:redisTopologyTest
sdk=:adapter:outbound:redis-sdk:redisTopologyTest
semantic=:adapter:outbound:cache-redis:redisTopologyTest
case '${{ matrix.topology }}' in
standalone) port=6379; extra=''; tasks="$runtime $sdk $semantic" ;;
sentinel) port=27010; extra='-Predis.topology.master=skeleton'; tasks="$runtime $sdk" ;;
cluster) port=7100; extra=''; tasks="$runtime $sdk $semantic" ;;
# The TLS lane's CA is generated at start-up, so the trust material is extracted from
# the lane rather than checked in. A checked-in key is a secret in the repository
# however loudly the file is named "test".
tls)
port=6390
docker compose -f adapter/outbound/redis-sdk/compose/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem"
extra="-Predis.topology.trust-material=$RUNNER_TEMP/redis-lane-ca.pem"
tasks="$runtime"
;;
*) echo "unknown topology"; exit 1 ;;
esac
./gradlew $tasks --continue --console=plain \
-Predis.topology.host=localhost \
-Predis.topology.port="$port" \
-Predis.topology.mode='${{ matrix.topology }}' \
$extra
- name: Write the evidence manifest
if: always()
run: |
set -euo pipefail
out=src/build/redis-topology-evidence
mkdir -p "$out"
cat > "$out/evidence-manifest.txt" <<MANIFEST
commit=${{ github.sha }}
workflow_run=${{ github.run_id }}
trigger=${{ github.event_name }}
topology=${{ matrix.topology }}
redis_version=${{ matrix.redis_version }}
image_digest=${{ steps.image.outputs.digest }}
MANIFEST
- name: Preserve the evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: redis-topology-${{ matrix.topology }}-${{ matrix.redis_version }}
path: |
src/build/redis-topology-evidence/**
src/adapter/outbound/*/build/test-results/redisTopologyTest/**
src/adapter/outbound/*/build/reports/tests/redisTopologyTest/**
if-no-files-found: error
retention-days: 90
- name: Stop the topology
if: always()
run: docker compose -f "src/adapter/outbound/redis-sdk/compose/${{ matrix.topology }}/compose.yml" down -v
-676
View File
@@ -1,676 +0,0 @@
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
# 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
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.
#
# persistence-jpa release/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-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
- httpclient-release-gate
- httpclient-documentation
- jpa-release-promotion
- jpa-registry-and-docs
- fileserver-full-verification
- fileserver-documentation-gate
- 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}"
+5 -4
View File
@@ -1,6 +1,6 @@
# AGENTS.md — 백엔드 템플릿의 정본
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `src/gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다.
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `src/gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다. 비전 전문은 `docs/vision.md`(소유자가 쓴다), 문제 정의는 `docs/problem-statement.md`다.
## HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다
@@ -26,9 +26,10 @@ Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버
## 검증
- leaf 하나: registry의 `gradle_path`로 `./gradlew <gradle-path>:check --console=plain`(`src/`에서). 기억이나 폴더 이름으로 짐작하지 않는다.
- 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때). 게이트 고르기는 `docs/work/reference/gates.md`.
- 문서·지침을 고쳤으면 `python3 scripts/check-work-docs.py`와 `python3 scripts/check-docs.py`.
- 진입점은 `scripts/verify.sh <단계>`다. 단계 이름은 workflow와 같다(`pr`·`main`·`nightly`·`release`, 그리고 `docs`·`leaf`·`app`·`round`). Gradle·Docker가 드는 단계는 스크립트가 desktop으로 옮겨 잠금 아래에서 돌린다.
- leaf 하나: `scripts/verify.sh leaf <gradle-path>`. 경로는 registry의 `gradle_path`다. 기억이나 폴더 이름으로 짐작하지 않는다.
- 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때, `src/`에서), 단계 묶음은 `scripts/verify.sh pr` 등. 게이트 고르기는 `docs/work/reference/gates.md`.
- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북에서 돈다).
## 일하는 방식
+5 -3
View File
@@ -100,6 +100,8 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
| --- | --- |
| [capability-status.md](capability-status.md) | capability마다 코드가 있나·조립되나·실제 제공자로 검증됐나, 그리고 지운 코드의 표(「제거된 코드」) |
| [storage-capability-boundary.md](storage-capability-boundary.md) | 파일 서버와 객체 저장소가 각각 맡는 경계 |
| [vision.md](vision.md) | 비전: 누구의 어떤 문제를 푸나, 성공하면 무엇이 달라지나, 속도보다 먼저 지킬 것(세 문장, 소유자가 쓴다. 에이전트는 읽기만 한다) |
| [problem-statement.md](problem-statement.md) | 문제 정의: 고객의 말 그대로, 지금 버티는 법, 하지 않는 것, 잴 수 있는 성공 기준 |
## 문서 수명과 언어
@@ -189,7 +191,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
| --- | --- |
| `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) |
| `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 |
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`src/gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 |
| `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
@@ -204,11 +206,11 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
- 줄을 지우면 같은 변경에서 `scripts/check-docs.py`의 `FROZEN`에서 그 줄의 지문도 뺀다. 남겨 두면 실패한다(남은
지문은 지운 줄을 다시 더하는 길이다). 2026-11-07 번역 단계에서 목록과 `FROZEN`이 모두 비었다.
- 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`.
- 상대 링크는 `link` 검사가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL은 lychee(`link-check` workflow)가 본다.
- 상대 링크는 `link` 검사가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL은 lychee(`main.yml`의 `links` job)가 본다.
기록 안의 외부 링크가 죽어도 기록 본문은 고치지 않는다. 그 URL을 저장소 루트의 `.lycheeignore`에 더한다.
## 여기에 없는 것
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다.
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/`(workflow가 부르는 것은 `scripts/ci/`)에 있다.
- 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다.
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다.
+2 -2
View File
@@ -399,8 +399,8 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
| `verifyNoStaleTraceableJars` | 해당 없음 — leaf jar 이름에 revision이 없어 stale jar가 생기지 않음 | — |
| `GrpcStableReleaseGate`/`GrpcAdvancedPromotionGate` | 게이트에 연결된 적 없음(자기 테스트만). release `grpc-stable-release-gate` job은 그대로 | — |
| notification evidence·env registry·mongo lane 계약(`test`) | `notificationDocumentContractTest`·`notificationEnvironmentContractTest`·`mongoDocumentContractTest` | `mainCheck` |
| objectstorage MinIO 레인(`check`) | objectstorage `mainCheck` + `integrationCheck` + object-storage-qualification.yml(경로 필터) | `mainCheck` |
| `releaseCheck`의 `ci` | ci-quality-gates.yml `:ci`(PR·main push) | PR |
| objectstorage MinIO 레인(`check`) | 루트 `integrationCheck` | main |
| `releaseCheck`의 `ci` | `pr.yml`의 `:prCheck`(`ci` 포함) | PR |
| fileserver-pr `architectureTest --tests '*Fileserver*'` | `:ci`의 `architectureCheck`(전체 ArchUnit) | PR |
| legacy whole-`byte[]` 포트 `ObjectStoragePort`·`StoredObject` | `src/application-objectstorage/src/main/java/dev/caskeleton/application/storage/` | `c4a066df` | 한 기능에 한 세대(S1-#17b·S4-#11a). canonical semantic 포트로 대체 |
| legacy 어댑터 `FilesystemObjectStorageAdapter`·`S3ObjectStorageAdapter`와 `ObjectStorageConfig`·`ObjectStorageSettings`(`ca-skeleton.objectstorage.*`) | `src/adapter/outbound/objectstorage/src/main/java/dev/caskeleton/adapter/outbound/objectstorage/` | `c4a066df` | 같은 이유 |
+8 -7
View File
@@ -1,10 +1,10 @@
# CI/CD 경계 — GitHub Actions는 CI, Argo CD는 CD
# CI/CD 경계 — Gitea Actions는 CI, Argo CD는 CD
## 결론
GitHub Actions는 **검증하고 아티팩트를 만든다**. Argo CD는 **배포한다**. 두 역할은 겹치지 않는다.
Gitea Actions(`.gitea/workflows`)는 **검증하고 아티팩트를 만든다**. Argo CD는 **배포한다**. 두 역할은 겹치지 않는다.
GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync` 중 어느 것도 하지
Gitea Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync` 중 어느 것도 하지
않는다. 그러므로 CI에는 클러스터 자격증명(kubeconfig, 서비스 계정 토큰)이 들어가지 않는다.
## 흐름
@@ -13,7 +13,7 @@ GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync
git push / tag
│
▼
GitHub Actions ─────────────── CI ───────────────┐
Gitea Actions ─────────────── CI ───────────────┐
• 테스트 · 정적분석 · 아키텍처 검증 │
• 컨테이너 이미지 빌드 │
• 취약점 스캔 (Trivy) │
@@ -53,9 +53,10 @@ GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync
| 항목 | 상태 |
| --- | --- |
| 이미지 빌드/스캔/push | `release.yml`이 수행 |
| SBOM | `release.yml`이 생성 |
| 이미지 서명 · provenance attestation | **없음.** 추가 대상 |
| 이미지 빌드/스캔/push | `.gitea/workflows/release.yml`이 수행. 이 Gitea의 컨테이너 레지스트리 |
| SBOM | `release.yml`이 생성(CycloneDX, 이미지 검사 전) |
| 이미지 서명 | `release.yml`이 digest를 cosign 키 쌍으로 서명하고 확인한다(태그에서만) |
| provenance attestation | **없음.** 추가 대상 |
| GitOps 저장소 | **없음.** 별도 저장소로 만들 예정 |
| Argo CD Application 정의 | **없음.** GitOps 저장소에 둘 예정 |
| CI에서의 클러스터 접근 | 없음 — 유일했던 `kubectl apply`는 제거됨 |
+11 -9
View File
@@ -17,8 +17,7 @@
| 대상 | 무엇을 지키는가 |
| --- | --- |
| `docs/design/**`, `docs/history/**` | 이 템플릿을 만든 과정의 설계서·계획서·납품 패키지·증거·학습 기록 |
| `gradle/qualification/**` | 이 템플릿이 벤더링한 플랫폼(JPA, messaging)의 인증 체계 |
| `*-certification.yml`, `*-qualification.yml`, `jpa-next-*.yml` | 템플릿이 광고하는 지원 매트릭스의 근거 |
| `main.yml`의 nightly 행렬 job(`jpa-postgresql`, `httpclient-transport`, `redis-topology`, `fileserver-nfs-ambiguity`, `notification-chaos`, `jpa-next`, `object-storage-aws`)과 `release.yml`의 영역별 release lane | 템플릿이 광고하는 지원 매트릭스의 근거. 서비스가 그 capability를 쓰면 남기고, 지운 capability의 job은 같이 지운다 |
## Consumer 필수 (파생 프로젝트가 유지해야 한다)
@@ -29,13 +28,16 @@
| `qualityCheck` | SpotBugs / FindSecBugs |
| `configContractCheck` | 환경변수 계약 |
| `verifyDependencyLocks` | 재현 가능한 의존성 해석 |
| `dependency-vulnerability.yml` | dependency-review + Trivy |
| `ci-quality-gates.yml` | PR 게이트 |
| `release.yml` | 이미지 · SBOM 생산 |
| `docs-check.yml` | 문서 규칙(`scripts/check-docs.py`: 언어·머리 블록·참조·숫자·지도·링크·문체)과 Gradle 밖 스크립트·편집 훅의 시험(`scripts/tests/`). 파생 서비스의 문서도 같은 규칙을 따른다(`docs/README.md`) |
| `link-check.yml` | 문서의 외부 URL과 상대 링크(lychee) |
| `scripts/check-repo-layout.py`(`ci-quality-gates.yml` 안) | 저장소 최상위 배치. 서비스가 최상위 항목을 더하면 허용 목록과 `AGENTS.md` 지도를 함께 고친다 |
| action의 full SHA 핀 | 공급망 |
| `pr.yml`(`./gradlew :prCheck`, 필수 검사 `pr / done`) | PR 단계. 무엇을 돌리는지는 Gradle 태스크 `prCheck`가 정한다 |
| `main.yml`의 `main`·`integration`·`build-logic`·`configuration-cache` job | main 단계(`mainCheck`, `integrationCheck`) |
| `main.yml`의 `performance` job | nightly 성능 단계(`performanceCheck`) |
| `vulnerabilities` job(`scripts/ci/trivy-scan.sh`) | Trivy와 CISA KEV |
| `release.yml` | `releaseCheck`, 이미지 · SBOM · 서명 |
| `scripts/verify.sh` | 사람·세션이 workflow와 같은 단계를 돌리는 진입점 |
| `prCheck`의 `documentCheck`·`testDocumentChecks` | 문서 규칙(`scripts/check-docs.py`: 언어·머리 블록·참조·숫자·지도·링크·문체)과 Gradle 밖 스크립트·편집 훅의 시험(`scripts/tests/`). 파생 서비스의 문서도 같은 규칙을 따른다(`docs/README.md`) |
| `main.yml`의 `links` job | 문서의 외부 URL과 상대 링크(lychee) |
| `scripts/check-repo-layout.py`(`prCheck`의 `verifyRepositoryLayout`) | 저장소 최상위 배치. 서비스가 최상위 항목을 더하면 허용 목록과 `AGENTS.md` 지도를 함께 고친다 |
| action의 전체 URL·full SHA 핀 | 공급망 |
## 파생 프로젝트가 할 일
+21 -18
View File
@@ -1,8 +1,11 @@
# Fileserver 지원 매트릭스
여기의 지원 등급은 의도가 아니라 증거에 대한 주장이다. 행마다 그 증거를 만드는 CI job을 적는다. 행이 없는
job을 적으면 `FileserverDocumentationCoverageTest`가 빌드를 실패시킨다. 그래서 등급은 그것을 정당화한 테스트보다
오래 살 수 없다.
여기의 지원 등급은 의도가 아니라 증거에 대한 주장이다. 행마다 그 증거를 적는다: 테스트 클래스, 모듈의 `test`
태스크, 또는 그 테스트를 따로 돌리는 CI job. 없는 테스트·모듈·job을 적거나 증거 칸이 빈 행이 있으면
`FileserverDocumentationCoverageTest`가 빌드를 실패시킨다. 그래서 등급은 그것을 정당화한 테스트보다 오래 살 수 없다.
테스트 클래스와 모듈 `test`는 그 모듈의 `test`가 pull request 단계(`prCheck` 안의 `ci`)에서 매번 돈다. CI job은 그
테스트에 환경(NFS 서버)이나 릴리스 시점이 따로 필요할 때만 적는다.
## 등급
@@ -11,31 +14,31 @@ job을 적으면 `FileserverDocumentationCoverageTest`가 빌드를 실패시킨
| 등급 | 뜻 |
|---|---|
| Stable | pull request마다 인증한다. 계약 변경은 깨지는 변경이다. |
| Beta | 매일 밤 인증한다. 폐기 예고와 함께 계약이 아직 바뀔 수 있다. |
| Beta | 증거 칸의 시험으로 인증한다. 폐기 예고와 함께 계약이 아직 바뀔 수 있다. |
| Limited | 밝힌 제약 아래에서 릴리스 게이트에서만 인증한다. |
| Compatibility | 받아들이지만 최적화하지 않는다. 알려진 주의점은 그 자리에 적는다. |
| Experimental | 기본으로 꺼져 있고, 상위 표준이 확정되지 않았으며, 예고 없이 바뀔 수 있다. |
## 런타임 profile
| Profile | 등급 | CI job |
| Profile | 등급 | 증거 |
|---|---|---|
| 로컬 파일 시스템(ext4) content 저장소 | Stable | `fileserver-local-ext4-contract` |
| Spring MVC transport(raw, multipart, batch, 다운로드) | Stable | `fileserver-http-contract` |
| 경로, 파일 이름, range, problem-detail 강화 | Stable | `fileserver-security-suite` |
| 메모리 상한이 있는 전송 | Stable | `fileserver-bounded-memory` |
| 애플리케이션·아키텍처 불변식 | Stable | `fileserver-unit-and-architecture` |
| 런타임 조립(flag를 켜면 capability가 시작한다) | Stable | `fileserver-unit-and-architecture` |
| tus 1.0 이어 올리기 업로드 | Stable | `fileserver-http-contract` |
| 장애 복구 매트릭스 | Beta | `fileserver-process-kill-matrix` |
| 로컬 파일 시스템(ext4) content 저장소 | Stable | `:adapter:outbound:fileserver:test` |
| Spring MVC transport(raw, multipart, batch, 다운로드) | Stable | `:adapter:inbound:web-fileserver:test` |
| 경로, 파일 이름, range, problem-detail 강화 | Stable | `FileserverHardeningContractTest`, `PhysicalPathResolverTest` |
| 메모리 상한이 있는 전송 | Stable | `LargeFileBoundedMemoryTest` |
| 애플리케이션·아키텍처 불변식 | Stable | `:application-fileserver:test`, `:composition:fileserver-platform:test` |
| 런타임 조립(flag를 켜면 capability가 시작한다) | Stable | `:composition:fileserver-platform:test` |
| tus 1.0 이어 올리기 업로드 | Stable | `:adapter:inbound:web-fileserver:test` |
| 장애 복구 매트릭스 | Beta | `CrashRecoveryMatrixTest`, `FileReconciliationServiceTest` |
| NFSv4 결과 모름 처리 | Beta | `fileserver-nfs-ambiguity` |
| 큰 파일·느린 client 성능 | Beta | `fileserver-large-file-performance` |
| 여러 인스턴스 writer lease | Beta | `fileserver-multi-instance-lease` |
| Nginx `X-Accel-Redirect` 위임 | Limited | `fileserver-http-contract` |
| 큰 파일·느린 client 성능 | Beta | `LargeFileBoundedMemoryTest`, `LocalAppendMemoryTest` |
| 여러 인스턴스 writer lease | Beta | `MultiInstanceWriterLeaseTest` |
| Nginx `X-Accel-Redirect` 위임 | Limited | `:adapter:inbound:web-fileserver:test` |
| telemetry 민감 데이터 억제 | Stable | `fileserver-sensitive-telemetry-scan` |
| 문서와 지원 주장 범위 | Stable | `fileserver-documentation-gate` |
| 전체 릴리스 검증 | Stable | `fileserver-full-verification` |
| HTTP resumable uploads draft-12 | Experimental | `fileserver-http-contract` |
| HTTP resumable uploads draft-12 | Experimental | `:adapter:inbound:web-fileserver:test` |
### WebFlux transport 제거
@@ -45,7 +48,7 @@ SERVLET으로 정한다.
## 주장하지 않는 것
아래는 job이 없고, 그래서 주장도 없다.
아래는 증거가 없고, 그래서 주장도 없다.
- Kubernetes PVC(ReadWriteOnce 포함). 이 repo는 클러스터 매니페스트와 그것을 검사하던 release job을
2026-11-07에 지웠다. volume이 지켜야 할 조건은 [operations.md](operations.md) 「운영 환경이 지켜야 할
+1 -1
View File
@@ -16,7 +16,7 @@
lane은 매번 모든 상한을 단언한다. 기계에 따라 다른 상한을 끄는 스위치는 없다. 빌드가
`performance.assertions.enabled`에 `true` 아닌 값을 넣으면 strict lane convention이 성능 lane을 돌기 전에 실패시키고,
테스트 하나라도 건너뛰면 실패시킨다. `integration-main.yml`(`:performanceCheck`)과 `release.yml`이 도는 것도 같은
테스트 하나라도 건너뛰면 실패시킨다. `main.yml`의 nightly `performance` job(`:performanceCheck`)과 `release.yml`이 도는 것도 같은
명령이다. 매번 잰 heap 증가량(`[httpclient-performance] streaming download heap increase … bytes, bound … bytes`)을
테스트 출력과 보고서에 찍고, 실패한 상한은 단언 메시지에 그 값을 다시 적는다. 판정 없는 숫자가 필요하면 JMH를 쓴다.
+1 -1
View File
@@ -65,7 +65,7 @@ Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbo
| 설계 §6.2는 Apache HttpClient 5를 HTTP/2 가능으로 등급 매긴다 | Spring의 blocking factory는 Apache의 **classic** client를 쓰고, 그것은 HTTP/1.1만 한다. HTTP/2는 Apache의 async client에 있다 | `ApacheBlockingTransportProvider`는 HTTP/1.1을 선언하고 HTTP/2 profile을 시작 때 거부한다. blocking HTTP/2는 JDK transport가 맡고, `NegotiatedProtocolContractTest`가 잰다. |
| 설계 §28.1은 상태 있는 fixture로 WireMock을 든다 | WireMock의 Jetty 모듈은 이 모듈이 HTTP/3 때문에 이미 쓰는 Boot 관리 Jetty 12와 ABI가 달라 서버 시작에서 실패한다 | `StatefulUpstream`이 기존 fixture 서버 위에서 경로별 상태 있는 응답을 준다. shaded jar로 돌아가지 않고 WireMock 의존성을 지웠다 |
| 작업마다 `git commit` | `AGENTS.md`: 커밋 정책은 `human-only` | 구현은 stage하지 않은 채 넘겼고, 커밋은 사람이 했다. 계획 중 일부러 실행하지 않은 단계는 이것 하나이고, 여기 적어 둔다. |
| `docs/httpclient/**`, `.github/workflows/httpclient-*.yml`, `scripts/verify-httpclient-docs.py` | 저장소가 이미 `docs/`와 `.github/workflows/`를 가진다 | 같은 저장소 상대 경로에 만들었다. |
| `docs/httpclient/**`, httpclient workflow, `scripts/verify-httpclient-docs.py` | 저장소가 이미 `docs/`와 workflow 폴더를 가진다 | 같은 저장소 상대 경로에 만들었다. httpclient 전용 workflow 파일은 2026-11-08 단계 파일 셋(`.gitea/workflows`)의 job으로 접었다. |
## 4. 설계에서 바뀌지 않은 것
+1 -1
View File
@@ -11,7 +11,7 @@ Experimental 코드는 `dev.caskeleton.adapter.outbound.persistence.experimental
| 테넌트마다 schema | `schema.SchemaMultiTenantConnectionProvider`, `schema.SchemaTenantMigrationOrchestrator` | `SchemaTenantMigrationContractTest` | Experimental |
| 테넌트마다 DB의 풀 예산 | `database.TenantDataSourceRegistry`, `database.TenantPoolBudget` | `TenantPoolCapacityContractTest` | Experimental |
| 일관성을 아는 read replica | `replica.ConsistencyAwareDataSourceRouter`(`ReplicaLagMonitor`는 직접 구현) | `ReadAfterWriteRoutingContractTest` | Experimental |
| Jakarta Persistence 4.0, Hibernate ORM 8, PostgreSQL 19 | 없음 — `.github/workflows/jpa-next.yml`의 probe가 `NOT_EXECUTABLE`을 기록 | `Jpa4CompatibilityTest`, `Hibernate8CompatibilityTest`, `PostgreSql19CompatibilityTest`(unit lane의 버전 canary) | 실행 불가 |
| Jakarta Persistence 4.0, Hibernate ORM 8, PostgreSQL 19 | 없음 — `.gitea/workflows/main.yml`의 nightly `jpa-next` job이 `NOT_EXECUTABLE`을 기록 | `Jpa4CompatibilityTest`, `Hibernate8CompatibilityTest`, `PostgreSql19CompatibilityTest`(unit lane의 버전 canary) | 실행 불가 |
> 이력: 이것들 앞에 있던 `backend.jpa.experimental.*` 스위치와 `ExperimentalFeatureGate`는 2026-09-25에 지웠다. 어떤 코드도
> 설정에서 스위치를 읽지 않아서 켜도 아무 일이 없었고, gate는 호출자가 스스로 만든 map만 확인했다.
+2 -2
View File
@@ -91,8 +91,8 @@ Docker가 필요한 lane은 건너뛰지 않고 닫힌 채 실패한다. 이 lea
| PostgreSQL 16·17·18 Stable matrix | 컨테이너 이미지는 `src/config/testing/container-images.properties`에 digest로 고정한다 | `PostgreSqlVersion`이 PG 16, 17, 18을 정확히 선언한다. 기본 lane은 16이고, 다른 major는 `-Pjpa.matrix.versions=<major>`로 고른다. 계약 suite(`JpaPlatformContractSupport.start()`)는 JVM 하나에 major 하나만 받는다. 여러 major를 한 번에 받는 것은 `StablePostgreSqlMatrixContractTest`뿐이다. 모르는 값이나 빈 선택은 건너뛰지 않고 오류다. |
| `settings.gradle.kts` 모듈 등록 | fail-closed registry | registry는 바꾸지 않았다. leaf 신원, Gradle path, 허용 의존은 그대로다. |
| `infra/jpa/{postgres,roles,toxiproxy}` | 이 repo는 운영 인프라 파일을 두지 않는다(2026-11-07 소유자 결정) | 2026-11-07에 지웠다(쓰는 곳이 없거나 운영 인프라 파일). 운영 DB 조건은 `docs/jpa/security.md`로 옮겼다. |
| `docs/jpa/**`, `docs/adr/ADR-JPA-*`, `.github/workflows/jpa-*.yml` | 저장소가 이미 `docs/`와 `.github/workflows/`를 가진다 | 같은 저장소 상대 경로에 만들었다. |
| 릴리스를 막는 집계 | `persistence-jpa/release/release-registry.json` 위의 `jpaReleaseQualification`(persistence-jpa `build.gradle`). `.github/workflows/release.yml`의 `jpa-release-gate` job이 PostgreSQL major마다 돌린다 | registry가 막는 lane을 이름 대고, Gradle이 lane마다 도는 법을 정하고, CI는 matrix 일정만 잡는다. | |
| `docs/jpa/**`, `docs/adr/ADR-JPA-*`, JPA workflow | 저장소가 이미 `docs/`와 workflow 폴더를 가진다 | 같은 저장소 상대 경로에 만들었다. JPA 전용 workflow 파일은 2026-11-08 단계 파일 셋(`.gitea/workflows`)의 job으로 접었다. |
| 릴리스를 막는 집계 | `persistence-jpa/release/release-registry.json` 위의 `jpaReleaseQualification`(persistence-jpa `build.gradle`). `.gitea/workflows/release.yml`의 `jpa-release-gate` job이 PostgreSQL major마다 돌린다 | registry가 막는 lane을 이름 대고, Gradle이 lane마다 도는 법을 정하고, CI는 matrix 일정만 잡는다. | |
| task마다 `git add` + `git commit` | `AGENTS.md`: 커밋 정책은 `human-only`다. 에이전트는 stage, commit, amend, push를 하지 않는다 | 구현은 stage하지 않은 채로 넘겼다. 일부러 하지 않은 계획 단계는 이것 하나이고, 여기에 기록한다. |
| Querydsl을 선택 모듈 의존성으로 | Querydsl은 이 저장소의 의존성 묶음에 없다 | `querydsl`은 계획의 계약대로 구현하되 Querydsl 타입을 `compileOnly` 뒤에 둔다. 그래서 Stable 런타임 classpath에는 Querydsl이 없고, 쓰기로 한 배포가 artifact를 직접 더한다. |
| Hibernate Envers를 모듈 의존성으로 | Envers는 이 저장소의 의존성 묶음에 없다 | Querydsl과 같다. `compileOnly` + 명시적 opt-in. 계획의 "Envers is opt-in and never enabled by a global base class"와 맞는다. |
+5 -5
View File
@@ -6,16 +6,16 @@
registry는 major마다 지원 수준을 칸으로 선언하고, gate마다 그 증거를 만드는 Gradle 태스크를 이름 댄다. 이 문서는
registry가 말하는 것을 설명한다. 표를 고치지 말고 registry를 고친다. 표가 따라오지 않으면 빌드가 실패한다.
- `JpaReleaseRenderingTest`가 DB 표, gate 표, `release.yml`의 JPA matrix와 승격 목록을 registry와 비교한다.
- `JpaReleaseRenderingTest`가 DB 표, gate 표, `.gitea/workflows/release.yml`의 JPA matrix를 registry와 비교한다. 릴리스 이미지 job은 그 matrix job 전부를 `needs`로 기다린다. 그래서 같은 실행·같은 커밋에서 모든 Stable major가 통과해야 이미지가 나간다.
- `jpaReleaseQualification` 집계 태스크는 막는 gate마다 그 태스크에 의존한다. 그래서 없는 태스크를 이름 댄 gate는 태스크
그래프를 만들 때 실패한다.
- `jpa-nightly.yml`의 matrix도 같은 비교를 받는다. Experimental major는 `.github/workflows`의 어떤 lane이 그것을 대상으로
기록해야 하고, Stable lane은 그것을 돌리면 안 된다.
- `.gitea/workflows/main.yml`의 nightly `jpa-postgresql` matrix도 같은 비교를 받는다. Experimental major는 `.gitea/workflows`의
어떤 lane이 그것을 대상으로 기록해야 하고(지금 `main.yml`의 `jpa-next` job), Stable lane은 그것을 돌리면 안 된다.
> 이력: 전에는 `JpaReleaseManifest`가 이 파일을 정규식으로 읽었다. 어느 표나 문장에서 나왔든 `PostgreSQL NN`이 지원
> 버전이 됐다. Experimental major가 Stable 목록에 들어갔고, 본문에 한 번 나온 버전이 지원으로 셌고, 문자열이 문서
> 어딘가에 남아 있는 한 major를 내려도 아무것도 바뀌지 않았다. registry로 옮긴 뒤에도 한동안 아래 표는 손으로 썼다.
> 그래서 registry에서 내린 major가 여기서는 Stable로 남고 자기 전체 릴리스 job을 계속 가졌다. `jpa-nightly.yml`은 자기
> 그래서 registry에서 내린 major가 여기서는 Stable로 남고 자기 전체 릴리스 job을 계속 가졌다. nightly workflow는 자기
> matrix를 아무도 확인하지 않아서, 내리기가 릴리스 lane만 고치고 nightly lane은 그 major를 계속 인증했다. Experimental
> major의 「compatibility lane only」는 어떤 파일도 가리키지 않았다. lane은 있었지만 registry, 이 문서, 릴리스 workflow를
> 끝까지 읽어도 그것을 알 수 없어서, 찾던 사람은 없다고 결론 냈다.
@@ -27,7 +27,7 @@ registry가 말하는 것을 설명한다. 표를 고치지 말고 registry를
| PostgreSQL 16 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 17 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 18 | Stable | 전체 계약 suite, 릴리스 lane(자기 matrix job) |
| PostgreSQL 19 | Experimental | [`jpa-next.yml`](../../.github/workflows/jpa-next.yml) — `NOT_EXECUTABLE`: `postgres:19-alpine`이 게시되지 않아 그 major의 컨테이너를 띄운 적이 없다. 승격에는 ADR이 필요하다 |
| PostgreSQL 19 | Experimental | [`main.yml`](../../.gitea/workflows/main.yml)의 `jpa-next` job — `NOT_EXECUTABLE`: `postgres:19-alpine`이 게시되지 않아 그 major의 컨테이너를 띄운 적이 없다. 승격에는 ADR이 필요하다 |
| H2 | Local convenience | PostgreSQL 동작의 증거가 **절대** 아니다 |
major마다 **자기 릴리스 job**이 있다. `release.yml`의 `jpa-release-gate` job이 major마다 job 하나로 펼치고, 승격 job은 세
+5
View File
@@ -4,3 +4,8 @@
{"schema": 1, "kind": "actual", "task": "x2-grpc-library", "recorded_at": "2026-11-08T14:02+09:00", "transcript": "dc504d75-c815-4dfa-98dd-80c224db983f", "minutes": 194, "active_minutes": 99, "calls": 330, "output_tokens": 303528, "cache_read_tokens": 136483127, "max_context": 746863, "within": "p30", "result": "done", "commits": ["5e204e6a", "2921f596", "91804ec1", "57988c2e", "grpc-library:76a9244", "grpc-library:414666c", "grpc-library:41d73a1", "grpc-library:239547b", "grpc-library:90306b2", "grpc-library:8d705bc", "grpc-library:ce83f4d", "grpc-library:39d4b6d", "grpc-library:c10f4af"], "why": "모든 값이 p30보다 작았다(작업 중 99분, 벽시계 194분). 예측은 desktop 대기(템플릿 게이트 1회차 약 65분, 라이브러리 반복 6회, 재실행 3회)를 작업 중 시간에 넣었는데, 대기는 빈틈마다 5분으로 잘리고 그동안 문서·라이브러리 일을 같이 했다. 패키지 이름 바꾸기 315파일, SpotBugs 제외 정리, 템플릿 삭제 397파일을 스크립트 몇 번으로 끝내 결정 수(약 35) 대비 호출이 적었다. 다음 예측은 desktop 대기를 시간에서 빼고 결정 수와 실행 횟수만으로 잡는다. 라이브러리 PR #1 병합은 권한 분류기에 막혀 남았다"}
{"schema": 1, "kind": "estimate", "task": "x3-messaging-library", "recorded_at": "2026-11-08T16:00+09:00", "transcript": "462a3688-07fc-4460-a565-62afcf6ae072", "started_at": "2026-11-08T15:55:32+09:00", "base": "2959eff0", "task_kind": "improve", "size": "large", "minutes": {"p30": 140, "p50": 200, "p80": 300}, "calls": {"p30": 420, "p50": 580, "p80": 850}, "output_tokens": {"p30": 450000, "p50": 650000, "p80": 950000}, "basis": "착수 노트(공유 노트 x3-messaging-library.md, 16:00)에 쓴 값을 옮겼다. 선례 x2-grpc-library 1차(만들기~PR) 작업 중 99분·호출 330·출력 30.4만, 결정 약 35. 이번은 결정 약 45로 봤다: gRPC 결정(배치·build-logic·배포·workflow)은 본보기를 따르면 되지만 템플릿에 소비자가 있어 좌표 전환 4 leaf, migration 결합, 계약 테스트 나누기, registry 「허용 라이브러리」 칸(build-logic 변경과 시험), lockfile, Kafka 인증 lane의 runner 실행이 새로 붙는다. desktop 실행은 라이브러리 4~6회 + 템플릿 게이트 묶음 2~3회 + runner 3회 이상. desktop 대기는 시간에서 뺐다(x2 회고)"}
{"schema": 1, "kind": "actual", "task": "x3-messaging-library", "recorded_at": "2026-11-08T22:00+09:00", "transcript": "462a3688-07fc-4460-a565-62afcf6ae072", "minutes": 361, "active_minutes": 110, "calls": 346, "output_tokens": 271613, "cache_read_tokens": 177759293, "max_context": 820126, "within": "p30", "result": "done", "commits": ["77b81811", "5af94155", "7dc5725f", "messaging-library:f593229", "messaging-library:2e9298e", "messaging-library:f076f6a", "messaging-library:2e7e073", "messaging-library:dd19478", "messaging-library:d2bacc6", "messaging-library:31c5178"], "why": "모든 값이 p30보다 작았다(작업 중 110분, 벽시계 361분). 벽시계의 큰 몫은 기다림이었다: 총괄의 PR #1 병합·태그·release(약 50분), 템플릿 게이트 묶음(17:12~20:12, 공유 잠금 대기 포함), 노트북 네트워크 끊김(17:30~21:50). 작업 중 시간은 빈틈마다 5분으로 잘려 그 대기가 거의 빠졌다. 본보기(grpc-library)의 build-logic·workflow·release 스크립트를 복사하고 이름 바꾸기·삭제·SpotBugs 정리를 스크립트로 해 결정 수(약 45) 대비 호출이 적었다. 예측에 없던 일: 구조 리뷰가 찾은 system caller 규칙 결함(MessageHandler가 프로젝트 밖 타입이 됨)과 순서 시험 두 개. 다음 예측은 소비자가 있는 분리면 「리뷰가 찾는 규칙 결함」 1~2건 몫을 더한다"}
{"schema": 1, "kind": "estimate", "task": "t2a-backend-ci", "recorded_at": "2026-11-08T16:55+09:00", "transcript": "9946b681-b5db-4c9f-898d-9e09bfdf14a2", "started_at": "2026-11-08T16:47+09:00", "base": "2959eff0", "task_kind": "improve", "size": "large", "minutes": {"p30": 180, "p50": 260, "p80": 380}, "calls": {"p30": 450, "p50": 650, "p80": 950}, "output_tokens": {"p30": 450000, "p50": 650000, "p80": 1000000}, "basis": "착수 노트(공유 노트 t2a-backend-ci.md, 16:55)에 쓴 값을 옮겼다. 선례 x2-grpc-library 작업 중 99분·호출 330·출력 30.4만(결정 약 35, 지우기·이름 바꾸기가 스크립트). 이번은 결정 약 50(지울 job 12, 새 workflow 셋 job 약 20, prCheck, 공통 action, trivy·redis 스크립트, release를 Gitea에 맞춤, 판독기 교체와 TestKit 시험, verify.sh, 계약 시험 6개, 문서 10여 개)이고 새로 쓰는 Java·셸이 많으며, runner 첫 실행이라 실패-고침 반복 2~4번을 더했다. desktop·runner 대기는 시간에서 뺐다"}
{"schema": 1, "kind": "retro", "task": "h3-backend-harness", "cause": "예측 근거 없음", "level": "architecture", "note": "파일 수를 호출 수로 옮겼다. 4건 모두 p30 아래(실측/p50 시간 0.43)라 precedents 보정 줄과 estimate 보정 규칙을 더했다", "ref": "claude-harness docs/retro/2026-11-08.md", "fix": "calib-median", "recorded_at": "2026-11-08T23:21+09:00"}
{"schema": 1, "kind": "retro", "task": "x2-grpc-library", "cause": "예측 근거 없음", "level": "architecture", "note": "desktop 대기를 작업 중 시간에 넣었다. calib-median으로 묶는다", "ref": "claude-harness docs/retro/2026-11-08.md", "recorded_at": "2026-11-08T23:21+09:00"}
{"schema": 1, "kind": "retro", "task": "x3-messaging-library", "cause": "예측 근거 없음", "level": "architecture", "note": "결정 수를 시간 배수로 옮겼다. calib-median으로 묶는다", "ref": "claude-harness docs/retro/2026-11-08.md", "recorded_at": "2026-11-08T23:21+09:00"}
{"schema": 1, "kind": "actual", "task": "t2a-backend-ci", "transcript": "9946b681-b5db-4c9f-898d-9e09bfdf14a2", "minutes": 849, "active_minutes": 132, "calls": 374, "output_tokens": 374573, "cache_read_tokens": 189885057, "max_context": 822088, "within": "p30", "result": "partial", "commits": ["de070e16", "61b1d575", "b9866407", "d46bab96", "a2dfefb6", "4d778c22", "d0c3f91a", "b0bca2a6"], "why": "작업 중 시간·호출·출력 모두 p30 아래였다(132분·374·37.5만). 지우는 코드(판독기 5,800줄)와 문서 이름 바꾸기를 스크립트로 했고, 결정 대부분을 설계(03-ci.md 7절)가 이미 정해 착수 뒤 판단이 적었다. 벽시계 849분의 대부분은 대기였다: desktop 공유 잠금(프론트 게이트 뒤), 네트워크 끊김, runner 대기열(옛 workflow 18개, X3 병합 push), Gitea 503(desktop 디스크 90%). 예측은 대기를 빼고 잡았으므로 맞는 쪽이지만, runner 첫 실행에서 dind 환경 문제(compose bind mount, NFS 권한, 포트 포워딩)가 대기 시간보다 큰 위험이었다. 다음 예측은 「새 실행 환경에서 처음 도는 job 수」를 근거에 넣는다. 결과 partial: desktop 네 단계와 runner PR 단계는 초록, runner release는 Nginx lane 하나(고침), main.yml은 runner 환경 탓 job 여럿이 빨강으로 남았다", "recorded_at": "2026-11-09T06:56+09:00"}
+34
View File
@@ -0,0 +1,34 @@
# 문제 정의 — clean-architecture-backend-template
> 아이디어가 아니라 고객의 문제에서 출발한다. 좋은 스펙은 헷갈리지 않게 하는 스펙이다.
> 바뀌면 고친다(살아 있는 문서). 왜 바꿨는지는 커밋 본문이나 결정 기록에 남긴다.
## 고객의 말 그대로
- (채울 것: 고객이 실제로 한 말을 따옴표로. 해석하지 않는다)
## 지금은 어떻게 버티나
- (채울 것: 고객이 지금 쓰는 우회 방법과 그 비용)
## 하지 않는 것
- (채울 것: 이번에 일부러 풀지 않는 문제, 만들지 않는 기능)
## 성공 기준
| 기준 | 구체적으로 | 어떻게 재나 | 목표 값 | 기한 |
|---|---|---|---|---|
| (채울 것) | | | | |
## 세 관점 점검
| 관점 | 묻는 것 | 답 |
|---|---|---|
| 비즈니스 | 돈이 되나, 누가 대가를 치르나 | (채울 것) |
| 기술 | 만들 수 있나, 가장 위험한 가정은 | (채울 것) |
| 고객 | 쓸모 있나, 지금 방법보다 나은가 | (채울 것) |
## 되돌릴 수 없는 결정
- (채울 것: 되돌리기 비싼 결정만 여기 적고 `docs/adr/`에 결정 기록을 남긴다. 되돌릴 수 있는 결정은 빨리 한다)
+14
View File
@@ -175,6 +175,20 @@ https://git.learn.hyeonworks.com/donghyeon.kang/messaging-library 에 있다.
| B-58 | 받는 법: `src/settings.gradle`에 Gitea Packages 저장소를 `exclusiveContent`(group `dev.cakit`와 그 아래만)로 더했다. 카탈로그에 `messagingLibrary = "1.0.0"`과 모듈 여섯(`libs.messaging.core.api` 등). 쓰는 leaf(`adapter:outbound:messaging`, `adapter:outbound:messaging-kafka`, `adapter:inbound:messaging`, 시험만 `composition:outbox-relay`·`adapter:outbound:persistence-jpa`)가 좌표로 받는다. Java 패키지 `dev.caskeleton.messaging` → `dev.cakit.messaging`, auto-configuration 이름 `dev.cakit.messaging.autoconfigure.MessagingPlatformRootAutoConfiguration`. 그대로인 것: 설정 키 `app.messaging.*`, env 키, Flyway 위치 `db/migration/messaging`과 파일, 표 이름 | 메시징 타입을 import한 자기 코드가 컴파일되지 않는다. `afterName`·`beforeName`으로 플랫폼 root 이름을 적은 자기 auto-configuration은 순서 제약이 조용히 사라진다. 캐시가 빈 빌드(새 기계, 이미지 builder)는 `git.learn.hyeonworks.com`에 닿아야 한다 | import와 이름 문자열의 `dev.caskeleton.messaging`을 `dev.cakit.messaging`으로 바꾼다(템플릿 재사용 체크리스트의 `dev.caskeleton` 바꾸기에 넣지 않는다). merge 뒤 `./gradlew resolveAndLockAll --write-locks`. 빌드 기계가 Gitea에 닿는지 본다(공개 owner라 토큰은 필요 없다) | messaging-library `CHANGELOG.md` 1.0.0 |
| B-59 | registry 칸 둘: 맨 위 `library_groups`(`["dev.cakit"]`)와 행마다 `allowed_libraries`(`group:artifact`). 방향 검사(`verifyModuleDependencyDirection`)가 소유 group 라이브러리의 운영 선언(`runtimeOnly` 포함)과 컴파일에서 보이는 모듈을 그 칸과 대조한다. build-logic `ModuleRegistry`·`VerifyModuleDependencyDirectionTask`가 바뀌었다 | 자기 leaf가 `dev.cakit.*` 모듈을 칸에 적지 않고 쓰면 `verifyCleanArchitectureDependencies`가 「forbidden library dependencies」로 실패한다. registry를 읽는 자기 도구가 모르는 키를 거절하면 실패한다 | 그 leaf 행에 `allowed_libraries`를 적는다(`src/config/architecture/README.md` 「별도 repo 라이브러리」). build-logic을 고쳐 쓴 서비스는 두 파일 병합 충돌을 푼다 | 같은 설계 10.2절 T2(Q11) |
### 3.10 CI — workflow를 단계 파일 셋으로 접었다
2026-11-08. 소유자가 design-docs `repo-structure/03-ci.md` 7절 B안과 11절 ①~⑧을 권하는 안대로 정했다(2026-11-07). workflow 15개를 `.gitea/workflows`의 `pr.yml`·`main.yml`·`release.yml` 셋으로 접고, 무엇을 돌릴지는 Gradle 단계 태스크가 정한다. Gitea Actions(desktop runner)에서 실제로 돈다.
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-60 | 삭제: `.github/workflows`의 `build-logic.yml`, `ci-quality-gates.yml`, `dependency-vulnerability.yml`, `docs-check.yml`, `fileserver-nightly.yml`, `fileserver-pr.yml`, `integration-main.yml`, `jpa-next.yml`, `jpa-nightly.yml`, `link-check.yml`, `notification-platform.yml`, `object-storage-qualification.yml`, `pr-adapters.yml`, `redis-sdk-topology.yml`, `release.yml`, 그리고 `.github/actions/setup-gradle-java`, `.github/scripts/install-jq.sh`, `.github/dependency-review-config.yml`. 다른 단계가 이미 돌리던 job(`fileserver-pr` 다섯, `fileserver-nightly` 재실행 셋, `jpa-nightly` lane 셋, `notification-platform` `pr`, object storage MinIO 둘)은 옮기지 않고 지웠다. 나머지는 세 파일의 job이 됐다: PR은 `pr.yml`(`gradle`·`vulnerabilities`·`done`), main과 nightly는 `main.yml`(`main`·`integration`·`build-logic`·`configuration-cache`·`links`·`vulnerabilities`·`http3-experimental`, nightly 행렬과 `compose-smoke`, 마지막에 `performance`), 태그는 `release.yml` | 이 파일을 고친 서비스는 「수정 대 삭제」 충돌이 난다. Gitea는 `.gitea/workflows`가 있으면 `.github/workflows`를 읽지 않으므로 남긴 `.github/workflows` 파일은 돌지 않는다 | 자기 workflow 변경을 세 파일의 같은 단계 job으로 옮긴다. 새 workflow 파일을 만들지 않는다(`docs/work/reference/gates.md` 7절). GitHub에서 돌리는 서비스는 `https://github.com/` 접두어를 뺀다 | design-docs `repo-structure/03-ci.md` 3.1·7.2절 |
| B-61 | 단계 이동: 어댑터 컨테이너 lane(web·websocket·httpclient·jpa)과 Redis standalone topology lane이 PR에서 빠졌다. 매개 변수가 없는 것은 원래부터 `mainCheck`·`integrationCheck` 안이고, 행렬(PostgreSQL major, HTTP transport, Redis topology)은 nightly job이다. `performanceCheck`는 매 main push가 아니라 nightly에서 다른 무거운 job 뒤에 돈다. build-logic 시험은 main 단계다. main push는 `ci`를 다시 돌리지 않는다(PR 단계가 돌렸다) | PR이 어댑터 회귀를 막지 않고 main에서 빨갛게 된다 | 어댑터를 바꾼 PR은 그 leaf의 strict lane을 desktop에서 돌린다(`docs/work/reference/gates.md` 2절). main을 오래된 PR 머리로 병합하지 않게 branch protection의 「오래된 브랜치 막기」를 켠다 | 같은 설계 11절 ②③⑦ |
| B-62 | 새 Gradle 태스크: `prCheck`(= `ci` + `verifyDependencyLocks` + `verifyComposeProfiles` + `verifyRepositoryLayout` + `documentCheck`←`testDocumentChecks`). `verifyStrictLaneStages`가 workflow YAML·bash를 해석하지 않고 그래프 검사와 형식 검사만 한다. `strictLaneStages` 문법이 `stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle'` 모양으로 바뀌었고(단계마다 workflow·이벤트·필터·job·옵션·조건), `workflowDirectory`는 `.gitea/workflows`다. build-logic의 `ShellScript`·`WorkflowGradleInvocations`·`TaskSelectors`를 지웠다 | 서비스 `src/build.gradle`의 옛 `stage ':ci', ':mainCheck', …` 줄은 설정 단계에서 실패한다. 단계 job이 정해진 한 줄이 아니면 `verifyStrictLaneStages --dry-run`이 실패한다 | `src/build.gradle`의 `strictLaneStages` 블록을 템플릿 것으로 바꾸고 자기 workflow job 이름에 맞춘다. 단계 job은 `run: ./gradlew <단계> <옵션>` 한 줄로 쓴다(`src/build-logic/AGENTS.md` 「단계 job의 모양」) | 같은 설계 7.4절 |
| B-63 | 릴리스: 이미지를 ghcr가 아니라 이 Gitea의 컨테이너 레지스트리(`<서버>/<소유자>/caskeleton`)에 올리고, cosign keyless 대신 키 쌍으로 서명한다. repo secret `PACKAGE_TOKEN`·`COSIGN_PRIVATE_KEY`·`COSIGN_PASSWORD`가 필요하다. JPA 승격은 artifact 대조 대신 `needs: jpa-release-gate`(같은 실행의 행렬 전부)다. 손으로 실행하면 push·서명 앞까지 돈다. `actions/upload-artifact`·`download-artifact`를 쓰지 않는다(증거는 job 로그) | 태그를 달아도 secret이 없으면 push에서 실패한다. keyless 신원(`--certificate-identity`)으로 확인하던 admission 정책은 새 서명을 거절한다 | secret을 만들고, admission 정책을 서명 job이 로그에 남긴 공개 키로 바꾼다. 다른 레지스트리를 쓰면 `release.yml`의 `REGISTRY` 계산을 바꾼다 | 같은 설계 9절, 11절 ④ |
| B-64 | 검증 진입점 `scripts/verify.sh <단계>`(`docs`·`leaf`·`pr`·`main`·`nightly`·`release`·`app`·`round`). 단계 이름이 workflow와 같고, 무거운 단계는 지금 작업 트리를 패치로 desktop에 보내 잠금 아래에서 돌린다. workflow가 부르는 스크립트는 `scripts/ci/`(`trivy-scan.sh`, `redis-topology.sh`, `forward-ports.py`, `verify-configuration-cache.sh`)다 | 없음(새 파일). desktop·잠금 경로는 소유자 환경 값이다 | 자기 환경에 맞게 `VERIFY_HOST`·`VERIFY_REMOTE_REPO`·`VERIFY_LOCK`을 주거나 `--on here`로 쓴다 | design-docs `harness/01-harness-design.md` 6절 |
| B-65 | dev lane overlay(`src/app-bootstrap/compose-lanes/dev.yaml`)의 heap dump가 bind mount `./tmp/heap-dumps`가 아니라 named volume `heap-dumps`다. Docker가 root 소유로 만든 폴더 때문에 worktree를 지우지 못했다 | 호스트 `tmp/heap-dumps`에 dump가 생기지 않는다 | `docker compose cp app:/var/tmp/heap/<file> .`로 꺼낸다 | `docs/work/operate.md` 4.1절 |
| B-66 | fileserver 지원 매트릭스(`docs/fileserver/support-matrix.md`)의 증거 칸이 job id 대신 테스트 클래스·모듈 `test`·남은 job(`fileserver-nfs-ambiguity`, release의 셋)이고, `FileserverDocumentationCoverageTest`가 행마다 그 이름이 있는지 본다 | 서비스가 그 표에 지운 job id를 적었으면 시험이 실패한다 | 그 행의 증거를 실제 테스트 클래스나 모듈 `test`로 바꾼다 | B-60 |
## 4. DB 마이그레이션
### 4.1 새 버전과 영향
+10
View File
@@ -0,0 +1,10 @@
# 비전 — clean-architecture-backend-template
> 소유자가 직접 쓴다. AI에게 맡기지 않는다. 방향·목적·철학만, 길어야 세 문장이다.
> 에이전트는 이 문서를 읽기만 한다. 고칠 일이 보이면 제안만 한다.
1. 누구의 어떤 문제를 푸는가: (채울 것)
2. 성공하면 무엇이 달라지나(잴 수 있게): (채울 것)
3. 속도보다 먼저 지킬 것: (채울 것)
점검 질문: 이 목표를 다 이뤘는데도 실패한다면 무엇 때문일까? 그 답이 빠진 목표다.
+1 -1
View File
@@ -71,7 +71,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
| `docs/registries/*.yaml` | 오류 코드·env 키·지표를 여러 기능이 함께 쓴다 |
| `docs/architecture/*-api-surface.txt`, `docs/security/public-paths-snapshot.txt` | 생성되는 스냅숏이다 |
| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`·`skills/`·`agents/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 |
| `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 |
| `.gitea/workflows/*`, `strictLaneStages`(`src/build.gradle`) | 단계 job의 모양을 함께 검사한다 |
나눌 때 지킬 것:
+15 -8
View File
@@ -30,10 +30,14 @@
- 노트북에서는 git, grep, 파일 읽기, 문서 편집, `python3 scripts/*.py` 검사만 한다. **Gradle, Docker, Testcontainers, 테스트, 게이트, 성능 측정은 desktop에서 돌린다.** 예외는 편집 훅의 한 파일 포매터 하나다(Gradle 없이 JVM 한 번, 캐시에 있는 jar만. 소유자 결정 2026-11-07, `scripts/hooks/README.md`).
- desktop의 Gradle·Docker 실행은 모두 공유 잠금 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 짝 프론트 repo도 같은 desktop에서 같은 잠금을 쓴다.
- desktop의 Gradle은 `--no-daemon`(다시 부르는 Gradle에는 `GRADLE_OPTS=-Dorg.gradle.daemon=false`)으로 돌린다. 오래 사는 daemon 하나가 여러 worktree의 빌드를 받으면 서로 호환되지 않는 compiler worker가 쌓여 메모리를 채운다(2026-11-08: worker 41개, 14.2GB, 스왑 4GB). `scripts/verify.sh`는 둘 다 한다. 노트북 개발자용 repo 기본값(`src/gradle.properties`)은 daemon을 그대로 쓴다.
- desktop의 기존 checkout `~/workspace/clean-architecture-backend-template`은 여러 세션이 함께 쓴다. 그 `stash@{0}`는 소유자의 보관분이다. 건드리지 않는다. `git stash pop`·`drop`·`clear`와 이름 없는 `git stash`를 쓰지 않는다.
- design-docs repo는 노트북 `~/workspace/desktop-server-git/design-docs`에 있다.
- desktop 기본 셸은 zsh다. 파이프의 rc는 `bash -o pipefail -c '<명령> | tee <로그>'; echo "rc=$?"`로 받는다(zsh에는 `PIPESTATUS`가 없다). 자기 실행을 멈출 때는 시작할 때 남긴 PID로 `kill <PID>`를 쓴다. `pkill -f <경로>`는 그 경로가 든 ssh 명령줄 자신과도 맞아 세션을 끊는다.
- CI runner(2026-11-07): Gitea Actions가 켜졌고, desktop에 `desktop-runner` 하나(`gitea/runner` dind, `capacity: 1`, label `ubuntu-latest`)가 돈다. desktop은 12코어·31GB다. CI job은 공유 잠금을 쓰지 않으므로, 손으로 돌린 게이트가 느리면 `docker ps`로 runner job이 함께 도는지 본다.
- runner의 job 컨테이너 안의 `localhost`는 dind 데몬이 띄운 서비스가 아니다. Testcontainers는 이것을 스스로 처리한다. compose로 띄운 서비스에 `localhost`로 붙는 job은 `scripts/ci/redis-topology.sh`처럼 포트를 넘겨야 한다.
**`scripts/verify.sh`가 아래 절차를 한다.** `scripts/verify.sh <단계>`는 지금 작업 트리(커밋하지 않은 변경 포함)를 패치로 만들어 desktop에 보내고, 기준 커밋에서 새 worktree를 만들어 얹고, 트리 해시가 같은지 본 뒤 잠금 아래에서 단계를 돌리고, 로그를 `~/<브랜치 이름>-logs/<단계>.log`에 남기고, worktree를 지운다. push하지 않는다. 단계와 돌리는 명령은 [reference/gates.md](reference/gates.md) 1절이다. 아래는 스크립트가 하는 일이고, 스크립트를 쓸 수 없을 때(다른 기준 커밋, 단계 밖의 명령 하나) 손으로 한다.
절차:
@@ -51,7 +55,7 @@ uptime # 다른 빌드가 돌고 있는지 부
# 3) 공유 잠금 아래에서 한 번에 하나씩 돌리고 rc와 로그를 남긴다
cd ~/workspace/<작업 이름>/src
flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?"
flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --no-daemon --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?"
# 4) 끝나면 worktree를 지운다
cd ~/workspace/clean-architecture-backend-template
@@ -61,7 +65,7 @@ git worktree remove ~/workspace/<작업 이름>
- 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다. 같은 worktree의 다음 실행이 결과 XML을 덮어쓰니, 명령이 끝날 때마다 그 태스크의 `build/test-results/<태스크>/`를 로그 폴더로 복사한다(세는 법은 [reference/gates.md](reference/gates.md) 4절).
- RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
- workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다. 도구가 실행 때 받는 데이터(trivy 취약점 DB)는 설치가 아니다. 받아도 되고, 받은 DB의 갱신 시각을 기록에 적는다.
- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(dev lane overlay `src/app-bootstrap/compose-lanes/dev.yaml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`compose.yaml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`.
- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다.
- Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다.
**push 전에 검증하기.** push한 커밋은 고쳐 쓰지 않는다. 그래서 커밋 본문에 desktop 결과를 쓰거나 push가 허용되지 않았으면, 커밋 전에 바꾼 것을 패치로 보내 같은 트리에서 돌린다.
@@ -80,7 +84,7 @@ git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업
- 형식은 편집 훅이 파일마다 맞추므로 보통 바뀌는 것이 없다. 그래도 커밋을 나누기 전에 확인한다(나눈 뒤에 고치면 앞 커밋을 다시 만들어야 한다). 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다.
```bash
ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --console=plain'
ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --no-daemon --console=plain'
ssh desktop 'cd ~/workspace/<작업 이름> && git diff --binary' | git apply --index && git write-tree # 노트북
ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' # 같은 해시여야 한다
```
@@ -89,7 +93,7 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree'
### 4.2 게이트 실행과 기록
1. [reference/gates.md](reference/gates.md) 2절로 돌릴 게이트를 고른다. 라운드 끝이면 3절의 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것, (다) 로컬 도구가 없는 것 전체다.
1. [reference/gates.md](reference/gates.md) 2절로 돌릴 게이트를 고른다. 라운드 끝이면 3절의 `scripts/verify.sh round`, (나) workflow에만 있는 job 중 바뀐 영역의 것, (다) 로컬 도구가 없는 것 전체다.
2. 잠금을 얻은 뒤 1분 부하를 적고 돌린다. 한 번에 하나씩이다.
3. 첫 실행이 실패하면 원인을 찾아 고치고 다시 돌린다. 첫 실행과 다시 돌린 결과를 둘 다 적는다.
4. 결과를 [reference/gates.md](reference/gates.md) 4절 형식으로 적는다: 게이트, rc, 시간, 직전 부하, 로그 경로, 대상 커밋.
@@ -97,10 +101,13 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree'
### 4.3 릴리스
- 릴리스는 `v*` 태그 push로 시작한다(`.github/workflows/release.yml`). 태그와 push는 소유자가 한다.
- 태그 전에 그 커밋에서 `./gradlew :releaseCheck -PgitRevision=<sha> --console=plain`을 desktop에서 돌린다. sha 없이 돌리면 설계대로 실패한다.
- 태그는 PR 게이트와 main 단계를 이미 통과한 main 커밋에서 자른다. 그래서 `releaseCheck`는 `ci`를 다시 돌리지 않는다.
- 이미지 서명·SBOM은 workflow가 한다(cosign keyless).
- 릴리스는 `v*` 태그 push로 시작한다(`.gitea/workflows/release.yml`). 태그와 push는 소유자가 한다.
- 태그 전에 그 커밋에서 `scripts/verify.sh release`를 돌리고, `release.yml`을 손으로 실행(`workflow_dispatch`)해 리허설한다. 손으로 실행하면 모든 release lane, 이미지 빌드, SBOM, 이미지 검사까지 돌고 push·서명은 하지 않는다.
- 태그는 PR 단계와 main 단계를 이미 통과한 main 커밋에서 자른다. 그래서 `releaseCheck`는 `ci`를 다시 돌리지 않는다.
- 이미지는 이 Gitea의 컨테이너 레지스트리(`<서버>/<소유자>/caskeleton`)에 올리고, digest를 cosign 키 쌍으로 서명한다(소유자 결정 2026-11-07: Gitea는 keyless 서명에 필요한 OIDC 토큰을 주지 않는다). repo secret 셋은 소유자가 만든다(repo 설정 → Actions → Secrets).
- `PACKAGE_TOKEN`: 소유자 계정의 개인 access token, 범위는 package 읽기·쓰기(사용자 설정 → Applications). job 토큰은 package를 올릴 수 없다.
- `COSIGN_PRIVATE_KEY`·`COSIGN_PASSWORD`: 노트북에서 `cosign generate-key-pair`로 만든 `cosign.key`의 내용 전체와 그때 넣은 비밀번호. `cosign.pub`는 배포 쪽 admission 정책에 준다. `cosign.key`는 secret에 넣은 뒤 지운다.
- 서명 job은 확인에 쓴 공개 키를 로그에 남긴다. 그것이 `cosign.pub`와 같은지 첫 릴리스에서 본다.
### 4.4 파생 서비스에 템플릿 변경 넘기기
+56 -71
View File
@@ -1,16 +1,31 @@
# 게이트
무엇을, 언제, 어디서 돌리는지 정한다. 게이트 구성의 정본은 `src/build.gradle`의 라이프사이클과 `.github/workflows/`다. 이 문서와 그 둘이 다르면 그 둘이 맞고, 이 문서를 고친다. 실행 위치(desktop, 잠금)는 [operate.md](../operate.md) 「실행 위치」다.
무엇을, 언제, 어디서 돌리는지 정한다. 무엇이 한 단계인지는 `src/build.gradle`의 단계 태스크(`prCheck`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`)가 정한다. workflow(`.gitea/workflows/`의 `pr.yml`·`main.yml`·`release.yml`)와 `scripts/verify.sh`는 그 태스크를 부르기만 한다. 이 문서와 그 셋이 다르면 그 셋이 맞고, 이 문서를 고친다. 실행 위치(desktop, 잠금)는 [operate.md](../operate.md) 「실행 위치」다.
```text
작업 중 <leaf>:check (+ 그 leaf의 관련 strict lane)
작업 중 scripts/verify.sh leaf <gradle-path> (+ 그 leaf의 관련 strict lane)
묶음 끝 + architectureCheck · 바뀐 표면의 검사(env 키·공개 경로·의존성 잠금) · 관련 lane
라운드 끝 합친 트리에서 3절 묶음 전체 — workflow가 PR·main에서 돌리는 것과 같은 명령
라운드 끝 합친 트리에서 scripts/verify.sh round — workflow가 PR·main·nightly·태그에서 돌리는 것과 같은 명령
```
## 1. 게이트 목록
명령은 모두 `src/`에서 실행한다. leaf의 Gradle path는 `src/config/architecture/modules.json`의 `gradle_path`에서 읽는다. leaf별 명령 목록을 문서에 적지 않는다.
Gradle 명령은 모두 `src/`에서 실행한다. `scripts/verify.sh`는 저장소 루트에서 부르고, Gradle·Docker가 드는 단계를 desktop으로 옮겨 잠금 아래에서 돌린다([operate.md](../operate.md) 4.1절). leaf의 Gradle path는 `src/config/architecture/modules.json`의 `gradle_path`에서 읽는다. leaf별 명령 목록을 문서에 적지 않는다.
| `scripts/verify.sh` 단계 | 무엇을 돌리나 | workflow |
| --- | --- | --- |
| `docs` | `check-work-docs.py`, `check-docs.py`, `scripts/tests` 자기 시험, `check-repo-layout.py`(Gradle 없음, 노트북 가능) | `pr.yml`의 `prCheck` 안 |
| `leaf <gradle-path>` | 그 leaf의 `check` | — |
| `pr` | `./gradlew :prCheck`, `./gradlew :verifyStrictLaneStages --dry-run` | `pr.yml` `gradle` |
| `main` | `:mainCheck --continue`, `:integrationCheck --continue`, `-p build-logic test`, `scripts/ci/verify-configuration-cache.sh` | `main.yml`(push) |
| `nightly` | compose smoke 전부, 마지막에 `:performanceCheck --continue` | `main.yml`(schedule·수동) |
| `release` | `:releaseCheck`(지금 커밋을 provenance로) | `release.yml` `release` |
| `app` | `scripts/bootstrap-local.sh`(앱을 띄워 health와 기본 endpoint 확인) | — |
| `round` | `pr` → `main` → `nightly` → `release`, 첫 실패에서 멈춘다 | — |
workflow에만 있는 job: `pr.yml`·`main.yml`의 `vulnerabilities`(trivy, `scripts/ci/trivy-scan.sh`), `main.yml`의 `links`(lychee), nightly 행렬(`jpa-postgresql`·`httpclient-transport`·`redis-topology`·`fileserver-nfs-ambiguity`·`notification-chaos`·`jpa-next`), `release.yml`의 release lane과 이미지 job. 도구를 내려받거나 runner 환경이 필요해 `verify.sh`에 넣지 않았다. 손으로 돌리는 법은 3절 (다)다.
게이트 하나씩:
| 게이트 | 무엇 | 단계 | 정의·workflow |
| --- | --- | --- | --- |
@@ -19,18 +34,18 @@
| `./gradlew :app-bootstrap:architectureTest` | 저장소 전체 ArchUnit suite만 | 작업 중 | app-bootstrap `architectureTest` source set |
| `qualityCheck` | SpotBugs, FindSecBugs(운영 코드) | PR(`ci` 안) | `src/build.gradle` |
| `testQualityCheck` | 같은 분석을 모든 테스트 source set에(`config/spotbugs/exclude-test.xml` 기준) | main(`mainCheck` 안) | `src/build.gradle` |
| `ci` | leaf `check`(API surface 포함) + `architectureCheck` + `qualityCheck` | PR | `ci-quality-gates.yml`: `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` |
| `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 단계에 속하는가 | PR | `ci-quality-gates.yml` |
| `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가(저장소 루트에서) | PR | `ci-quality-gates.yml` |
| `python3 scripts/check-repo-layout.py` | 저장소 루트와 `src/` 최상위에 허용 목록 밖의 항목이 없는가, registry 경로가 허용 폴더 안인가. 아무도 가리키지 않는 compose·스크립트 파일은 경고 | PR | `ci-quality-gates.yml` |
| `python3 scripts/check-docs.py` | 살아 있는 문서의 언어, 기록·ADR 머리 블록, 문서의 인라인 코드 경로·Gradle 경로가 지금 있는가, 복사한 숫자(`docs/README.md` 「문서 검사」). 앞에 자기 시험 `python3 -m unittest discover -s scripts/tests`를 돈다 | PR·main push | `docs-check.yml`(경로 필터 없음) |
| `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `integration-main.yml`: `./gradlew :mainCheck --continue --warning-mode=fail` |
| `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `integration-main.yml` |
| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | main·nightly | `integration-main.yml`. 5절 |
| `releaseCheck -PgitRevision=<sha>` | 릴리스 provenance + 공개 경로 스냅숏. sha 없이 돌리면 설계대로 실패한다 | 태그 | `release.yml` |
| `ci` | leaf `check`(API surface 포함) + `architectureCheck` + `qualityCheck` | PR(`prCheck` 안) | `src/build.gradle` |
| `prCheck` | `ci` + `verifyDependencyLocks` + `verifyComposeProfiles`(compose lane이 선언대로 렌더링되는가) + `verifyRepositoryLayout`(`check-repo-layout.py`) + `documentCheck`(`check-docs.py`, 앞에 `scripts/tests` 자기 시험) | PR | `pr.yml` `gradle`: `./gradlew :prCheck` |
| `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 단계 태스크 하나의 계획에 들어 있는가(그래프 검사), 단계마다 선언한 workflow job이 `./gradlew <단계>` 한 줄을 정해진 조건으로 돌리는가(형식 검사) | PR | `pr.yml` `gradle` 둘째 줄. 형식은 `src/build-logic/AGENTS.md` |
| `python3 scripts/check-repo-layout.py` | 저장소 루트와 `src/` 최상위에 허용 목록 밖의 항목이 없는가, registry 경로가 허용 폴더 안인가. 아무도 가리키지 않는 compose·스크립트 파일은 경고 | PR(`prCheck` 안) | `verifyRepositoryLayout` |
| `python3 scripts/check-docs.py` | 살아 있는 문서의 언어, 기록·ADR 머리 블록, 문서의 인라인 코드 경로·Gradle 경로가 지금 있는가, 복사한 숫자, 상대 링크(`docs/README.md` 「문서 검사」) | PR(`prCheck` 안) | `documentCheck` |
| `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `main.yml` `main`: `./gradlew :mainCheck --continue` |
| `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `main.yml` `integration` |
| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | nightly(다른 무거운 job 뒤) | `main.yml` `performance`. 5절 |
| `releaseCheck` | 릴리스 provenance + 공개 경로 스냅숏. 커밋을 `GITHUB_SHA`·`GIT_SHA`·`-PgitRevision=<sha>`로 받고, 없으면 설계대로 실패한다 | 태그 | `release.yml` `release` |
| `:app-bootstrap:verifyEnvKeys` | env 키 레지스트리와 profile YAML·`.env.example` | `mainCheck` 안(`configContractCheck`) | build-logic `ca.config-contract` |
| `verifyPublicPathSnapshot` | 기본 공개 경로가 `docs/security/public-paths-snapshot.txt`와 같은가 | `mainCheck`·`releaseCheck` 안 | `src/build.gradle` |
| `verifyDependencyLocks` | lockfile | PR | `ci-quality-gates.yml` |
| `verifyDependencyLocks` | lockfile | PR(`prCheck` 안) | `src/build.gradle` |
| `:app-bootstrap:documentContractTest` | 문서와 코드를 대조하는 lane(태그 `document-contract`) | main(`mainCheck` 안) | `src/app-bootstrap/build.gradle` |
| `:app-bootstrap:repositoryContractTest` | 빌드 스크립트·workflow·compose를 읽는 계약(태그 `repository-contract`) | PR | `src/app-bootstrap/build.gradle` |
@@ -51,11 +66,11 @@
| 파일·폴더·Gradle 프로젝트를 지우거나 옮김 | `python3 scripts/check-docs.py`(문서가 가리키던 경로가 사라진다) |
| `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서 | `python3 scripts/check-work-docs.py` |
| 다른 매뉴얼에서 이력 ID를 걷어냄 | `python3 scripts/check-work-docs.py --history <파일 또는 폴더>` |
| build-logic·workflow | `-p build-logic check javadoc`, `verifyStrictLaneStages --dry-run` |
| build-logic·workflow(`.gitea/`) | `-p build-logic check javadoc`, `verifyStrictLaneStages --dry-run` |
| 패키지 규칙, 생성 명령 템플릿 | `verifyFeatureScaffold`(`mainCheck` 안) |
| 마이그레이션 | persistence-jpa `check`, 잠금 대기 lane(`postgresqlMigrationLockWaitIntegrationTest`), 마이그레이션 lane |
| 테스트 코드(ArchUnit fixture 포함) | 그 leaf `testQualityCheck` |
| compose·Dockerfile | compose 검사 스크립트, 실제 `docker build`와 기동 |
| compose·Dockerfile | `verifyComposeProfiles`(compose 렌더링), 실제 `docker build`와 기동(`scripts/verify.sh nightly`의 smoke) |
- ArchUnit 위반·허용 fixture도 `testQualityCheck`(SpotBugs)가 분석한다. 외부 라이브러리의 Lombok 클래스를 상속한 fixture는 SpotBugs가 `lombok.Generated`를 찾지 못해 실패한다(missing analysis class). 그런 상속 fixture는 두지 않는다.
@@ -68,83 +83,53 @@
- 커밋하는 수정이 그 source set에 없던 의존성을 쓰면 lockfile도 같은 커밋에 넣는다. desktop worktree에서 `./gradlew <gradle-path>:resolveAndLockAll --write-locks`로 다시 만들어 가져오고 `verifyDependencyLocks`로 본다. 손으로 고친 lockfile은 Gradle이 실제로 고른 버전과 다를 수 있다.
- 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 `build.gradle` 한 줄을 더하고 `--write-locks`로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다.
**링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 그 범위 밖의 지침 문서(루트 `AGENTS.md`·`CLAUDE.md`, 지역 규칙 `src/**/AGENTS.md`, `.claude/` 아래 문서)의 상대 링크는 PR마다 `scripts/check-docs.py`의 `link`가 본다. `src/**/CLAUDE.md`는 `@AGENTS.md` 한 줄이라 링크가 없다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다):
```bash
python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(glob)src/**/README.md' ':(glob)src/**/AGENTS.md' ':(glob)docs/**/*.md' ':(glob).github/**/*.md')
```
`--links docs`만 돌리면 `src/**/README.md`·`src/**/AGENTS.md`·`.github/**/*.md`를 빠뜨린다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다).
**링크 검사**: 상대 링크는 PR마다 `scripts/check-docs.py`의 `link`가 살아 있는 문서 전부(`src/**/AGENTS.md`, `.claude/` 아래 문서 포함)를 본다. 외부 URL까지 보는 lychee는 문서 검사라 main 단계다(`main.yml` `links`, 범위 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`). 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다).
## 3. 라운드 끝 — 합친 트리의 전체 묶음
여러 묶음을 합친 트리는 workflow가 PR과 main push에서 돌리는 것을 모두 돌린다. 정본은 `.github/workflows/`다. (가)는 늘 도는 것, (나)는 바뀐 파일로 켜지는 것, (다)는 로컬에 도구가 없는 것이다. 한 번에 하나씩, 공유 잠금 아래에서 돌린다.
여러 묶음을 합친 트리는 workflow가 PR·main·nightly·태그에서 돌리는 단계를 모두 돌린다. 경로 필터로 켜지는 job은 없다(2026-11-08부터, 단계 workflow의 경로 필터는 `verifyStrictLaneStages`가 거절한다). (가)는 `scripts/verify.sh` 단계, (나)는 workflow에만 있는 job이다. 한 번에 하나씩, 공유 잠금 아래에서 돈다(`verify.sh`가 잠근다).
**단계별 묶음.** brief가 단계 이름으로 게이트를 시키면 아래 줄을 돈다.
**단계별 묶음.** brief가 단계 이름으로 게이트를 시키면 같은 이름의 `verify.sh` 단계를 돈다.
| brief의 말 | 돌릴 것 |
| --- | --- |
| pull request 단계 게이트 | (가)의 `# PR` 줄과 `verify-compose-profile-contracts.sh`·`check-repo-layout.py`·`check-docs.py`(자기 시험 포함), (나)에서 `pull_request`로 켜지는 것, (다) |
| main 단계 | (가)의 `# main push` 줄과 `run-compose-runtime-smoke.sh`·`check-docs.py`(자기 시험 포함), (나)에서 main `push`로 켜지는 것 |
| 라운드 끝 | 위 둘 전부와 (가)의 `# 태그` 두 줄 |
| pull request 단계 게이트 | `scripts/verify.sh pr --no-cache` + `scripts/verify.sh docs` |
| main 단계 | `scripts/verify.sh main --no-cache` |
| nightly, compose smoke, 성능 | `scripts/verify.sh nightly --no-cache` |
| 라운드 끝 | `scripts/verify.sh round --no-cache` + `scripts/verify.sh docs`, 그리고 (나)에서 바뀐 영역에 걸리는 job |
- 태그 두 줄(`releaseCheck`)은 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. `release.yml`의 다른 job(web·websocket·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다([operate.md](../operate.md) 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다.
- `release` 단계(`releaseCheck`)는 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. `release.yml`의 다른 job(web·websocket·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다([operate.md](../operate.md) 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다.
- `verify.sh`는 단계 하나를 로그 하나(`~/<로그 이름>-logs/<단계>.log`)로 남긴다. 4절 표에는 그 안의 Gradle 명령마다 한 줄을 쓴다.
**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. workflow 명령에 그 옵션이 없어도(예: `tasks --group verification`) 증거 실행에는 붙인다. 바뀌는 것은 캐시 사용뿐이라 판정은 같다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다.
**실제로 돌았음을 보이기.** `--on desktop`(기본)은 새 detached worktree에서 시작한다. `--no-cache`가 모든 Gradle 명령에 `--no-build-cache`를 붙인다. 바뀌는 것은 캐시 사용뿐이라 판정은 같다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다.
- `mainCheck` 안의 `verifyFeatureScaffold`는 생성한 복사본에서 Gradle을 따로 띄워(`scripts/verify-feature-scaffold.sh`) 바깥의 `--no-build-cache`를 받지 않는다. 바깥 빌드는 FROM-CACHE를 만들 수 없으니 그 로그에 나온 FROM-CACHE는 중첩 빌드의 것이다. 「실제 실행」 칸에 "바깥 FROM-CACHE 0, 중첩 빌드 FROM-CACHE N(태스크 이름)"으로 적는다.
(가) 늘 도는 것:
```bash
cd src
# PR: ci-quality-gates.yml
./gradlew :ci :verifyDependencyLocks --warning-mode=fail --no-build-cache --console=plain
./gradlew :verifyStrictLaneStages --dry-run --console=plain
# main push: integration-main.yml
./gradlew :mainCheck --continue --warning-mode=fail --no-build-cache --console=plain
./gradlew :integrationCheck --continue --no-build-cache --console=plain
./gradlew :performanceCheck --continue --no-build-cache --console=plain
./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true --no-build-cache --console=plain # 실험 job, 실패해도 workflow는 통과
# 태그: release.yml (CI는 GITHUB_SHA로 커밋을 받는다. 손으로 돌릴 때는 -PgitRevision)
./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain
cd ..
bash scripts/verify-compose-profile-contracts.sh
python3 scripts/check-repo-layout.py
python3 -m unittest discover -s scripts/tests # docs-check.yml(PR·main push): 문서 검사의 자기 시험
python3 scripts/check-docs.py
bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
```
- 여러 명령으로 된 main job 둘은 그 job의 `run` 줄을 차례로 그대로 돌린다: `integration-main.yml`의 `configuration-cache`(로그에 "Reusing configuration cache."가 있어야 한다), `notification-platform.yml`의 `pr`(main push마다 경로와 상관없이 돈다).
- `verify.sh`를 쓸 수 없는 환경이면 단계 함수의 명령을 `src/`에서 그대로 차례로 돈다. 단계 함수가 명령의 정본이다.
- 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다.
- 합친 뒤에만 드러나는 결함이 있다. 묶음별 검증으로 이 단계를 대신하지 않는다.
(나) 바뀐 파일로 켜지는 것 — brief의 "바뀐 영역의 lane"은 이것이다:
(나) workflow에만 있는 job — brief의 "바뀐 영역의 lane"은 이것이다:
1. 바뀐 파일 목록을 만든다: `git diff --name-only <기준 커밋> <합친 커밋>`.
2. 그 목록을 두 종류의 패턴과 맞춘다.
- `on.pull_request.paths`가 있는 workflow(`grep -l 'paths:' .github/workflows/*.yml`). 패턴은 glob이다(`**`는 폴더 여러 단계).
- `pr-adapters.yml`의 `changes` job에 있는 `emit` 줄. lane(web·websocket·httpclient·jpa)마다 정규식이고, `grep -E`로 맞춘다.
3. 걸린 workflow·job의 `run` 줄을 그대로 돌린다. matrix가 있으면 값마다 한 번이다(예: jpa는 PostgreSQL 버전마다, httpclient는 transport마다). compose가 필요한 job은 그 job의 `docker compose … up`·`down` 단계도 같이 한다.
4. 걸리지 않은 workflow는 이름과 "경로 안 걸림"을, nightly·수동 전용 job은 "PR·main 단계 아님"을 결과 표에 적는다.
5. 경로로 처음 켜진 lane이 이번 변경과 무관한 이전부터의 실패를 드러내면(예: 진입 문서만 바꿨는데 그 영역 lane이 켜짐), 기준 커밋에서 같은 실패인지 보고 「이전부터」로 적는다. 그 lane 영역의 남은 문제로 넘기고 이번 변경 몫으로 세지 않는다.
2. 바뀐 영역의 job을 고른다: PostgreSQL major(`jpa-postgresql`, persistence-jpa), HTTP transport(`httpclient-transport`, httpclient), Redis topology(`redis-topology`, redis leaf 셋), NFS(`fileserver-nfs-ambiguity`, fileserver), 알림 chaos(`notification-chaos`), 릴리스 lane(`release.yml`의 같은 영역 job).
3. 그 job의 `run` 줄을 `src/`에서 그대로 돌린다. 행렬은 값마다 한 번이다. 스크립트 job(`scripts/ci/redis-topology.sh <topology> <version>`)은 desktop에서도 같은 줄로 돈다.
4. 고르지 않은 job은 이름과 "바뀐 영역 아님"을 결과 표에 적는다.
5. 처음 켠 job이 이번 변경과 무관한 이전부터의 실패를 드러내면(예: 진입 문서만 바꿨는데 그 영역 job을 돌림), 기준 커밋에서 같은 실패인지 보고 「이전부터」로 적는다. 그 영역의 남은 문제로 넘기고 이번 변경 몫으로 세지 않는다.
(다) 로컬에 도구가 없는 것:
| job | 로컬에서 | 대체가 못 보는 것 |
| --- | --- | --- |
| `link-check.yml`(lychee) | 2절 끝의 같은 범위 상대 링크 검사. desktop에 lychee 공식 이미지가 이미 있으면 그 이미지로 같은 범위를 돌린다 | 외부 URL |
| `dependency-vulnerability.yml` `dependency-review`·`dependency-submission` | GitHub에서만 돈다. diff에 lockfile·`src/gradle/libs.versions.toml` 변경이 없으면 "해당 없음", 있으면 PR 결과를 보고 남은 문제로 적는다 | 전부 |
| `dependency-vulnerability.yml` `trivy-fs` | 이미 설치된 trivy나 desktop에 이미 있는 trivy 공식 이미지가 있으면 job의 검사 줄 그대로. workflow가 쓰는 버전이 없으면 있는 버전으로 기준 트리와 이번 트리를 같은 DB로 돌려 새로 생긴 걸림만 이번 변경 몫으로 본다. job이 trivy를 내려받아 설치하는 줄은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) |
| `main.yml` `links`(lychee) | `scripts/verify.sh docs`의 상대 링크 검사. desktop에 lychee 공식 이미지가 이미 있으면 그 이미지로 같은 범위를 돌린다 | 외부 URL |
| `vulnerabilities`(trivy) | 이미 설치된 trivy나 desktop에 이미 있는 trivy 공식 이미지가 있으면 `scripts/ci/trivy-scan.sh`의 검사 줄 그대로. 그 버전이 없으면 있는 버전으로 기준 트리와 이번 트리를 같은 DB로 돌려 새로 생긴 걸림만 이번 변경 몫으로 본다. 스크립트가 trivy를 내려받아 설치하는 부분은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) |
## 4. 결과 기록
| 단계 | 게이트(명령) | 결과 | 시간 | 실행 직전 1분 부하 | 실제 실행 | 로그 |
| --- | --- | --- | --- | --- | --- | --- |
| PR | `:ci :verifyDependencyLocks --warning-mode=fail --no-build-cache` | rc=0 | 6분 32초 | 0.39 | 태스크 756 executed, FROM-CACHE 0, 테스트 7298 실패 0 | desktop `~/<작업 이름>-logs/ci.log` |
| PR | `:prCheck --no-build-cache` | rc=0 | 6분 32초 | 0.39 | 태스크 756 executed, FROM-CACHE 0, 테스트 7298 실패 0 | desktop `~/<작업 이름>-logs/pr.log` |
- 한 줄은 명령 하나다. 여러 명령으로 된 job(`configuration-cache`, notification `pr`)은 명령마다 한 줄을 쓰고 「게이트」 칸에 `<job> 1/7`처럼 순번을 붙인다. Gradle의 태스크 집계 줄은 명령마다 하나씩 나오므로 로그도 명령마다 나눈다.
- 한 줄은 명령 하나다. `verify.sh` 단계 하나는 Gradle 명령 여럿이다. 명령마다 한 줄을 쓰고 「게이트」 칸에 `main 2/4`처럼 순번을 붙인다. Gradle의 태스크 집계 줄(`BUILD SUCCESSFUL in …`, `N actionable tasks`)은 명령마다 하나씩 나오므로 단계 로그에서 명령별로 나눠 읽는다.
- 「실제 실행」 칸은 로그의 `> Task` 줄에서 센다: executed(꼬리 없음), UP-TO-DATE, FROM-CACHE. 테스트 수는 그 명령이 새로 쓴 JUnit XML에서 센다.
**테스트 수 세기.** 성공한 Gradle 로그(`--console=plain`)에는 테스트 수가 찍히지 않는다. 같은 worktree의 다음 실행(특히 `--tests` 필터 실행)은 같은 leaf의 XML을 덮어쓴다. 그래서 명령이 끝날 때마다 XML을 로그 폴더로 복사하고 사본에서 센다.
@@ -198,8 +183,8 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
| 거짓 통과 모양 | 지금의 장치 |
| --- | --- |
| 어떤 workflow도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR) |
| 실패를 막지 못하는 workflow 명령을 실행으로 셈(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) | `src/build-logic/AGENTS.md` 「`verifyStrictLaneStages`가 세는 명령」 |
| 어떤 단계도 돌리지 않는 lane | `verifyStrictLaneStages --dry-run`(PR)의 그래프 검사 |
| 단계 job이 단계를 조용히 돌리지 않음(바뀐 명령 줄, `if:`, `continue-on-error`, 경로 필터) | `verifyStrictLaneStages --dry-run`의 형식 검사(`src/build-logic/AGENTS.md` 「단계 job의 모양」) |
| lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 |
| 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) |
| 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 |
@@ -209,18 +194,18 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
| smoke rc=0인데 앱이 OOM으로 재시작함 | `scripts/run-compose-runtime-smoke.sh`가 lane 컨테이너 재시작·OOMKilled를 실패로 보고 `restarts.txt`·`app-memory-peak-bytes.txt`를 남긴다. 그 밖의 compose 실행은 `docker inspect -f '{{.RestartCount}} {{.State.OOMKilled}}' <컨테이너>`로 본다 |
| 셸 함수·`if` 조건 안에서 `set -e`가 꺼져 중간 실패가 지나감 | 실패를 받아야 하는 명령은 `if`·`&&`·`||` 조건 밖에 두거나 rc를 직접 본다(`<명령>; rc=$?; [ "$rc" -eq 0 ] \|\| exit "$rc"`) |
게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다.
게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. workflow를 바꿨으면 바꾸기 전후로 이벤트마다 계획되는 태스크 집합(`--dry-run`)을 비교한다.
## 7. workflow·검사 스크립트를 더할 때
리뷰는 빠진 검사만 찾기 쉽다. 장치를 더하기 전에 아래를 보고, 더하는 PR 본문에 답을 적는다. workflow 파일을 고치는 일은 CI 담당 작업이 한다.
1. 어느 단계인가(PR·main·nightly·release), 그리고 그 단계의 기존 workflow에 job으로 넣을 수 없는 이유를 한 줄로 쓴다. 모듈 이름의 workflow 파일은 만들지 않는다.
1. 어느 단계인가(PR·main·nightly·release). workflow 파일은 셋(`pr.yml`·`main.yml`·`release.yml`)뿐이다. 먼저 단계 태스크(`prCheck` 등)의 의존으로 넣을 수 있는지 보고, 안 되면 그 단계 파일의 job으로 넣는다. 새 workflow 파일과 모듈 이름의 workflow는 만들지 않는다.
2. 새 job이 다른 단계가 이미 돌리는 태스크를 다시 돌리지 않는지 `--dry-run` 태스크 목록으로 보인다.
3. lane 고르기·순서·집계는 Gradle에 둔다. 단계 job의 `run:`은 한 줄이다.
4. 경로 필터를 새로 쓰려면 그 lane이 다른 단계에서 무조건 돈다는 것을 보인다.
5. 문서·이름·개수·CI 배선을 검사하는 것은 main 단계다(2026-09-16 소유자 결정). PR에 두어야 하면 이유를 적는다.
6. 이벤트별 job 수 변화와 잰 실행 시간을 적는다. runner 용량은 [operate.md](../operate.md) 4.1절의 값으로 판단한다.
7. 실행 환경(Gitea)에서 돌지 않는 action·권한(`id-token`, ghcr, GitHub 의존성 그래프, `upload-artifact@v4` 이상)을 쓰지 않는다. 써야 하면 `github.server_url` 조건을 단다.
8. Gradle 밖 검사 스크립트는 `scripts/`에 두고, 머리 주석에 누가 부르는지(workflow·Gradle·사람·훅)를 적는다. 부르는 곳이 없는 검사 스크립트는 만들지 않는다. 같은 일을 하는 빌드 태스크가 있으면 거기에 넣는다. 스크립트의 시험은 `scripts/tests/`에 unittest로 둔다. `docs-check.yml`이 PR마다 `python3 -m unittest discover -s scripts/tests`로 돌린다.
8. Gradle 밖 검사 스크립트는 `scripts/`(workflow만 부르면 `scripts/ci/`)에 두고, 머리 주석에 누가 부르는지(workflow·Gradle·사람·훅)를 적는다. 부르는 곳이 없는 검사 스크립트는 만들지 않는다. 같은 일을 하는 빌드 태스크가 있으면 거기에 넣는다. 스크립트의 시험은 `scripts/tests/`에 unittest로 둔다. `prCheck`의 `testDocumentChecks`가 PR마다 `python3 -m unittest discover -s scripts/tests`로 돌린다.
9. 같은 장치에서 결함이 두 라운드 연속 나오면 고치기 전에 그 장치가 필요한지 다시 본다([improve.md](../improve.md) 7절).
+3 -3
View File
@@ -10,7 +10,7 @@
head 기록(docs/design, docs/history, docs/adr)의 .md는 맨 위에
머리 블록이 있다. 상태는 종류별 고정 어휘, 작성일은 날짜, 요약은 한국어, 현재
정본과 대체됨이 가리키는 경로는 지금 있다.
reference 살아 있는 문서의 인라인 코드 안 repo 경로(src/, docs/, scripts/, compose/, .github/로
reference 살아 있는 문서의 인라인 코드 안 repo 경로(src/, docs/, scripts/, compose/, .github/, .gitea/로
시작. 2026-11-07에 지운 infra/ 아래 경로도 본다)와 Gradle 경로(:a:b)가 지금 트리와
registry에 있다. 「있다」는 git이 아는 파일(추적 + 무시되지 않은 새 파일)과 그 위 폴더다. 디스크에만
있는 것(git mv가 남긴 빈 폴더 등)은 새 checkout에 없으므로 세지 않는다. 기록의 「현재 정본」·「대체됨」
@@ -125,7 +125,7 @@ TOKEN = re.compile(r"[^\s가-힣]+")
WORD = re.compile(r"^[(\[\"'“‘*_]*[A-Za-z][a-z]*(?:['’][a-z]+)?(?:-[a-z]+)*[)\]\"'”’*_.,;:!?…]*$")
# --- 참조
PATH_ROOTS = ("src/", "docs/", "scripts/", "compose/", "infra/", ".github/")
PATH_ROOTS = ("src/", "docs/", "scripts/", "compose/", "infra/", ".github/", ".gitea/")
PLACEHOLDER = re.compile(r"[*?<>{}\[\]$…]|\.\.\.|YYYY|NNN|[가-힣]")
LINE_SUFFIX = re.compile(r"(?::\d+(?:[-,]\d+)*)+$")
# 모든 leaf에 있는 소스 세트 이름(src/test, src/main/java)은 어느 leaf의 것인지 문장이 정한다.
@@ -148,7 +148,7 @@ VERSION = re.compile(r"(?<![\w.§])v?\d+\.\d+\.\d+(?:[.-][A-Za-z][A-Za-z0-9]*)*(
SPRING_BOOT_CELL = re.compile(r"^Spring Boot(?:\s+(?:BOM|버전))?$")
CELL_MARKUP = re.compile(r"[*_`]")
LINK_TEXT = re.compile(r"\[([^\]\n]*)\]\([^)\s]*\)")
# 상대 링크: 살아 있는 문서의 `[글](경로)`가 이 트리의 파일·폴더를 가리킨다. lychee(link-check.yml)는 PR에서
# 상대 링크: 살아 있는 문서의 `[글](경로)`가 이 트리의 파일·폴더를 가리킨다. lychee(main.yml links)는 main에서
# 정해진 경로만 보고, 그 밖의 문서(`src/**/AGENTS.md`, `.claude/**`, 루트 `AGENTS.md`)의 상대 링크는 이 검사만 본다.
LINK_TARGET = re.compile(r"\[[^\]\n]*\]\(([^)\s]+)\)")
URL_SCHEME = re.compile(r"^[a-z][a-z0-9+.-]*:", re.I)
+2 -1
View File
@@ -39,7 +39,8 @@ REGISTRY = "src/config/architecture/modules.json"
ROOT_ALLOWED = {
# 폴더
".claude": "Claude Code 세션 설정(추적: settings.json의 권한·훅, rules·skills·agents)",
".github": "workflow와 공용 action",
".gitea": "Gitea Actions workflow(pr·main·release)와 공용 action",
".github": "CODEOWNERS, PR 템플릿, 의존성 취약점 정책",
"compose": "compose.yaml이 마운트하는 보조 파일",
"docs": "문서",
"scripts": "Gradle 밖 검사·실행 스크립트",
+48
View File
@@ -0,0 +1,48 @@
"""Forwards 127.0.0.1:<port> to <host>:<port> for each port given, until killed.
Called by scripts/ci/redis-topology.sh when it runs inside a CI job container. The runner's job
container does not share the network of the Docker daemon that starts the Compose lanes, so the
daemon's published ports are on the daemon host, not on the job's localhost — while the Redis lanes
are built around localhost: the cluster announces 127.0.0.1 in its redirects and the TLS lane's
certificate names localhost. Forwarding keeps those lanes exactly as they run on a workstation.
python3 scripts/ci/forward-ports.py <host> <port>...
"""
import asyncio
import sys
async def pipe(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
try:
while data := await reader.read(65536):
writer.write(data)
await writer.drain()
except (ConnectionError, asyncio.CancelledError):
pass
finally:
writer.close()
async def serve(host: str, port: int) -> asyncio.base_events.Server:
async def handle(client_reader, client_writer):
try:
upstream_reader, upstream_writer = await asyncio.open_connection(host, port)
except OSError:
client_writer.close()
return
await asyncio.gather(pipe(client_reader, upstream_writer), pipe(upstream_reader, client_writer))
return await asyncio.start_server(handle, "127.0.0.1", port)
async def main(host: str, ports: list[int]) -> None:
servers = [await serve(host, port) for port in ports]
print(f"forward-ports: 127.0.0.1 -> {host} for {ports}", flush=True)
await asyncio.gather(*(server.serve_forever() for server in servers))
if __name__ == "__main__":
if len(sys.argv) < 3:
sys.exit(__doc__)
asyncio.run(main(sys.argv[1], [int(port) for port in sys.argv[2:]]))
+74
View File
@@ -0,0 +1,74 @@
#!/usr/bin/env bash
# One Redis topology lane against a real server: start the Compose topology, run the leaves'
# `redisTopologyTest` for it, print the evidence manifest, stop the topology. Called by the
# `redis-topology` nightly job of .gitea/workflows/main.yml (one call per matrix row); a person can
# run the same line on a machine with Docker.
#
# bash scripts/ci/redis-topology.sh <standalone|sentinel|cluster|tls> <redis version>
#
# The lanes are explicitOnly: they need the endpoint this script passes, so no stage runs them
# (docs/redis/support-matrix.md records which lane produced which evidence). Each Gradle task fails
# closed on its own account: an unknown mode, a missing endpoint, a lane with no tagged test class
# and a run that executed zero tests are all errors.
set -euo pipefail
topology=${1:?topology}
version=${2:?redis version}
cd "$(dirname "${BASH_SOURCE[0]}")/../.."
compose=(docker compose -f "src/adapter/outbound/redis-sdk/compose/${topology}/compose.yml")
forwarder=''
stop() {
[ -z "${forwarder}" ] || kill "${forwarder}" 2>/dev/null || true
"${compose[@]}" down -v
}
trap stop EXIT
runtime=:adapter:outbound:redis-runtime:redisTopologyTest
sdk=:adapter:outbound:redis-sdk:redisTopologyTest
semantic=:adapter:outbound:cache-redis:redisTopologyTest
extra=()
case "${topology}" in
standalone) port=6379; ports=(6379); tasks=("${runtime}" "${sdk}" "${semantic}") ;;
sentinel) port=27010; ports=(7010 7011 27010 27011 27012); tasks=("${runtime}" "${sdk}"); extra=(-Predis.topology.master=skeleton) ;;
cluster) port=7100; ports=(7100 7101 7102 7103 7104 7105); tasks=("${runtime}" "${sdk}" "${semantic}") ;;
tls) port=6390; ports=(6390); tasks=("${runtime}") ;;
*) echo "redis-topology: unknown topology ${topology}" >&2; exit 2 ;;
esac
REDIS_VERSION=${version} "${compose[@]}" up -d --wait
# Inside a CI job container the Docker daemon's ports are on the daemon host, not on localhost, and
# the lanes are built around localhost (cluster redirects announce 127.0.0.1, the TLS certificate
# names localhost). Forward them, so the lane runs exactly as it does on a workstation.
if [ -f /.dockerenv ]; then
# The default gateway of the job's network is the daemon host. /proc/net/route stores it as
# little-endian hex; awk reads "0x.." as 0 and would point the forwarder at itself.
daemon_host=$(python3 -c 'import socket, struct
for line in open("/proc/net/route").readlines()[1:]:
fields = line.split()
if fields[1] == "00000000":
print(socket.inet_ntoa(struct.pack("<L", int(fields[2], 16))))
break')
[ -n "${daemon_host}" ] && [ "${daemon_host}" != 0.0.0.0 ] \
|| { echo "redis-topology: no default gateway to reach the Docker daemon host" >&2; exit 1; }
python3 scripts/ci/forward-ports.py "${daemon_host}" "${ports[@]}" &
forwarder=$!
sleep 1
fi
# The tag says 7.4; the digest says which 7.4. Evidence that names only the tag cannot be reproduced
# once the tag moves, so a run that cannot name its digest has nothing to certify.
digest=$(docker image inspect --format '{{index .RepoDigests 0}}' "redis:${version}")
[ -n "${digest}" ] || { echo "redis-topology: no repository digest for redis:${version}" >&2; exit 1; }
if [ "${topology}" = tls ]; then
trust=$(mktemp "${RUNNER_TEMP:-/tmp}/redis-lane-ca.XXXXXX")
"${compose[@]}" cp redis:/tls/ca.crt "${trust}"
extra=(-Predis.topology.trust-material="${trust}")
fi
(cd src && ./gradlew "${tasks[@]}" --continue \
-Predis.topology.host=localhost -Predis.topology.port="${port}" -Predis.topology.mode="${topology}" \
"${extra[@]}")
printf 'evidence: commit=%s run=%s topology=%s redis_version=%s image_digest=%s\n' \
"$(git rev-parse HEAD)" "${GITHUB_RUN_ID:-local}" "${topology}" "${version}" "${digest}"
+108
View File
@@ -0,0 +1,108 @@
#!/usr/bin/env bash
# Vulnerability gate, shared by the stage workflows. Called by .gitea/workflows/pr.yml and main.yml
# (`filesystem`) and release.yml (`image <reference>`); not by Gradle and not on the desktop, because
# it downloads and installs its tools (docs/work/operate.md 4.1).
#
# bash scripts/ci/trivy-scan.sh filesystem dependency tree: block High/Critical, report
# Medium/Low, fail on any CISA KEV match
# bash scripts/ci/trivy-scan.sh image <reference> release image: write image-sbom.cdx.json,
# block High/Critical, report Medium/Low
#
# Tools are pinned release binaries with an asserted SHA-256, installed under RUNNER_TEMP (or a
# temporary directory): a checksum is a supply-chain claim that can be checked offline, an action
# pinned to a commit is not. .trivyignore.yaml is the one suppression source; each entry carries a
# reason and an expiry by policy (.github/dependency-vulnerability-policy.md).
# Optional mirrors: TRIVY_DOWNLOAD_BASE_URL, JQ_DOWNLOAD_BASE_URL, KEV_FEED_URL.
set -euo pipefail
readonly TRIVY_VERSION='0.71.2'
readonly TRIVY_SHA256_AMD64='0510e71e2fd39bf863856d499c8dc19feb4e7336546394c502a8f5cc7ab27460'
readonly TRIVY_SHA256_ARM64='fe1c7106e15a5365d485b098a8c338f91e3b7ba71cb0e4963b98a3a098763cfc'
readonly JQ_VERSION='1.8.1'
readonly JQ_SHA256_AMD64='020468de7539ce70ef1bceaf7cde2e8c4f2ca6c3afb84642aabc5c97d9fc2a0d'
readonly JQ_SHA256_ARM64='6bc62f25981328edd3cfcfe6fe51b073f2d7e7710d7ef7fcdac28d4e384fc3d4'
readonly DEFAULT_KEV_FEED_URL='https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json'
cd "$(dirname "${BASH_SOURCE[0]}")/../.."
tools="$(mktemp -d "${RUNNER_TEMP:-/tmp}/trivy-scan.XXXXXX")"
trap 'rm -rf "${tools}"' EXIT
download() { # url, sha256, destination
curl --fail --show-error --silent --location --retry 3 --proto '=https' --tlsv1.2 "$1" --output "$3"
printf '%s %s\n' "$2" "$3" | sha256sum -c -
}
case "$(uname -m)" in
x86_64 | amd64) trivy_arch='64bit'; trivy_sha="${TRIVY_SHA256_AMD64}"; jq_asset='jq-linux-amd64'; jq_sha="${JQ_SHA256_AMD64}" ;;
aarch64 | arm64) trivy_arch='ARM64'; trivy_sha="${TRIVY_SHA256_ARM64}"; jq_asset='jq-linux-arm64'; jq_sha="${JQ_SHA256_ARM64}" ;;
*) echo "trivy-scan: unsupported architecture $(uname -m)" >&2; exit 1 ;;
esac
download "${TRIVY_DOWNLOAD_BASE_URL:-https://github.com/aquasecurity/trivy/releases/download/v${TRIVY_VERSION}}/trivy_${TRIVY_VERSION}_Linux-${trivy_arch}.tar.gz" \
"${trivy_sha}" "${tools}/trivy.tar.gz"
tar -xzf "${tools}/trivy.tar.gz" -C "${tools}" trivy
download "${JQ_DOWNLOAD_BASE_URL:-https://github.com/jqlang/jq/releases/download/jq-${JQ_VERSION}}/${jq_asset}" \
"${jq_sha}" "${tools}/jq"
chmod 0755 "${tools}/trivy" "${tools}/jq"
export PATH="${tools}:${PATH}"
[ "$(jq --version)" = "jq-${JQ_VERSION}" ] || { echo "trivy-scan: unexpected $(jq --version)" >&2; exit 1; }
scan_filesystem() {
trivy fs --scanners vuln,license --severity CRITICAL,HIGH --exit-code 1 --ignorefile .trivyignore.yaml .
trivy fs --scanners vuln,license --severity MEDIUM,LOW --exit-code 0 --ignorefile .trivyignore.yaml .
trivy fs --scanners vuln --severity CRITICAL,HIGH,MEDIUM,LOW,UNKNOWN --exit-code 0 \
--ignorefile .trivyignore.yaml --format json --output "${tools}/trivy-kev.json" .
# A KEV-listed vulnerability fails regardless of its CVSS score. The feed and the scan are both
# checked for shape first: an empty or malformed input would otherwise intersect to nothing and
# print "no catalog match" for a check that never ran.
if ! curl --fail --show-error --silent --location --retry 3 --proto '=https' --tlsv1.2 \
"${KEV_FEED_URL:-${DEFAULT_KEV_FEED_URL}}" --output "${tools}/kev.json"; then
echo "trivy-scan: KEV feed unavailable; set KEV_FEED_URL to an approved mirror" >&2
exit 1
fi
jq -e '
(.catalogVersion | type == "string" and test("\\S"))
and (.dateReleased | type == "string" and test("\\S"))
and (.count | type == "number")
and (.count > 0)
and (.count == (.count | floor))
and (.vulnerabilities | type == "array")
and ((.vulnerabilities | length) > 0)
and (.count == (.vulnerabilities | length))
and (all(.vulnerabilities[]; (.cveID | type == "string" and test("^CVE-[0-9]{4}-[0-9]{4,}$"))))
and (([.vulnerabilities[].cveID] | unique | length) == .count)
' "${tools}/kev.json" > /dev/null || { echo "trivy-scan: the KEV feed is malformed" >&2; exit 1; }
jq -e '
(type == "object")
and (.Results | type == "array")
and ((.Results | length) > 0)
and (all(.Results[]; type == "object"))
and (all(.Results[]; (.Vulnerabilities == null) or (.Vulnerabilities | type == "array")))
and (all(.Results[]; all(.Vulnerabilities[]?;
(type == "object") and (.VulnerabilityID | type == "string" and test("\\S")))))
' "${tools}/trivy-kev.json" > /dev/null || { echo "trivy-scan: the Trivy KEV input is malformed" >&2; exit 1; }
jq -r '[.Results[]?.Vulnerabilities[]?.VulnerabilityID] | unique[]' "${tools}/trivy-kev.json" | sort -u > "${tools}/found.txt"
jq -r '.vulnerabilities[].cveID' "${tools}/kev.json" | sort -u > "${tools}/kev.txt"
hits="$(comm -12 "${tools}/found.txt" "${tools}/kev.txt")"
if [ -n "${hits}" ]; then
printf 'trivy-scan: CISA KEV-listed vulnerability found regardless of CVSS:\n%s\n' "${hits}" >&2
exit 1
fi
echo "trivy-scan: no KEV catalog match."
}
# The image scan sees the base image's OS packages, which the filesystem scan cannot. The SBOM is
# written before the blocking scan, so the inventory survives the run that refuses to publish.
scan_image() {
trivy image --format cyclonedx --scanners license --output image-sbom.cdx.json "$1"
test -s image-sbom.cdx.json
trivy image --scanners vuln,license --severity CRITICAL,HIGH --exit-code 1 --ignorefile .trivyignore.yaml "$1"
trivy image --scanners vuln,license --severity MEDIUM,LOW --exit-code 0 --ignorefile .trivyignore.yaml "$1"
}
case "${1:-}" in
filesystem) scan_filesystem ;;
image) scan_image "${2:?image reference}" ;;
*) sed -n '2,13p' "$0" >&2; exit 2 ;;
esac
+26
View File
@@ -0,0 +1,26 @@
#!/usr/bin/env bash
# Two questions about Gradle's configuration cache. Called by the `configuration-cache` job of
# .gitea/workflows/main.yml and by scripts/verify.sh main.
# 1. Can every repository-wide gate be stored? A property of the task graph, so --dry-run answers it
# for all of them in seconds without running a lane.
# 2. Is a stored entry reused while the build still executes its work? Checked on the two core
# leaves, whose check runs in a minute.
# prCheck and verifyStrictLaneStages are not in the list: the strict-lane check reads the task graph
# itself and is declared incompatible, and prCheck is ci plus scripts.
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")/../../src"
reused() { # gradle arguments...; fails unless the second identical run reuses the stored entry
./gradlew "$@" --configuration-cache --configuration-cache-problems=fail
output=$(./gradlew "$@" --configuration-cache --configuration-cache-problems=fail 2>&1)
printf '%s\n' "${output}"
grep -Fq 'Reusing configuration cache.' <<<"${output}" || {
echo "configuration cache: not reused for: $*" >&2
exit 1
}
}
for gate in ci mainCheck integrationCheck releaseCheck; do
reused "${gate}" --dry-run
done
reused :domain-core:check :application-core:check
+190
View File
@@ -0,0 +1,190 @@
#!/usr/bin/env bash
# 검증 진입점. 사람·세션·문서가 같은 명령을 쓰고, 단계 이름은 workflow(.gitea/workflows)와 같다.
#
# scripts/verify.sh <단계> [대상] [--on here|<호스트>] [--log <이름>] [--no-cache]
#
# 단계 무엇 workflow
# docs 문서·지침 검사와 스크립트 시험(Gradle 없음) pr.yml의 prCheck 안
# leaf <경로> registry gradle_path 하나의 check (작업 중)
# pr :prCheck, :verifyStrictLaneStages --dry-run pr.yml `gradle`
# main :mainCheck, :integrationCheck, build-logic 시험, 설정 캐시 main.yml(push)
# nightly compose smoke 전부, :performanceCheck(마지막) main.yml(nightly)
# release :releaseCheck(이 커밋을 provenance로) release.yml `release`
# app 앱을 띄워 health와 기본 endpoint를 직접 본다 (없음)
# round pr → main → nightly → release, 첫 실패에서 멈춘다 라운드 끝 묶음
# docs 밖의 단계는 Gradle·Docker를 쓴다. 이 repo에서는 desktop에서만 돈다(docs/work/operate.md 4.1절).
# trivy·lychee·nightly 행렬(Redis topology, PostgreSQL major, NFS)은 도구를 내려받거나 runner 환경이 필요해
# workflow에서만 돈다.
#
# --on <호스트>: 지금 작업 트리(커밋 안 된 변경 포함)를 패치로 그 호스트에 옮긴다. 기준 커밋에서 새 worktree를
# 만들어 패치를 적용하고, 트리 해시가 여기와 같은지 본 뒤 잠금 아래에서 같은 단계를 돌리고 worktree를 지운다.
# push하지 않는다. 기준 커밋은 원격 checkout이 fetch로 받을 수 있어야 한다(기본: origin/main과 갈라진 곳).
# docs 밖의 단계는 기본이 desktop이다. desktop에서 직접 돌릴 때는 --on here.
# --no-cache: Gradle 명령마다 --no-build-cache를 붙인다(증거로 쓸 실행, docs/work/reference/gates.md 3절).
# 환경 변수: VERIFY_HOST(무거운 단계의 --on 기본값, 없으면 desktop), VERIFY_REMOTE_REPO(원격 checkout, 기본
# ~/workspace/<repo 이름>), VERIFY_BASE_REF(기본 origin/main), VERIFY_LOCK(기본 /tmp/claude-gates/heavy.lock),
# VERIFY_SSH(기본 ssh).
# 종료 코드: 단계의 종료 코드. 2 = 사용법, 4 = 원격 준비 실패.
set -euo pipefail
ROOT=$(git rev-parse --show-toplevel)
cd "$ROOT"
TMP_FILES=()
trap '[ ${#TMP_FILES[@]} -eq 0 ] || rm -f "${TMP_FILES[@]}"' EXIT # 빈 배열 + set -u는 옛 bash에서 오류다
# 빌드마다 쓰고 버리는 daemon. 여러 worktree의 빌드를 한 오래 사는 daemon이 받으면 서로 호환되지 않는 compiler
# worker가 쌓여 desktop 메모리를 채운다(2026-11-08 측정: worker 41개, 14.2GB). GRADLE_OPTS는 단계 안에서 다시 부르는
# Gradle(생성 명령 왕복, 설정 캐시·Redis 스크립트)에도 같은 규칙을 준다. repo 기본값(src/gradle.properties)은 그대로다.
GRADLE_FLAGS=(--console=plain --no-daemon)
export GRADLE_OPTS="${GRADLE_OPTS:+$GRADLE_OPTS }-Dorg.gradle.daemon=false"
LOCK=${VERIFY_LOCK:-/tmp/claude-gates/heavy.lock}
usage() {
awk 'NR > 1 && /^#/ { sub(/^# ?/, ""); print; next } NR > 1 { exit }' "$ROOT/scripts/verify.sh" >&2
exit 2
}
gradle() { (cd src && ./gradlew "$@" "${GRADLE_FLAGS[@]}"); }
# ---------------------------------------------------------------- 단계 본문
run_docs() {
python3 scripts/check-work-docs.py
python3 scripts/check-docs.py
python3 -m unittest discover -s scripts/tests
python3 scripts/check-repo-layout.py
}
# 대상은 registry의 gradle_path여야 한다. 폴더 이름이나 기억으로 짐작한 경로는 여기서 거절한다.
run_leaf() {
local path=${1:?leaf 뒤에 registry gradle_path(예: :adapter:outbound:persistence-jpa)}
python3 - "$path" <<'PY' || { echo "verify: $path는 registry(src/config/architecture/modules.json)의 gradle_path가 아니다" >&2; exit 2; }
import json, sys
paths = {m["gradle_path"] for m in json.load(open("src/config/architecture/modules.json"))["modules"]}
sys.exit(0 if sys.argv[1] in paths else 1)
PY
gradle "$path:check"
}
run_pr() {
gradle :prCheck
gradle :verifyStrictLaneStages --dry-run
}
run_main() {
gradle :mainCheck --continue
gradle :integrationCheck --continue
gradle -p build-logic test
bash scripts/ci/verify-configuration-cache.sh
}
# performanceCheck는 마지막이다: 상한은 다른 빌드가 돌지 않는 머신에서만 뜻이 있다.
run_nightly() {
bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
gradle :performanceCheck --continue
}
# CI는 GITHUB_SHA로 커밋을 받는다. 여기서는 HEAD를 준다(--on 원격 실행에서는 패치를 얹은 기준 커밋).
run_release() { GIT_SHA=${GIT_SHA:-$(git rev-parse HEAD)} gradle :releaseCheck; }
run_app() { bash scripts/bootstrap-local.sh; }
# 함수를 && 목록 안에서 부르면 그 안의 set -e가 꺼진다. 그래서 차례로 부른다.
run_round() {
run_pr
run_main
run_nightly
run_release
}
# ---------------------------------------------------------------- 실행 위치
run_here() {
local stage=$1
shift
case "$stage" in
docs) run_docs ;;
leaf | pr | main | nightly | release | app | round)
# 같은 머신의 다른 세션·프론트 repo와 무거운 실행이 겹치지 않게 공유 잠금 아래에서 돈다.
if [ -z "${VERIFY_LOCKED:-}" ] && [ -d "$(dirname "$LOCK")" ]; then
export VERIFY_LOCKED=1
exec flock "$LOCK" "$ROOT/scripts/verify.sh" "$stage" "$@" --on here "${NO_CACHE[@]}"
fi
"run_$stage" "$@"
;;
*) usage ;;
esac
}
run_remote() {
local stage=$1 target=$2 host=$3 log=$4 ssh=${VERIFY_SSH:-ssh}
local name base tree tmp_index patch id remote_repo
name=$(basename "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")")
remote_repo=${VERIFY_REMOTE_REPO:-"~/workspace/$name"}
base=$(git merge-base HEAD "${VERIFY_BASE_REF:-origin/main}")
tmp_index=$(mktemp)
patch=$(mktemp)
TMP_FILES+=("$tmp_index" "$patch")
cp "$(git rev-parse --git-path index)" "$tmp_index"
GIT_INDEX_FILE=$tmp_index git add -A
tree=$(GIT_INDEX_FILE=$tmp_index git write-tree)
git diff --binary "$base" "$tree" > "$patch"
id="verify-$(date +%s)-$$"
echo "verify: $host에서 '$stage $target' (기준 ${base:0:12}, 트리 ${tree:0:12}, 로그 ~/$log-logs/$stage.log)" >&2
$ssh "$host" "cat > /tmp/$id.patch" < "$patch"
# compose lane이 만든 root 소유 파일이 있어도 지울 수 있게 정리는 worktree remove --force 하나로 한다.
$ssh "$host" bash -s <<EOF
set -u
cd $remote_repo || exit 4
git fetch -q origin || exit 4
wt=\$(mktemp -d /tmp/$id.XXXXXX)
git worktree add -q --detach "\$wt" $base || exit 4
cleanup() { cd $remote_repo && git worktree remove --force "\$wt"; rm -f /tmp/$id.patch; }
trap cleanup EXIT
cd "\$wt"
if [ -s /tmp/$id.patch ]; then git apply --binary --index /tmp/$id.patch || exit 4; fi
got=\$(git write-tree)
if [ "\$got" != "$tree" ]; then echo "트리 해시가 다르다: 원격 \$got, 여기 $tree" >&2; exit 4; fi
mkdir -p "\$(dirname $LOCK)" ~/$log-logs
echo "verify: \$(uptime)" >&2
VERIFY_LOCKED=1 flock $LOCK ./scripts/verify.sh $stage $target --on here ${NO_CACHE[*]} 2>&1 | tee ~/$log-logs/$stage.log
rc=\${PIPESTATUS[0]}
# 새 worktree라 여기 있는 JUnit XML은 모두 이번 실행의 것이다. worktree를 지우기 전에 센다.
find . -path '*/build/test-results/*' -name 'TEST-*.xml' -print0 | xargs -0 -r cat \\
| grep -o '<testsuite [^>]*' \\
| awk '{ for (i = 1; i <= NF; i++) if (split(\$i, kv, "=") == 2) { gsub(/"/, "", kv[2]); n[kv[1]] += kv[2] } }
END { printf "verify: 테스트 tests=%d failures=%d errors=%d skipped=%d\\n", n["tests"], n["failures"], n["errors"], n["skipped"] }' \\
| tee -a ~/$log-logs/$stage.log
echo "verify: rc=\$rc" | tee -a ~/$log-logs/$stage.log
exit \$rc
EOF
}
main() {
local stage=${1:-} target="" on="" log=""
NO_CACHE=()
[ -n "$stage" ] || usage
shift
if [ "$stage" = leaf ] && [ $# -gt 0 ] && [ "${1#--}" = "$1" ]; then
target=$1
shift
fi
while [ $# -gt 0 ]; do
case "$1" in
--on) on=${2:?--on 뒤에 호스트}; shift 2 ;;
--log) log=${2:?--log 뒤에 이름}; shift 2 ;;
--no-cache) NO_CACHE=(--no-cache); GRADLE_FLAGS+=(--no-build-cache); shift ;;
*) usage ;;
esac
done
if [ -z "$on" ]; then
if [ "$stage" = docs ]; then on=here; else on=${VERIFY_HOST:-desktop}; fi
fi
if [ "$on" = here ]; then
run_here "$stage" ${target:+"$target"}
else
log=${log:-$(git branch --show-current | tr '/' '-')}
run_remote "$stage" "$target" "$on" "${log:-detached}"
fi
}
main "$@"
+11 -11
View File
@@ -27,9 +27,10 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
| `configContractCheck` | `:app-bootstrap:verifyEnvKeys`로 환경 설정 계약을 검사 |
| `qualificationCheck` | 전체 기동(system) 레인과 보조 source set Checkstyle을 실행 |
| `integrationCheck` | 선언된 strict integration lane을 실행. 대부분 container runtime이 필요. 입력이 필요한 lane(Redis topology: `-Predis.topology.mode`, AWS: 보호 자격 증명 env)은 입력이 없으면 빠지고 집계가 그 이유를 출력 |
| `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(`-Pperformance.assertions.enabled`가 `true`가 아니면 실패, skip된 테스트가 있어도 실패). `integration-main.yml` `performance-check`가 main·nightly에 같은 명령으로 돌림 |
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 workflow가 실제 실행하는 단계(`ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 각 단계를 workflow가 `--dry-run` 없이 실행하는지 검사. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-v`·`--help` 등)과, 실패해도 단계가 실패하지 않을 수 있거나(`\|\| true`, pipefail 없는 파이프, `if` 조건 등) 돌지 않을 수 있거나(조건부 `exit 0` 뒤, 요청으로만 시작하는 workflow, `paths` 필터로만 시작하는 workflow, `releaseCheck` 밖의 단계를 태그 push·`release`로만 시작하는 workflow 등) 검사가 읽지 않는(`\|\| exit 1`, `{ }` 안 등) 명령은 실행으로 세지 않는다. 자세한 목록은 `build-logic/README.md`. PR 게이트가 돌림 |
| `ci` | PR 게이트: 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` |
| `performanceCheck` | 선언된 strict performance lane(부하·종료·pool·자원 상한)을 실행. 실서버·container가 필요. 상한은 매번 단언하고 끄는 속성이 없다(`-Pperformance.assertions.enabled`가 `true`가 아니면 실패, skip된 테스트가 있어도 실패). `main.yml` `performance` job이 nightly에 다른 무거운 job 뒤에서 같은 명령으로 돌림 |
| `verifyStrictLaneStages` | `--dry-run` 전용. `explicitOnly`가 아닌 strict lane이 `strictLaneStages`에 선언한 단계(`prCheck`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나의 계획에 있는지, 단계마다 선언한 workflow job이 `./gradlew <단계>`를 정해진 한 줄로 조건 없이(또는 선언한 조건으로) 돌리는지 검사. 형식은 `build-logic/AGENTS.md` 「단계 job의 모양」. PR 단계가 돌림 |
| `prCheck` | PR 단계: `ci` + `verifyDependencyLocks` + compose 렌더링(`verifyComposeProfiles`) + 저장소 배치(`verifyRepositoryLayout`) + 문서 검사(`documentCheck`) |
| `ci` | 모든 leaf `check`(API surface 검사 포함, 소유자 결정 20) + `architectureCheck` + `qualityCheck` |
| `mainCheck` | main 단계: `configContractCheck` + `qualificationCheck` + `verifyPublicPathSnapshot` + 전송·메시징 qualification 레인 + 각 leaf의 `mainCheck`(문서 대조 레인 `*DocumentContractTest`, objectstorage MinIO 레인) |
| `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) |
@@ -80,7 +81,7 @@ version은 root `.tool-versions`의 Temurin 값으로 맞춘다.
archive task 자체는 timestamp 비보존·재현 가능한 file order·고정 mode를 강제한다. 현재 저장소에는
별도의 `verify-reproducible-build.sh`가 없으므로 byte-for-byte 이중-build 비교를 자동 게이트라고
주장하지 않는다. 릴리스 검증의 정본 진입점은 `./gradlew releaseCheck`와
`.github/workflows/release.yml`이다.
`.gitea/workflows/release.yml`이다.
### `-parameters` 컴파일러 플래그
@@ -190,18 +191,17 @@ drift하기 시작하면 그때 자동화한다. 진짜 항목을 상대로, 진
- **소유 범위.** 이 계약은 *게이트 배선*(어떤 게이트가 CI 에서 돌고 실패 시 어떻게 릴리스를 막는가)을
소유한다. 개별 scanner/tool/severity *정책* 은 owner 브랜치가 소유하며, 그 20행 매핑의 in-repo
SSOT는 Gradle task graph와 GitHub Actions job graph 그 자체다.
SSOT는 Gradle task graph와 workflow job graph 그 자체다.
> 이력: 게이트 표 `.github/ci-gate-matrix.yml`(1,025줄, 107개 게이트 행)과 그 검사기
> `.github/scripts/verify-gate-matrix.sh`(568줄)는 삭제했다. 그 표는 이미 두 그래프에 있는 정보의
> 세 번째 사본이었고, 검사기는 세 사본을 서로 같게 유지하는 일을 했다. 결과적으로 체크 하나를
> 추가하려면 Gradle · workflow · 표 · 검사기 기대값 · Java 계약 테스트 다섯 곳을 같이 고쳐야 했다.
- **워크플로.** `.github/workflows/ci-quality-gates.yml` 의 `release-gate` 잡이 모든 release-blocking
게이트의 fan-in(단일 required status check)이다. included build 테스트는 경로 필터가 걸린
`build-logic.yml`이, main 단계(`mainCheck`)·configuration-cache·JPA candidate evidence는
`integration-main.yml`이 돌린다. 위임 게이트(Trivy SCA/이미지 스캔)는 `dependency-vulnerability.yml` 가 소유하며,
GitHub Actions 는 워크플로 간 `needs` 를 못 쓰므로 branch protection 의 required check 합집합으로
묶는다.
- **워크플로.** `.gitea/workflows/`의 세 파일이다. `pr.yml`의 `done` job이 PR 단계의 모든 job(`gradle`:
`./gradlew :prCheck`와 `verifyStrictLaneStages --dry-run`, `vulnerabilities`: Trivy)을 모으는 단일 필수 검사다.
`main.yml`이 main 단계(`mainCheck`·`integrationCheck`·build-logic 시험·configuration cache·링크)와
nightly(행렬 job, compose smoke, 마지막에 `performanceCheck`)를, `release.yml`이 태그 단계를 돌린다.
무엇을 돌릴지는 Gradle 단계 태스크가 정하고, `verifyStrictLaneStages`가 단계 job의 모양을 지킨다.
---
@@ -30,12 +30,15 @@ public final class NginxWebSocketHarness implements AutoCloseable {
*/
@SuppressWarnings("resource")
public NginxWebSocketHarness(int applicationPort, String configurationResource) {
// The application listens in this JVM's network, which a container reaches by name only
// through Testcontainers' host-port tunnel. `host-gateway` was the Docker host: this JVM's
// host on a workstation, but not on a CI runner whose job runs in a container of its own
// (the Gitea runner), where Nginx reached nothing and every upgrade failed.
org.testcontainers.Testcontainers.exposeHostPorts(applicationPort);
this.nginx =
new GenericContainer<>(IMAGE)
.withExposedPorts(8080)
// host.docker.internal is not resolvable on stock Linux Docker; without the gateway
// the container fails with a connection refused that reads as a config error.
.withExtraHost("host.docker.internal", "host-gateway")
.withAccessToHost(true)
.withCopyToContainer(
Transferable.of(configuration(configurationResource, applicationPort)),
"/etc/nginx/nginx.conf");
@@ -68,7 +71,7 @@ public final class NginxWebSocketHarness implements AutoCloseable {
throw new IllegalStateException(resource + " is missing from the lane's resources");
}
return new String(stream.readAllBytes(), StandardCharsets.UTF_8)
.replace("APPLICATION_HOST", "host.docker.internal")
.replace("APPLICATION_HOST", "host.testcontainers.internal")
.replace("APPLICATION_PORT", Integer.toString(applicationPort));
} catch (IOException e) {
throw new IllegalStateException(resource + " could not be read", e);
+1 -1
View File
@@ -329,7 +329,7 @@ rate-limit 어댑터가 있다고 SDK 명령 정책이 강제된다고 짐작하
`redisContainerContractTest`는 cache-region, lease, 멱등성 store 포트 계약(메모리 fake가 통과하는 것. 멱등성 계약의
시간 있는 경우는 여기서 서버 자신의 시계로 돌고, `test`에서는 명령 fake의 시계로 돈다 — 후자는 program 자체가 아니라
fixture가 가진 program 사본을 증명한다)과 살아 있는 semantic 포트 시험을, standalone topology의 ACL 파일 아래에서 스스로
띄운 Redis에 대고 돌린다. `integrationCheck`(integration-main.yml의 `integration-check` job)에 있고 거기에만 있다:
띄운 Redis에 대고 돌린다. `integrationCheck`(`main.yml`의 `integration` job)에 있고 거기에만 있다:
`mainCheck`에도 적었을 때는 main push마다 두 번 돌았다. image는 `config/testing/container-images.properties`의
`redis`다.
@@ -71,9 +71,9 @@ redisTopologyLane {
// the same defect (05-02, 05-03). The image is config/testing/container-images.properties' `redis`,
// and the ACL file is the one the development stack and the redis-sdk topologies share
// (compose/redis/acl), so the accounts and their rights are the standalone
// topology's. Integration category, so integrationCheck runs it — integration-main.yml's
// `integration-check` job, on every push to main and nightly. It is deliberately not in this leaf's
// mainCheck as well: `main-check` and `integration-check` are two jobs of the same workflow run, so a
// topology's. Integration category, so integrationCheck runs it — main.yml's `integration` job, on
// every push to main and nightly. It is deliberately not in this leaf's mainCheck as well: `main` and
// `integration` are two jobs of the same workflow run, so a
// lane in both started a second Redis container and ran every live contract twice per push without
// covering anything the first run did not (found while fixing review 2026-11-03). Sentinel, cluster
// and TLS remain the topology lane's.
+2 -2
View File
@@ -230,8 +230,8 @@ strictTestLanes {
// the deadline and evidence contracts against real TCP faults — a slow drip, a cut stream, a refused
// connect — and review 2026-11-01 05-06/05-16 put it in the main stage because it was reachable only
// through integrationCheck, which then ran on no main-branch build. That premise no longer holds:
// integration-main.yml's `integration-check` job runs integrationCheck (an integration lane, so this
// one) on every push to main and nightly, in the same workflow run as the `main-check` job. In both
// main.yml's `integration` job runs integrationCheck (an integration lane, so this one) on every push
// to main and nightly, in the same workflow run as the `main` job. In both
// stages, every main push started a second Toxiproxy and httpbin and ran every fault twice without
// covering anything the first run did not (review 2026-11-03 README §8, closed in round 9; the
// cache-redis container lane left mainCheck for the same reason). verifyStrictLaneStages still fails
@@ -108,6 +108,18 @@ apiSurface {
]
}
// NotificationReleaseGateTest (pull-request `test`) requires the notification documents and the
// NOTIF-ADR records to exist. They are inputs of `test`, or a moved or deleted ADR would leave the
// task up to date and its absence unseen — the path filter of the workflow that used to run the
// notification tests had the same blind spot once the ADRs moved to docs/adr/.
tasks.named('test') {
inputs.dir(rootProject.file('../docs/notification')).withPropertyName('notificationDocuments')
.withPathSensitivity(PathSensitivity.RELATIVE)
inputs.files(fileTree(rootProject.file('../docs/adr')) { include 'NOTIF-ADR-*' })
.withPropertyName('notificationAdrs')
.withPathSensitivity(PathSensitivity.RELATIVE)
}
// NotificationEvidenceVerifierTest's repository case holds docs/notification/evidence-manifest.json,
// the support matrix it grades and the evidence files it names to each other. A comparison with
// repository documents, so it runs in this leaf's `mainCheck`, not in the pull-request `test`
+3 -3
View File
@@ -99,9 +99,9 @@ testImplementation testFixtures(project(':adapter:outbound:objectstorage'))
### MinIO 검증 lane
`objectStorageMinioContractTest`와 `objectStorageMinioFaultTest`는 실제 MinIO와 Toxiproxy를 돌린다. 루트
`integrationCheck`(main push와 nightly)와, object storage를 건드리는 pull request의
`.github/workflows/object-storage-qualification.yml`에서 돈다 — 이 leaf의 `mainCheck`에서는 돌지 않는다.
거기서는 main push마다 두 번 돌았다. image는 파일 하나
`integrationCheck`(main push와 nightly)에서 돈다. 이 leaf의 `mainCheck`에서는 돌지 않는다. 거기서도 돌던 때는
main push마다 두 번 돌았다. object storage를 건드린 pull request에서 따로 돌던 workflow job은 2026-11-08에
지웠다(같은 태스크를 `integrationCheck`가 돌린다). image는 파일 하나
`src/test/resources/object-storage/minio-provider-evidence.json`에서 읽는다. 그 `image` digest는 옆에 적힌
`status`, `excludedProfiles`, `limitations`를 잰 릴리스다. `MinioQualificationImage`(`src/test`에 있고, leaf의
`test`가 Docker 없이 검사한다)가 그것을 읽는다.
@@ -151,8 +151,8 @@ strictTestLanes {
description = 'Runs only with explicit protected AWS sandbox authority and exact inputs.'
requires 'dev.caskeleton.adapter.outbound.objectstorage.qualification.AwsS3QualificationPreconditionsTest'
rejectSkipped = true
// The protected environment of object-storage-qualification.yml is the only caller that has
// the authority. Without it the lane can only fail, so integrationCheck leaves it out and
// The protected AWS workflow job, run on request with the sandbox secrets, is the only caller
// that has the authority. Without it the lane can only fail, so integrationCheck leaves it out and
// says so (review NEW-16); naming the task still runs it and still fails closed.
if (providers.environmentVariable('OBJECT_STORAGE_AWS_QUALIFICATION_ENABLED').getOrElse('') != 'true') {
explicitOnly 'it needs OBJECT_STORAGE_AWS_QUALIFICATION_ENABLED=true and the protected AWS sandbox inputs'
@@ -162,7 +162,7 @@ strictTestLanes {
// The MinIO lanes start a container, so they are not this leaf's pull-request `check` (review
// BUILD-계획-B3). They are integration lanes, and the root integrationCheck owns every container lane
// on main and nightly; object-storage-qualification.yml runs them on pull requests that touch object
// storage. This leaf's `mainCheck` used to run them too, so each main push ran them twice in two
// parallel jobs (review 2026-11-03 RR-06-09, original 08-04 (d)).
// on main and nightly. This leaf's `mainCheck` used to run them too, so each main push ran them twice
// in two parallel jobs (review 2026-11-03 RR-06-09, original 08-04 (d)); a path-filtered pull-request
// workflow ran them a third time until 2026-11-08.
@@ -341,7 +341,7 @@ tasks.named('test') {
// The whole directory, not the two named workflows: the Experimental-major check asks whether
// *some* lane records that major as its target, so adding or deleting any workflow can change
// its answer. Naming files here would leave the lane that matters outside the up-to-date check.
inputs.dir(new File(rootProject.projectDir.parentFile, '.github/workflows'))
inputs.dir(new File(rootProject.projectDir.parentFile, '.gitea/workflows'))
inputs.file(file('build.gradle'))
inputs.dir(file('src/jpaPlatformPerformanceTest/java'))
// AppliedMigrationImmutabilityTest pins the notification and fileserver streams where they live.
@@ -7,7 +7,8 @@ import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/**
* The Hibernate 8 probe that {@code .github/workflows/jpa-next.yml} runs.
* The Hibernate 8 probe that the nightly {@code jpa-next} job of {@code .gitea/workflows/main.yml}
* runs.
*
* <p>The provider version is read from Hibernate itself rather than from the build file, because
* the build file states an intent and the classpath states the fact. Dependency resolution,
@@ -7,7 +7,8 @@ import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/**
* The Jakarta Persistence 4 probe that {@code .github/workflows/jpa-next.yml} runs.
* The Jakarta Persistence 4 probe that the nightly {@code jpa-next} job of {@code
* .gitea/workflows/main.yml} runs.
*
* <p>JPA 4 is not released, so nothing can run against it. The probe reads the specification
* version off the API actually on the classpath, so the day a dependency upgrade brings JPA 4 in it
@@ -6,7 +6,8 @@ import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
/**
* The PostgreSQL 19 probe that {@code .github/workflows/jpa-next.yml} runs.
* The PostgreSQL 19 probe that the nightly {@code jpa-next} job of {@code
* .gitea/workflows/main.yml} runs.
*
* <p>Unlike the specification and provider probes, this one has no artifact to detect: a server
* version is only observable by starting one. So the assertion is about the support matrix instead
@@ -34,7 +34,6 @@ class PoolLaneClaimTest {
"src/adapter/outbound/persistence-jpa/src/jpaPlatformPerformanceTest/java/dev/caskeleton/adapter/outbound/persistence/platform/pool/PoolPressureContractTest.java",
"src/adapter/outbound/persistence-jpa/src/jpaPlatformPerformanceTest/java/dev/caskeleton/adapter/outbound/persistence/platform/pool/HikariPoolSaturationContractTest.java",
"src/adapter/outbound/persistence-jpa/src/jpaPlatformPerformanceTest/java/dev/caskeleton/adapter/outbound/persistence/platform/pool/RequiresNewPoolPressureContractTest.java",
".github/workflows/jpa-nightly.yml",
"docs/jpa/repository-adaptation.md");
/**
@@ -75,19 +74,6 @@ class PoolLaneClaimTest {
}
}
@Test
@DisplayName("nightly job은 동작 lane을 그 동작 이름으로 돌린다")
void theNightlyJobRunsTheBehaviourLane() {
String nightly = read(".github/workflows/jpa-nightly.yml");
assertThat(nightly)
.as("the lane that runs must be the one the build registers")
.contains(":adapter:outbound:persistence-jpa:jpaPlatformPoolContractTest");
assertThat(nightly)
.as("the old task name would silently select nothing")
.doesNotContain(":adapter:outbound:persistence-jpa:jpaPlatformPerformanceTest");
}
/** Reads a repository-relative file, locating the root by walking up. */
private static String read(String repositoryRelativePath) {
for (Path directory = Path.of("").toAbsolutePath();
@@ -31,8 +31,8 @@ class JpaReleaseRenderingTest {
private final JpaReleaseManifest manifest = JpaReleaseManifest.loadFromRepository();
private final String supportMatrix = read("docs/jpa/support-matrix.md");
private final String releaseWorkflow = read(".github/workflows/release.yml");
private final String nightlyWorkflow = read(".github/workflows/jpa-nightly.yml");
private final String releaseWorkflow = read(".gitea/workflows/release.yml");
private final String nightlyWorkflow = read(".gitea/workflows/main.yml");
@Test
@DisplayName("the support document states the registry's support level for every major")
@@ -109,14 +109,6 @@ class JpaReleaseRenderingTest {
.containsExactlyElementsOf(manifest.stableVersions());
}
@Test
@DisplayName("the promotion job requires evidence for exactly the Stable majors")
void thePromotionJobRequiresEvidenceForExactlyTheStableMajors() {
assertThat(JpaReleaseRendering.workflowPromotionMajors(releaseWorkflow))
.as("promotion that checks fewer majors than the matrix runs ignores a failed one")
.containsExactlyElementsOf(manifest.stableVersions());
}
@Test
@DisplayName("a workflow matrix that drops a Stable major is caught")
void aWorkflowMatrixThatDropsAStableMajorIsCaught() {
@@ -204,7 +196,7 @@ class JpaReleaseRenderingTest {
*/
private static List<Integer> compatibilityTargetsAcrossWorkflows() {
List<Integer> targets = new ArrayList<>();
Path directory = locate(".github/workflows");
Path directory = locate(".gitea/workflows");
try (var entries = Files.list(directory)) {
for (Path workflow : entries.sorted().toList()) {
if (workflow.getFileName().toString().endsWith(".yml")) {
@@ -27,7 +27,6 @@ public final class JpaReleaseRendering {
private static final Pattern DOCUMENT_GATE_ROW =
Pattern.compile("^\\|\\s*`([a-z0-9-]+)`\\s*\\|\\s*gate\\s*\\|", Pattern.MULTILINE);
private static final Pattern WORKFLOW_MATRIX = Pattern.compile("postgresql:\\s*\\[([^\\]]*)\\]");
private static final Pattern WORKFLOW_PROMOTION_LOOP = Pattern.compile("for major in ([0-9 ]+);");
private static final Pattern QUOTED_MAJOR = Pattern.compile("\"(\\d+)\"");
private static final Pattern COMPATIBILITY_TARGET =
Pattern.compile("^\\s*target:\\s*PostgreSQL\\s+(\\d+)\\s*$", Pattern.MULTILINE);
@@ -77,26 +76,6 @@ public final class JpaReleaseRendering {
return majors;
}
/**
* The majors the promotion job requires evidence for.
*
* <p>Read separately from the matrix on purpose. They are two hand-written lists in one file, and
* a promotion that requires fewer majors than the matrix produces is a promotion that ignores a
* failed one.
*/
public static List<Integer> workflowPromotionMajors(String workflow) {
Objects.requireNonNull(workflow, "workflow");
Matcher loop = WORKFLOW_PROMOTION_LOOP.matcher(workflow);
if (!loop.find()) {
throw new IllegalArgumentException("the release workflow declares no promotion major list");
}
List<Integer> majors = new ArrayList<>();
for (String major : loop.group(1).trim().split("\\s+", -1)) {
majors.add(Integer.parseInt(major));
}
return majors;
}
/**
* Every major some job in a workflow fans out to.
*
@@ -122,15 +101,15 @@ public final class JpaReleaseRendering {
* The majors a compatibility lane records itself as targeting.
*
* <p>An Experimental major is declared "compatibility lane only" and nothing tied that phrase to
* a file. The lane does exist — it runs weekly and records {@code NOT_EXECUTABLE} with its reason
* — but the registry, the support document and the release workflow could each be read end to end
* without establishing that. A reader who cannot find the lane concludes there is none, which is
* the conclusion this repository's own review pass reached before checking the workflow
* a file. The lane does exist — it runs nightly and records {@code NOT_EXECUTABLE} with its
* reason — but the registry, the support document and the release workflow could each be read end
* to end without establishing that. A reader who cannot find the lane concludes there is none,
* which is the conclusion this repository's own review pass reached before checking the workflow
* directory.
*
* <p>The target is read from the workflow matrix declaration rather than from its filename. The
* status artifact receives that same matrix value through {@code TARGET}; a lane that stops
* declaring its PostgreSQL target therefore stops counting as a lane.
* <p>The target is read from the workflow matrix declaration rather than from a job name. The
* job's NOT_EXECUTABLE line prints that same matrix value; a lane that stops declaring its
* PostgreSQL target therefore stops counting as a lane.
*/
public static List<Integer> compatibilityLaneTargets(String workflow) {
Objects.requireNonNull(workflow, "workflow");
@@ -5,8 +5,10 @@
허락하는지.
넷 모두 Redis 7.4에서 돌았고 증거는 `docs/redis/support-matrix.md`에 적혀 있다.
`.github/workflows/redis-sdk-topology.yml`은 Redis leaf를 건드리는 pull request마다 standalone lane을, 매일 밤
지원 버전 × topology 표 전체를, 릴리스 후보에는 요청할 때 같은 표를 돌린다.
`.gitea/workflows/main.yml`의 nightly `redis-topology` job이 매일 밤(그리고 손으로 실행할 때) 지원 버전 × topology 표
전체를 행마다 `scripts/ci/redis-topology.sh <topology> <version>`으로 돌린다. 같은 줄을 Docker가 있는 머신에서
손으로 돌릴 수 있다. pull request마다 돌던 standalone lane은 2026-11-08에 nightly로 옮겼다(어댑터 컨테이너 lane은
main 단계, 소유자 결정 2026-11-07).
TLS는 손으로 배선할 것이 아니라 그 표의 lane 하나다. 배포 모드가 아니라 `tls`다: 모양은 standalone이고 검증하는
것은 전송이다. 그래서 `redisTopologyTest`는 시험에서 lane 이름을 `standalone`으로 대응시키고, tag 필터와 필요한
+2 -2
View File
@@ -333,13 +333,13 @@ dependencies {
// leaves it up to date
//
// The pull-request lane exists because some of those contracts are release and security
// properties — the signing job's OIDC scope, the Docker staging contract, the request-logging body
// properties — the signing job's key handling, the Docker staging contract, the request-logging body
// capture ban — that must stop a merge, not be found after one.
def repositoryRootForContractTests = rootProject.projectDir.parentFile
def repositoryContractExcludes = ['**/build/**', '**/.gradle/**', '**/node_modules/**']
def repositoryContractInputs = files(
fileTree(repositoryRootForContractTests) {
include '.github/**', 'compose/**', 'scripts/**', '*.yml', '*.yaml', '*.example', '.tool-versions'
include '.gitea/**', '.github/**', 'compose/**', 'scripts/**', '*.yml', '*.yaml', '*.example', '.tool-versions'
exclude '**/*.md'
exclude repositoryContractExcludes
},
+10 -5
View File
@@ -74,21 +74,23 @@ services:
disable: true
# Do not restart automatically so crash loops stay visible.
restart: "no"
# Optional: mount heap dump directory to host for dev analysis.
# Heap dumps survive the container that wrote them.
# The base declares /var/tmp/heap as a tmpfs, which is right for an ephemeral runtime and wrong
# for dev: a heap dump written into a tmpfs dies with the container that produced it, which is
# the one moment somebody wants the file. Compose refuses to have both, and correctly — it will
# not silently pick one — so the tmpfs list is replaced rather than appended to.
#
# A named volume, not a bind mount of ./tmp/heap-dumps: Docker created that folder as root inside
# the checkout, and a git worktree holding it could not be removed without root. Copy a dump out
# with `docker compose cp app:/var/tmp/heap/<file> .` or read it from the volume.
#
# `!override` needs Compose >= 2.24.4. An empty sequence is not assumed to delete the base
# sequence by itself; scripts/verify-compose-profile-contracts.sh checks mount-target uniqueness
# in the merged model, which is what actually proves the collision is gone.
volumes:
- type: bind
source: ./tmp/heap-dumps
- type: volume
source: heap-dumps
target: /var/tmp/heap
bind:
create_host_path: true
# The same network the shared infrastructure lives on. The local stack (now compose.yaml) joins it and the dev
# overlay did not, so a dev lane that started PostgreSQL beside the application put the two on
# different networks: `UnknownHostException: db`, from a container that was running and healthy
@@ -102,3 +104,6 @@ networks:
# Defined in compose.yaml, where the services that share it live.
caskeleton-infra:
external: false
volumes:
heap-dumps:
@@ -17,10 +17,10 @@ import org.junit.jupiter.api.Test;
*
* <p>A stack that cannot merge has no failure mode short of total: nothing starts, and the error
* arrives at the moment somebody most wants the environment. The dev stack was in exactly that
* state — the base declares {@code /var/tmp/heap} as a tmpfs, the dev overlay bind-mounts the same
* target so heap dumps survive on the host, and the overlay\'s {@code tmpfs: []} merged with the
* base list instead of replacing it. {@code !override} replaces it, and the merged model is checked
* for duplicate mount targets rather than the fix being assumed from the syntax.
* state — the base declares {@code /var/tmp/heap} as a tmpfs, the dev overlay mounts a volume at
* the same target so heap dumps survive the container, and the overlay\'s {@code tmpfs: []} merged
* with the base list instead of replacing it. {@code !override} replaces it, and the merged model
* is checked for duplicate mount targets rather than the fix being assumed from the syntax.
*/
class ComposeMergeCharacterizationTest {
@@ -32,6 +32,9 @@ import org.yaml.snakeyaml.constructor.SafeConstructor;
class DeveloperExperienceContractTest {
private static final Path REPOSITORY_ROOT = repositoryRoot();
private static final String PR_WORKFLOW = ".gitea/workflows/pr.yml";
private static final String MAIN_WORKFLOW = ".gitea/workflows/main.yml";
private static final String RELEASE_WORKFLOW = ".gitea/workflows/release.yml";
// The workflow-mutation fixtures that stood here are gone with the tests that used them: a
// hex-escaped `uses:`, a line-continued action reference, a `run:` block impersonating a
@@ -143,47 +146,26 @@ class DeveloperExperienceContractTest {
@Test
@Tag("repository-contract")
void linkCheckIsBlockingAndUsesThePinnedLycheeAction() throws IOException {
String workflow = read(".github/workflows/link-check.yml");
@DisplayName("링크 검사는 main 단계 job 하나가 고정한 lychee action으로 정해진 문서 범위를 실패하게 검사한다")
void linkCheckScansTheExactDocumentationScopeAndFails() throws IOException {
// given
Map<?, ?> links = requireMap(requireMap(parseYamlMap(read(MAIN_WORKFLOW)), "jobs"), "links");
assertThat(workflow).contains("lycheeverse/lychee-action@v2.0.2").contains("fail: true");
}
@Test
@Tag("repository-contract")
void linkCheckTriggersAndScansTheExactDocumentationScope() throws IOException {
List<String> expectedPaths =
List.of(
"README.md",
"src/README.md",
"src/**/README.md",
"src/**/CLAUDE.md",
"docs/**/*.md",
".github/**/*.md",
".github/workflows/link-check.yml");
Map<?, ?> workflow = parseYamlMap(read(".github/workflows/link-check.yml"));
Map<?, ?> triggers = requireMap(workflow, workflow.containsKey("on") ? "on" : true);
assertThat(triggers.keySet().stream().map(String::valueOf).toList())
.containsExactlyInAnyOrder("pull_request", "push", "workflow_dispatch");
assertThat(requireStringList(requireMap(triggers, "pull_request"), "paths"))
.containsExactlyElementsOf(expectedPaths);
Map<?, ?> push = requireMap(triggers, "push");
assertThat(requireStringList(push, "branches")).containsExactly("main");
assertThat(requireStringList(push, "paths")).containsExactlyElementsOf(expectedPaths);
Map<?, ?> lycheeJob = requireMap(requireMap(workflow, "jobs"), "lychee");
List<?> steps = requireList(lycheeJob, "steps");
// when
Map<?, ?> lycheeStep =
steps.stream()
requireList(links, "steps").stream()
.filter(Map.class::isInstance)
.map(Map.class::cast)
.filter(
step ->
"lycheeverse/lychee-action@7cd0af4c74a61395d455af97419279d86aafaede"
.equals(step.get("uses")))
.filter(step -> String.valueOf(step.get("uses")).contains("lychee-action@"))
.findFirst()
.orElseThrow(() -> new AssertionError("missing pinned lychee action step"));
.orElseThrow(() -> new AssertionError("missing lychee action step"));
// then
assertThat(links.containsKey("if"))
.as("a conditional link check is one nobody sees run")
.isFalse();
assertThat(String.valueOf(lycheeStep.get("uses")))
.endsWith("lycheeverse/lychee-action@7cd0af4c74a61395d455af97419279d86aafaede");
Map<?, ?> with = requireMap(lycheeStep, "with");
assertThat(with.get("fail")).isEqualTo(true);
assertThat(shellWords(requireString(with, "args")))
@@ -204,8 +186,9 @@ class DeveloperExperienceContractTest {
void testcontainersReuseIsLocalOptInAndExplicitlyDisabledInCi() throws IOException {
assertThat(read("testcontainers.properties.example"))
.contains("testcontainers.reuse.enable=true");
assertThat(read(".github/workflows/ci-quality-gates.yml"))
.contains("TESTCONTAINERS_REUSE_ENABLE: \"false\"");
for (String workflow : List.of(PR_WORKFLOW, MAIN_WORKFLOW, RELEASE_WORKFLOW)) {
assertThat(read(workflow)).as(workflow).contains("TESTCONTAINERS_REUSE_ENABLE: \"false\"");
}
}
@Test
@@ -226,7 +209,7 @@ class DeveloperExperienceContractTest {
//
// The wrapper guarantee itself is unchanged and is now the official action's:
// gradle/actions/setup-gradle validates every wrapper jar in the repository by default, it is
// applied through .github/actions/setup-gradle-java, and it is pinned to a full commit SHA.
// applied through .gitea/actions/setup-java-gradle, and it is pinned to a full commit SHA.
// What is left to assert here is what that action cannot: that the wrapper is committed, and
// that its distribution is pinned by checksum rather than by URL alone.
assertThat(REPOSITORY_ROOT.resolve("src/gradle/wrapper/gradle-wrapper.jar")).isRegularFile();
@@ -238,13 +221,14 @@ class DeveloperExperienceContractTest {
.contains("validateDistributionUrl=true")
.contains("https\\://services.gradle.org/distributions/");
String setupAction = read(".github/actions/setup-gradle-java/action.yml");
String setupAction = read(".gitea/actions/setup-java-gradle/action.yml");
assertThat(setupAction)
.as("wrapper validation has to be reachable from every Gradle job")
.contains("gradle/actions/setup-gradle@");
assertThat(setupAction)
.as("an action reference is only immutable when it is a full commit SHA")
.containsPattern("uses: [\\w./-]+@[0-9a-f]{40} #");
.containsPattern("uses: [\\w.:/-]+@[0-9a-f]{40} #")
.doesNotContainPattern("uses: [\\w.:/-]+@(?![0-9a-f]{40} )");
}
@Test
@@ -287,18 +271,13 @@ class DeveloperExperienceContractTest {
void architectureWorkflowSelectorsUseTheArchitectureSourceSetTask() throws IOException {
String staleSelector = ":app-bootstrap:test --tests 'dev.caskeleton.bootstrap.architecture.*'";
// The whole-repository architecture suite runs once per pull request, in ci-quality-gates.yml's
// `:ci` (architectureCheck). The fileserver workflow's filtered second run was removed (review
// BUILD-중복-6), and the release workflow runs only the tag-only releaseCheck.
assertThat(read(".github/workflows/ci-quality-gates.yml"))
.as("the pull-request gate is the one place the architecture suite runs")
.contains("./gradlew :ci");
assertThat(read(".github/workflows/fileserver-pr.yml"))
.as("the fileserver PR workflow must not repeat the architecture suite")
.doesNotContain(":app-bootstrap:architectureTest")
// The whole-repository architecture suite runs once per pull request, in pr.yml's `:prCheck`
// (`ci` -> architectureCheck), and the release workflow runs only the tag-only releaseCheck.
assertThat(read(PR_WORKFLOW))
.as("the pull-request stage is the one place the architecture suite runs")
.contains("./gradlew :prCheck")
.doesNotContain(staleSelector);
assertThat(read(".github/workflows/release.yml"))
assertThat(read(RELEASE_WORKFLOW))
.as("the release workflow runs the tag-only checks through releaseCheck")
.contains("./gradlew :releaseCheck")
.doesNotContain(staleSelector);
@@ -321,29 +300,23 @@ class DeveloperExperienceContractTest {
@Test
@Tag("repository-contract")
@DisplayName("릴리스 이미지는 서명 job 하나만 OIDC 토큰을 받아 digest를 keyless 서명하고 검증한다")
void onlyTheSigningJobHoldsAnOidcTokenAndItSignsAndVerifiesTheDigest() throws IOException {
@DisplayName("릴리스 이미지는 태그에서만 서명 job 하나가 키 쌍으로 digest를 서명하고 검증한다")
void onlyTheSigningJobHoldsTheReleaseKeyAndItSignsAndVerifiesTheDigest() throws IOException {
// given
Map<?, ?> workflow = parseYamlMap(read(".github/workflows/release.yml"));
Map<?, ?> jobs = requireMap(workflow, "jobs");
Map<?, ?> jobs = requireMap(parseYamlMap(read(RELEASE_WORKFLOW)), "jobs");
// when
List<String> jobsWithIdToken =
List<String> jobsWithTheKey =
jobs.entrySet().stream()
.filter(
job ->
job.getValue() instanceof Map<?, ?> body
&& body.get("permissions") instanceof Map<?, ?> permissions
&& permissions.containsKey("id-token"))
.filter(job -> String.valueOf(job.getValue()).contains("secrets.COSIGN_PRIVATE_KEY"))
.map(job -> String.valueOf(job.getKey()))
.toList();
// then
assertThat(requireMap(workflow, "permissions").containsKey("id-token")).isFalse();
assertThat(jobsWithIdToken).containsExactly("app-image-signing");
assertThat(jobsWithTheKey).containsExactly("app-image-signing");
Map<?, ?> signing = requireMap(jobs, "app-image-signing");
assertThat(requireMap(signing, "permissions").get("id-token")).isEqualTo("write");
assertThat(requireStringList(signing, "needs")).containsExactly("app-image-release");
assertThat(requireString(signing, "if")).contains("github.ref_type == 'tag'");
String script =
String.join(
"\n",
@@ -354,9 +327,8 @@ class DeveloperExperienceContractTest {
assertThat(script)
.contains("cosign_checksums.txt")
.contains("sha256sum -c -")
.contains("cosign sign --yes")
.contains("cosign verify")
.contains("--certificate-oidc-issuer https://token.actions.githubusercontent.com");
.contains("cosign sign --yes --key env://COSIGN_PRIVATE_KEY")
.contains("cosign verify --key");
assertThat(requireList(signing, "steps"))
.as("the signing job installs a checksum-pinned binary, not a third-party action")
.noneMatch(step -> step instanceof Map<?, ?> map && map.containsKey("uses"));
+5 -9
View File
@@ -7,7 +7,7 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge, 그리고 별도 repo 라이브러리 edge(맨 위 `library_groups`, 행마다 `allowed_libraries`. 계층 leaf 행은 비워 둔다. 설명은 `src/config/architecture/README.md`). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다.
- `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다.
- `src/build-logic/`: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(`strictTestLanes`). leaf는 `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. `ca.architecture`가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다.
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전·리비전.
- `src/build.gradle`: 루트 라이프사이클(`ci`, `prCheck`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 그것을 workflow job에 묶는 `strictLaneStages`, 버전·리비전.
## 저장소 파일을 읽는 테스트
@@ -23,15 +23,11 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을
- `PERFORMANCE` lane은 상한을 매번 단언한다. 끄는 스위치가 없다. convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도). 사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의 `ca.config-contract`다.
## `verifyStrictLaneStages`가 세는 명령
## 단계 job의 모양
`verifyStrictLaneStages --dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는 단계(`ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈 줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. `-x`로 뺀 lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·`-m`·`-v`·`--help`·`--status`·`--stop`·`--foreground`, 묶음 `-qm`·`-qv` 포함)과 Gradle이 거부하는 짧은 옵션 묶음(`-mx`), 다른 빌드를 실행하는 명령은 세지 않는다. 그 밖에 세지 않는 명령은 이유가 셋이다.
1. 실패해도 단계가 실패하지 않을 수 있다: `|| exit <0 아닌 값>` 밖의 `||`(`|| true` 등), pipefail 없는 파이프 왼쪽, `!`, `&`, `if`·`while` 조건, 스크립트 마지막이 아닌 `&&` 목록의 앞쪽, `set +e` 뒤, `exit 0` 하는 `EXIT`·`ERR` trap 뒤, `continue-on-error`.
2. 돌지 않을 수 있다: `||` 뒤, 마지막이 아닌 `&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나 부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태 함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만 시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore` 필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches` 없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이 부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job.
3. 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른 명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤, `bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`).
실패 메시지는 명령마다 이유를 적고 단계 명령을 혼자 한 줄로 두라고 안내한다. 명령이 어느 빌드를 실행하는지는 `working-directory`에서 시작해 같은 셸이 그 앞에서 확실히 실행한 `cd <상대 경로>`를 따라간 뒤 `-p`를 합친 디렉터리로 정한다.
- `verifyStrictLaneStages --dry-run`(PR)은 `explicitOnly`가 아닌 strict lane마다 `src/build.gradle`의 `strictLaneStages`가 선언한 단계 태스크 하나의 계획에 들어 있는지 본다(그래프 검사).
- 단계마다 선언한 workflow job은 step의 `run: ./gradlew <단계> <옵션>` 줄을 가지고, 다른 step `run:`도 셸 문법 없는 `./gradlew` 한 줄이며, 선언 밖의 `if:`, 선언한 조건이 `!cancelled()`·`always()`가 아닌데 `needs:`, `continue-on-error`·`shell:`·`defaults:`, 따옴표 키·flow 형식, 이 빌드 밖의 `working-directory`가 없다. workflow는 선언한 이벤트로, 선언한 필터 한 줄만 달고 시작하고, PR 단계 job 하나가 이 검사를 돌린다(형식 검사, 셸을 해석하지 않는다).
- 단계를 더하거나 job을 바꾸면 `strictLaneStages`의 `stage` 줄과 workflow를 같은 커밋에서 고친다.
## 테스트
File diff suppressed because one or more lines are too long
-4
View File
@@ -96,8 +96,4 @@ gradlePlugin {
tasks.named('test') {
useJUnitPlatform()
// GradleCommandLineTest runs the launcher of the Gradle that runs this build — the distribution
// the workflows' ./gradlew starts — and holds the workflow reader's copy of its command-line
// options to it (review 2026-11-05 RR6-04-02).
systemProperty 'ca.gradle.home', gradle.gradleHomeDir.absolutePath
}
@@ -65,7 +65,7 @@ public final class RedisTopologyLanePlugin implements Plugin<Project> {
// so rather than failing on an input it was never given (review NEW-16).
lane.explicitOnly(
"it needs -Predis.topology.mode=<standalone|sentinel|cluster|tls> and the topology"
+ " coordinates from redis-sdk/compose (redis-sdk-topology.yml passes them)");
+ " coordinates from redis-sdk/compose (scripts/ci/redis-topology.sh passes them)");
}
lane.setTag("redis-topology & lane-" + declaredMode);
lane.setDescription(
@@ -1,29 +1,83 @@
package dev.caskeleton.buildlogic.strictlane;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.gradle.api.GradleException;
import org.gradle.api.file.DirectoryProperty;
import org.gradle.api.provider.ListProperty;
/**
* The stages a strict lane may belong to, and where the workflows that run them live.
* The stages a strict lane may belong to, and the one workflow job that runs each of them.
*
* <p>A stage is a task path a workflow executes ({@code :ci}, {@code :mainCheck}, ...). Every strict
* lane that is not {@code explicitOnly} must be in the plan of at least one stage, and every stage
* must be executed — not merely planned with {@code --dry-run} — by at least one workflow.
* <pre>
* strictLaneStages {
* workflowDirectory = layout.projectDirectory.dir('../.gitea/workflows')
* stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle'
* stage ':mainCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]',
* job: 'main', options: '--continue'
* stage ':performanceCheck', workflow: 'main.yml', event: 'schedule', job: 'performance',
* options: '--continue', condition: '${{ !cancelled() }}'
* }
* </pre>
*
* <p>The job runs the stage as {@code ./gradlew <stage> <options>} on a line of its own. {@code
* filter} is the one line under the event (none if absent; a schedule takes its cron lines), and
* {@code condition} is the job's {@code if:}: both are written out here so that changing when a
* stage runs is a reviewed change of the build rather than an edit to a workflow. Single quotes,
* because Groovy reads {@code ${...}} in double quotes as its own expression.
*/
public abstract class StrictLaneStagesExtension {
public abstract ListProperty<String> getStages();
/** The options a stage line may carry: none of them changes which tasks run. */
static final Set<String> STAGE_OPTIONS = Set.of("--continue", "--stacktrace");
/**
* The repository's {@code .github/workflows}. Its grandparent is the repository root, and a
* command executes this build's stages only when it starts in this build's directory from there
* — its step's {@code working-directory} joined with its {@code -p}. The directory is read from
* where the build is, so no build states it (review 2026-11-04 RR2-04-04: a {@code -p} value
* alone missed {@code working-directory: src/platforms/optional-build} with {@code ../gradlew}, in
* the optional gRPC build that has since moved to its own repository).
*/
private final List<Stage> stages = new ArrayList<>();
/** The repository's workflow directory. Its grandparent is the repository root. */
public abstract DirectoryProperty getWorkflowDirectory();
public void stage(String... taskPaths) {
getStages().addAll(taskPaths);
public void stage(Map<String, String> job, String taskPath) {
Stage stage =
new Stage(
taskPath,
required(job, "workflow", taskPath),
required(job, "event", taskPath),
job.get("filter"),
required(job, "job", taskPath),
job.getOrDefault("options", ""),
job.get("condition"));
for (String option : stage.options().split(" ", -1)) {
if (!option.isEmpty() && !STAGE_OPTIONS.contains(option)) {
throw new GradleException(
"stage " + taskPath + ": option " + option + " is not one of " + STAGE_OPTIONS);
}
}
stages.add(stage);
}
List<Stage> getStages() {
return List.copyOf(stages);
}
private static String required(Map<String, String> job, String key, String taskPath) {
String value = job.get(key);
if (value == null || value.isBlank()) {
throw new GradleException("stage " + taskPath + " needs '" + key + "'");
}
return value;
}
/** One stage and the workflow job that runs it. */
record Stage(
String taskPath,
String workflow,
String event,
String filter,
String job,
String options,
String condition) {
String command() {
return options.isEmpty() ? "./gradlew " + taskPath : "./gradlew " + taskPath + " " + options;
}
}
}
@@ -5,16 +5,16 @@ import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Comparator;
import java.util.Deque;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.gradle.api.GradleException;
import org.gradle.api.Plugin;
import org.gradle.api.Project;
@@ -22,63 +22,51 @@ import org.gradle.api.Task;
import org.gradle.api.execution.TaskExecutionGraph;
/**
* Fails when a strict lane belongs to no stage a workflow executes.
* Fails when a strict lane belongs to no stage, or when a stage's workflow job does not run it.
*
* <p>A strict lane fails closed when it runs, but nothing makes it run: a lane that no workflow
* reaches is a file that looks like coverage (review 2026-11-01 08-01 found fourteen). The rule is
* stated once, here, instead of as one workflow line per lane:
* reaches is a file that looks like coverage (review 2026-11-01 08-01 found fourteen). Two checks
* answer that, both with fixed rules rather than by interpreting shell:
*
* <ol>
* <li>every strict lane that is not {@code explicitOnly} is in the task plan of a declared stage
* as a workflow runs it — a lane the command removes with {@code -x} is not covered, matched
* the way Gradle matches it, abbreviations included ({@link TaskSelectors});
* <li>every declared stage is executed by a workflow. Not counted ({@code NOT_COUNTED}; review
* 2026-11-03 RR-06-04, 2026-11-04 RR2-04-04, RR5-02-02, 2026-11-05 RR6-04-01..06, 2026-11-06
* RR7-05-01, owner decision 2026-11-07 on the release flow): a command
* after which Gradle runs no task ({@code --dry-run}, {@code -v}, {@code --help}, …) or that
* Gradle rejects (a short-option bundle such as {@code -mx}), one for another build, and one
* that does not gate for one of three reasons — its failure may not fail its step, it may not
* run, or this check does not read it although its failure would fail the step ({@code
* WorkflowGradleInvocations} and {@code ShellScript} name the shapes).
* <li><b>Graph.</b> Every strict lane that is not {@code explicitOnly} is in the task plan of a
* declared stage. The plan is Gradle's own: this task depends on the stages, so its {@code
* --dry-run} builds the real plan, and the check reads it when the graph is ready.
* <li><b>Form.</b> Each stage names the workflow job that runs it, and that job has one shape.
* Its steps' {@code run:} lines are single {@code ./gradlew} commands with no shell syntax, and
* one of them is {@code ./gradlew <stage> <options>}. It has no {@code if:} but the declared
* condition, no {@code needs:} unless that condition runs it after a skipped or failed job, no
* {@code continue-on-error}, {@code shell:} or {@code defaults:}, no quoted keys or flow
* mappings, and every {@code working-directory} in it or in the workflow's {@code defaults}
* is this build's. The workflow starts on the declared event with exactly the declared filter
* (a misspelt branch is a filter too). One pull-request stage job also runs this check.
* </ol>
*
* <p>A build that holds strict lanes applies it at its root (here, the main build; until 2026-11-08
* the optional gRPC platform build applied it too). A command executes this build when it starts
* in this build's directory — its step's {@code working-directory}, moved by the {@code cd}
* commands the same shell surely
* ran before it, joined with its {@code -p}, from the repository root, which is where GitHub keeps
* {@code .github/workflows} ({@code ShellScript} says which {@code cd} it follows).
* A stage named only by commands that do not count is reported with each command's reason. Applied
* to the main build only, it said "every strict lane" while the optional build's performance lane
* ran nowhere (RR-06-03).</p>
* <p>Until 2026-11-08 the second half read every workflow's shell with a general interpreter, which
* produced a new defect in nearly every review round. A narrow form needs no interpreter: a job that
* does not have it fails here, on its own pull request.
*
* <p>The task plan is Gradle's own: {@code verifyStrictLaneStages} depends on the stages, so a
* {@code --dry-run} of it builds the real plan, and the check reads it when the graph is ready. It
* refuses to run without {@code --dry-run}, which would execute every stage.
* <p>It refuses to run without {@code --dry-run}, which would execute every stage.
*/
public final class StrictLaneStagesPlugin implements Plugin<Project> {
public static final String TASK_NAME = "verifyStrictLaneStages";
/** What a failure names as not counted, in the three reasons the readers give, and what to do. */
static final String NOT_COUNTED =
"Not counted: a command after which Gradle runs no task (--dry-run, -m, -v, --help,"
+ " --status, ...) or that Gradle rejects (a short-option bundle such as -mx), and one"
+ " for another build; one whose failure may not fail its step (|| true, a pipe without"
+ " pipefail, !, &, an if/while condition, the part before && of a list that is not the"
+ " script's last command, after set +e or a trap that exits 0, continue-on-error); one"
+ " that may not run (after ||, inside if/while/for/case or a function, after an exit 0,"
+ " exec or set -n, under an if: other than always()/success()/!cancelled(), in a"
+ " workflow that starts only on a request, or on changes only through a paths or"
+ " paths-ignore filter, or a reusable one no counted job calls, in a"
+ " job that needs a job that may be skipped, and for any stage but :releaseCheck in a"
+ " workflow that starts only on a tag push or a release); and one this check does not"
+ " read although"
+ " its failure"
+ " would fail the step (|| exit 1, inside { } or ( ), $( ), bash -c, gradlew as"
+ " another command's argument, after a cd it does not follow, a shell other than bash"
+ " or sh, a runner that may be Windows). Run the stage as ./gradlew on a line of its"
+ " own, in a step and job that run on every push, pull request or schedule, with no"
+ " paths or paths-ignore filter (:releaseCheck may run on a tag push or a release)";
/** The command a pull-request stage job runs so that this check itself runs. */
static final String SELF_CHECK = "./gradlew :" + TASK_NAME + " --dry-run";
private static final Pattern ANY_RUN = Pattern.compile("^\\s*(?:-\\s+)?run:");
/** A step's command: `- run:` at the step indent, or `run:` under a step's first key. */
private static final Pattern STEP_RUN = Pattern.compile("^(?: {6}- | {8})run: (.*?)\\s*$");
/** One Gradle invocation and nothing a shell would read as more than words. */
private static final Pattern GRADLE_LINE = Pattern.compile("^\\./gradlew(?: [\\w:.=-]+)+$");
private static final Pattern IF = Pattern.compile("^(\\s*)(?:-\\s+)?if:\\s*(.*?)\\s*$");
private static final Pattern WORKING_DIRECTORY =
Pattern.compile("^\\s*(?:-\\s+)?working-directory:\\s*(.*?)\\s*$");
private static final Pattern FORBIDDEN_IN_JOB =
Pattern.compile("^\\s*(?:-\\s+)?(continue-on-error|shell|defaults):");
private static final Pattern NEEDS = Pattern.compile("^ {4}needs:");
private static final Pattern QUOTED_KEY = Pattern.compile("^\\s*(?:-\\s+)?[\"'][^\"']*[\"']\\s*:");
private static final Pattern EXPRESSION = Pattern.compile("\\$\\{\\{.*?}}");
@Override
public void apply(Project project) {
@@ -95,12 +83,18 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
task -> {
task.setGroup("verification");
task.setDescription(
"Fails when a strict lane is in no stage a workflow executes. Run with --dry-run.");
"Fails when a strict lane is in no stage or a stage's workflow job does not"
+ " run it. Run with --dry-run.");
task.notCompatibleWithConfigurationCache(
"the check reads the task graph itself, which a cached entry does not rebuild");
});
project.afterEvaluate(
ignored -> verify.configure(task -> task.dependsOn(extension.getStages().get().toArray())));
ignored ->
verify.configure(
task ->
extension
.getStages()
.forEach(stage -> task.dependsOn(stage.taskPath()))));
project
.getGradle()
.getTaskGraph()
@@ -110,207 +104,275 @@ public final class StrictLaneStagesPlugin implements Plugin<Project> {
if (!graph.hasTask(task)) {
return;
}
List<StrictLaneStagesExtension.Stage> stages = extension.getStages();
if (!project.getGradle().getStartParameter().isDryRun()) {
throw new GradleException(
TASK_NAME
+ " checks the plan of "
+ extension.getStages().get()
+ stages.stream().map(StrictLaneStagesExtension.Stage::taskPath).toList()
+ " and would execute all of them; run it with --dry-run.");
}
File workflowDirectory = extension.getWorkflowDirectory().get().getAsFile();
List<String> problems =
problems(
project,
graph,
extension.getStages().get(),
workflowDirectory,
buildDirectory(project, workflowDirectory));
List<String> problems = new ArrayList<>(laneProblems(project, graph, stages));
String buildDirectory = buildDirectory(project, workflowDirectory);
boolean selfChecked = false;
for (StrictLaneStagesExtension.Stage stage : stages) {
Path workflow = workflowDirectory.toPath().resolve(stage.workflow());
problems.addAll(formProblems(workflow, buildDirectory, stage));
selfChecked |=
stage.event().equals("pull_request") && runs(workflow, stage, SELF_CHECK);
}
if (!selfChecked) {
problems.add(
"no pull_request stage job runs `"
+ SELF_CHECK
+ "`; without it nothing checks the stages on a pull request");
}
if (!problems.isEmpty()) {
throw new GradleException(
TASK_NAME
+ ": "
+ problems.size()
+ " problem(s). A lane no executed stage reaches runs nowhere; put it in a"
+ " stage, or declare explicitOnly(\"reason\") if it needs an input no stage"
+ " has.\n - "
+ " problem(s). A lane no stage reaches runs nowhere; put it in a stage, or"
+ " declare explicitOnly(\"reason\") if it needs an input no stage has. A"
+ " stage job runs `./gradlew <stage>` on a line of its own.\n - "
+ String.join("\n - ", problems));
}
project
.getLogger()
.lifecycle(
TASK_NAME + ": every strict lane is in an executed stage.");
.lifecycle(TASK_NAME + ": every strict lane is in a stage its workflow job runs.");
});
}
private static List<String> problems(
Project root,
TaskExecutionGraph graph,
List<String> stages,
File workflowDirectory,
String buildDirectory) {
List<String> problems = new ArrayList<>(foldedCommandBreaks(workflowDirectory));
Map<String, List<WorkflowGradleInvocations.Invocation>> invocationsByWorkflow =
invocations(workflowDirectory);
List<WorkflowGradleInvocations.Invocation> invocations =
invocationsByWorkflow.values().stream().flatMap(List::stream).toList();
// Only an executed stage covers a lane — a stage no workflow runs is the same gap one level
// up — and only as the command runs it: what its -x removes is not covered.
Map<String, Set<String>> tasksByProject = new LinkedHashMap<>();
root.getAllprojects()
.forEach(
project -> tasksByProject.put(project.getPath(), Set.copyOf(project.getTasks().getNames())));
Map<String, Set<String>> plans = new LinkedHashMap<>();
for (String stage : stages) {
List<WorkflowGradleInvocations.Invocation> executions =
invocations.stream()
.filter(invocation -> invocation.executes(stage, buildDirectory))
.toList();
if (executions.isEmpty()) {
problems.add(
"stage "
+ stage
+ " is executed by no workflow in "
+ workflowDirectory.getName()
+ " for the build in "
+ buildDirectory
+ ". "
+ NOT_COUNTED
+ notCounted(invocationsByWorkflow, stage, buildDirectory));
continue;
}
Task stageTask = root.getTasks().findByPath(stage);
int run = 0;
for (WorkflowGradleInvocations.Invocation execution : executions) {
Set<String> excluded =
TaskSelectors.excludedPaths(execution.excludedTasks(), tasksByProject);
plans.put(
stage + "#" + run++, stageTask == null ? Set.of() : plan(graph, stageTask, excluded));
private static List<String> laneProblems(
Project root, TaskExecutionGraph graph, List<StrictLaneStagesExtension.Stage> stages) {
Set<String> planned = new HashSet<>();
for (StrictLaneStagesExtension.Stage stage : stages) {
Task stageTask = root.getTasks().findByPath(stage.taskPath());
if (stageTask != null) {
planned.addAll(plan(graph, stageTask));
}
}
List<String> lanes = new ArrayList<>();
List<String> problems = new ArrayList<>();
root.getAllprojects().stream()
.sorted(Comparator.comparing(Project::getPath))
.forEach(
project -> {
StrictTestLaneExtension lanesOf =
StrictTestLaneExtension lanes =
project.getExtensions().findByType(StrictTestLaneExtension.class);
if (lanesOf == null) {
if (lanes == null) {
return;
}
lanesOf.getLanes().stream()
lanes.getLanes().stream()
.filter(lane -> lane.getExplicitOnlyReason() == null)
.map(lane -> taskPath(project, lane.getName()))
.sorted()
.forEach(lanes::add);
.filter(lane -> !planned.contains(lane))
.forEach(
lane ->
problems.add(
"strict lane "
+ lane
+ " is in no stage of "
+ stages.stream()
.map(StrictLaneStagesExtension.Stage::taskPath)
.toList()));
});
for (String lane : lanes) {
if (plans.values().stream().noneMatch(plan -> plan.contains(lane))) {
problems.add("strict lane " + lane + " is in no executed stage of " + stages);
return problems;
}
/** What the stage job must look like; each problem names the file and job. */
static List<String> formProblems(
Path workflow, String buildDirectory, StrictLaneStagesExtension.Stage stage) {
String file = workflow.getFileName().toString();
String where = file + " job " + stage.job();
if (!Files.exists(workflow)) {
return List.of(file + " does not exist; nothing runs " + stage.taskPath());
}
List<String> lines = read(workflow);
List<String> problems = new ArrayList<>();
List<String> triggers = block(lines, "on:", 0);
if (!triggers.contains(" " + stage.event() + ":")) {
problems.add(file + " does not start on " + stage.event());
} else {
List<String> filter = content(block(triggers, " " + stage.event() + ":", 2));
boolean exact =
stage.event().equals("schedule")
? !filter.isEmpty() && filter.stream().allMatch(line -> line.startsWith("- cron:"))
: filter.equals(stage.filter() == null ? List.of() : List.of(stage.filter()));
if (!exact) {
problems.add(
file
+ " starts on "
+ stage.event()
+ " only with "
+ filter
+ "; the build declares "
+ (stage.filter() == null ? "no filter" : List.of(stage.filter())));
}
}
List<String> defaults = block(lines, "defaults:", 0);
int jobs = lines.indexOf("jobs:");
List<String> job =
jobs < 0
? List.of()
: block(lines.subList(jobs + 1, lines.size()), " " + stage.job() + ":", 2);
if (job.isEmpty()) {
problems.add(where + " does not exist; nothing runs " + stage.taskPath());
return problems;
}
for (String line : defaults) {
if (line.strip().startsWith("shell:")) {
problems.add(file + " sets a default shell, which can hide every run's result");
}
}
List<String> directories = new ArrayList<>(defaults);
directories.addAll(job);
for (String line : directories) {
Matcher directory = WORKING_DIRECTORY.matcher(line);
if (directory.matches() && !directory.group(1).equals(buildDirectory)) {
problems.add(
where
+ " runs in "
+ directory.group(1)
+ ", not in this build's directory "
+ buildDirectory);
}
}
boolean runsStage = false;
boolean waits = false;
List<String> conditions = new ArrayList<>();
for (String line : content(job, false)) {
String bare = EXPRESSION.matcher(line).replaceAll("");
if (bare.contains("{") || bare.contains("}") || QUOTED_KEY.matcher(line).find()) {
problems.add(where + " has `" + line.strip() + "`; write it as a plain block mapping");
continue;
}
if (ANY_RUN.matcher(line).find()) {
Matcher run = STEP_RUN.matcher(line);
if (!run.matches()) {
problems.add(where + " has `" + line.strip() + "`, which is not a step's command");
} else if (!GRADLE_LINE.matcher(run.group(1)).matches()) {
problems.add(where + " runs `" + run.group(1) + "`, which is not one ./gradlew line");
} else {
runsStage |= run.group(1).equals(stage.command());
}
}
Matcher condition = IF.matcher(line);
if (condition.matches()) {
conditions.add(condition.group(1).length() == 4 ? condition.group(2) : line.strip());
}
Matcher forbidden = FORBIDDEN_IN_JOB.matcher(line);
if (forbidden.find()) {
problems.add(where + " has " + forbidden.group(1) + ", which can hide its result");
}
waits |= NEEDS.matcher(line).find();
}
if (!runsStage) {
problems.add(where + " has no line `run: " + stage.command() + "`");
}
List<String> expected = stage.condition() == null ? List.of() : List.of(stage.condition());
if (!conditions.equals(expected)) {
problems.add(
where
+ " has the conditions "
+ conditions
+ "; the build declares "
+ (expected.isEmpty() ? "none" : expected));
}
boolean runsAfterAnything =
stage.condition() != null
&& (stage.condition().contains("!cancelled()")
|| stage.condition().contains("always()"));
if (waits && !runsAfterAnything) {
problems.add(
where
+ " needs other jobs, so a skipped or failed one skips the stage; declare a"
+ " condition with !cancelled() or always()");
}
return problems;
}
/**
* The commands that name {@code stage} but do not execute it for this build, each with why — its
* uncounted reason, the other build it starts (review 2026-11-04 RR5-02-03: a typo in a {@code cd}
* or a {@code cd src} under {@code working-directory: src} is named, not hidden), or a dry run: a
* workflow that calls the stage in a way this check does not count is told so, instead of failing
* as if it never did.
*/
private static String notCounted(
Map<String, List<WorkflowGradleInvocations.Invocation>> invocationsByWorkflow,
String stage,
String buildDirectory) {
List<String> lines = new ArrayList<>();
invocationsByWorkflow.forEach(
(workflow, invocations) ->
invocations.stream()
.filter(invocation -> invocation.requests(stage))
.forEach(
invocation ->
lines.add(
workflow
+ ": gradlew "
+ String.join(" ", invocation.tasks())
+ " — "
+ invocation.whyNotExecuting(stage, buildDirectory))));
return lines.isEmpty()
? ""
: "; commands that name it but do not count:\n " + String.join("\n ", lines);
/** Whether the stage's job has the step {@code run: <command>}. */
private static boolean runs(Path workflow, StrictLaneStagesExtension.Stage stage, String command) {
if (!Files.exists(workflow)) {
return false;
}
List<String> lines = read(workflow);
int jobs = lines.indexOf("jobs:");
if (jobs < 0) {
return false;
}
return block(lines.subList(jobs + 1, lines.size()), " " + stage.job() + ":", 2).stream()
.map(STEP_RUN::matcher)
.anyMatch(run -> run.matches() && run.group(1).equals(command));
}
/** The tasks {@code stage} reaches as a command runs it: what its -x removes is cut off. */
private static Set<String> plan(TaskExecutionGraph graph, Task stage, Set<String> excluded) {
private static List<String> read(Path workflow) {
try {
return Files.readAllLines(workflow, StandardCharsets.UTF_8);
} catch (IOException unreadable) {
throw new UncheckedIOException(unreadable);
}
}
/** The non-blank, non-comment lines, stripped. */
private static List<String> content(List<String> lines) {
return content(lines, true).stream().map(String::strip).toList();
}
private static List<String> content(List<String> lines, boolean ignored) {
return lines.stream()
.filter(line -> !line.isBlank() && !line.strip().startsWith("#"))
.toList();
}
/**
* The lines under {@code header}, a key at {@code indent} spaces, up to the next line at the same
* or a lower indent. Comments and blank lines belong to the block they are in. Job keys are the
* only two-space keys after {@code jobs:} in a workflow, and the first match is the job.
*/
private static List<String> block(List<String> lines, String header, int indent) {
List<String> block = new ArrayList<>();
boolean inside = false;
for (String line : lines) {
if (!inside) {
inside = line.stripTrailing().equals(header);
continue;
}
String content = line.strip();
boolean structural = !content.isEmpty() && !content.startsWith("#");
if (structural && line.length() - line.stripLeading().length() <= indent) {
break;
}
block.add(line);
}
return block;
}
/** The tasks {@code stage} reaches in this build's plan. */
private static Set<String> plan(TaskExecutionGraph graph, Task stage) {
Set<String> seen = new HashSet<>();
Deque<Task> pending = new ArrayDeque<>(List.of(stage));
while (!pending.isEmpty()) {
Task task = pending.pop();
if (!excluded.contains(task.getPath()) && seen.add(task.getPath())) {
if (seen.add(task.getPath())) {
pending.addAll(graph.getDependencies(task));
}
}
return seen;
}
/** A folded run block broken by a blank line runs its options as commands; see the reader. */
private static List<String> foldedCommandBreaks(File workflowDirectory) {
List<String> problems = new ArrayList<>();
for (File file : workflowFiles(workflowDirectory)) {
try {
WorkflowGradleInvocations.foldedCommandBreaks(
Files.readString(file.toPath(), StandardCharsets.UTF_8))
.forEach(problem -> problems.add(file.getName() + " " + problem));
} catch (IOException exception) {
throw new UncheckedIOException("failed to read " + file, exception);
}
}
return problems;
}
private static File[] workflowFiles(File workflowDirectory) {
File[] files =
workflowDirectory.listFiles(
file -> file.getName().endsWith(".yml") || file.getName().endsWith(".yaml"));
if (files == null || files.length == 0) {
throw new GradleException(
TASK_NAME + ": no workflow files in " + workflowDirectory + "; nothing could run a stage.");
}
Arrays.sort(files);
return files;
}
/**
* Each workflow file's Gradle commands, by file name, in file order — read together, because a
* reusable workflow runs only through the workflows that call it (RR6-04-06).
*/
private static Map<String, List<WorkflowGradleInvocations.Invocation>> invocations(
File workflowDirectory) {
Map<String, String> workflows = new LinkedHashMap<>();
for (File file : workflowFiles(workflowDirectory)) {
try {
workflows.put(file.getName(), Files.readString(file.toPath(), StandardCharsets.UTF_8));
} catch (IOException exception) {
throw new UncheckedIOException("failed to read " + file, exception);
}
}
return WorkflowGradleInvocations.readAll(workflows);
}
/**
* This build's directory from the repository root, which holds {@code .github/workflows}: {@code
* src} for the main build.
*/
/** This build's directory from the repository root, the workflow directory's grandparent. */
private static String buildDirectory(Project root, File workflowDirectory) {
File repository = workflowDirectory.getAbsoluteFile().getParentFile().getParentFile();
Path repository = workflowDirectory.getAbsoluteFile().toPath().getParent().getParent();
String relative =
repository
.toPath()
.normalize()
.relativize(root.getRootDir().getAbsoluteFile().toPath().normalize())
.toString()
.replace(File.separatorChar, '/');
return WorkflowGradleInvocations.Invocation.normalized(relative);
return relative.isEmpty() ? "." : relative;
}
private static String taskPath(Project project, String name) {
@@ -1,214 +0,0 @@
package dev.caskeleton.buildlogic.strictlane;
import java.util.Collection;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.TreeSet;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
* Which tasks a command line's {@code -x} selectors remove, matched the way Gradle matches them.
*
* <p>Gradle accepts an abbreviation wherever it accepts a task or project name: {@code -x
* grpcPerformanceT} removes {@code grpcPerformanceTest}, and {@code :g-t:gPT} a task of {@code
* :grpc-testkit}. The workflow reader compared names exactly, so an abbreviated {@code -x} — the
* form people type in a terminal and paste into a workflow — removed a lane from Gradle's plan while
* the stage check still counted it (review 2026-11-04 RR2-04-04).
*
* <p>The matching is a copy of Gradle's {@code org.gradle.util.internal.NameMatcher} (9.0): exact,
* then case-insensitive, then camel-case, then kebab-case abbreviation. It is copied rather than
* called because that class is internal API. Where Gradle would refuse the selector as ambiguous,
* every candidate counts as removed: the command cannot run, so it covers none of them.
*/
final class TaskSelectors {
private static final Pattern CAMEL_CASE_BOUNDARY =
Pattern.compile(
"((^|\\p{Punct})\\p{javaLowerCase}+)|((\\p{javaUpperCase}|\\p{Digit})\\p{javaLowerCase}*)");
private static final Pattern KEBAB_BOUNDARY =
Pattern.compile("((^|\\p{Punct})\\p{javaLowerCase}+)|(\\p{javaUpperCase}\\p{javaLowerCase}*)");
private TaskSelectors() {}
/**
* The paths of the tasks the selectors remove from a command started at the root project.
*
* @param selectors the {@code -x} values, as written
* @param tasksByProject each project's path ({@code :} for the root) and its task names
* @return the removed task paths
*/
static Set<String> excludedPaths(
List<String> selectors, Map<String, ? extends Collection<String>> tasksByProject) {
Set<String> excluded = new LinkedHashSet<>();
for (String selector : selectors) {
excluded.addAll(selected(selector, tasksByProject));
}
return excluded;
}
private static Set<String> selected(
String selector, Map<String, ? extends Collection<String>> tasksByProject) {
Set<String> paths = new LinkedHashSet<>();
if (!selector.contains(":")) {
// A bare name is matched against every task name in the build and removes the task of that
// name in every project.
Set<String> names = new TreeSet<>();
tasksByProject.values().forEach(names::addAll);
for (String name : matches(selector, names)) {
tasksByProject.forEach(
(project, tasks) -> {
if (tasks.contains(name)) {
paths.add(taskPath(project, name));
}
});
}
return paths;
}
String relative = selector.startsWith(":") ? selector.substring(1) : selector;
String[] segments = relative.split(":", -1);
Set<String> projects = Set.of(":");
for (int index = 0; index < segments.length - 1; index++) {
Set<String> next = new LinkedHashSet<>();
for (String project : projects) {
for (String child : matches(segments[index], children(project, tasksByProject.keySet()))) {
next.add(project.equals(":") ? ":" + child : project + ":" + child);
}
}
projects = next;
}
String taskName = segments[segments.length - 1];
for (String project : projects) {
Collection<String> tasks = tasksByProject.get(project);
for (String name : matches(taskName, tasks == null ? List.of() : tasks)) {
paths.add(taskPath(project, name));
}
}
return paths;
}
private static Set<String> children(String project, Set<String> projects) {
String prefix = project.equals(":") ? ":" : project + ":";
Set<String> children = new TreeSet<>();
for (String candidate : projects) {
if (candidate.startsWith(prefix) && candidate.length() > prefix.length()) {
String rest = candidate.substring(prefix.length());
if (!rest.contains(":")) {
children.add(rest);
}
}
}
return children;
}
private static String taskPath(String project, String name) {
return project.equals(":") ? ":" + name : project + ":" + name;
}
/**
* The names {@code pattern} selects among {@code items}: one when Gradle would accept it, several
* when Gradle would refuse it as ambiguous, none when nothing matches.
*/
static Set<String> matches(String pattern, Collection<String> items) {
if (items.contains(pattern)) {
return Set.of(pattern);
}
if (pattern.isEmpty()) {
return Set.of();
}
Pattern camelCase = Pattern.compile(camelCasePattern(pattern));
Pattern camelCaseIgnoringCase =
Pattern.compile(camelCasePattern(pattern), Pattern.CASE_INSENSITIVE | Pattern.UNICODE_CASE);
String kebabCasePattern = kebabCasePattern(pattern);
Pattern kebabCase = Pattern.compile(kebabCasePattern);
Pattern kebabCasePrefix = Pattern.compile(kebabCasePattern + "[\\p{javaLowerCase}\\p{Digit}-]*");
Set<String> ignoringCase = new TreeSet<>();
Set<String> camelCaseWhole = new TreeSet<>();
Set<String> camelCaseStart = new TreeSet<>();
Set<String> camelCaseStartIgnoringCase = new TreeSet<>();
Set<String> kebabCaseWhole = new TreeSet<>();
Set<String> kebabCaseStart = new TreeSet<>();
for (String candidate : items) {
if (candidate.equalsIgnoreCase(pattern)) {
ignoringCase.add(candidate);
}
if (camelCase.matcher(candidate).matches()) {
camelCaseWhole.add(candidate);
}
if (camelCase.matcher(candidate).lookingAt()) {
camelCaseStart.add(candidate);
}
if (camelCaseIgnoringCase.matcher(candidate).lookingAt()) {
camelCaseStartIgnoringCase.add(candidate);
}
if (kebabCase.matcher(candidate).matches()) {
kebabCaseWhole.add(candidate);
}
if (kebabCasePrefix.matcher(candidate).matches()) {
kebabCaseStart.add(candidate);
}
}
Set<String> matches = new TreeSet<>();
if (!ignoringCase.isEmpty()) {
matches.addAll(ignoringCase);
} else if (!camelCaseWhole.isEmpty()) {
matches.addAll(camelCaseWhole);
} else if (!camelCaseStart.isEmpty()) {
matches.addAll(camelCaseStart);
} else if (kebabCaseWhole.isEmpty() && kebabCaseStart.isEmpty()) {
matches.addAll(camelCaseStartIgnoringCase);
}
if (!kebabCaseWhole.isEmpty()) {
matches.addAll(kebabCaseWhole);
} else if (!kebabCaseStart.isEmpty()) {
matches.addAll(kebabCaseStart);
}
return matches;
}
private static String camelCasePattern(String name) {
return pattern(
name,
CAMEL_CASE_BOUNDARY,
(builder, position, part) ->
builder.append(Pattern.quote(part)).append("[\\p{javaLowerCase}]*"));
}
private static String kebabCasePattern(String name) {
return pattern(
name,
KEBAB_BOUNDARY,
(builder, position, part) -> {
if (position > 0) {
builder.append('-');
}
builder
.append(Pattern.quote(part.toLowerCase(Locale.ROOT)))
.append("[\\p{javaLowerCase}\\p{Digit}]*");
});
}
private interface PartWriter {
void write(StringBuilder builder, int position, String part);
}
private static String pattern(String name, Pattern boundary, PartWriter writer) {
Matcher matcher = boundary.matcher(name);
int position = 0;
StringBuilder builder = new StringBuilder();
while (matcher.find()) {
String prefix = name.substring(position, matcher.start());
if (!prefix.isEmpty()) {
builder.append(Pattern.quote(prefix));
}
writer.write(builder, position, matcher.group());
position = matcher.end();
}
if (position < name.length()) {
builder.append(Pattern.quote(name.substring(position)));
}
return builder.toString();
}
}
@@ -1,162 +0,0 @@
package dev.caskeleton.buildlogic.strictlane;
import static org.assertj.core.api.Assertions.assertThat;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.TimeUnit;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
/**
* Holds the workflow reader's copy of Gradle's command-line options to the Gradle that runs this
* build — the distribution the workflows' {@code ./gradlew} starts (review 2026-11-05 RR6-04-01/02).
*
* <p>It runs that distribution's own launcher ({@code bin/gradle}) rather than TestKit: {@code
* --help}, {@code --version}, {@code --status} and {@code --stop} are the launcher's options, and a
* workflow step runs the launcher. An upgrade that adds an option (9.2's {@code --task-graph}) fails
* the first test until the reader is told whether the option takes a value and whether Gradle then
* runs any task.
*/
class GradleCommandLineTest {
/**
* Options the reader reads as ending without a task that this test does not run: {@code --stop}
* stops every daemon of this Gradle version in the user home it is given, and {@code --foreground}
* runs a daemon until it is idle. Gradle's {@code BuildActionsFactory} returns a daemon action, not
* a build, for both.
*/
private static final Set<String> NOT_RUN_HERE = Set.of("stop", "foreground");
@TempDir Path temp;
private Path project;
@BeforeEach
void setUp() throws IOException {
project = temp.resolve("project");
Files.createDirectories(project);
Files.writeString(project.resolve("settings.gradle"), "rootProject.name = 'probe'\n");
Files.writeString(
project.resolve("build.gradle"),
"""
tasks.register('ci') {
def marker = file('ci-ran')
doLast { marker.text = 'ran' }
}
""");
}
@Test
@DisplayName("판독기의 Gradle 옵션 표는 이 빌드를 돌리는 Gradle의 --help가 보이는 옵션과 정확히 같다")
void theReadersOptionTableNamesExactlyTheOptionsTheRunningGradleLists() throws Exception {
// when
Run help = gradle("--help");
// then
assertThat(help.exitCode()).as(help.output()).isZero();
assertThat(optionNames(help.output()))
.as("the options of the Gradle in %s", gradleHome())
.containsExactlyInAnyOrderElementsOf(WorkflowGradleInvocations.gradleOptionNames());
}
@Test
@DisplayName("판독기가 작업 없이 끝난다고 읽는 옵션을 붙이면 Gradle은 성공으로 끝나고 작업을 실행하지 않는다")
void gradleEndsWithoutRunningTheTaskWhenGivenAnOptionTheReaderReadsAsRunningNoTask()
throws Exception {
// given
List<String> options = new ArrayList<>();
for (String name : WorkflowGradleInvocations.optionsThatRunNoTask()) {
if (!NOT_RUN_HERE.contains(name)) {
options.add(name.length() == 1 ? "-" + name : "--" + name);
}
}
options.add("-qv");
// when
Map<String, Run> runs = new LinkedHashMap<>();
for (String option : options) {
runs.put(option, gradle(":ci", option));
}
// then
assertThat(options).contains("-v", "--version", "-h", "-?", "--help", "--status");
runs.forEach(
(option, run) -> {
assertThat(run.exitCode()).as(option + "\n" + run.output()).isZero();
assertThat(project.resolve("ci-ran")).as(option).doesNotExist();
});
}
@Test
@DisplayName("버전을 찍고 계속하는 -V를 붙이면 Gradle은 작업을 실행하므로, 위 검사는 실행을 알아볼 수 있다")
void gradleRunsTheTaskWhenGivenShowVersionWhichContinues() throws Exception {
// when
Run run = gradle(":ci", "-V");
// then
assertThat(run.exitCode()).as(run.output()).isZero();
assertThat(project.resolve("ci-ran")).exists();
}
/** The option names a {@code --help} lists, without dashes; {@code --} itself is not an option. */
private static Set<String> optionNames(String help) {
Set<String> names = new LinkedHashSet<>();
for (String line : help.lines().toList()) {
if (!line.startsWith("-")) {
continue;
}
for (String spelling : line.split("\\s{2,}", 2)[0].split(",\\s*")) {
String name = spelling.strip().replaceFirst("^-+", "");
if (!name.isEmpty()) {
names.add(name);
}
}
}
return names;
}
private record Run(int exitCode, String output) {}
/** Runs the launcher of this build's Gradle on the probe project, isolated from every daemon. */
private Run gradle(String... arguments) throws IOException, InterruptedException {
List<String> command = new ArrayList<>();
boolean windows = System.getProperty("os.name").startsWith("Windows");
command.add(gradleHome().resolve(windows ? "bin/gradle.bat" : "bin/gradle").toString());
command.addAll(
List.of(
"--no-daemon",
"--gradle-user-home",
temp.resolve("gradle-user-home").toString(),
"--project-dir",
project.toString()));
command.addAll(List.of(arguments));
Path output = Files.createTempFile(temp, "gradle", ".log");
ProcessBuilder builder =
new ProcessBuilder(command).redirectErrorStream(true).redirectOutput(output.toFile());
builder.environment().put("JAVA_HOME", System.getProperty("java.home"));
builder.environment().remove("GRADLE_OPTS");
Process process = builder.start();
if (!process.waitFor(5, TimeUnit.MINUTES)) {
process.destroyForcibly();
throw new IllegalStateException("gradle " + String.join(" ", arguments) + " did not end");
}
return new Run(process.exitValue(), Files.readString(output, StandardCharsets.UTF_8));
}
private static Path gradleHome() {
String home = System.getProperty("ca.gradle.home");
assertThat(home)
.as("build-logic's test task passes the running Gradle's home as ca.gradle.home")
.isNotBlank();
return Path.of(home);
}
}
@@ -1,71 +0,0 @@
package dev.caskeleton.buildlogic.strictlane;
import static org.assertj.core.api.Assertions.assertThat;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
class TaskSelectorsTest {
private static final Map<String, Set<String>> BUILD =
Map.of(
":", Set.of("ci", "performanceCheck", "test"),
":grpc", Set.of("test"),
":grpc:grpc-testkit",
Set.of("test", "testClasses", "grpcPerformanceTest", "grpcPerformanceTestClasses"),
":leaf", Set.of("test", "databaseLane", "databaseLoadTest"));
@Test
@DisplayName("이름이 정확히 같은 태스크가 있으면 그 이름만 모든 프로젝트에서 뺀다")
void anExactNameRemovesOnlyThatNameInEveryProject() {
// when
Set<String> excluded = TaskSelectors.excludedPaths(List.of("test"), BUILD);
// then
assertThat(excluded)
.containsExactlyInAnyOrder(":test", ":grpc:test", ":grpc:grpc-testkit:test", ":leaf:test");
}
@Test
@DisplayName("camel-case 축약 이름은 Gradle처럼 그 태스크를 뺀다")
void aCamelCaseAbbreviationRemovesTheTaskGradleWouldRemove() {
// when
Set<String> excluded = TaskSelectors.excludedPaths(List.of("grpcPerformanceT"), BUILD);
// then
assertThat(excluded).containsExactly(":grpc:grpc-testkit:grpcPerformanceTest");
}
@Test
@DisplayName("경로의 프로젝트 이름도 축약할 수 있다")
void aQualifiedSelectorMayAbbreviateItsProjectNames() {
// when
Set<String> excluded = TaskSelectors.excludedPaths(List.of(":grpc:grpcT:gPT"), BUILD);
// then
assertThat(excluded).containsExactly(":grpc:grpc-testkit:grpcPerformanceTest");
}
@Test
@DisplayName("Gradle이 모호하다고 거부할 축약은 후보 전부를 뺀 것으로 본다")
void anAmbiguousAbbreviationRemovesEveryCandidate() {
// when
Set<String> excluded = TaskSelectors.excludedPaths(List.of("database"), BUILD);
// then
assertThat(excluded).containsExactlyInAnyOrder(":leaf:databaseLane", ":leaf:databaseLoadTest");
}
@Test
@DisplayName("맞는 태스크가 없는 선택자는 아무것도 빼지 않는다")
void aSelectorThatMatchesNothingRemovesNothing() {
// when
Set<String> excluded = TaskSelectors.excludedPaths(List.of(":leaf:cacheLane"), BUILD);
// then
assertThat(excluded).isEmpty();
}
}
+62 -10
View File
@@ -18,7 +18,8 @@ plugins {
// and archive hygiene is gone with the revision it cleaned out of every leaf's jar name (review
// 2026-09-24 BUILD-O3-5).
id 'ca.architecture'
// Every strict lane belongs to a stage a workflow executes (review 2026-11-01 08-01).
// Every strict lane belongs to a stage, and each stage's workflow job runs it (review
// 2026-11-01 08-01).
id 'ca.strict-lane-stages'
}
@@ -65,7 +66,9 @@ tasks.register('verifyDependencyLocks') {
// check every leaf's check (Gradle matches the name across projects)
// architectureCheck dependency direction + purity + app-bootstrap whole-repository ArchUnit
// qualityCheck SpotBugs + FindSecBugs across every leaf (ca.quality-conventions)
// ci the pull-request gate: leaf checks + architectureCheck + qualityCheck
// ci leaf checks + architectureCheck + qualityCheck
// prCheck the pull-request stage: ci + dependency locks + the Compose render, the
// repository layout and the document checks (scripts outside Gradle)
// mainCheck the main-branch stage: environment contract, full-boot qualification,
// public-path baseline, transport and messaging qualification lanes, each
// leaf's document-contract lanes, and the feature generator round trip
@@ -104,7 +107,7 @@ tasks.register('integrationCheck') {
}
// Performance lanes are not the pull request's or the main stage's: their bounds need a machine that
// is not compiling something else. integration-main.yml runs this aggregate on main and nightly.
// is not compiling something else. main.yml runs this aggregate nightly, after its other jobs.
tasks.register('performanceCheck') {
group = 'verification'
description = "Runs every production CI leaf's performance-category test lanes. Several need a container runtime."
@@ -190,14 +193,63 @@ tasks.register('mainCheck') {
dependsOn tasks.named('verifyFeatureScaffold')
}
// The stages a strict lane may belong to. `verifyStrictLaneStages --dry-run` (pull-request gate)
// fails when a strict lane that is not `explicitOnly` is in the plan of none of these, or when a
// stage is executed by no workflow — the gap that left fourteen lanes running nowhere while each
// one failed closed (review 2026-11-01 08-01). A new lane joins a stage through its category
// aggregate; no workflow line names it.
// The checks outside Gradle that the pull-request stage runs. Each is a script with its own tests
// (scripts/tests); these tasks only give them a stage, so pr.yml and scripts/verify.sh run the same
// one line. Repository root as working directory: that is where the scripts expect to start.
def repositoryRoot = rootProject.projectDir.parentFile
tasks.register('verifyComposeProfiles', Exec) {
group = 'verification'
description = 'Renders every Compose lane and checks it renders exactly what it declares.'
workingDir = repositoryRoot
commandLine 'bash', 'scripts/verify-compose-profile-contracts.sh'
}
tasks.register('verifyRepositoryLayout', Exec) {
group = 'verification'
description = 'Refuses a top-level entry of the repository or src/ outside the allow list.'
workingDir = repositoryRoot
commandLine 'python3', 'scripts/check-repo-layout.py'
}
tasks.register('testDocumentChecks', Exec) {
group = 'verification'
description = 'Runs the tests of the scripts outside Gradle (document checker, hooks, ledger).'
workingDir = repositoryRoot
commandLine 'python3', '-m', 'unittest', 'discover', '-s', 'scripts/tests'
}
tasks.register('documentCheck', Exec) {
group = 'verification'
description = 'Checks living documents: language, head blocks, references, numbers, links, style.'
workingDir = repositoryRoot
commandLine 'python3', 'scripts/check-docs.py'
dependsOn tasks.named('testDocumentChecks')
}
tasks.register('prCheck') {
group = 'verification'
description = 'The pull-request stage: ci, dependency locks, the Compose render, the layout and the documents.'
dependsOn tasks.named('ci')
dependsOn tasks.named('verifyDependencyLocks')
dependsOn tasks.named('verifyComposeProfiles')
dependsOn tasks.named('verifyRepositoryLayout')
dependsOn tasks.named('documentCheck')
}
// The stages a strict lane may belong to, and the one workflow job that runs each.
// `verifyStrictLaneStages --dry-run` (pull-request stage) fails when a strict lane that is not
// `explicitOnly` is in the plan of none of them — the gap that left fourteen lanes running nowhere
// while each one failed closed (review 2026-11-01 08-01) — or when a stage job is not the line
// `./gradlew <stage> <options>` under the declared event and condition. A new lane joins a stage
// through its category aggregate; no workflow line names it. The performance lane runs only
// nightly, after the other heavy jobs, on a runner nothing else is using (owner decision 2026-11-07).
strictLaneStages {
stage ':ci', ':mainCheck', ':integrationCheck', ':performanceCheck', ':releaseCheck'
workflowDirectory = layout.projectDirectory.dir('../.github/workflows')
workflowDirectory = layout.projectDirectory.dir('../.gitea/workflows')
stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle'
stage ':mainCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]', job: 'main',
options: '--continue'
stage ':integrationCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]', job: 'integration',
options: '--continue'
stage ':performanceCheck', workflow: 'main.yml', event: 'schedule', job: 'performance', options: '--continue',
condition: '${{ !cancelled() && github.event_name != \'push\' }}'
stage ':releaseCheck', workflow: 'release.yml', event: 'push', filter: 'tags: ["v*"]', job: 'release'
}
// The deny-by-default public path baseline: app-bootstrap's approval-test lane under its old name.
@@ -63,13 +63,19 @@ dependencies {
}
// FileserverDocumentationCoverageTest reads the fileserver documents, the workflows that define the
// support-matrix jobs and the fileserver transport sources. They are inputs of `test`, or Gradle
// would call it up to date after an edit to any of them — which is the edit it exists to catch.
// support-matrix jobs, the fileserver test sources the matrix names as evidence and the fileserver
// transport sources. They are inputs of `test`, or Gradle would call it up to date after an edit to
// any of them — which is the edit it exists to catch.
def repositoryRoot = rootProject.projectDir.parentFile
tasks.named('test') {
inputs.dir(new File(repositoryRoot, 'docs/fileserver')).withPropertyName('fileserverDocuments')
.withPathSensitivity(PathSensitivity.RELATIVE)
inputs.dir(new File(repositoryRoot, '.github/workflows')).withPropertyName('workflows')
inputs.dir(new File(repositoryRoot, '.gitea/workflows')).withPropertyName('workflows')
.withPathSensitivity(PathSensitivity.RELATIVE)
inputs.files(['application-fileserver', 'adapter/inbound/web-fileserver', 'adapter/outbound/fileserver',
'adapter/outbound/persistence-fileserver', 'composition/fileserver-platform']
.collect { rootProject.file("${it}/src/test/java") })
.withPropertyName('fileserverTestSources')
.withPathSensitivity(PathSensitivity.RELATIVE)
inputs.dir(rootProject.file('adapter/inbound/web-fileserver/src/main/java')).withPropertyName('transportSources')
.withPathSensitivity(PathSensitivity.RELATIVE)
@@ -5,6 +5,7 @@ import static org.assertj.core.api.Assertions.assertThatCode;
import dev.caskeleton.adapter.outbound.fileserver.platform.autoconfigure.FileserverPlatformSettings;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
@@ -14,6 +15,7 @@ import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Stream;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.boot.context.properties.bind.BindHandler;
import org.springframework.boot.context.properties.bind.Bindable;
@@ -32,21 +34,45 @@ import org.springframework.core.env.StandardEnvironment;
*/
class FileserverDocumentationCoverageTest {
private static final Pattern CI_JOB = Pattern.compile("`(fileserver-[a-z0-9-]+)`");
private static final String WORKFLOWS = ".gitea/workflows";
private static final Pattern EVIDENCE = Pattern.compile("`([^`]+)`");
private static final Pattern CI_JOB = Pattern.compile("fileserver-[a-z0-9-]+");
private static final Pattern TEST_TASK = Pattern.compile("(:[a-z0-9:-]+):test");
private static final Pattern TEST_CLASS = Pattern.compile("[A-Z][A-Za-z0-9]*Test");
private static final Pattern WORKFLOW_JOB = Pattern.compile("^ {2}([a-z0-9-]+):\\s*$");
private static final String PROFILE_TABLE_HEADER = "| Profile | 등급 | 증거 |";
private static final List<String> FILESERVER_LEAVES =
List.of(
"src/application-fileserver",
"src/adapter/inbound/web-fileserver",
"src/adapter/outbound/fileserver",
"src/adapter/outbound/persistence-fileserver",
"src/composition/fileserver-platform");
private static final Pattern MAPPING_PATH =
Pattern.compile("\"(/v1/[^\"]*|/internal/fileserver[^\"]*)\"");
@Test
void everySupportClaimNamesAJobThatExists() throws IOException {
List<String> claimed =
referencedCiJobs(repositoryRoot().resolve("docs/fileserver/support-matrix.md"));
List<String> defined = definedWorkflowJobs();
@DisplayName("지원 매트릭스의 행마다 있는 테스트·모듈·job을 증거로 적는다")
void everySupportClaimNamesEvidenceThatExists() throws IOException {
// given
Map<String, List<String>> claims =
evidenceByProfile(repositoryRoot().resolve("docs/fileserver/support-matrix.md"));
assertThat(claimed)
.as("a support level whose evidence job does not exist is an unbacked claim")
.isNotEmpty()
.allSatisfy(job -> assertThat(defined).contains(job));
// when
Map<String, List<String>> unbacked = new LinkedHashMap<>();
claims.forEach(
(profile, evidence) -> {
List<String> missing = evidence.stream().filter(item -> !exists(item)).toList();
if (evidence.isEmpty() || !missing.isEmpty()) {
unbacked.put(profile, evidence.isEmpty() ? List.of("(none)") : missing);
}
});
// then
assertThat(claims).isNotEmpty();
assertThat(unbacked)
.as("a support level whose evidence does not exist is an unbacked claim")
.isEmpty();
}
@Test
@@ -201,30 +227,62 @@ class FileserverDocumentationCoverageTest {
Map.entry("quota.soft-high-water", "0.70"),
Map.entry("quota.hard-high-water", "0.85"));
private static List<String> referencedCiJobs(Path supportMatrix) throws IOException {
List<String> jobs = new ArrayList<>();
Matcher matcher = CI_JOB.matcher(Files.readString(supportMatrix));
while (matcher.find()) {
jobs.add(matcher.group(1));
/** The evidence cell of every runtime-profile row, keyed by the profile it backs. */
private static Map<String, List<String>> evidenceByProfile(Path supportMatrix)
throws IOException {
Map<String, List<String>> claims = new LinkedHashMap<>();
List<String> lines = Files.readAllLines(supportMatrix);
int header = lines.indexOf(PROFILE_TABLE_HEADER);
assertThat(header).as("the runtime-profile table header").isNotNegative();
for (String line : lines.subList(header + 2, lines.size())) {
if (!line.startsWith("|")) {
break;
}
String[] cells = line.split("\\|", -1);
List<String> evidence = new ArrayList<>();
Matcher matcher = EVIDENCE.matcher(cells[3]);
while (matcher.find()) {
evidence.add(matcher.group(1));
}
claims.put(cells[1].trim(), evidence);
}
return jobs;
return claims;
}
/**
* Job identifiers across every fileserver workflow and the release workflow (which holds the
* certification jobs since review BUILD-계획-B2), read from the two-space indent level.
* Whether one evidence item names something real: a CI job defined in a workflow, a project whose
* {@code test} has test sources, or a test class of a fileserver leaf.
*/
private static boolean exists(String evidence) {
try {
if (CI_JOB.matcher(evidence).matches()) {
return definedWorkflowJobs().contains(evidence);
}
Matcher task = TEST_TASK.matcher(evidence);
if (task.matches()) {
return Files.isDirectory(
repositoryRoot().resolve("src" + task.group(1).replace(':', '/') + "/src/test/java"));
}
if (TEST_CLASS.matcher(evidence).matches()) {
for (String leaf : FILESERVER_LEAVES) {
try (Stream<Path> files = Files.walk(repositoryRoot().resolve(leaf + "/src/test/java"))) {
if (files.anyMatch(file -> file.getFileName().toString().equals(evidence + ".java"))) {
return true;
}
}
}
}
return false;
} catch (IOException unreadable) {
throw new UncheckedIOException(unreadable);
}
}
/** Job identifiers of every workflow, read from the two-space indent level. */
private static List<String> definedWorkflowJobs() throws IOException {
List<String> jobs = new ArrayList<>();
Path workflows = repositoryRoot().resolve(".github/workflows");
try (Stream<Path> files = Files.list(workflows)) {
for (Path file :
files
.filter(
path ->
path.getFileName().toString().startsWith("fileserver-")
|| path.getFileName().toString().equals("release.yml"))
.toList()) {
try (Stream<Path> files = Files.list(repositoryRoot().resolve(WORKFLOWS))) {
for (Path file : files.toList()) {
for (String line : Files.readAllLines(file)) {
Matcher matcher = WORKFLOW_JOB.matcher(line);
if (matcher.matches()) {
@@ -269,7 +327,7 @@ class FileserverDocumentationCoverageTest {
private static Path repositoryRoot() {
Path working = Path.of("").toAbsolutePath();
Path candidate = working;
while (candidate != null && !Files.isDirectory(candidate.resolve(".github/workflows"))) {
while (candidate != null && !Files.isDirectory(candidate.resolve(WORKFLOWS))) {
candidate = candidate.getParent();
}
if (candidate == null) {
+2 -2
View File
@@ -20,7 +20,7 @@ org.gradle.parallel=true
# `resolveAndLockAll`), which is `notCompatibleWithConfigurationCache`. Resolving every
# configuration at execution time is not an implementation detail of that task, it is the task:
# STRICT lock validation happens during resolution, so moving it behind a provider would move lock
# verification into every build's configuration phase. Because the pull-request gate runs `:ci` and
# verification into every build's configuration phase. Because the pull-request stage runs `:ci` and
# `:verifyDependencyLocks` in one invocation, turning the flag on repository-wide would discard the
# entry for that invocation anyway. Enabling it is therefore a change to how CI is split, not a
# property — and `.github/workflows/ci-quality-gates.yml` proves the storable half on every PR.
# property — and scripts/ci/verify-configuration-cache.sh (main.yml) proves the storable half.
+1 -1
View File
@@ -154,7 +154,7 @@ toxiproxy-java = { module = "eu.rekawek.toxiproxy:toxiproxy-java", version.ref =
uuid-creator = { module = "com.github.f4b6a3:uuid-creator", version.ref = "uuidCreator" }
# Pinned: libraries no leaf declares, whose upstream still brings a version with a High or Critical
# advisory (the trivy gate in dependency-vulnerability.yml). Not for a leaf to depend on: build-logic's
# advisory (the trivy gate, scripts/ci/trivy-scan.sh). Not for a leaf to depend on: build-logic's
# JavaConventionsPlugin pins every `pinned-*` entry, through Spring dependency management, in every
# configuration of every leaf — the Checkstyle and Error Prone classpaths included. The version's
# comment names the advisory and the upstream; delete the entry once every upstream named there