CI/CD의 새 언어는 자연어다 — GitHub Agentic Workflows 해부

YAML 들여쓰기를 한 칸 틀려서 파이프라인이 깨지고, 30분을 허비한 경험이 한 번쯤은 있을 것이다. needs, uses, with의 미묘한 조합을 외우다 지친 적도 있을 것이다. GitHub이 이 고통에 정면으로 답했다. 워크플로우를 마크다운으로 기술하고, AI 에이전트가 해석해서 실행하는 Agentic Workflows다.

레시피북에서 셰프로 — Agentic Workflows의 정체

GitHub Agentic Workflows는 .github/workflows/ 디렉토리에 마크다운 파일을 넣으면, AI 코딩 에이전트가 지시를 읽고 리포지토리 맥락을 활용해 작업을 수행하는 시스템이다. GitHub, Microsoft Research, Azure Core Upstream의 협업 결과물이며, 현재 기술 프리뷰(Technical Preview) 단계다.

기존 GitHub Actions가 한 글자도 틀리면 안 되는 요리 레시피북이라면, Agentic Workflows는 "냉장고에 뭐 있는지 보고 적당히 저녁 만들어줘"라고 지시할 수 있는 AI 셰프다. 정해진 스텝을 기계적으로 따르는 것이 아니라, 상황을 파악하고 판단해서 행동한다.

지원하는 AI 에이전트는 세 가지다.

[💡 잠깐! 이 용어는?] AI 에이전트(AI Agent): 단순 질의응답을 넘어, 스스로 계획을 세우고 도구를 사용해 작업을 수행하는 AI 시스템. 코드를 읽고, 수정하고, PR을 생성하는 등 개발자의 행동을 자율적으로 수행할 수 있다.

마크다운 한 장의 해부학 — 파일 구조

Agentic Workflow 파일은 YAML 프론트매터와 마크다운 지시사항, 두 층으로 구성된다.

---
name: Issue Triage
description: Automatically triage and label new issues
triggers:
  - issues:
      types: [opened]
model: copilot
permissions:
  issues: write
  contents: read
safe-outputs:
  - labels: 1-3
  - comment: 1
---
 
## Task
 
When a new issue is opened, analyze its content and apply appropriate labels.
 
### Steps
 
1. Read the issue title and body
2. Check existing labels in the repository
3. Determine the most relevant labels (1-3) based on:
   - Issue type (bug, feature, documentation, question)
   - Affected area (frontend, backend, infrastructure)
   - Priority (critical, high, medium, low)
4. Apply the labels
5. If the issue lacks sufficient detail, add a comment asking for more information

프론트매터가 규칙을 선언한다. 언제 실행할지(triggers), 뭘 읽을 수 있는지(permissions), 어떤 쓰기가 허용되는지(safe-outputs). 마크다운 본문은 AI 에이전트에게 건네는 지시서다. 자연어로 "뭘 해야 하는지"를 기술한다.

비유하면 프론트매터는 직원에게 주는 출입증과 권한카드이고, 마크다운 본문은 업무 지시서다. 출입증으로 어디까지 갈 수 있는지 정하고, 지시서로 뭘 해야 하는지 알려주는 구조다.

컴파일이라는 안전장치 — .lock.yml의 역할

마크다운 파일을 작성했다고 바로 돌아가는 것이 아니다. gh aw CLI로 컴파일 단계를 거친다.

gh aw compile

이 명령이 마크다운을 읽고, 보안 검증을 수행한 뒤, .lock.yml 파일을 생성한다. GitHub Actions가 실제로 실행하는 것은 이 lock 파일이다.

.github/workflows/
  ├── issue-triage.md       ← 사람이 읽고 편집하는 소스 파일
  └── issue-triage.lock.yml ← 컴파일된 Actions 워크플로우 (자동 생성)

이름에서 짐작할 수 있듯이 package-lock.json과 같은 맥락이다. 컴파일 시점의 설정을 잠가두어(lock) 재현성과 감사 가능성을 보장한다. 두 파일 모두 버전 관리에 커밋해야 한다.

[💡 잠깐! 이 용어는?] Safe-Outputs: Agentic Workflows의 핵심 보안 메커니즘. AI 에이전트에게 직접 쓰기 권한을 주지 않고, 미리 승인된 유형의 출력(라벨 추가, 코멘트 작성, PR 생성 등)만 허용하는 방식이다.

울타리 안의 AI — 보안 모델 설계

AI 에이전트에게 리포지토리 접근 권한을 주는 것은 본질적으로 위험하다. GitHub은 이를 위해 7겹의 보안 계층을 설계했다.

기존 GitHub Actions와 나란히 놓으면 차이가 선명하다.

실전 시나리오 — 어디에 쓸 수 있나

CI 실패를 AI가 고치는 워크플로우

CI가 깨지면 로그를 분석해 원인을 파악하고, 간단한 문제는 직접 수정 PR을 생성한다. 복잡한 문제는 사람에게 보고한다.

---
name: CI Failure Auto-Fix
description: Analyze CI failures and suggest or apply fixes
triggers:
  - check_run:
      types: [completed]
      conclusion: [failure]
model: claude
permissions:
  contents: read
  pull-requests: read
  checks: read
safe-outputs:
  - pull-request: 1
---
 
## Task
 
When a CI check fails, analyze the failure and attempt to fix it.
 
### Steps
 
1. Read the failed check run logs
2. Identify the root cause of the failure
3. If the fix is straightforward (lint error, type error, missing import):
   - Create a fix and open a pull request
4. If the fix requires human judgment:
   - Add a comment to the PR explaining the failure and suggesting approaches

24시간 대기하는 주니어 개발자가 CI 실패를 감시하면서 간단한 건 직접 고치고, 복잡한 건 시니어에게 보고하는 구조와 같다.

이슈 자동 분류

새 이슈가 열리면 AI가 내용을 분석해 라벨을 붙이고, 정보가 부족하면 추가 정보를 요청한다.

PR 자동 리뷰

PR이 생성되면 코드 변경을 분석해 잠재적 문제를 지적하고, 테스트 커버리지를 확인하고, 개선 제안을 코멘트로 남긴다.

[💡 잠깐! 이 용어는?] Technical Preview: 정식 출시 전 단계로, 기능이 변경되거나 제거될 수 있다. 프로덕션 환경에서의 사용은 주의가 필요하며, 피드백을 수집하기 위한 목적으로 공개된다.

시작 가이드

gh extension install github/gh-aw
 
gh aw init
 
gh aw compile
 
git add .github/workflows/
git commit -m "feat: add agentic workflow for issue triage"
git push

에이전트별로 필요한 시크릿이 다르다.

리포지토리 Settings > Secrets에서 해당 키를 설정하면 된다.

마무리

GitHub Agentic Workflows는 CI/CD 파이프라인에 AI 에이전트를 공식적으로 투입하는 첫 시도다. YAML 문법과 씨름하는 대신 자연어로 의도를 기술하고, AI가 맥락을 파악해 실행하는 패러다임은 매력적이다. 다만 아직 기술 프리뷰 단계이므로, 핵심 CI/CD 파이프라인보다는 이슈 분류나 코드 리뷰 보조 같은 부가적인 자동화부터 시도해보는 것이 현실적이다.

참고:

• GitHub Agentic Workflows 문서: https://github.github.io/gh-aw/
• GitHub Blog: https://github.blog/changelog/2026-02-13-github-agentic-workflows-are-now-in-technical-preview/
• gh-aw CLI: https://github.com/github/gh-aw