실습 노트
GitHub Agentic Workflows: Markdown으로 정의하는 저장소 자동화
GitHub Agentic Workflows가 Markdown 지시문을 GitHub Actions로 컴파일하고, 읽기 전용 에이전트와 제한된 쓰기를 분리하는 방식을 정리합니다.
저장소 자동화에 AI를 넣을 때 모든 단계를 에이전트에게 맡기면 재현성과 권한 관리가 약해집니다. GitHub Agentic Workflows(gh-aw)는 결정적인 빌드·테스트·배포는 기존 GitHub Actions에 남기고, 이슈 분류·PR 검토·실패 원인 조사처럼 해석이 필요한 작업만 Markdown 기반 에이전트 워크플로우로 분리합니다.
Markdown을 Actions로 컴파일
gh-aw의 에이전트 워크플로우는 YAML frontmatter와 Markdown 본문으로 구성됩니다. frontmatter에는 트리거, 권한, 도구, AI 엔진을 적고, 본문에는 에이전트가 달성할 목적을 설명합니다.
공식 저장소가 설명하는 기본 흐름은 다음과 같습니다.
gh extension install github/gh-aw
gh aw compile
gh aw compile은 작성한 원본을 검증하고 GitHub Actions가 실행할 .lock.yml 파일을 생성합니다. 사람은 읽기 쉬운 Markdown을 관리하고, Actions는 고정된 실행 정의를 수행하는 분리입니다.
판단 작업과 결정 작업 분리
일반 Actions에 적합한 작업은 입력과 결과가 명확합니다.
- 의존성 설치
- 테스트 실행
- 린트와 빌드
- 정해진 스크립트 실행
- 배포 단계
반면 다음 작업은 문맥 해석이 필요합니다.
- 이슈를 담당 영역으로 분류하기
- PR 변경 내용을 요약하고 위험 지점 찾기
- CI 실패 로그에서 원인 후보 묶기
- 문서의 오래된 예시 찾기
- 여러 파일의 변경 영향 설명하기
이 둘을 섞지 않으면 에이전트의 판단 결과를 결정적인 검사와 대조할 수 있습니다. 에이전트가 “테스트가 필요하다”고 판단하는 것과 테스트 명령이 실제로 통과하는 것은 다른 사실이기 때문입니다.
읽기와 쓰기를 다른 작업으로
gh-aw는 에이전트 작업을 기본적으로 읽기 전용·샌드박스 실행으로 두고, 저장소에 쓰는 작업은 safe-outputs를 거치는 별도 작업으로 설명합니다. 이 구조에서는 에이전트가 초안을 제안하더라도 실제 이슈 댓글, 라벨, 파일 변경은 설정된 출력 형식과 권한을 통과해야 합니다.
도입할 때 확인할 항목은 단순히 AI 모델 이름이 아닙니다.
- 어떤 이벤트가 워크플로우를 시작하는가
- 에이전트가 읽을 수 있는 저장소와 외부 도메인은 어디까지인가
- 생성 결과가 파일·댓글·라벨 중 무엇으로 제한되는가
- 쓰기 작업을 적용하는 별도 job의 권한은 무엇인가
- 생성된 lock 파일과 실행 결과를 어떻게 검토하는가
공식 문서도 도구, 네트워크, 권한, 생성 파일을 배포 전에 검토하고 사람의 감독을 유지해야 한다고 명시합니다.
최신 릴리스에서 무엇이 달라졌나요?
GitHub의 2026년 9월 7일 주간 업데이트는 v0.88.4 릴리스가 에이전트 방화벽·네트워크 경계와 CI 안정성에 초점을 둔다고 설명합니다. GitHub API와 릴리스 페이지에서 확인한 v0.88.4는 현재 pre-release로 표시되어 있으므로 운영 저장소에 바로 고정하기보다 테스트 저장소에서 먼저 확인해야 합니다.
이번 릴리스에는 trusted enclave의 민감도 설정, GitHub App 워크플로를 위한 DIFC(data-flow integrity/confidentiality) 정책 생성, aw.json 프로젝트 지원이 포함됩니다. Linear·Jira 연동을 점검하는 예약 워크플로와 방화벽 라우팅·OTLP·경로 처리 관련 수정도 함께 기록되어 있습니다.
이 변화는 에이전트에게 작업 순서만 알려 주는 방식에서 벗어나 데이터 흐름, 실행 환경, 외부 연동의 경계까지 선언하려는 방향으로 읽을 수 있습니다. 기능이 있다는 사실은 조직의 보안 승인이나 규정 준수를 뜻하지 않습니다.
공식 README에는 0.83.3 이상 0.85.4 미만 버전에서 발견된 보안 취약점과 해당 버전의 철회 안내가 있습니다. 설치 전에 사용할 버전의 릴리스 상태와 보안 공지를 확인해야 합니다.
적용 판단
gh-aw는 기존 CI/CD를 에이전트로 대체하는 도구가 아니라, GitHub 이벤트에 해석 작업을 추가하는 계층입니다. 첫 적용은 읽기 전용 이슈 요약이나 PR 위험 지점 보고처럼 결과를 관찰하기 쉬운 업무가 적합합니다.
자동 댓글, 라벨 변경, 파일 수정으로 넓힐 때는 safe outputs와 최소 권한을 먼저 설계해야 합니다. 에이전트가 만든 결과가 맞는지보다, 틀린 결과가 나와도 저장소를 망가뜨리지 않는 경계가 먼저 갖춰져야 합니다.