UML과 DevOps를 하나의 워크플로우로 묶기

모델과 코드가 같은 라이프사이클을 타야 하는 이유

모델과 코드, 인프라 변경이 서로 다른 속도로 움직이면 문서는 반드시 뒤처진다. UML 모델, 아키텍처 다이어그램, API 스펙, 인프라 설계를 소스 저장소에 코드로 두고, CI/CD 파이프라인에서 자동 생성·검증·배포하는 운영 체계를 만드는 게 이 글의 주제다. 문서-as-code와 모델-as-code 원칙을 적용해 생성·검증·배포를 CI/CD에 통합하면, 개발·운영·보안 팀이 같은 근거 자료를 자동화된 산출물로 공유할 수 있다.

PlantUML/Mermaid/Structurizr DSL, OpenAPI/AsyncAPI, IaC 도면 같은 선언적 산출물을 버전 관리하고 릴리스와 연동하는 것이 문서-as-code·모델-as-code의 핵심이다. 여기에 문서 빌드 성공, 링크 검증, 모델 검증, 코드-문서 일치 검사, 릴리스 태그와 문서 버전 동기화를 필수 체크로 강제하는 품질 게이트를 얹는다.

워크플로우의 구성 계층

저장소 구조와 거버넌스는 docs/, models/, adr/, api/, iac/, .ci/처럼 표준 디렉터리로 나누고, CODEOWNERS·PR 템플릿·Conventional Commits 같은 변경 이력 규칙으로 책임과 추적성을 확보한다. 변경된 모듈 대비 UML/API/ADR 갱신 여부를 자동 검증하는 문서 커버리지 체크도 여기 속한다.

생성 파이프라인은 *.puml, *.mmd, structurizr.dsl, openapi.yaml, terraform, 소스 주석(Javadoc/KDoc/Doxygen)을 입력으로 받는다. 처리는 다이어그램 렌더링(PlantUML/Graphviz 또는 Mermaid CLI), 스키마 추출, 링크 검사, 문서 사이트 빌드(MkDocs/Docusaurus/Sphinx)로 이어지고, 출력은 버전 태그별 정적 사이트, PDF 아티팩트, 다이어그램 이미지, SBOM/서명 메타데이터다.

검증·일치성 체크는 세 갈래다. 모델 정합성은 UML 문법, 네임스페이스, 순환 의존, 사용 금지 스테레오타입을 검사한다. 코드-문서 일치는 OpenAPI ↔ 컨트롤러 엔드포인트 diff, 엔티티 ↔ ER 다이어그램 스키마 diff, IaC ↔ 아키텍처 C4 맵 매핑을 검사한다. 링크·품질 검사는 사내 표준 용어 린트, 깨진 링크, 라이선스/비밀정보 스캔을 통합한다.

배포·버전 관리는 태그 생성 → 문서 빌드 → 서명 → 배포 순서로 릴리스 태그와 문서 버전을 원자적으로 결합한다. 아티팩트 해시·서명 검증, 이전 버전 보관·롤백 절차로 변경 불변성을 보장하고, 내부 포털·GitHub Pages/GitLab Pages·패키지 레지스트리·PDF 이메일 배포처럼 소비 채널을 다각화한다.

운영 가시성·최적화는 빌드 시간, 실패율, 문서 신선도(staleness), 커버리지를 대시보드로 제공하는 데서 시작한다. 캐시·병렬화, 변경 영향도 기반 부분 빌드, 다이어그램 렌더링 컨테이너화로 성능을 최적화하고, 렌더링 정밀도·출력 형식·검사 강도를 조절해 파이프라인 시간과 정확도의 균형을 잡는다.

실제로 쓰이는 곳

마이크로서비스 API 문서화에서는 OpenAPI 스펙으로 컨트롤러 테스트를 통합하고, 성공하면 시퀀스/컴포넌트 다이어그램을 생성해 포털에 배포한다. 엔드포인트가 바뀌면 diff 리포트를 생성해 리뷰어에게 문서 영향 범위를 자동으로 알린다.

레거시 시스템 리팩토링에서는 소스에서 리버스 엔지니어링으로 클래스/패키지 다이어그램을 생성하고, 릴리스 간 구조 변화 비교 리포트를 제공한다. ADR로 의사결정 이력을 관리하고 리팩토링 단계별 모델 안정성 지표를 추적한다.

인프라 변경과 아키텍처 동기화에서는 Terraform 계획서(plan)에서 리소스 그래프를 추출해 C4 컨테이너 다이어그램을 갱신한다. 보안/네트워크 경계가 바뀌면 승인 게이트로 위반 규칙을 차단한다.

규제/감사 대응에서는 문서 빌드 타임스탬프, 커밋 해시, 서명을 포함한 변경 대장을 자동 생성한다. 릴리스 단위로 PDF를 패키징·보관하고, 재현 가능한 빌드로 감사 대응을 단순화한다.

파이프라인 절차

⤢✕

입력은 코드/모델/스펙/ADR 변경이고, 처리는 렌더링 → 일치성 검사 → 서명/배포 순서를 따르며 실패 시 중단과 재시도 가이드를 제공한다. 출력은 버전별 문서 사이트, 아티팩트, 지표와 알림이다.

수동 위키와 비교하면

