GitHub Agentic Workflows 가이드 — 마크다운 워크플로가 코딩 에이전트를 어디까지 통제하는가

1. 핵심 요약

용어를 먼저 정합니다. GitHub Actions는 저장소 이벤트에 맞춰 워크플로를 실행하는 GitHub의 자동화 서비스입니다. 코딩 에이전트는 자연어 지시를 받아 파일을 읽고 명령을 실행하며 여러 단계를 스스로 진행하는 프로그램으로, Copilot CLI·Claude Code·Codex가 여기 해당합니다. 안전한 출력(safe outputs)은 에이전트가 직접 GitHub에 쓰는 대신 "이슈를 하나 만들어 달라"처럼 구조화된 요청을 내놓고, 권한을 가진 별도 잡이 그 요청을 검증해 실행하는 구조입니다. AI 크레딧(AIC)은 GitHub Copilot의 사용량 과금 단위로 1 AIC가 미화 1센트입니다. [1] [4]

이 글의 수치는 모두 2026-09-16 확인한 GitHub 공식 문서의 기본값입니다. 자체 측정은 없으며, 미리보기 기능이라 기본값과 명령이 바뀔 수 있습니다. 문서가 "설계"라고 적은 것과 "보장"이라고 적은 것을 구분해 옮겼습니다.

2. GitHub Agentic Workflows는 무엇인가

공식 문서의 정의는 이렇습니다. "마크다운으로 정의하고 GitHub Actions 워크플로로 실행하는 AI 기반 저장소 자동화". 기존 Actions가 정해진 조건과 명령을 그대로 실행한다면, 에이전트 워크플로는 이슈 본문이나 CI 로그 같은 맥락을 읽고 무엇을 할지 판단합니다. 문서가 드는 용도는 이슈 분류, PR 자동 리뷰, CI 실패 조사, 문서 유지보수, 코드 품질 개선, 보안 리뷰입니다. [1] [2]

동작 구조는 두 단계입니다. 워크플로 파일은 YAML 프론트매터(언제 실행하고 무엇을 허용하는가)와 마크다운 본문(에이전트에게 주는 자연어 지시)으로 구성됩니다. 이 파일을 gh aw compile로 컴파일하면 옆에 .lock.yml이 생기고, 실제로 Actions가 실행하는 것은 이 잠금 파일입니다. 두 파일을 모두 커밋합니다. 마크다운 본문은 GitHub 웹에서 고쳐도 되지만 프론트매터를 바꾸면 다시 컴파일해야 합니다. [8]

엔진마다 인증 방식이 다릅니다. Copilot은 워크플로 권한에 copilot-requests: write를 주면 기본 GITHUB_TOKEN으로 조직에 과금되고, Claude Code는 ANTHROPIC_API_KEY, Codex는 CODEX_API_KEY 또는 OPENAI_API_KEY, Gemini는 GEMINI_API_KEY를 저장소 시크릿으로 넣습니다. 문서는 Copilot이 에이전트 선택, 사용자 정의 실행 하네스, 중단된 실행 이어가기 같은 엔진별 기능을 가장 폭넓게 지원한다고 설명합니다. 개발사 자신의 설명입니다. [5]

3. 설치와 첫 워크플로

공식 빠른 시작의 명령은 다섯 개입니다. 확장을 설치하고, 미리 만들어진 워크플로를 마법사로 추가하고, 컴파일하고, 실행하고, 상태를 봅니다. [7]

아래는 docs.github.com이 싣고 있는 예제의 프론트매터를 표로 요약한 것입니다. 매주 월요일 이슈 활동을 정리해 이슈 하나를 만드는 워크플로이며, 키와 값은 문서 그대로입니다. [12]

본문은 "지난 7일의 이슈 활동을 검토하고, 열린·닫힌 이슈 수, 반복되는 주제, 주의가 필요한 이슈, 관리자에게 권하는 두세 가지를 담은 이슈를 만들라. 간결하게"입니다. 눈여겨볼 것은 본문이 아니라 프론트매터입니다. 이 워크플로가 저장소에 할 수 있는 쓰기 작업은 이슈 하나를 만드는 것뿐이고, 그것도 에이전트가 직접 하는 게 아니라 요청을 남기면 다른 잡이 만듭니다. 샘플 저장소 githubnext/agentics에는 이슈 분류, CI 실패 조사, 비용 추적, 악성 코드 일일 스캔 같은 워크플로가 더 있습니다. 문서는 "신뢰할 수 있는 출처의 워크플로만 가져오고, 추가하기 전에 무엇을 하는지 검토하라"고 적었습니다. [13] [12]

4. 통제 ① 읽기 전용 권한과 안전한 출력

