github-agentic-workflows

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가 문서를 작성하더라도 최종 병합은 사람이 담당하도록 설계하는 것이 안전성과 문서 품질을 함께 확보하는 방법이다.

GitHub 에이전틱 워크플로의 토큰 효율성 향상 (새 탭에서 열림)

GitHub Agentic Workflows는 반복 실행되는 CI 자동화인 만큼 토큰 비용이 누적되기 쉬우며, YAML과 실행 로그를 분석하면 이를 체계적으로 줄일 수 있다. GitHub는 토큰 사용량을 표준화해 수집하고, 감사·최적화 워크플로를 통해 불필요한 MCP 도구를 제거하거나 GitHub CLI로 대체했다. 그 결과 동작을 바꾸지 않고도 요청당 수천 토큰을 절약할 수 있었다. ## 토큰 사용량을 표준화해 기록 - Claude CLI, Copilot CLI, Codex CLI 등 에이전트 프레임워크마다 로그 형식이 달라 사용량 비교가 어려웠다. - 인증 정보를 에이전트에 직접 노출하지 않도록 사용하는 API 프록시를 활용해 모든 실행의 토큰 사용량을 한 형식으로 수집했다. - 각 워크플로는 `token-usage.jsonl` 아티팩트를 생성한다. - API 호출별 입력 토큰 - 출력 토큰 - 캐시 읽기·쓰기 토큰 - 모델과 제공업체 - 호출 시각 - 실행 로그와 이 데이터를 결합해 워크플로별 일반적인 토큰 소비 패턴과 이상 실행을 파악했다. ## 감사·최적화 워크플로로 자동 개선 - **Daily Token Usage Auditor** - 최근 실행의 토큰 사용량을 워크플로별로 집계한다. - 사용량이 급증한 워크플로, 비용이 큰 워크플로, 비정상적인 실행을 탐지한다. - 예를 들어 평소 4번의 LLM 턴으로 끝나던 작업이 18턴까지 늘어난 경우를 표시한다. - **Daily Token Optimizer** - 감사 결과가 나온 워크플로의 YAML과 최근 로그를 분석한다. - 불필요한 동작과 구체적인 최적화 방안을 GitHub Issue로 제안한다. - 감사·최적화 도구 자체도 에이전트 워크플로이므로 사용량을 함께 측정할 수 있고, 이를 통해 개선 작업이 반복되는 순환 구조를 만든다. ## 사용하지 않는 MCP 도구 제거 - LLM API는 상태를 유지하지 않기 때문에 MCP 도구의 함수명과 JSON 스키마가 매 요청에 포함되는 경우가 많다. - GitHub MCP 서버의 도구가 40개라면 매 턴마다 10~15KB의 스키마가 추가될 수 있다. - 실제로 두 도구만 사용하는 에이전트라면 나머지 38개 도구의 스키마는 매번 순수한 오버헤드가 된다. - 도구 설정과 실제 호출 기록을 대조하면 장기간 사용되지 않은 도구를 식별할 수 있다. - 스모크 테스트에서는 사용하지 않는 MCP 도구를 제거해 요청당 컨텍스트를 8~12KB 줄였고, 동작 변경 없이 실행당 수천 토큰을 절약했다. ## 데이터 조회를 GitHub CLI로 대체 MCP 호출은 단순한 데이터 조회에도 LLM의 판단 과정을 요구한다. - 에이전트가 도구를 선택하고 인자를 구성한 뒤 결과를 받는 과정 전체가 추가 LLM 호출이 된다. - 이 과정에서 도구 스키마, 인자 JSON, 응답 데이터가 모두 토큰을 소비한다. - 반면 `gh pr diff` 같은 GitHub CLI 명령은 결정적인 API 요청이므로 LLM 추론 단계가 필요 없다. GitHub는 두 가지 방식으로 MCP 데이터 조회를 CLI로 옮겼다. - **에이전트 실행 전 데이터 다운로드** - 항상 필요한 PR diff, 변경 파일 목록 등을 에이전트 시작 전에 `gh` 명령으로 가져온다. - 결과를 작업 공간 파일에 저장하고 에이전트가 파일을 읽도록 한다. - MCP 호출과 별도 추론 라운드트립을 제거하며, 에이전트가 Bash 도구를 활용해 데이터를 효율적으로 처리할 수 있다. - **에이전트 내부 CLI 프록시** - 실행 중 어떤 데이터를 가져올지 에이전트가 결정해야 하는 경우 사용한다. - 인증 토큰을 노출하지 않는 투명 HTTP 프록시가 CLI 요청을 GitHub API로 전달한다. - 에이전트는 `gh pr view --json` 같은 명령을 실행하고 구조화된 결과를 받는다. - 보안상 “에이전트에 비밀정보를 직접 제공하지 않는다”는 원칙을 유지하면서 토큰 사용량을 줄인다. ## 효율성 측정에서 고려할 요소 단순히 토큰 개수만 비교하면 최적화 효과를 정확히 판단하기 어렵다. - 모델별 토큰 가격이 다르다. - Claude Haiku와 Sonnet은 비슷한 토큰 수를 사용할 수 있지만 Haiku가 토큰당 약 4배 저렴하다. - 이를 반영하기 위해 모델과 토큰 종류에 가중치를 적용한 **Effective Tokens(ET)** 지표를 사용한다. ```text ET = m × (1.0 × I + 0.1 × C + 4.0 × O) ``` - `m`: 모델 비용 배수 - Haiku = 0.25 - Sonnet = 1.0 - Opus = 5.0 - `I`: 새로 처리한 입력 토큰 - `C`: 캐시에서 읽은 토큰 - `O`: 출력 토큰 - 출력 토큰은 입력 토큰보다 비용 영향이 크므로 4배 가중치를 적용한다. - 따라서 최적화가 토큰 수를 줄였는지뿐 아니라, 더 저렴한 모델을 사용했는지와 작업 품질을 유지했는지도 함께 평가해야 한다. 반복 실행되는 에이전트 워크플로는 먼저 사용량을 관측하고, 실제 사용 도구만 남기며, 결정적인 데이터 조회를 CLI나 사전 다운로드로 이동하는 방식이 효과적이다. 특히 MCP를 편리하다는 이유로 전체 등록하기보다 워크플로별 최소 도구만 구성하고, ET 같은 비용 반영 지표로 품질 저하 없이 최적화되는지 검증하는 것이 권장된다.