지표	수동 위키 중심	문서-as-code 파이프라인
성능	작성·검증 수작업으로 느림	자동 렌더링·부분 빌드로 빠름
확장성	팀 규모 확대 시 품질 저하 발생	리포지토리·파이프라인 수평 확장 용이
일관성	코드와 문서 불일치 빈번	릴리스 태그·게이트로 일관성 보장
안정성	사람 의존 절차, 누락 위험 큼	재현 가능한 빌드, 실패 시 롤백 용이
운영 편의	변경 추적 어려움	버전·이력·메트릭 자동화로 관리 용이

GitHub Actions로 구현하기

리포지토리는 docs/에 Markdown, models/에 *.puml, api/에 openapi.yaml을 둔다. 도구는 Docker 가능 환경이나 Java 17+Graphviz, MkDocs 1.5+(mkdocs-material)가 필요하고, 브랜치 전략은 main 보호·PR 필수 리뷰·태그 기반 릴리스를 기본으로 한다.

name: Docs CI
on:
  pull_request:
    paths: ["docs/**", "models/**", "api/**", ".github/workflows/**"]
  push:
    tags: ["v*.*.*"]

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate UML with PlantUML (Docker)
        run: |
          docker run --rm -v "$PWD/models":/work plantuml/plantuml:1.2024.6 \
            -failfast2 -tpng -o ../docs/images *.puml
      - name: Validate OpenAPI and diff
        run: |
          pipx install openapi-spec-validator openapi-diff
          openapi-spec-validator api/openapi.yaml
          # 예: 기준 스펙과 비교
          test -f api/openapi-base.yaml && openapi-diff api/openapi-base.yaml api/openapi.yaml || true
      - name: Link check
        run: |
          pipx install lychee
          lychee --no-progress docs
      - name: Build MkDocs
        run: |
          pipx install mkdocs mkdocs-material
          mkdocs build --strict
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: site
          path: site
  deploy:
    if: startsWith(github.ref, 'refs/tags/')
    needs: build-docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: site
          path: site
      - name: Sign and publish (example)
        run: |
          tar -C site -cf site.tar .
          sha256sum site.tar > site.tar.sha256
      - uses: actions/upload-pages-artifact@v3
        with:
          path: site
  publish:
    if: startsWith(github.ref, 'refs/tags/')
    needs: deploy
    permissions:
      pages: write
      id-token: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/configure-pages@v5
      - uses: actions/deploy-pages@v4

PlantUML 렌더링이 실패하거나 링크가 깨지면 빌드를 실패 처리하고, 로그·이미지 아티팩트로 원인 분석을 돕는다. 성능은 models/ 변경이 감지될 때만 렌더링하고, MkDocs 캐시와 다이어그램 병렬 렌더링을 적용해 최적화할 수 있다.

주문 생성 시퀀스를 다루는 간단한 예시(models/sample.puml)는 다음과 같다.

@startuml
title 주문 생성 시퀀스
actor User
participant API as "Order API"
participant SVC as "Order Service"
participant DB as "DB"
User -> API: POST /orders
API -> SVC: validate+create()
SVC -> DB: insert(order)
DB --> SVC: ok
SVC --> API: 201 Created
API --> User: orderId
@enduml

보안·아키텍처 선택에서 트레이드오프

보안 모범사례는 다이어그램·문서에 자격증명·키를 노출하지 않고 시크릿 스캐너를 필수로 적용하는 것부터 시작한다. 내부 아키텍처 세부 노출 수준을 구분해 외부 배포물에는 마스킹·요약을 적용하고, 문서 아티팩트는 서명·무결성 검증과 접근 제어·감사 로그 보존을 갖춘다.

아키텍처 선택에도 트레이드오프가 있다. PlantUML은 표현력이 높은 대신 Java/Graphviz 의존성 부담이 있다. Mermaid는 경량·웹 친화적이지만 정밀한 모델 검증 기능이 제한적이다. Structurizr DSL은 C4 중심 아키텍처 표현에 강점이 있지만 러닝커브가 있다.

운영 최적화는 변경 영향도 기반 부분 빌드로 파이프라인 시간을 줄이고, 대규모 리포지토리에서는 문서 리포 분리나 모노레포 캐시 전략을 병행한다. 린트 규칙은 단계적으로 강화하고, 초기에는 경고 모드로 도입하는 편이 안전하다.

효과

문서 신선도 지표가 개선된다 — 릴리스 대비 문서 지연율이 30%에서 5% 이하로 전환될 가능성이 있다. 문서 diff/검증 자동화로 리뷰 리드타임이 20~~40% 감소할 가능성이 있고, 최신 아키텍처를 참조할 수 있어 MTTR이 10~~20% 개선될 가능성도 있다. 정성적으로는 팀 간 공통 이해 기반이 강화되고 온보딩 기간이 줄며, 문서 신뢰도가 높아지고 지식 사일로가 해소된다. 변경 리스크가 가시화되면서 의사결정 품질도 함께 올라간다.

문서-as-code를 기반으로 생성·검증·배포를 CI/CD에 결합하면 최신성과 일관성을 함께 확보할 수 있다. 코드-문서 일치 검사와 버전 동기화는 릴리스 신뢰성을, 자동화는 운영 비용 절감을 가져온다. 중소 규모 팀은 Mermaid+MkDocs로 가볍게 시작하고, 대규모 조직은 PlantUML/Structurizr와 엄격한 게이트로 단계적으로 확장하는 편이 현실적이다.