GitHub Actions에서의 Claude Code: 코드 에이전트를 위한 CI/CD, 권한 및 보안

Claude Code는 GitHub Actions 내에서 실행될 수 있지만, CI(지속적 통합) 환경의 에이전트는 대화형 개발자와 동일한 권한을 가져서는 안 됩니다.

GitHub Actions에서의 Claude Code는 에이전트와의 대화를 재현 가능한 자동화로 변환합니다. 댓글, Pull Request (PR), Issue, 예약된 작업 또는 내부 워크플로우(Workflow)를 통해 호출할 수 있습니다. 그 약속은 명확합니다. 에디터를 열지 않고도 PR을 검토하고, 변경 사항을 준비하며, Issue를 분류하거나 유지보수를 수행하는 것입니다.

왜 중요한가

위험 요소 또한 명확합니다. CI 내의 에이전트는 워크플로우 권한, Secret (비밀값) 접근, 저장소 체크아웃(Checkout) 권한을 가지며, 허용할 경우 댓글 작성, PR 생성 또는 파일 수정 능력까지 갖게 됩니다. 이는 로컬에서 Claude Code에게 도움을 요청하고 터미널에서 각 명령어를 직접 검토하는 것과는 차원이 다른 문제입니다.

실질적인 가이드는 단순히 anthropics/claude-code-action@v1을 활성화하고 마법이 일어나길 기다리는 것이 아닙니다. 에이전트가 좁은 범위의 명령만을 수행하고, 최소한의 권한을 가지며, 감사 가능한(Auditable) 출력과 저장소에 쓰기 작업을 수행하기 전의 비용 제한을 갖도록 워크플로우를 설계하는 것입니다.

v1 액션(Action)에서 변경된 점

Anthropic의 현재 문서는 anthropics/claude-code-action@v1 사용을 권장합니다. v1 버전은 prompt 및 claude_args와 같은 통합된 입력값을 통해 설정을 단순화하고, 기존의 모드(Mode) 관련 설정 일부를 제거하며, 워크플로우에서 Claude Code의 인자(Arguments)를 전달할 수 있도록 합니다.

이는 사용 편의성(Ergonomics)을 향상시키지만, 중요한 결정 사항들을 없애주는 것은 아닙니다. 어떤 이벤트가 에이전트를 트리거할지, 무엇을 읽고 쓸 수 있는지, 어떤 모델을 사용할지, 몇 번의 턴(Turn)을 허용할지, MCP (Model Context Protocol)를 사용할지, Bedrock이나 Vertex와 같은 프로바이더를 사용할 수 있는지, 그리고 결과물이 댓글, PR 또는 직접적인 변경 사항이 될지를 결정해야 합니다.

베타 버전에서의 마이그레이션을 단순한 YAML의 기계적 교체가 아닌 보안 검토로 취급하십시오. 이전 워크플로우에 이미 광범위한 권한이 설정되어 있었다면, 이번 업데이트는 해당 권한을 축소할 좋은 기회입니다.

세 가지 유용한 패턴

첫 번째 패턴은 온디맨드 어시스턴트 (on-demand assistant)입니다. Claude는 이슈(issue)나 풀 리퀘스트(pull request)에 누군가가 @claude라고 작성할 때만 동작합니다. 이는 명시적인 인간의 의도를 유지하기 때문에 도입하기 가장 쉽습니다.

두 번째 패턴은 제한된 리뷰 (scoped review)입니다. PR(pull request)에서 실행되지만, 중요한 경로(critical paths), 대규모 변경 사항 또는 특정 라벨(label)에 대해서만 실행됩니다. 이는 사소한 모든 변경 사항을 검토하는 것을 방지하고, API 비용과 Actions 실행 시간을 줄여줍니다.

세 번째 패턴은 예정된 유지보수 (scheduled maintenance)입니다. 일일 보고서, 문서 업데이트, 이슈 트리아지 (triage) 또는 리팩터링 제안 등이 이에 해당합니다. 여기서의 위험은 댓글 자체가 아니라, 자동화된 권장 사항을 아무도 검토하지 않는 작업으로 변질시키는 데 있습니다.

GitHub Actions에서의 최소 권한 (Least Privilege)

워크플로우(workflow) 또는 작업(job) 내에 명시적인 permissions 설정을 사용하는 것부터 시작하세요. 에이전트가 PR에 댓글만 남긴다면, contents에 대한 광범위한 권한은 필요하지 않습니다. 만약 PR을 직접 생성해야 한다면 contents와 pull requests에 대한 쓰기 권한이 필요하겠지만, 반드시 packages, deployments 또는 id-token에 대한 액세스가 필요한 것은 아닙니다.

