pile·
AI / ML·github-engGitHub Engineering·

GitHub Agentic Workflows로 크로스 레포 문서 자동화하기

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·플랫폼 엔지니어에게 실제 운영 지표와 보안 아키텍처 레퍼런스를 제공한다.
github-eng
GitHub Engineering 블로그
원문은 여기서 이어서 읽을 수 있어요
원문 읽기
읽음 (0)

이 글과 비슷한

  1. AI / ML·무신사 테크무신사 테크·

    LLM 비용 64% 절감, 캐시 히트율 98% 달성기

    29CM(무신사 그룹)이 AWS Bedrock 기반 LLM 비용이 지속 증가하는 원인을 메트릭 가시성 확보부터 차근차근 파악하고, Prompt Caching 도입으로 전체 LLM 청구액의 64%를 절감한 과정을 다룬다. 문제는 AWS Bedrock 콘솔이 일별 합계만 보여주고 API별 토큰 분리를 지원하지 않는다는 점이었고, 직접 메트릭 파이프라인을 구축한 뒤에야 단일 속성 추출 API가 전체 토큰의 92%를 차지한다는 사실을 발견했다.

    #aws-bedrock#llm#cost-optimization+2
  2. AI / ML·네이버 D2네이버 D2·

    [AI 해커톤 후기] 코드와 문서만 읽은 LLM은 어떻게 사람과 같은 팀을 1위로 골랐을까

    네이버가 2026년 봄 개최한 '모두의 Engineering Day' AI 해커톤에서, 25개 팀의 코드와 문서를 LLM이 자동 채점하는 'LLM as a Judge' 평가 파이프라인을 설계하고 실제 운영한 사례를 다룬다. 코드만 읽는 LLM이 사람의 판단에 가까운 결론에 도달할 수 있는지, 반복해도 안정적인 결과가 나오는지를 검증했다.

    #llm-app#llm-as-a-judge#prompt-engineering+2
  3. AI / ML·인프랩 (인프런)인프런 (인프랩)·

    학습 에이전트 — AI 두뇌 구축하기

    인프런이 강의 학습 에이전트를 구축하며 겪은 기술 스택 선정, 컨텍스트·도구 설계, LLM-as-a-Judge 품질 개선, 비용 최적화 전략을 다룬다. LLM SSE 스트리밍 처리를 위해 Spring MVC + Virtual Thread + Spring AI를 선택하고, 명시적 프롬프트 캐싱으로 입력 토큰을 90% 절감하는 과정까지 실전 경험이 담겨 있다.

    #ai-agent#llm#llm-as-a-judge+2