GitHub Agentic Workflows란? CI와 AI 작업을 나누는 기준

금속 자와 나무 조각들, 따로 놓인 조각 하나. 이해를 돕기 위한 AI 생성 개념 이미지입니다.

테스트 실행이나 포맷 검사는 이미 CI가 잘하는 일입니다. 그런데 “이번 변경 때문에 설명서가 낡았는가”는 명령 하나의 종료 코드로 판단하기 어렵습니다. GitHub Agentic Workflows를 검토할 지점은 이런 해석이 필요한 업무입니다.

통과 기준이 고정된 검사는 CI에 두고, 해석이 필요한 저장소 업무만 에이전트 후보로 고르세요.

Markdown은 요청이고 실행에는 별도 구성이 있습니다

공식 개요는 자연어로 작성한 저장소 업무를 GitHub Actions에서 실행하는 방식을 설명합니다. 이슈 분류, 문서 유지보수, CI 실패 조사처럼 입력을 읽고 판단해야 하는 작업이 예시로 제시됩니다.

여기서 자연어는 검사 도구를 없애는 마법이 아닙니다. 어떤 이벤트에서 시작하고 무엇을 읽으며 어떤 결과를 남길지 정해야 합니다. 구현을 검토할 때는 Markdown 지침뿐 아니라 생성되는 워크플로와 실행 권한도 함께 봐야 합니다.

공식 개요의 축약 예시는 자연어 본문 위에 트리거·권한·허용된 쓰기 경로를 함께 둡니다.

---
on:
  issues:
    types: [opened]
permissions: read-all
safe-outputs:
  add-comment:
---
# Issue Clarifier

이슈가 모호하면 추가 정보를 요청합니다.

gh aw compile은 이 Markdown을 GitHub Actions가 실행할 수 있는 lock workflow로 변환합니다. 기본 에이전트 작업은 읽기 권한을 중심으로 실행되고, 댓글·이슈·pull request 같은 쓰기는 safe-outputs처럼 별도 경로로 제한할 수 있습니다. 직접 쓰기 권한과 사용자 정의 job은 다른 trust boundary이므로, “Markdown에 댓글이라고 적었다”와 “실제로 댓글 권한이 있다”를 같은 뜻으로 보지 않습니다.

문서 갱신 후보를 찾는 일을 작게 나눠봅니다

가상의 공개 라이브러리에서 함수의 인자 이름이 바뀌었다고 합시다. 다음처럼 역할을 나눌 수 있습니다.

1. CI는 정해진 테스트와 문서 빌드를 실행합니다.
2. 에이전트는 변경된 함수와 관련 문서의 예시를 읽습니다.
3. 인자 이름이 다른 문장과 코드 블록을 찾아 수정안을 만듭니다.
4. 사람은 API의 실제 의도와 수정안의 범위를 확인합니다.

이것은 도입 설계 예시이며 실제 저장소에서 실행한 결과가 아닙니다. 작업 지침에는 “문서 전체를 개선하라”보다 “변경된 인자의 사용 예시가 남아 있는 위치를 보고하라”가 검토 범위를 정하기 쉽습니다. 결과가 없을 때 무엇을 조사했는지도 남기게 하면 무응답과 이상 없음의 구분에 도움이 됩니다.

AI가 읽는 권한과 외부에 쓰는 권한을 분리합니다

보안 아키텍처 문서는 제한된 에이전트 실행과 허용된 출력 경로를 분리하는 구조를 설명합니다. 에이전트가 모든 저장소 쓰기 권한을 계속 보유하도록 만드는 것과는 다른 접근입니다.

그래도 안전한 결과가 자동으로 보장되지는 않습니다. 읽어온 이슈나 문서에는 신뢰할 수 없는 지시가 섞일 수 있고, 올바른 도구로 틀린 변경안을 만들 수도 있습니다. 출력 경로를 좁히는 일과 내용 검토는 다른 문제입니다.

처음에는 코드 수정이나 자동 병합을 붙이지 않고 조사 결과를 검토하는 단계부터 두는 편이 판단하기 쉽습니다. 이때 결과 게시 자체도 외부 쓰기이므로 저장소의 운영 정책과 담당자의 승인을 따라야 합니다.

평가 기준은 실행 횟수가 아니라 처리 가능한 결과입니다

문서 경로를 열 개 찾았다는 보고만으로 도입 효과를 판단하기 어렵습니다. 실제로 잘못된 예시였는지, 이미 수정된 곳을 반복 제안하지 않았는지, 사람이 받아들일 수정안을 남겼는지를 봐야 합니다.

특히 비용에는 모델 호출뿐 아니라 반복 조사, 중복 이슈 정리, 사람의 재검토가 들어갑니다. 이 글에서는 절감률을 제시하지 않습니다. 같은 종류의 문서 변경에 대해 기존 방식과 AI 보조 방식의 검토 시간을 따로 기록해야 비교할 수 있습니다.