GitHub 문서에 따르면, 토큰을 명시적으로 전달하지 않더라도 액션(action)은 github.token 컨텍스트를 통해 GITHUB_TOKEN에 접근할 수 있습니다. 따라서 토큰을 입력값(input)으로 숨기는 것만으로는 충분하지 않으며, 토큰에 부여된 권한 자체를 제한해야 합니다.

클라우드 제공업체의 경우, 긴 수명의 비밀값(secrets) 대신 가능한 경우 OIDC를 선호하세요. Actions에서 Bedrock 또는 Vertex를 사용하는 경우, 몇 달 동안 저장된 정적 키(static key)보다는 저장소(repository) 및 브랜치(branch) 조건을 포함한 임시 역할(temporary role)을 사용하는 것이 보안상 더 타당합니다.

비밀값(Secrets) 및 컨텍스트

ANTHROPIC_API_KEY는 반드시 GitHub 비밀값(secret)으로 저장해야 하며, 절대로 YAML 파일이나 CLAUDE.md에 포함해서는 안 됩니다. 워크플로우가 다른 비밀값을 사용한다면 작업을 분리하세요. 코드를 검토하거나 댓글을 다는 작업은 배포를 수행하지 않는 한 배포용 자격 증명(credentials)을 상속받아서는 안 됩니다.

프롬프트에 민감한 메타데이터를 포함하지 마세요. PR 제목, 이슈(issue) 댓글, 외부 사용자의 본문(body)은 신뢰할 수 없는 입력값입니다. 만약 해당 텍스트를 셸(shell) 명령어 내부나 쓰기 권한이 있는 프롬프트에 보간(interpolation)한다면, 프롬프트 인젝션(prompt injection)과 CI 인젝션(CI injection)을 혼합하는 결과를 초래하게 됩니다.

GitHub는 스크립트 내의 컨텍스트 입력값을 잠재적으로 위험한 것으로 취급할 것을 권장합니다. 에이전트(agent)가 포함된 워크플로우(workflow)에서는 동일한 기준이 두 배로 적용됩니다. 즉, 댓글로부터 전달된 내용이 모델의 결정에 영향을 미칠 수 있을 뿐만 아니라, 작업(job)이 실제로 실행하는 내용에도 영향을 미칠 수 있습니다.

도구 및 MCP 제한 방법

MCP(Model Context Protocol)는 Claude가 내부 문서를 읽거나, 티켓을 조회하거나, 기업 시스템과 통신해야 할 때 유용합니다. 하지만 CI 환경에서는 각 MCP 서버가 권한의 표면(surface)을 넓힙니다. 워크플로우에 필요하지 않은 쓰기 작업(write actions)을 포함하고 있다면, 로컬에서 사용하는 것과 동일한 서버를 연결하지 마세요.

도구 및 서버에 대한 허용 목록(allowlist)을 사용하세요. Claude Code에서는 claude_args를 통해 --allowedTools, --max-turns, --model 또는 MCP 설정 경로와 같은 옵션을 전달할 수 있습니다. 이러한 제어는 프롬프트 내의 비공식적인 지시사항이 아니라, YAML 파일이나 버전 관리되는 설정에 포함되어야 합니다.

훅(hook)이 필요한 경우, 다음과 같은 결정론적 검증(deterministic validations)을 위해 사용하세요: 민감한 경로 차단, 편집 후 테스트 강제, 태그 없는 마이그레이션 변경 방지, 또는 호출된 도구 기록 등입니다. 훅이 인간의 검토를 대체할 수는 없지만, 변경 사항(diff)이 PR에 도달하기 전에 위험한 상태를 줄여줍니다.

측정해야 할 비용

두 가지 비용이 발생합니다. 하나는 GitHub Actions 비용입니다. 에이전트가 종속성(dependencies)을 설치하거나, 테스트를 실행하거나, 여러 번 반복(iteration)할 경우 각 실행마다 러너(runner)의 분(minutes)이 소모됩니다. 다른 하나는 Claude API 비용입니다. 이 비용은 컨텍스트(context), 모델, 저장소(repo)의 길이 및 턴(turn) 수에 따라 달라집니다.