GitHub 에이전틱 워크플 (새 탭에서 열림)

GitHub Agentic Workflows는 자연어로 작성한 Markdown 지시를 GitHub Actions에서 코딩 에이전트가 실행하도록 해 저장소 업무를 자동화하는 기술이다. 이슈 분류, 문서 갱신, 테스트 보강, CI 실패 분석처럼 기존의 결정론적 YAML 워크플로로는 처리하기 어려운 작업을 자동화하면서도, 권한·샌드박스·검토 절차를 통해 통제할 수 있도록 설계됐다. GitHub는 이를 CI/CD를 대체하는 것이 아니라 보완하는 “Continuous AI”로 소개하며, 2026년 2월 기술 프리뷰로 공개했다. ## Markdown으로 정의하는 에이전트 기반 저장소 자동화 - 원하는 결과를 일반 Markdown으로 설명하고, 이를 저장소의 자동화 워크플로로 등록한다. - 워크플로는 GitHub Actions에서 실행되며, 설정에 따라 다음과 같은 코딩 에이전트를 사용할 수 있다. - Copilot CLI - Claude Code - OpenAI Codex - 기존 개발팀이 이미 사용하는 GitHub Actions의 권한 관리, 로그, 감사 기능, 저장소 컨텍스트를 그대로 활용한다. - 복잡한 절차를 직접 YAML로 세부 구현하기보다, 사람이 의도와 목표를 설명하고 에이전트가 저장소를 분석해 작업을 수행하는 방식이다. ## 지속적인 저장소 관리에 활용되는 작업 - **이슈 트리아지** - 새 이슈를 요약하고 라벨을 붙인다. - 관련 담당자나 적절한 처리 경로로 이슈를 분류한다. - **문서 유지 관리** - 코드 변경 사항을 분석해 README와 기술 문서를 최신 상태로 갱신한다. - **코드 단순화** - 반복적으로 개선 가능한 코드를 식별한다. - 개선안을 pull request로 생성해 사람이 검토하도록 한다. - **테스트 개선** - 테스트 커버리지를 평가한다. - 가치가 높은 테스트를 추가하도록 제안하거나 pull request를 만든다. - **품질 관리** - CI 실패 원인을 조사한다. - 문제에 맞는 구체적인 수정안을 제안한다. - **정기 보고** - 저장소의 건강 상태, 활동량, 주요 추세를 정기적으로 분석하고 보고서를 작성한다. ## Continuous AI와 기존 CI/CD의 관계 - GitHub는 에이전트 기반 자동화를 소프트웨어 개발 생명주기에 AI를 지속적으로 결합하는 **Continuous AI**라고 부른다. - Agentic Workflow는 빌드, 테스트, 릴리스처럼 결과가 명확하고 결정론적인 CI/CD 파이프라인을 대체하지 않는다. - 대신 다음과 같이 판단과 분석이 필요한 작업을 담당한다. - 어떤 이슈가 중요한지 판단 - 문서와 코드의 불일치 탐색 - 실패 원인 분석 - 개선 가치가 높은 테스트나 리팩터링 선별 - 따라서 기존 CI/CD는 안정적인 검증과 배포를 담당하고, Agentic Workflow는 저장소 운영과 엔지니어링 작업의 지능화를 담당하는 구조다. ## 권한과 안전장치 - 안전성과 통제는 설계의 핵심 요소로 제시된다. - 워크플로는 기본적으로 **읽기 전용 권한**으로 실행된다. - 파일 수정, 이슈 변경, pull request 생성 등 쓰기 작업은 명시적인 승인이 필요하다. - 쓰기 작업은 **safe outputs**를 통해 사전에 허용된 형태로 제한하고, 사람이 검토할 수 있도록 한다. - 샌드박스 실행, 권한 제어, 감사 로그, 실행 기록 등을 활용해 의도하지 않은 동작과 프롬프트 인젝션 공격에 대비한다. - 결과적으로 에이전트가 자율적으로 작업하더라도, 실행 시점과 변경 범위를 저장소 관리자가 정의한 경계 안에 둘 수 있다. ## 실제 적용 사례와 기대 효과 - Home Assistant에서는 대규모 이슈를 분석해 반복적으로 나타나는 문제와 사용자에게 영향이 큰 이슈를 파악하는 데 활용한다. - CNCF는 문서 자동화와 조직 차원의 팀 보고를 개선하는 데 사용하고 있다. - Carvana는 여러 저장소에 걸친 엔지니어링 작업에 에이전트를 적용하면서도 내장된 제어 기능을 활용하고 있다. - 개인 저장소부터 오픈소스 프로젝트와 대기업 규모의 복잡한 시스템까지 적용 범위를 확장할 수 있다. - 반복적인 관리 업무를 줄이고, 사람이 중요한 판단과 검토에 집중하도록 돕는 것이 주요 목표다. 실제로 도입할 때는 읽기 전용·보고서 생성처럼 위험이 낮은 작업부터 시작한 뒤, 사람이 검토하는 pull request 생성 단계로 확장하는 것이 적절하다. 빌드와 배포 파이프라인은 기존 CI/CD로 유지하고, Agentic Workflow는 분석·분류·문서화·개선 제안처럼 판단이 필요한 업무에 사용하는 편이 안전하다.