GitHub Agentic Workflow를 구축해 보았다

Agentic Workflow란

GitHub Actions에서 AI를 결합한 작업을 실행하는, CI/CD에 이은 Continuous AI 중 하나입니다.

원래 GitHub Next에서 공개되었던 것이 일반 프리뷰(General Preview)가 되었습니다.

간단히 말하자면 AI를 결합한 CI입니다.

지금까지의 GitHub Actions와 다른 점은 크게 두 가지가 있습니다.

첫 번째는, 정의를 마크다운(Markdown)으로 자연어로 관리한다는 점입니다.

그것을 컴파일함으로써 GitHub Actions가 읽어들이는 yaml이 생성됩니다.

즉, 관리하는 단계에서 AI가 개입합니다.

두 번째는, 작업(Job) 내에서 비결정론적(Non-deterministic)인 작업을 수행할 수 있다는 점입니다.

지금까지의 CI에서는 린터(Linter)나 테스트 실행 등 정적 평가나 결정론적 평가가 주를 이루었습니다.

여기에 AI를 결합함으로써 비결정론적인 작업을 지속적으로 수행할 수 있게 되었습니다.

요금

GitHub Actions의 요금과 AI 요금이 각각 발생합니다.

사전 준비

GitHub CLI (gh)를 설치하고 로그인한 상태일 것
brew install gh
aw extension을 설치
gh extension install github/gh-aw
gh 본체와 aw extension을 최신 버전으로 업데이트해 둘 것
brew update && brew upgrade gh gh extension upgrade aw

실전

우선 샘플을 도입해 보기

githubnext/agentics: A sample pack of GitHub Agentic Workflows! 리포지토리에 많은 샘플이 준비되어 있습니다.

우선 여기서부터 시도해 보는 것이 좋을 것 같습니다.

gh aw add-wizard githubnext/agentics/test-improver

test-improver는 정기 실행을 통해 테스트가 부족한 부분의 테스트 코드 추가 PR을 생성해 줍니다.

그 외에도 문서 자동 업데이트, 리포지토리 활동 요약 생성, 코드 리뷰 워크플로우, CI 최적화, 접근성 리뷰 등 상당한 양의 샘플이 준비되어 있습니다.

인증

Engine	Required secret	Notes
Copilot (default)	COPILOT_GITHUB_TOKEN	Fine-grained PAT with Copilot Requests permission
...

이러한 사용하고자 하는 API KEY를 GitHub의 Repository Setting > Security and quality > Secrets and variables > Actions > Repository secrets에 설정합니다.

Copilot의 경우에는 GitHub의 Fine-grained PAT를 생성합니다.

이때, public repository를 선택해 주세요.

호출 방식: 자동 실행형과 호출형

위 리포지토리의 샘플에 있는 것처럼 정기 실행, 기존 CI와 같이 PR 업데이트 시 실행, 그 외에 PR 댓글에 슬래시 명령(Slash command) 형식으로 댓글을 달면 실행하는 방식 등, 자동 실행하는 것과 수동으로 호출하는 것도 가능합니다.

하나의 워크플로우에 여러 트리거(Trigger)를 설정하는 것은 현재 불가능하므로, 여러 트리거를 설정하고 싶을 경우에는 트리거마다 만들어야 합니다.

자동 발화는 소비가 빨라지므로 정기 실행이나 슬래시 명령을 통한 호출이 무난할 것 같습니다.

또한, 트리거에 유효 기간을 설정할 수 있습니다.

stop-after: +3mo

라고 설정하면 컴파일로부터 3개월간 유효하며, 그 이후에는 pre-activation 단계에서 종료됩니다.

Fine-grained PAT의 유효 기간과 맞춰도 좋을 것 같습니다.

만들어 보기

기본적으로 하고 싶은 말을 AI에게 하여 마크다운을 만들게 하면 됩니다.

Copilot 기본값 이외의 것을 사용하고 싶다면 어떤 LLM을 사용할지, 어떤 모델을 사용할지 잊지 말고 지시합시다.