보안 아키텍처 문서는 이 통제 구조를 세 계층으로 설명합니다. 첫 번째 계층은 러너와 컨테이너·가상화 격리, 두 번째 계층은 컴파일 시점의 검증(스키마 검사, 표현식 허용 목록, 액션의 SHA 고정), 세 번째 계층은 실행 시점의 단계 분리입니다. 이 글이 가장 중요하게 보는 것은 세 번째 계층입니다. 문서의 표현을 풀어 쓰면, 에이전트는 외부 시스템에 직접 쓰기 권한을 갖지 않고, 쓰기 작업은 에이전트 실행이 끝난 뒤 별도 잡에서만 실행됩니다. 에이전트 잡의 기본 권한은 contents: read, issues: read, pull-requests: read입니다. [3]

쓰기는 안전한 출력으로만 합니다. 프론트매터에는 허용할 쓰기 작업의 종류와 최대 개수를 선언하고, 에이전트는 실행 중에 그 형식에 맞는 요청만 남깁니다. 요청은 위협 탐지 잡을 거친 뒤 쓰기 권한을 가진 잡이 실행합니다. 문서의 기본 상한은 아래와 같습니다. [4]

안전한 출력 참조 문서의 기본값입니다. 표에 없는 종류(이슈 갱신·닫기, 토론 생성, 마일스톤, 릴리스 갱신, 체크 런 등)도 있으며 대부분 기본 1입니다. 상한은 프론트매터에서 바꿀 수 있습니다.

이 구조가 실제로 막는 것과 막지 못하는 것을 나눠 보면 이렇습니다. 막는 것은 에이전트가 지시문이나 이슈 본문에 속아 임의의 쓰기를 하는 것입니다. 선언하지 않은 종류의 쓰기는 실행할 잡이 없고, 선언한 종류도 개수 상한에 걸립니다. 막지 못하는 것은 허용한 쓰기의 내용이 틀린 것입니다. 이슈 하나를 만들도록 허용했다면 그 이슈의 내용이 엉뚱해도 구조는 막지 않습니다. PR 생성을 허용했다면 PR의 코드가 나쁜 것도 마찬가지입니다. 그 부분은 5절의 위협 탐지와 사람의 리뷰가 맡습니다. AI가 만든 PR을 어떻게 검토할지는 AI가 쓴 코드의 품질 리포트에서 다뤘습니다.

5. 통제 ② 네트워크 방화벽·샌드박스·위협 탐지

네트워크. 프론트매터에 network:가 없으면 network: defaults가 적용되어 인증서·JSON 스키마·Ubuntu·주요 패키지 미러·Microsoft 도메인 같은 기반 도메인만 허용됩니다. 그 위에 python·node·github 같은 생태계 이름이나 개별 도메인을 더하고, blocked로 뺄 수 있습니다. 이 네트워크 제한은 Agent Workflow Firewall(AWF)이 적용합니다. 아키텍처 문서에 따르면 iptables로 HTTP·HTTPS 트래픽을 Squid 프록시 컨테이너로 돌려 도메인 허용 목록을 적용하며, 목적은 "데이터 유출 방지"입니다. 모든 엔진에 기본 적용되고 끌 수 있지만 문서는 "운영 환경에서는 켜 두라"고 적었습니다. [14] [3]

샌드박스. 아키텍처 문서는 첫 번째 계층을 GitHub 호스팅 러너 또는 Linux 자체 호스팅 러너 위의 Docker·gVisor·KVM 격리로 설명하고, 9월 7일 주간 업데이트는 워크플로 실행 환경을 Cloud Hypervisor 기반 마이크로VM으로 옮기는 중이라고 적었습니다. 격리 방식 자체의 강약보다 운영 설정이 결과를 좌우한다는 점은 에이전트 샌드박스 리포트에서 다뤘습니다. [3] [15]

입력 정제. 이슈 본문처럼 외부인이 쓴 텍스트가 에이전트에게 들어갈 때 @user는 코드 서식으로 감싸 알림이 가지 않게 하고, fixes #123 같은 자동 연결 문구도 무력화하며, XML 태그는 (script)처럼 바꾸고, 신뢰하지 않는 도메인의 URL은 (redacted)로 지웁니다. 프롬프트 인젝션(외부 텍스트에 숨긴 지시로 에이전트를 조종하는 공격)의 파급을 줄이려는 조치이며, 인젝션 자체를 없애는 것은 아닙니다. [3]

위협 탐지. 안전한 출력이 실행되기 전에 별도 잡이 에이전트의 출력물(이슈·댓글·PR 본문과 git 패치)을 검사합니다. 검사 항목은 프롬프트 인젝션, 시크릿 유출, 악성 패치 세 가지이고, 기본적으로 본 워크플로와 같은 AI 엔진이 JSON 판정을 내립니다. 위협이 발견되면 탐지 잡이 실패하고 안전한 출력 잡은 건너뜁니다. 설정은 프론트매터의 safe-outputs 아래 각 출력 종류에 threat-detection:으로 붙이며, 그 안의 max-ai-credits로 본 에이전트와 별도인 예산을 두고, engine: false로 AI 판정을 끄고 직접 넣은 스캐너만 쓸 수도 있습니다. 문서는 "탐지는 본 에이전트의 예산을 물려받지 않으며 두 상한이 각자 적용된다"고 적었습니다. [16]

