Consumer Integration

소비자 레포 연동

Stella 는 스캐너만 들고 있고 스캔 대상 코드는 갖고 있지 않습니다. 그래서 연동의 방향은 항상 소비자 레포가 Stella 를 가져다 쓰는 쪽입니다. 워크플로도, 시크릿도, 매핑 YAML 도 소비자 레포가 소유합니다.

소비자 레포	스캔 대상	워크플로
umc-product-iOS	AppProduct/, UMCApp/	.github/workflows/api-coverage.yml

---

왜 체크아웃인가

Stella 를 SwiftPM 의존성으로 넣지 않는 이유는 두 가지입니다.

• apicov 는 라이브러리가 아니라 실행 파일입니다. 소비자 앱 타깃과 링크될 일이 없습니다
• 스캐너가 swift-syntax 를 끌고 오는데, 이걸 앱 레포의 Package.resolved 에 섞고 싶지 않습니다

그래서 CI 에서 별도 경로로 체크아웃해 빌드하고 그 자리에서 실행합니다.

워크플로 구조

iOS 레포의 api-coverage.yml 이 레퍼런스 구현입니다. 핵심만 옮기면 이렇습니다.

jobs:
  scan:
    runs-on: macos-26
    defaults:
      run:
        working-directory: .stella

    steps:
      # blame 으로 작성자를 뽑으므로 전체 히스토리가 필요하다
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/checkout@v4
        with:
          repository: UMC-PRODUCT/umc-product-stella
          path: .stella

      - run: swift build -c release --product apicov

      - env:
          UMC_API_USER: ${{ secrets.UMC_API_USER }}
          UMC_API_PASS: ${{ secrets.UMC_API_PASS }}
        run: |
          .build/release/apicov scan \
            --openapi-url https://dev.api.umc.it.kr/docs-json \
            --auth-env UMC_API_USER:UMC_API_PASS \
            --app-product ../AppProduct \
            --umc-app ../UMCApp \
            --blame-root .. \
            --out coverage.json

포인트 네 가지입니다.

• fetch-depth: 0 — 얕은 클론이면 git blame 이 대부분의 줄을 못 짚습니다. 작성자가 전부 Unknown 으로 나오면 이 설정부터 확인하세요
• path: .stella — Stella 는 소비자 레포 안의 하위 디렉터리로 들어옵니다. 이후 스텝의 working-directory 가 .stella 라서 ../AppProduct 처럼 한 단계 올라가 대상 코드를 가리킵니다
• --blame-root .. — blame 은 소비자 레포 루트에서 돌아야 합니다. 스냅샷의 filePath 도 이 기준으로 상대화됩니다
• 시크릿은 값이 아니라 변수 이름으로 — --auth-env UMC_API_USER:UMC_API_PASS 는 환경변수 이름을 받습니다. 자격증명이 명령줄에 남지 않으므로 CI 로그에 노출되지 않습니다

매핑 YAML 은 선택

authors.yml · overrides.yml · owners.yml 은 소비자 레포에 두고 있으면 붙이고 없으면 넘어가는 게 편합니다. iOS 워크플로가 쓰는 방식입니다.

extra=()
[ -f authors.yml ]   && extra+=("--authors"   "authors.yml")
[ -f overrides.yml ] && extra+=("--overrides" "overrides.yml")
[ -f owners.yml ]    && extra+=("--owners"    "owners.yml")

.build/release/apicov scan ... ${extra[@]+"${extra[@]}"}

${extra[@]+"${extra[@]}"} 는 set -u 아래에서 빈 배열을 펼칠 때 나는 오류를 피하는 관용구입니다.

각 파일이 뭘 하는지는 매핑 YAML 을 보세요.

결과 배포

스캔이 끝나면 두 갈래로 나갑니다.

산출물	방법	보존
coverage.json	upload-artifact (coverage-snapshot)	30일
HTML 리포트	upload-pages-artifact → 별도 deploy 잡에서 GitHub Pages	최신본만

- run: |
    mkdir -p _site
    .build/release/apicov report coverage.json --out _site/index.html

