GitHub 에이전틱 워크플로로 리포지토리 간 문서화 자동화 (새 탭에서 열림)

Aspire 팀은 GitHub Agentic Workflows를 활용해 제품 코드 저장소와 문서 저장소가 분리된 환경에서도 기능 변경 직후 문서 PR을 자동 생성하는 시스템을 구축했다. 에이전트가 변경 사항과 이슈를 분석해 문서를 작성하지만, 실제 쓰기 작업은 제한된 별도 핸들러가 수행하도록 분리해 보안을 확보했다. 그 결과 Aspire 13.3·13.4에서 82개의 문서 PR이 제품 PR 병합 후 중앙값 44.8시간 내 생성됐고, 모두 해당 기능을 구현한 엔지니어의 검토를 받았다.

교차 저장소 문서화가 어려운 이유

• 제품 코드는 microsoft/aspire, 문서 사이트는 microsoft/aspire.dev에 있어 저장소와 배포 대상, 리뷰 절차가 분리되어 있다.
• 기존 방식은 문서 작성자가 몇 주 뒤 닫힌 PR을 찾아 변경 내용을 역추적하는 구조였다.
• 기능 작성자는 이미 다음 작업으로 넘어간 상태라 문서 작성에 필요한 맥락을 충분히 제공하기 어려웠다.
• 저장소 전체에 쓰기 권한을 가진 광범위한 토큰은 보안상 부적절하므로, 단순한 크로스 리포지토리 자동화도 권한 설계가 병목이 된다.

GitHub Agentic Workflows의 구조

• 워크플로를 YAML 대신 하나의 Markdown 파일로 작성한다.
  • YAML 형식의 frontmatter에 설정을 작성한다.
  • 아래에는 에이전트가 수행할 작업을 자연어 프롬프트로 작성한다.
• 컴파일하면 일반 GitHub Actions 워크플로인 .lock.yml 파일이 생성된다.
• 실행 시 에이전트는 제한된 도구와 프롬프트를 바탕으로 변경 사항을 분석한다.
• 에이전트가 GitHub에 직접 쓰지 않는 점이 핵심이다.
  • 에이전트는 생성하려는 PR, 이슈, 댓글을 JSON 형태의 의도로 출력한다.
  • 별도의 safe-outputs handler가 허용된 작업만 실제로 실행한다.
• 저장소와 작업 종류를 명시적으로 제한할 수 있어 보안 검토와 자동화의 균형을 맞춘다.

기능 PR에서 문서 PR로 이어지는 자동화 흐름

• microsoft/aspire의 main 또는 release/* 브랜치에 병합된 PR을 pull_request: closed 이벤트로 감지한다.
• merged == true 조건을 적용해 실제 병합된 PR만 처리한다.
• 에이전트가 실행되기 전에 Bash 기반의 결정론적 로직으로 문서 대상 브랜치를 결정한다.
  1. 제품 PR의 마일스톤 제목을 확인한다. 예를 들어 13.4는 문서 저장소의 release/13.4로 매핑된다.
  2. PR 본문에서 Fixes, Closes, Resolves로 연결된 이슈를 찾고, 해당 이슈의 첫 번째 비어 있지 않은 마일스톤을 확인한다.
  3. PR의 base ref가 release/X.Y 또는 release/X.Y.Z 형식이면 이를 사용한다.
  4. 어느 조건에도 해당하지 않으면 main을 사용한다.
• 마일스톤과 문서 브랜치를 명확히 매핑해 에이전트가 대상 브랜치를 추측하지 않도록 한다.
• 에이전트는 제품 diff와 연결된 이슈를 읽고 문서화가 필요한 변경인지 판단한다.
• 문서가 필요하면 체크아웃된 microsoft/aspire.dev 작업 공간에 기존 문서 작성 규칙에 맞춰 초안을 작성한다.
  • 문서의 문체
  • MDX 규칙
  • Astro Starlight 컴포넌트 사용법
• 이후 create_pull_request safe output을 생성해 문서 PR 생성을 요청한다.

제한된 권한으로 PR 생성하기

• safe-outputs 핸들러는 실제 PR 생성 시 다음 제약을 적용한다.
  • PR 제목에 [docs] 접두사 사용
  • docs-from-code 라벨 부착
  • 자동 병합 없이 항상 draft PR로 생성
  • base 브랜치는 main 또는 release/*로 제한
  • 대상 저장소는 microsoft/aspire.dev로 고정
• 제품 PR의 리뷰 기록에서 해당 기능을 승인한 SME를 찾아 문서 PR 리뷰어로 요청한다.
• 문서 리뷰가 기능 구현자의 맥락과 분리되지 않도록, 실제 기능을 승인한 사람이 문서도 검토하게 한다.
• 별도 작업은 원본 제품 PR에 문서 PR 링크를 댓글로 남긴다.
• 재실행 시 이전 pr-docs-check 댓글을 최소화해 중복 알림을 줄인다.
• 기능을 병합한 엔지니어는 몇 분 안에 문서 초안을 확인할 수 있다.

보안 설계와 safe-outputs 계약

• GitHub 도구 세트를 repos, issues, pull_requests 등 필요한 범위로 제한한다.
• min-integrity: approved 설정으로 무결성이 검증된 작업만 실행하도록 한다.
• 허용 저장소를 microsoft/*처럼 제한할 수 있다.
• 전용 GitHub App의 App ID와 private key를 사용해 일반적인 광범위 토큰 대신 작업별 권한을 부여한다.
• App이 접근할 수 있는 저장소도 aspire.dev, aspire로 한정한다.
• 에이전트의 분석 권한과 실제 변경 권한을 분리해, 에이전트가 임의로 저장소에 쓰거나 병합하지 못하게 한다.
• 최종 문서 반영은 여전히 draft PR과 사람의 리뷰를 거친다.

측정된 결과

• Aspire 13.3과 13.4에서 문서 기능 PR 82개가 병합됐다.
• 문서 PR은 제품 PR 병합 후 중앙값 44.8시간 뒤에 생성됐다.
• 모든 문서 PR을 해당 기능을 구현한 엔지니어가 검토했다.
• 별도의 인력 충원이나 새로운 프로세스 교육 없이 운영됐다.
• 문서 작성 시점이 기능 출시 후 수 주가 아니라 기능 병합 직후로 앞당겨졌다.

기능 저장소와 문서 저장소가 분리되어 있다면, 에이전트에게 광범위한 쓰기 권한을 주기보다 결정론적인 브랜치 선택 로직, 제한된 safe outputs, 초안 PR, 담당 엔지니어 리뷰를 결합하는 방식이 실용적이다. AI가 문서를 작성하더라도 최종 병합은 사람이 담당하도록 설계하는 것이 안전성과 문서 품질을 함께 확보하는 방법이다.