문서 자동 업데이트 워크플로우를 직접 만들었을 때의 프롬프트

api, CI/CD 업데이트, 또는 인증 관련 등 복잡한 작업이 있는 경우 docs 하위의 문서를 업데이트하도록 슬래시 커맨드(slash command)로도 실행할 수 있는 스킬을 추가하고, develop 브랜치를 향해 PR(Pull Request)이 생성되었을 때 자동으로 문서를 업데이트하는 Agentic Workflow를 작성해 줘.
불명확한 점이나 명확히 했을 때 더 좋은 결과를 낼 수 있는 부분에 대해서는 질문을 먼저 한 뒤에 작업을 진행할 것

앞서 언급했듯이 워크플로우의 트리거(trigger)는 한 종류만 지정할 수 있으므로, 이 경우에는 PR에서 자동으로 발화하는 것과 슬래시 커맨드로 호출하는 형식을 각각 만들도록 했습니다.

PR이 생성되었을 때

라고 지시했지만, 트리거의 특성상 PR 생성 시뿐만 아니라 push를 통해 PR이 업데이트될 때마다 실행되었습니다.

슬래시 커맨드로 호출하면 아래 이미지와 같이 실행됩니다. 워크플로우가 완료되면 GitHub Actions의 코멘트가 업데이트됩니다.

참고로, 이 슬래시 커맨드는 PR 하단의 'Add a comment'를 통해 코멘트를 보내면 되지만, 전혀 자동 완성되지 않습니다. 맞는지 불안할 수 있지만 자신 있게 코멘트를 입력하세요.

실패했을 경우에는 일반적인 GitHub Actions와 마찬가지로 Actions 탭에서 로그를 확인할 수 있습니다. 자주 발생하는 실수로는 인증 정보 관련 오류나 워크플로우 자체의 유효 기간 만료, 토큰(token)의 유효 기간 만료 등이 있었습니다.

그 외에 Dependabot의 PR을 업데이트하는 워크플로우를 만들 때 사용했던 프롬프트입니다.

당시에는 아직 GitHub Copilot의 요금 체계가 Premium Requests였기에 Codex를 사용했지만, 비용과 용도에 따라 변경하시기 바랍니다. 지금 Copilot을 사용한다면 auto 설정으로도 충분할 수 있습니다.

Dependabot으로부터의 PR을 감지하여 최신 코드 스타일로 마이그레이션(migration)을 수행하는 워크플로우를 작성하고 싶다.
context7 MCP와 serena MCP를 이용하여 대상 버전의 문서를 가져와서 최신 문법 및 권장 사항에 맞게 수정하고, 해당 PR 브랜치에 push 해줘.
AI 모델은 gpt-5.3-codex를 사용하도록 해.
...

md 파일이 만들어지면 컴파일합니다.

gh aw compile

를 통해 lock.yml이 생성됩니다.

lock.yml은 직접 편집하지 않고, gh aw compile만으로 생성되도록 합시다.

md와 lock.yml은 모두 갖춰져서 관리되어야 하므로, md를 편집했다면 컴파일하여 함께 커밋하도록 합시다.

MCP

Using MCPs | GitHub Agentic Workflows

MCP를 사용할 수도 있습니다.

하지만 브라우저 기반의 OAuth 2.0 인증은 CI 환경이므로 당연히 불가능합니다.

로컬 커맨드만 가능한 MCP나 API 토큰을 통한 인증만 이용할 수 있다는 점에 주의하십시오.

해보니

코드에 맞춰 문서를 자동으로 업데이트하는 등, 기존의 CI로는 할 수 없었던 일들을 지속적으로 수행할 수 있게 된 점이 도움이 되었습니다.

직접 만드는 것도 작성은 AI에게 맡겨서 간단하게 생성할 수 있습니다. 직접 만들어 본 것들도 지금 다시 보니 유사한 사례가 샘플에 있기도 합니다.

따라서 우선은 샘플로 시도해 보고, 자신의 프로젝트에 맞춰 서비스 연동을 하고 싶을 때 커스텀해 나가는 것이 좋지 않을까 생각합니다.