Pages 배포에는 permissions: { contents: read, pages: write, id-token: write } 가 필요합니다.

아티팩트로 받은 이전 coverage.json 을 내려받아 두면 apicov diff old.json new.json 으로 주간 변화를 뽑을 수 있습니다.

실행 시점

iOS 레포는 세 가지 트리거를 씁니다.

트리거	설정
주간 정기	schedule: cron "0 0 * * 1" — 매주 월요일
Router 변경	push (develop) + paths 필터로 Router 디렉터리만
수동	workflow_dispatch

concurrency: { group: api-coverage, cancel-in-progress: false } 로 동시 실행을 막습니다. Pages 배포가 겹치면 서로를 덮어씁니다.

새 소비자 레포 붙이기

1. Router enum 이 어느 경로 패턴에 있는지 확인합니다. 현재 프로젝트 입력은 두 가지로 고정돼 있습니다 — --app-product 는 **/Router/*Router.swift, --umc-app 은 **/Data/Sources/*Router.swift. 둘 다 안 맞으면 코드를 손봐야 합니다 (아래)
2. iOS 레포의 api-coverage.yml 을 복사해 경로와 스펙 URL 을 고칩니다
3. 스펙에 인증이 필요하면 시크릿 두 개를 등록하고 --auth-env 로 이름을 넘깁니다
4. 첫 실행은 workflow_dispatch 로 돌려보고 unmatchedRouterCases 를 훑어 매핑이 필요한지 봅니다

macOS 지원에 필요한 선행 작업

umc-product-macOS 는 아직 스캔 대상이 아닙니다. 도구를 분리한 이유가 macOS 앱과의 공유였지만 실제로 붙이려면 두 가지가 남아 있습니다.

하나. 프로젝트 플래그가 iOS 두 개로 고정돼 있습니다.

ScanCommand 가 받는 프로젝트 옵션은 --app-product 와 --umc-app 뿐이고 각각 ProjectInput.appProduct · ProjectInput.umcApp 팩토리로 직결됩니다 (Sources/apicov/Commands/ScanCommand.swift, Sources/StellaCore/Pipeline/ScanConfig.swift). 코어의 ProjectInput 자체는 key · displayName · rootPath · routerGlobs 를 받는 범용 구조라 손댈 필요가 없습니다. 막힌 쪽은 CLI 표면입니다.

가장 얇은 해법은 --project key:이름:경로:글로브 같은 반복 옵션을 하나 추가해 기존 두 플래그를 그 위의 단축형으로 남기는 겁니다. key 는 스냅샷의 connections·summary 키로 그대로 나가므로 한 번 정하면 되돌리기 어렵습니다.

둘. macOS 레포에 아직 Router 가 없습니다.

현재 umc-product-macOS 는 템플릿 상태라 Moya Router enum 이 없습니다. 네트워킹 레이어가 자리를 잡고 나서 그 디렉터리 규칙에 맞는 글로브를 정하는 게 순서입니다. 먼저 정해두면 십중팔구 다시 고칩니다.

Stella 앱(GUI)도 같은 제약을 공유합니다. 설정 화면의 프로젝트 경로가 두 칸으로 고정돼 있어서 CLI 를 일반화하면 GUI 도 같이 손봐야 합니다.

로컬에서 같은 걸 돌려보려면

CI 와 똑같은 배치를 로컬에 만들면 됩니다.

~/Work/
├── umc-product-iOS/       # 소비자 레포
└── umc-product-stella/    # 여기

cd umc-product-stella
swift run apicov scan \
  --openapi-url https://dev.api.umc.it.kr/docs-json \
  --auth-env UMC_API_USER:UMC_API_PASS \
  --app-product ../umc-product-iOS/AppProduct \
  --umc-app ../umc-product-iOS/UMCApp \
  --blame-root ../umc-product-iOS \
  --out coverage.json

경로 해석 규칙은 설치와 첫 스캔 에 정리돼 있습니다.

---

관련: CLI 레퍼런스 · 매핑 YAML · 트러블슈팅