아키텍처 문서는 이 설계의 한계도 함께 설명합니다. 첫 번째 계층(러너·격리)이 뚫리면 "상위 계층의 보안 보장은 성립하지 않을 수 있다"고 했고, 하드웨어·암호 기본 요소의 침해와 부채널·은닉 채널 공격은 범위 밖이라고 명시했습니다. 두 번째 계층에 대해서는 "보안 위반은 잘못된 설정, 과도한 허용, 선언형 모델의 한계에서 생긴다"고 적었습니다. 즉 통제의 강도는 결국 프론트매터를 얼마나 좁게 쓰느냐에 달려 있습니다. [3]

6. 통제 ③ AI 크레딧과 비용 구조

비용은 두 갈래입니다. GitHub Actions 분(러너 시간)과, 엔진의 추론 비용입니다. 추론 비용은 AI 크레딧으로 셉니다. GitHub Copilot은 2026년 6월 1일부터 사용량 기반 과금으로 바뀌어 요청 횟수 대신 토큰 사용량을 크레딧으로 계산하며, Copilot Pro는 월 $10 요금에 $10어치, Business는 사용자당 $19에 $19어치 크레딧이 포함됩니다. 코드 완성은 크레딧을 쓰지 않습니다. [17] 에이전트 워크플로 문서는 1 AIC = $0.01로 명시하고, 아래 기본 상한을 둡니다. [6]

비용 관리 문서와 프론트매터 참조의 값입니다. 달러 환산은 1 AIC = $0.01로 이 글이 계산한 파생값입니다. 하루 상한 5,000 AIC는 비용 관리 문서의 기본 가드레일 목록에 있고, 프론트매터 참조 문서는 max-daily-ai-credits의 기본값을 비활성으로 설명해 두 문서가 서로 다르게 읽힙니다. 9절에 적었습니다.

실행당 $10은 상한이지 예상 비용이 아닙니다. 실제 사용량은 모델 요금과 컨텍스트 크기에 따라 달라지며, 문서는 비용을 낮추는 방법으로 네 가지를 듭니다. 에이전트를 깨우기 전에 skip-if-match·skip-if-no-match로 조건을 걸러 아예 실행하지 않기, 더 싼 모델(gpt-4.1-mini·claude-haiku-4-5가 예시) 쓰기, 이벤트마다 반응하지 말고 일정 실행으로 묶기, 동시 실행과 속도 제한을 두기입니다. Actions 분은 잡 단위로 올림 과금되므로 실행 시간이 곧 비용입니다. [6]

누가 내는지는 엔진에 따라 다릅니다. Copilot 엔진은 copilot-requests: write 권한으로 조직의 Copilot 크레딧에서 나가고, Claude·Codex·Gemini는 저장소 시크릿에 넣은 API 키의 계정으로 각 개발사가 청구합니다. 위협 탐지 잡도 추론을 쓰므로 그 비용이 별도로 붙습니다. [1] [16] 토큰 비용을 줄이는 일반 원칙은 프롬프트 캐싱 리포트에서 다뤘습니다.

7. 어디에 맞고 어디에 맞지 않는가

문서와 샘플로 보면 이 기능이 겨냥하는 자리는 분명합니다. 고정된 규칙만으로 처리하기 어렵지만, 틀려도 되돌리기 쉬운 반복 작업입니다. 이슈에 라벨을 붙이고, CI 실패 로그를 읽어 원인 후보를 댓글로 남기고, 주간 활동을 이슈로 요약하고, 문서의 낡은 부분을 PR로 제안하는 일입니다. 결과물이 이슈·댓글·PR이라 사람이 보고 버릴 수 있습니다.

이 표는 공식 문서의 통제 범위와 샘플 워크플로를 바탕으로 이 글이 정리한 판단이며, 문서가 "맞지 않는다"고 명시한 목록은 없습니다.

선택 기준 하나를 덧붙이면, 이 기능은 Copilot을 이미 쓰는 조직에서 마찰이 가장 적습니다. 인증이 GITHUB_TOKEN으로 끝나고 과금이 조직 크레딧으로 합쳐지며, 문서가 밝힌 대로 엔진별 기능도 Copilot이 가장 넓기 때문입니다. Claude Code나 Codex를 엔진으로 쓰면 API 키를 시크릿에 넣어야 하고 비용은 따로 관리해야 합니다. 어느 쪽이든 macOS 러너는 쓸 수 없습니다.

