Automating cross-repo documentation with GitHub Agentic Workflows

개요

Aspire 팀은 GitHub Agentic Workflows를 활용하여 코드 변경 사항이 제품 저장소에 병합된 후, 문서 변경 사항을 자동으로 생성하고 숙련된 전문가(SME)의 검토를 거쳐 Pull Request를 생성하는 프로세스를 구축했습니다.

주요 내용

* 현실적인 문제점: 기존에는 제품 기능이 출시된 후에야 문서 작성자가 변경 사항을 파악하고, 엔지니어는 다음 작업으로 넘어가 희미한 기억에 의존하여 문서 초안을 작성하는 등 문서화 지연이 발생했습니다.
* GitHub Agentic Workflows의 도입: 이 워크플로우는 GitHub Actions에 LLM 기반 작업 처리 및 보안 가드레일을 결합한 형태로, 단일 Markdown 파일로 워크플로우를 정의하고 컴파일 시 GitHub Actions 워크플로우를 생성합니다.
* 교차 저장소(Cross-repo) 자동화의 어려움: 동일 저장소 내 자동화는 비교적 쉽지만, 코드 저장소와 문서 저장소가 분리된 경우 보안 제약으로 인해 교차 저장소 자동화에 병목 현상이 발생합니다.
* 보안 강화 메커니즘: Agent는 GitHub App 토큰을 사용하여 두 개의 특정 저장소(제품 및 문서)에만 접근 가능하며, 쓰기 작업은 안전한 출력(safe-outputs) 핸들러를 통해 엄격하게 제어됩니다. Agent는 직접 GitHub에 쓰지 않고 의도(JSON blob)를 내보내며, 이를 검증된 파이프라인이 처리합니다.
* 자동화 파이프라인 흐름: pr-docs-check.md 워크플로우는 제품 저장소의 Pull Request가 병합되면 트리거됩니다. 먼저 타겟 브랜치를 결정하고, Agent가 코드 변경 사항과 연결된 이슈를 분석하여 문서화 필요성을 판단합니다. 필요시 문서 초안을 작성하고, SME(기능 승인 엔지니어)를 검토자로 지정한 Pull Request를 생성합니다.
* 성공 지표: Aspire 13.3 및 13.4 릴리스 동안 82개의 문서 Pull Request가 생성되었으며, 제품 Pull Request 병합 후 평균 44.8시간 이내에 병합되었습니다. 모든 문서 Pull Request는 해당 기능을 출시한 엔지니어의 검토를 거쳤습니다.
* 긍정적 결과:
* 마일스톤을 릴리스 브랜치로 매핑하는 기능이 효과적이었습니다.
* Agent는 문서를 자동으로 병합하지 않고, SME가 검토하도록 하여 역공학을 줄였습니다.
* 워크플로우별로 스코핑된 GitHub App을 사용하여 보안 검토를 통과했습니다.
* AGENTS.md, 패키지 매니페스트 등 중요 파일에 대한 Agent의 접근이 차단되었습니다.
* 초기 문제점 및 해결 방안:
* 초기 Agent의 "문서 가치 판단" 기준이 너무 광범위하여 불필요한 PR 생성을 초래했으나, 프롬프트 개선 및 예외 사례 추가로 해결했습니다.
* 교차 저장소 PR 생성 시 미러링된 체크아웃 패턴이 명확하지 않았으나, 타겟 저장소를 두 번 체크아웃하여 해결했습니다.
* 대규모 diff는 프롬프트 예산을 초과했으나, Agent 실행 전 PR 메타데이터를 추출하여 소형화했습니다.
* 기타 워크플로우: milestone-changelog.md (마일스톤 변경 사항 위키 페이지 생성), release-update-support-mdx.md (지원 정책 업데이트), update-integration-data.md (통합 데이터 및 NuGet 메타데이터 업데이트), repo-pulse.md (저장소 활동 대시보드) 등 다양한 자동화 워크플로우도 함께 운영됩니다.

시사점

GitHub Agentic Workflows는 저장소 간 자동화의 복잡성과 보안 제약을 효과적으로 관리하며, 개발팀이 문서화 프로세스를 혁신하고 문서 작성자의 부담을 줄여 더욱 가치 있는 작업에 집중할 수 있도록 지원합니다.