보수적인 --max-turns 설정과 워크플로(workflow) 타임아웃으로 시작하세요. 하나의 PR(Pull Request)에 대해 다섯 개의 댓글이 달렸을 때 다섯 개의 세션이 동시에 실행되는 것을 방지하려면 concurrency를 추가하십시오. 만약 푸시(push)마다 워크플로가 자동으로 실행된다면, 단순히 월간 비용이 아니라 PR당 비용을 측정해야 합니다.

유용한 지표는 Claude가 얼마나 많은 댓글을 생성하느냐가 아닙니다. 얼마나 많은 댓글이 수락된 변경 사항으로 이어지는지, 얼마나 많은 거짓 양성(false positives)을 생성하는지, 그리고 추가적인 검토 비용 대비 인간의 시간을 얼마나 절약해 주는지입니다.

합리적인 초기 워크플로

먼저 중요한 프로덕션(production) 환경이나 무의미한 샌드박스(sandbox)가 아닌, 중간 정도의 위험도를 가진 저장소(repository)에서 활성화하십시오. 멘션(mention)을 통한 수동 트리거, 명시적인 permissions, Secrets에 저장된 ANTHROPIC_API_KEY, 낮은 --max-turns 설정, 그리고 변경 전 분석을 요청하는 프롬프트(prompt)를 사용하세요.

2주 동안은 에이전트가 생성한 자동 머지(merge)를 금지하십시오. Claude는 댓글을 달고, 제안하고, PR을 생성할 수 있지만, 반드시 사람이 승인해야 합니다. 작업(job)의 지속 시간, 대략적인 토큰(token) 수, 수정된 경로, 실행된 테스트, 그리고 무시된 댓글들을 기록하십시오.

그 후에 사용 사례(use case)에 따라 확장 여부를 결정하십시오. 백엔드(backend) PR 검토에서 잘 작동했다고 해서 배포, 마이그레이션(migration) 또는 인프라(infrastructure)까지 건드려야 한다는 의미는 아닙니다. 건강한 확장은 열정이 아니라 권한과 워크플로에 따라 이루어져야 합니다.

보안 체크리스트

작업(job)별로 permissions를 정의하고 광범위한 글로벌 권한은 피하십시오.
GitHub Secrets를 사용하고 어떤 작업이 이에 접근할 수 있는지 검토하십시오.
댓글, PR 제목, 이슈(issue)를 신뢰할 수 없는 입력값(untrusted input)으로 취급하십시오.
claude_args를 통해 --max-turns, 모델, 도구(tool)를 제한하십시오.
검토(review), 편집(edit), 배포(deploy)를 서로 다른 워크플로로 분리하십시오.
사용 사례가 반드시 요구하지 않는 한 쓰기 권한이 있는 MCP를 부여하지 마십시오.
민감한 경로, 필수 테스트 및 로깅(logging)을 위한 훅(hook)을 추가하십시오.
정적 키(static key)를 피할 수 있는 경우 클라우드(cloud)를 위해 OIDC를 사용하십시오.
각 디프(diff)를 인간이 작성한 새로운 코드처럼 검토하십시오: 의도, 테스트, 권한 및 롤백(rollback) 여부를 확인해야 합니다.

결론

Claude Code를 GitHub Actions에서 사용하는 것이 강력한 이유는 에이전트를 팀이 이미 의사결정을 내리는 곳인 이슈(Issues), PR(Pull Requests), CI(지속적 통합) 근처로 가져오기 때문입니다. 이는 에이전트를 고립된 어시스턴트보다 더 유용하게 만들지만, 설계 없이 권한을 상속받을 경우 더 위험하게 만들 수도 있습니다.

책임감 있는 설정은 anthropics/claude-code-action@v1, 제한된 프롬프트(prompts), 최소한의 GITHUB_TOKEN, 잘 분리된 비밀값(secrets), 턴(turn) 제한, 훅(hooks), 최소 권한을 가진 MCP(Model Context Protocol), 그리고 인간의 검토를 결합하는 것입니다. 만약 한 가지 요소라도 빠진다면 워크플로(workflow)는 계속 작동할 수 있겠지만, 무언가 잘못되었을 때 에이전트가 무엇을 했는지 설명하기가 더 어려워질 것입니다.

운영 규칙: 자동화는 단순히 검토 가능한 노이즈를 생성하는 곳이 아니라, 댓글(comment)이 기술적 의사결정을 바꿀 수 있는 곳에서 활성화하십시오.

출처 및 참고 문헌

원문은 devaisemanal.com에 게시되었습니다.

Insights