Microsoft Aspire 팀이 GitHub Agentic Workflows를 도입해 기능 릴리즈와 문서화 간의 시차 문제를 해결한 사례다. 제품 저장소(microsoft/aspire)와 문서 저장소(microsoft/aspire.dev)가 분리된 환경에서, PR 병합 시 AI 에이전트가 문서화 필요 여부를 판단하고 초안 PR을 자동 생성한다. 보안을 유지하면서 크로스 레포 자동화를 실현한 아키텍처와 30일 실제 운영 성과를 담는다.
핵심 포인트- 워크플로우 정의를 마크다운 파일(.github/workflows/*.md)에 작성하면 .lock.yml GitHub Actions 워크플로우로 컴파일된다.
- Safe-Outputs Handler가 보안 핵심: 에이전트가 GitHub에 직접 쓰지 않고 JSON intent를 emit하면 좁은 스코프의 별도 Job이 실제 PR을 생성한다.
- GitHub App 토큰을 두 레포(aspire, aspire.dev)로만 제한하고 protected files(AGENTS.md, 보안 설정)는 차단한다.
- Milestone-to-Branch 매핑으로 문서 PR의 대상 브랜치를 자동 결정해 수동 선택 오류를 제거했다.
- 30일간 396개 PR 병합 → 82개 문서 초안 PR 생성 → 82건 전량 병합(0건 비병합), 중앙값 44.8시간 소요.
상세 정리- 배경: Aspire 제품·문서 저장소가 분리돼 기능 릴리즈 후 문서 반영이 수 주씩 지연됐다. "Where are the docs?" 문제가 반복.
- 워크플로우 구성: pr-docs-check.md 파일 하나를 .github/workflows/에 두면 CI가 .lock.yml로 컴파일해 실행한다.
- 실행 흐름: PR 병합 → diff와 연결 이슈를 읽어 문서화 필요 여부 판단 → 필요 시 MDX/Starlight 형식 문서 초안 생성 → 기능 승인자를 리뷰어로 지정.
- Safe-Outputs 모델: 에이전트는 "어떤 PR을 만들어달라"는 JSON intent만 반환하고, 별도의 narrowly-scoped job이 GitHub App 토큰으로 실제 PR을 생성한다. 에이전트가 GitHub API를 직접 호출하지 않아 권한 남용을 구조적으로 차단한다.
- GitHub App 스코프 설정: allowed-repos: microsoft/*, allowed-base-branches: [main, release/*], protected-files: blocked, fallback-as-issue: true(PR 생성 실패 시 이슈로 폴백).
- 초기 오탐률: 첫 69개 PR 중 13%가 문서 불필요(내부 리팩토링/의존성 변경)로 닫힘 → 프롬프트 개선으로 이후 비율 대폭 감소.
- 대용량 diff 처리: diff가 프롬프트 한계를 초과할 경우 bash에서 PR 메타데이터를 사전 추출한 뒤 에이전트에 전달하는 패턴을 확립했다.
- 크로스 레포 체크아웃: aspire.dev를 워크스페이스용과 _repos/aspire.dev 아래 미러용으로 이중 체크아웃해 크로스 레포 브랜치 생성 문제를 해결했다.
- 성과(5/3~6/2): 396 PR 중 314는 문서 불필요로 판단, 82건 문서 PR 생성 → 전량 병합. 38%가 24시간 이내, 96%가 7일 이내 병합.
- 효과: 문서 작성자가 기능 역추적에 쓰던 시간을 개념 설명·샘플 코드·튜토리얼 작성으로 재배분. 자동화가 대체가 아닌 역할 재배분.
- 추가 워크플로우: milestone-changelog.md(346 runs), update-integration-data.md(일일 NuGet/GitHub 메타데이터 갱신, 8건 PR 병합) 등도 함께 배포.
왜 읽나크로스 레포 AI 에이전트 자동화를 보안 제약 안에서 설계하려는 DevOps·플랫폼 엔지니어에게 실제 운영 지표와 보안 아키텍처 레퍼런스를 제공한다.