8. 오늘 적용할 체크리스트

• 되돌리기 쉬운 작업 하나로 시작합니다. 이슈 라벨링이나 주간 요약처럼 결과가 이슈·댓글로 남는 것을 고릅니다. gh aw add-wizard githubnext/agentics/<이름>으로 샘플을 가져오되, 추가 전에 프론트매터를 읽습니다.
• 안전한 출력을 최소로 선언합니다. 필요한 종류만, 개수 상한은 기본값(대부분 1)을 유지합니다. create-pull-request를 열 때는 보호 파일 목록을 확인합니다.
• 네트워크는 defaults에서 시작해 필요한 생태계만 더합니다. 방화벽을 끄지 않습니다. 사내 API를 열어야 하면 도메인 단위로 추가하고 blocked로 제외할 것을 적습니다.
• 위협 탐지 엔진을 본 워크플로와 다르게 둡니다. 프론트매터의 safe-outputs 아래 해당 출력의 threat-detection: engine:에 다른 엔진을 지정하거나, 자체 스캐너를 steps로 앞에 둡니다.
• 비용 상한을 명시합니다. max-ai-credits와 max-daily-ai-credits를 프론트매터에 적어 두고, 이벤트 트리거보다 일정 실행을 우선합니다. Actions 분은 실행 시간이 곧 비용입니다.
• 트리거 조건을 먼저 거릅니다. skip-if-match로 라벨·제목 조건에 맞지 않으면 에이전트를 깨우지 않게 합니다.
• 잠금 파일을 함께 커밋하고, 프론트매터를 고치면 다시 컴파일합니다. .lock.yml이 실제 실행 파일입니다. 미리보기라 gh aw upgrade 뒤 gh aw update로 워크플로도 갱신해야 합니다.
• 비용과 결과를 기록합니다. 샘플의 Cost Tracker처럼 실행당 지출을 PR에 남기고, 사람이 실제로 채택한 제안의 비율을 셉니다. 채택률이 낮으면 지시문보다 트리거 조건을 먼저 좁힙니다.

9. 아직 결론이 아닌 것

• 이 글은 공식 문서의 정리이며 자체 측정이 없습니다. 통제가 실제로 어느 정도 막는지, 위협 탐지가 인젝션을 얼마나 잡는지에 대한 독립 측정을 확인하지 못했습니다. 문서도 탐지 정확도를 제시하지 않습니다.
• 공개 미리보기입니다. GitHub 자신이 "변경될 수 있다"고 적었고, 저장소는 9월 13~14일 이틀 사이에 다섯 번 릴리스됐습니다. 이 글의 명령·키·기본값은 2026-09-16 기준입니다.
• 하루 상한의 기본값이 문서마다 다르게 읽힙니다. 비용 관리 문서는 "워크플로당 하루 5,000 AI 크레딧"을 기본 가드레일로 적고, 프론트매터 참조 문서는 max-daily-ai-credits의 기본값을 비활성으로 설명합니다. 두 값 중 어느 것이 실제 기본인지는 실행해 확인해야 합니다.
• Copilot 크레딧 포함량은 공식 블로그의 요금제 설명이며, 에이전트 워크플로 실행이 그 포함량에서 얼마나 빠지는지는 문서가 수치로 적지 않았습니다. 실행당 상한 1,000 AIC는 상한이지 평균이 아닙니다.
• 공식 한국어 문서는 기계 번역으로 보입니다. "에이전트 워크플로", "안전한 출력" 같은 표기는 그 문서를 따랐지만, 문장 일부가 어색합니다. 정확한 뜻은 영어 문서를 기준으로 삼았습니다.
• 7절의 "맞는 자리·맞지 않는 자리"는 이 글의 판단입니다. 문서는 용도를 나열할 뿐 부적합 목록을 두지 않았습니다.
• 샌드박스 이전(마이크로VM)은 진행 중인 변경입니다. 9월 7일 주간 업데이트가 "옮기는 중"이라고 적었고, 어느 러너에 언제 적용됐는지는 확인하지 못했습니다.
• Actions 분 비용은 러너 종류와 요금제에 따라 달라 이 글이 계산하지 않았습니다.

10. 참고자료

모두 2026-09-16 확인했습니다. 전부 GitHub의 공식 문서·변경 로그·저장소이며, 제공사의 설명이지 독립 측정이 아닙니다. 이 글은 기본값과 명령을 그대로 옮기고 판단은 판단이라고 표시했습니다.

편집 기준: 문서의 기본값과 명령은 그대로 옮기고, 통제가 "막는 것"과 "막지 못하는 것"을 나누어 적었으며, 문서 사이에 어긋나는 기본값은 어느 쪽인지 확정하지 않고 한계 절에 남겼습니다.