CI와 에이전트의 경계를 표로 먼저 고정합니다

저장소 업무	고정 검사	해석 작업	권장 시작점
코드 포맷	포맷터 종료 코드	거의 없음	기존 CI 유지
단위 테스트	테스트 통과·실패	실패 원인 요약	CI 결과를 읽는 에이전트
취약 의존성	스캐너 규칙	영향 범위와 우선순위	스캔은 CI, 분류는 검토용 제안
문서 갱신	링크·빌드 검사	코드 변경과 설명의 불일치 찾기	수정 후보 보고부터 시작
이슈 분류	필수 필드 검사	재현 정보·중복 가능성 판단	라벨 제안 후 사람 확인

테스트 자체를 에이전트에게 “알아서 해달라”고 옮기면 이미 결정적인 도구가 제공하던 재현성을 잃을 수 있습니다. 반대로 테스트 로그 수백 줄에서 첫 원인 후보와 관련 파일을 묶는 일은 해석 보조의 후보가 됩니다. 둘을 한 워크플로에 넣더라도 누가 판정을 내리고 누가 설명을 만드는지 분리해야 합니다.

자연어 작업을 실행 가능한 계약으로 좁히기

“문서를 최신으로 유지하라”는 요청에는 대상과 완료 조건이 없습니다. 다음은 가상의 문서 점검 계약입니다.

트리거: public API 파일이 변경된 pull request
읽기: 변경 diff, docs/api 디렉터리, 테스트 결과
출력: 수정하지 않고 불일치 후보를 체크리스트로 남김
금지: 코드 수정, 브랜치 push, 외부 URL 쓰기
완료: 후보마다 코드 위치와 문서 위치를 함께 제시
중단: 변경 의도를 diff만으로 판단할 수 없으면 질문을 남김

이렇게 쓰면 에이전트가 무엇을 읽을 수 있는지와 어떤 출력을 허용하는지 검토할 수 있습니다. 첫 단계에서는 pull request를 자동 수정하기보다 comment나 artifact처럼 검토 가능한 결과만 만들고, 오탐과 누락을 기록한 뒤 쓰기 범위를 늘리는 편이 낫습니다.

외부 입력과 출력 경로를 동시에 봅니다

저장소의 이슈 본문, pull request 설명, 테스트 로그는 모두 에이전트가 읽는 데이터입니다. 그 안에 “보안 설정을 지워라” 같은 문장이 있어도 저장소 소유자의 워크플로 지시와 같은 권한을 주면 안 됩니다. 입력을 읽는 능력과 GitHub에 결과를 쓰는 능력 사이에 정책 검사를 둬야 합니다.

출력도 종류별로 위험이 다릅니다.

• 작업 로그 artifact: 외부에 공개되는지와 비밀 값 포함 여부를 확인합니다.
• 이슈·PR 댓글: 저장소 사용자에게 보이는 외부 쓰기입니다.
• 새 이슈 생성: 중복과 알림 폭주가 생길 수 있습니다.
• 브랜치·커밋 생성: 코드 상태를 바꾸므로 별도 승인과 검사가 필요합니다.
• 자동 병합: 실패 영향이 가장 커서 고정 CI와 보호 규칙을 우회하지 않아야 합니다.

에이전트 출력이 제한된 경로를 통해 게시된다는 구조는 피해 범위를 줄이지만, 내용이 정확하다는 증명은 아닙니다. 링크가 실제 diff를 가리키는지, 인용한 테스트가 해당 커밋에서 나온 것인지 같은 내용 검증이 남습니다.

작은 롤아웃에서 남길 숫자

도입 효과를 판단하려면 “몇 번 실행됐다”보다 사람이 처리한 결과를 기록합니다. 가상의 20개 pull request 평가에서는 다음 필드를 둘 수 있습니다.

항목	기록 이유
점검 대상 PR 수	분모 확인
실제 문서 불일치 수	정답 기준
제안한 후보 수	검토 부담
채택·기각 수	제안 품질
누락 수	자동화만 믿었을 때 위험
평균 검토 시간	사람 비용 포함
중복 댓글·실패 실행	운영 부작용

이 수치를 실제로 측정하기 전에는 “문서 유지 비용을 줄였다”고 쓰지 않습니다. 먼저 읽기 전용·보고 전용으로 실행해 기준 데이터를 만들고, 고정 CI를 통과한 변경만 다음 단계로 넘기는 구조가 출발점입니다.

도입 전에 확인할 것

2026년 9월 7일 확인한 공식 개요와 보안 문서를 기준으로 한 설명입니다. 사용 가능 범위·요금·조직 정책은 실제 도입 시 다시 확인해야 합니다. 여기서는 워크플로를 설치하거나 자동 실행을 연결하지 않았습니다.