CI는 통과했는데, 실패 이유를 설명해 줄 사람은 없다
밤새 테스트가 실패했는데 아침에 로그를 열어 보면 오류 메시지만 수백 줄 남아 있는 경우가 있다. 정해진 명령을 실행하고 성공·실패를 판정하는 일은 기존 GitHub Actions가 잘한다. 하지만 실패한 커밋과 최근 변경을 읽어 원인을 추려 이슈로 남기는 일은 보통 개발자가 직접 맡는다.
GitHub가 2026년 10월 28일 정식 제공을 발표한 GitHub Agentic Workflows는 이처럼 판단이 필요한 저장소 관리 작업을 대상으로 한다. 이슈 분류, CI 실패 분석, 문서 업데이트 제안, 테스트 보강 같은 일을 코딩 에이전트에게 맡기되 실행과 기록은 GitHub Actions 안에 남긴다. 기존 CI를 없애는 새 배포 시스템은 아니다.
이 기능의 출발점은 Markdown 파일이다. 언제 실행할지, 어떤 권한을 줄지, 결과를 어떤 방식으로 기록할지는 파일 상단의 설정에 적고, 에이전트에게 맡길 판단은 자연어로 설명한다. 도구가 이를 GitHub Actions에서 실행할 수 있는 YAML로 컴파일하므로, 프롬프트만 저장해 놓고 누군가 수동으로 실행해야 하는 구조와 다르다.
중요한 구분은 '에이전트가 코드를 알아서 병합한다'가 아니라 '정해 둔 범위 안에서 조사하고 제안한다'는 점이다. 공식 문서도 일반적인 빌드·린트·테스트에는 결정적인 기존 Actions를 쓰고, 로그 해석이나 이슈 정리처럼 문맥 판단이 필요한 작업에만 에이전트 흐름을 추가하라고 안내한다. 따라서 먼저 자동화할 판단 업무 하나를 골라야 한다.
Markdown 한 파일이 실행 가능한 Actions로 바뀌는 과정
워크플로 소스는 보통 `.github/workflows/` 아래에 두는 Markdown 파일이다. 맨 위 YAML frontmatter에는 `on` 같은 트리거와 `safe-outputs`처럼 허용할 결과 유형을 적는다. 그 아래에는 어떤 정보를 읽고 무엇을 보고할지 문장으로 쓴다. 문장 자체가 모든 GitHub 권한을 주는 것이 아니라, 설정과 생성된 작업 파일이 실행 범위를 정한다.
공식 소개의 하루 한 번 이슈 요약 예시에서는 `on: daily`로 주기를 정하고 `safe-outputs`에 `create-issue`를 선언한다. 본문은 전날 이슈를 요약하고 답변이 필요한 항목을 표시하라는 지시다. 에이전트가 결과를 만들면 허용된 출력 경로를 통해 이슈를 생성한다. 이 예시는 공식 문서 기반이며 이번 기사 작성 과정에서 실제 저장소에 적용해 실행한 결과는 아니다.
`gh aw compile`은 사람이 작성한 Markdown을 검증해 GitHub Actions가 읽는 `.lock.yml`을 만든다. 그래서 소스 Markdown과 생성된 잠금 파일을 함께 커밋해야 한다. 프롬프트만 고치고 잠금 파일을 갱신하지 않으면 실제 실행 내용이 기대와 달라질 수 있다. 공식 문서는 설정을 바꾼 뒤 다시 컴파일하도록 안내한다.
작업 흐름을 만들었다고 해서 곧바로 모든 브랜치에서 실행되는 것도 아니다. GitHub Actions가 활성화된 저장소, 트리거, 엔진 인증, 조직 정책이 모두 맞아야 한다. 실행 뒤에는 Actions 탭에서 로그와 산출물을 확인한다. 즉 'Markdown으로 자동화'는 설정 작성이 쉬워진다는 뜻이지 운영 설정이 사라진다는 뜻은 아니다.
---
on: daily
safe-outputs:
create-issue:
---
Summarise yesterday's issues and flag items that need a maintainer reply.첫 실행은 이슈 요약부터 시작하는 편이 낫다
처음부터 코드 수정과 PR 생성을 맡기면 결과가 맞는지 검수하는 비용이 커진다. 공식 빠른 시작은 저장소의 최근 활동을 모아 이슈로 남기는 `repo-status` 샘플을 사용한다. 결과가 마음에 들지 않아도 기존 코드를 바꾸지 않으므로, 입력 자료와 출력 품질을 확인하기 좋은 시작점이다.
먼저 GitHub CLI가 설치돼 있고 로그인돼 있는지 확인한다. 공식 문서의 기본 요구 사항은 `gh` 2.0 이상, 쓰기 권한이 있는 저장소, 활성화된 GitHub Actions, 사용할 AI 계정이다. 확장은 `gh extension install github/gh-aw`로 설치한다. 설치 명령은 도구를 준비하는 것이며 그 자체로 워크플로를 활성화하지 않는다.
그다음 저장소 루트에서 `gh aw add-wizard githubnext/agentics/repo-status`를 실행한다. 마법사가 엔진과 인증 방식을 선택하고 필요한 Markdown·잠금 파일을 추가하도록 안내한다. 공식 가이드는 직접 반영하거나 PR을 열 수 있는 경로를 설명한다. 민감한 저장소라면 처음부터 PR로 검토하고, 실제 실행 전에 생성된 YAML과 권한을 읽어 보는 편이 안전하다.
첫 실행이 끝나면 Actions 실행 로그와 생성된 이슈를 비교한다. 보고서가 실제 최근 PR과 이슈를 반영했는지, 이미 닫힌 문제를 다시 추천하지 않았는지, 답변이 필요한 사람을 잘못 지목하지 않았는지를 살핀다. 잘못된 결과가 있으면 프롬프트를 수정하고 `gh aw compile`로 다시 생성한 뒤 다음 실행을 관찰한다.
gh --version
gh auth status
gh extension install github/gh-aw
gh aw add-wizard githubnext/agentics/repo-status
# 수정한 뒤: gh aw compile
# 실행 상태 확인: gh aw status읽기 권한과 쓰기 권한을 나눠야 하는 이유
에이전트가 이슈 본문이나 외부 문서를 읽으면 그 안에는 악의적인 지시가 섞여 있을 수 있다. 단순한 자동화 스크립트와 달리 언어 모델은 이런 문장을 작업 지시로 오해할 가능성이 있다. 그래서 에이전트가 저장소를 읽는 단계와 GitHub에 실제 변경을 쓰는 단계를 분리하는 설계가 중요하다.
GitHub Agentic Workflows는 기본적으로 에이전트 작업에 읽기 전용 접근을 적용하고 샌드박스 안에서 실행한다. 네트워크 접근은 Agent Workflow Firewall이 제한하며, 결과는 `safe-outputs` 절차로 검증한다. 공식 발표에 따르면 별도 위협 탐지 작업이 적용 전에 제안된 변경을 검사한다. 이런 장치는 위험을 낮추지만 모든 프롬프트 주입이나 잘못된 제안을 막는 보증은 아니다.
예를 들어 CI 실패 원인을 조사하는 에이전트에게는 로그와 변경 내역을 읽을 권한이면 충분할 수 있다. 새 이슈를 생성해야 한다면 `create-issue` 같은 결과 유형만 허용하고, 저장소 전체에 무제한 쓰기 권한을 주지 않는다. 수정 PR을 만들 때도 에이전트가 제안한 diff를 사람이 검토한 뒤 병합하는 흐름이 안전하다.
특히 공개 저장소의 외부 기여 PR을 다룰 때는 `pull_request_target`의 높은 권한과 신뢰할 수 없는 코드 실행을 섞지 않아야 한다. GitHub 빠른 시작 문서도 가능한 경우 일반 `pull_request` 이벤트를 권한다. 안전 장치가 있다는 이유로 트리거·토큰·비밀키 설정을 검토하지 않아도 된다는 뜻은 아니다.
무료로 시작할 수 있어도 실행 비용은 따로 계산한다
GitHub는 Agentic Workflows 자체가 github.com의 GitHub Free, Team, Enterprise에서 정식 제공된다고 발표했다. 하지만 기본 Copilot CLI 엔진을 이용해 모델 추론을 실행하려면 Copilot 라이선스가 필요하다. 'GitHub Free에서 사용 가능'이라는 문장을 모델 호출까지 무조건 무료라는 뜻으로 읽으면 안 된다.
다른 엔진도 선택할 수 있다. 공식 빠른 시작은 Copilot, Claude Code, OpenAI Codex, Gemini, Pi를 소개하지만, 선택한 엔진에 맞는 계정·인증과 과금 조건이 다르다. 예를 들어 Codex 엔진은 API 키를 사용하는 경로를 설명하고, Claude 구독 로그인 토큰을 그대로 워크플로 인증에 쓰는 방법은 지원하지 않는다고 명시한다.
비용은 모델 사용량만으로 끝나지 않는다. GitHub Actions 실행 시간과 선택한 모델의 사용량, 안전 검사에 드는 크레딧 등이 함께 고려될 수 있다. `gh aw forecast`는 예상 사용량을 살펴보는 도구이며 정식 제공 시점에 실험 기능 표시가 제거됐다. 실제 청구액은 실행 빈도와 작업 난이도, 계정의 과금 정책에 따라 달라지므로 이 기사에서 임의의 월 요금을 제시하지 않는다.
처음에는 하루 한 번 요약이나 실패 시 한 번 조사처럼 트리거를 좁히고, 모델 사용량 상한과 로그를 확인하는 편이 낫다. 이슈가 열릴 때마다 무조건 에이전트를 실행하도록 설정하면 중복 이슈나 자동 생성 이벤트 때문에 호출 횟수가 늘어날 수 있다. 비용 관리 문서는 실행 빈도, 크레딧 제한, 모델 선택과 로그 확인 방법을 별도로 안내한다.
정식 제공에서 늘어난 기능과 여전히 남는 제약
이번 정식 제공은 단순히 공개 프리뷰의 이름표를 바꾼 발표만은 아니다. GitHub는 Actions Runner Controller와 Docker-in-Docker를 쓰는 자체 러너 지원, 더 구체적인 예산 예측, 모델·엔진 선택 확대, 모델 라우팅, 에이전트 격리 개선을 주요 변화로 소개했다. 자체 인프라와 정책이 있는 팀이 운영할 수 있는 범위를 넓힌 것이다.
다만 GitHub가 소개한 기업 사례의 생산성 수치는 특정 팀의 사례 발표다. 누구나 같은 시간 절감이나 오류 감소를 얻는다는 의미가 아니다. 팀의 저장소 규모, 실패 로그의 품질, 반복 업무의 종류, 사람이 결과를 검토하는 시간에 따라 실제 효과는 크게 달라진다. 이 글에서도 그 수치를 일반적인 성능 보증처럼 사용하지 않는다.
또한 GitHub Actions에서 실행되기 때문에 Actions 사용이 금지된 저장소나 조직 정책이 제한적인 환경에서는 도입할 수 없다. 조직의 러너 그룹과 정책 제약도 그대로 적용된다. 외부 모델에 코드와 로그를 보낼 수 있는지, 저장소에 민감한 정보가 포함되는지, AI가 만든 이슈나 PR을 누가 검토할지도 별도로 결정해야 한다.
도구의 소스는 공개돼 있고 저장소의 LICENSE는 MIT 라이선스다. 그러나 소프트웨어 라이선스가 발표 페이지의 스크린샷·브랜드 이미지까지 자유롭게 재배포할 권한을 자동으로 주는 것은 아니다. 그래서 이 글은 제품 화면을 무단 복사하지 않고, 공식 데모와 문서로 바로 이동할 수 있는 링크를 제공한다.
우리 저장소에 도입할지 판단하는 세 가지 질문
첫째, 자동화하려는 작업이 정말 판단을 요구하는가. `npm test`를 실행하고 실패하면 중단하는 일은 기존 Actions가 더 단순하고 예측 가능하다. 반면 반복되는 실패 로그를 읽고 원인을 추려 담당자에게 설명하는 일은 에이전트의 강점이 드러날 수 있다. 정해진 규칙만 필요한 작업을 굳이 모델 호출로 바꾸면 비용과 불확실성만 늘어난다.
둘째, 결과를 검증할 사람이 있는가. 자동 분류된 이슈가 틀렸을 때 누가 고치는지, 자동 제안 PR의 테스트를 누가 확인하는지 정하지 않으면 저장소가 오히려 시끄러워질 수 있다. 처음에는 기존 코드를 변경하지 않는 일일 보고서나 CI 원인 분석처럼 되돌리기 쉬운 결과로 실험하는 것이 합리적이다.
셋째, 비용과 보안 범위를 설명할 수 있는가. 트리거 하나가 한 달에 몇 번 실행되는지, 어떤 모델이 어떤 자료를 읽는지, 결과가 어느 권한으로 기록되는지 문서화해야 한다. 실행 기록과 비용을 며칠 관찰한 뒤 필요한 경우에만 작업 범위를 넓히면, 자동화가 실제로 시간을 줄이는지 판단하기 쉬워진다.
정리하면 이번 발표의 핵심은 'GitHub에서 AI가 일한다'는 문구보다 Markdown으로 정의한 판단 작업을 기존 Actions의 실행·감사 체계에 연결할 수 있게 됐다는 데 있다. 일단 작은 읽기 중심 워크플로 하나로 시작하고, 사람이 결과를 검증할 수 있을 때에만 쓰기 작업을 허용하는 접근이 적합하다.