Files
clean-architecture-backend-…/docs/ci-cd/boundary.md
T
DongHyeonka d46bab9659
pr / gradle (pull_request) Successful in 16m42s
pr / vulnerabilities (pull_request) Successful in 37s
pr / done (pull_request) Canceled after 0s
ci!: workflow를 pr·main·release 셋으로 접고 단계 job 모양만 검사한다
workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로
나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations·
TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸
모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는
한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절).

소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다.

- .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와
  `./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities`
  (trivy), 필수 검사 하나 `done`.
- main.yml: push마다 mainCheck·integrationCheck·build-logic 시험·
  configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서
  PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos,
  jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck.
- release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea
  레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명
  앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은
  `needs: jpa-release-gate`가 대신한다.
- 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 +
  저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다.
- verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의
  계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로
  바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에
  선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른
  run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는
  needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른
  working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job
  하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다
  (build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를
  TestKit 시험으로 둔다.
- scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업
  트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의
  손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트
  포워더·configuration cache 스크립트다.
- workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease
  RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을
  .gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다.
- 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic
  AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조,
  docs/upgrade B-57~B-61.

버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수
없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기
(결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다.

위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지
않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를
다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다.
`.github/workflows/messaging-certification.yml`은 메시징 분리 작업이
지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이
없어 실제 태그로는 돌려 보지 않았다.

BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법,
릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity-
review.md B-57~B-61을 따른다.
2026-11-08 21:55:43 +09:00

3.9 KiB

CI/CD 경계 — Gitea Actions는 CI, Argo CD는 CD

결론

Gitea Actions(.gitea/workflows)는 검증하고 아티팩트를 만든다. Argo CD는 배포한다. 두 역할은 겹치지 않는다.

Gitea Actions 워크플로는 kubectl apply, helm upgrade, argocd app sync 중 어느 것도 하지 않는다. 그러므로 CI에는 클러스터 자격증명(kubeconfig, 서비스 계정 토큰)이 들어가지 않는다.

흐름

   git push / tag
        │
        ▼
  Gitea Actions   ─────────────── CI ───────────────┐
   • 테스트 · 정적분석 · 아키텍처 검증               │
   • 컨테이너 이미지 빌드                            │
   • 취약점 스캔 (Trivy)                             │
   • SBOM 생성                                       │
   • 레지스트리에 이미지 push                        │
        │                                            │
        │ 이미지 태그(다이제스트)를 manifest에 기록  │
        ▼                                            │
  GitOps 저장소 (배포 희망 상태)  ──────────────────┘
        │
        │ Argo CD가 watch
        ▼
     Argo CD  ──────────────────── CD ───────────────
        │ auto-sync
        ▼
   Kubernetes

용어 한 줄 풀이:

  • GitOps 저장소 — 클러스터에 무엇이 떠 있어야 하는지를 적어 둔 Git 저장소. 애플리케이션 소스와 분리한다.
  • manifest — Kubernetes에 넣을 YAML(Deployment, Service 등).
  • auto-sync — Argo CD가 GitOps 저장소의 변경을 스스로 감지해 클러스터에 반영하는 모드. 이걸 쓰면 CI가 Argo CD API 서버에 접근할 필요가 없다.

왜 이렇게 나누나

  1. 자격증명 반경. CI가 배포하면 CI 러너가 프로덕션 클러스터에 대한 쓰기 권한을 갖는다. 포크된 PR, 서드파티 액션, 캐시 오염이 모두 그 권한에 닿는다. auto-sync를 쓰면 그 권한은 클러스터 안의 Argo CD에만 있고, CI는 Git에 커밋만 한다.
  2. 현재 상태의 소유자가 하나. 클러스터에 무엇이 떠 있는지는 GitOps 저장소가 답한다. CI가 직접 apply 하면 답이 두 개가 된다 — Git에 적힌 것과 실제로 떠 있는 것.
  3. 롤백이 revert. 배포를 되돌리는 것이 git revert가 된다.

이 저장소의 현재 위치

항목 상태
이미지 빌드/스캔/push .gitea/workflows/release.yml이 수행. 이 Gitea의 컨테이너 레지스트리
SBOM release.yml이 생성(CycloneDX, 이미지 검사 전)
이미지 서명 release.yml이 digest를 cosign 키 쌍으로 서명하고 확인한다(태그에서만)
provenance attestation 없음. 추가 대상
GitOps 저장소 없음. 별도 저장소로 만들 예정
Argo CD Application 정의 없음. GitOps 저장소에 둘 예정
CI에서의 클러스터 접근 없음 — 유일했던 kubectl apply는 제거됨

PVC 매니페스트와 그 파일을 검사하던 release.yml 잡(fileserver-pvc-certification)은 2026-11-07에 지웠다(소유자 결정: Kubernetes·프록시 설정은 이 repo 밖). 클러스터 인증은 배포하는 쪽이 docs/fileserver/storage-certification.md 절차로 하고, volume 조건은 docs/fileserver/operations.md 「운영 환경이 지켜야 할 조건」에 있다.

규칙

  • 워크플로에 클러스터 자격증명 secret을 추가하지 않는다.
  • 배포 대상이 바뀌면 GitOps 저장소의 manifest를 바꾼다. 워크플로를 바꾸지 않는다.
  • CI가 만드는 것은 불변 다이제스트로 지정된 이미지다. latest 태그로 배포하지 않는다.