byteforce

CPN 한국어 자습서 · Claude Code in Action

2 · 직접 해보기

GitHub 통합

Github integration

Claude Code에는 공식 GitHub 통합이 있어, Claude Code를 GitHub Action 안에서 돌릴 수 있습니다. /install-github-app 한 번이면 이슈·PR에서 @claude 로 작업을 시키거나, PR이 올라올 때마다 자동으로 리뷰하게 만들 수 있습니다. 워크플로를 손봐 Playwright MCP까지 붙이는 법도 함께 봅니다.

전체 내레이션영상 나레이션 한국어 번역 (전체)›

Stephen Grider · Anthropic 기술 스태프

Claude Code에는 공식 GitHub 통합이 있어, Claude Code를 GitHub Action 안에서 돌릴 수 있습니다. 이 통합은 /install-github-app 을 실행해 설정합니다. 그러면 몇 가지 단계를 안내해 줍니다. 먼저 GitHub에 Claude Code 앱을 설치하고, 다음으로 API 키를 추가합니다. 그러고 나면 풀 리퀘스트(PR)가 자동으로 생성됩니다.

이 PR은 두 개의 서로 다른 GitHub Action을 추가합니다. 첫 번째 액션은 멘션 지원을 더합니다. 이슈나 PR에서 @claude 로 Claude를 멘션해 어떤 작업이든 시킬 수 있습니다. 두 번째 액션은 PR 리뷰 지원을 더합니다. PR을 만들 때마다 Claude Code가 자동으로 실행되어 제안된 변경을 리뷰합니다. 두 액션 모두 커스터마이즈할 수 있고, 다른 종류의 이벤트에 반응하는 액션을 추가로 더할 수도 있습니다.

멘션 기능을 커스터마이즈하는 법을 보여 드리죠. 먼저 그 두 액션 설정 파일을 GitHub 저장소에 방금 머지했으니, 그 변경을 로컬로 내려받아야(pull) 합니다. 그러면 새로 생긴 .github/workflows 디렉터리에 두 개의 액션 설정 파일이 보입니다. 하나는 PR 리뷰 지원을, 다른 하나는 멘션 처리를 더하는 파일입니다.

제가 멘션 기능을 이렇게 바꾸고 싶습니다 — 이슈나 PR에서 Claude를 멘션하면, GitHub Action 안에서 프로젝트를 실행하고 Playwright MCP 서버로 브라우저에서 앱에 접근할 수 있게요. 이걸 가능하게 하려면, 먼저 Claude Code가 워크플로에서 실행되기 전에 한 단계를 추가합니다 — setup 명령을 돌리고 개발 서버를 띄우는 단계입니다.

그다음 Claude Code 설정을 업데이트합니다. 커스텀 지시(custom instructions)를 추가합니다. 이건 Claude에게 직접 전달되어 추가 지침이나 맥락을 줄 수 있습니다. 여기서는 개발 서버가 이미 돌고 있다는 것, 그리고 필요하면 Playwright MCP 서버로 브라우저에서 앱에 접근해도 된다는 것을 알려 줍니다. 그런 다음 Playwright MCP 서버 자체를 설정하는 구성을 추가합니다.

여기 한 가지 더 알아 둘 점이 있습니다. Claude Code를 액션 안에서 돌릴 때는, Claude Code에 부여할 권한을 모두 명시적으로 나열해야 합니다. 그리고 까다로운 점이 하나 있는데, MCP 서버를 쓰는 경우에는 그 서버의 도구 하나하나를 개별적으로 나열해야 합니다. 앞에서 본 것 같은 권한 단축키가 여기엔 없습니다. 안타깝게도 Playwright MCP 서버는 도구가 아주 많아서, 그것들을 일일이 적어 줘야 합니다. 이 설정 업데이트를 마치면, 변경을 커밋하고 푸시합니다.

이제 이 업데이트된 워크플로를 테스트할 차례입니다. Claude에게 작은 작업을 하나 주겠습니다. 우리 실제 앱에 위쪽 두 개의 버튼이 보이죠. 지금은 잘 동작합니다 — 미리보기와 코드 패널을 문제없이 전환할 수 있습니다. 하지만 마치 그게 의도대로 동작하지 않는 척하겠습니다. 그 버튼을 스크린샷으로 찍고, 이슈를 만들고, 스크린샷을 붙여 넣은 뒤, @claude 로 멘션해 두 버튼이 의도대로 동작하는지 확인해 달라고 요청합니다. 그리고 이슈를 만들고 기다립니다.

액션이 실제로 시작되고 Claude가 응답하기까지 1~2분 정도 걸립니다. 방금 액션에서 봤듯이, 이제 우리는 Claude Code가 실행되기도 전에 앱 전체를 setup 하고 띄워 둡니다. 하지만 결국 Claude가 응답합니다. Claude는 흔히 주어진 작업을 해내기 위한 체크리스트를 만듭니다. 이 경우엔 앱을 방문하고, 버튼을 직접 테스트해 보고, 발견되는 문제를 고치려 합니다. Claude는 버튼이 사실 멀쩡히 동작한다는 걸 확인하고, 그래서 자신의 발견을 기록하는 메시지와 함께 일찍 작업을 마칩니다.

이것은 Claude Code의 GitHub 통합을 활용하는 작은 예시일 뿐입니다. 여러분의 프로젝트에 맞게 이걸 어떻게 맞춤 설정할지 시간을 들여 생각해 보길 권합니다.

이 장에서 배우는 것What you'll learn

약 4분

/install-github-app — GitHub 앱 설치 → API 키 → 자동 PR 생성

그 PR이 액션 2개를 더한다 — @claude 멘션 처리 + PR 자동 리뷰

.github/workflows/ 의 설정 파일을 직접 커스터마이즈

Claude 실행 전에 setup + 개발 서버 띄우는 단계를 추가

커스텀 지시로 맥락 전달 + Playwright MCP 서버 구성 추가

액션에선 권한을 전부 명시 — MCP 도구는 하나하나 나열(단축키 없음)

먼저 짚고 갈 용어

GitHub Action: GitHub 이벤트(이슈·PR 등)에 반응해 자동 실행되는 워크플로. Claude Code를 이 안에서 돌린다.
/install-github-app: GitHub 통합을 설정하는 명령. 앱 설치·API 키·자동 PR 생성을 안내한다.
@claude 멘션: 이슈나 PR 댓글에서 @claude 로 Claude를 불러 작업을 시키는 기능.
.github/workflows/: 액션 설정(.yml) 파일들이 놓이는 폴더. 자동 생성된 두 파일을 여기서 손본다.
커스텀 지시: Claude에게 직접 전달하는 추가 지침·맥락(예: 개발 서버가 떠 있음, MCP 사용 가능).

Claude Code를 GitHub Action으로

/install-github-app

공식 GitHub 통합은 Claude Code를 GitHub Action 안에서 돌리게 해 줍니다. /install-github-app 을 실행하면 앱 설치 → API 키 → 자동 PR 생성까지 안내하고, 그 PR이 액션 두 개(멘션 처리·PR 리뷰)를 더합니다.

설치 흐름 · /install-github-app 이 안내

GitHub 앱 설치

/install-github-app 을 실행하면 GitHub에 Claude Code 앱을 설치하도록 안내합니다.

API 키 추가

저장소 시크릿에 API 키를 등록합니다. 액션 안의 Claude가 이 키로 동작합니다.

자동 PR 생성

설정이 끝나면 PR이 자동으로 생성됩니다. 이 PR이 액션 두 개를 저장소에 더합니다.

자동 생성된 PR은 @claude 멘션 처리와 PR 자동 리뷰 두 가지 액션을 더합니다. 둘 다 입맛대로 고칠 수 있고, 다른 이벤트용 액션을 더 추가할 수도 있습니다.

두 액션 — 멘션과 PR 리뷰

@claude · auto review

자동 생성된 PR을 머지하면 .github/workflows/ 에 설정 파일 두 개가 생깁니다. 하나는 @claude 멘션 처리, 다른 하나는 PR 자동 리뷰입니다.

무엇을 하나

@claude 멘션 — 이슈·PR에서 @claude 로 부르면 그 작업을 액션이 실행한다.
PR 자동 리뷰 — PR이 올라올 때마다 Claude가 자동 실행되어 변경을 리뷰한다.
둘 다 커스터마이즈 가능하고, 다른 이벤트용 액션을 더 추가할 수도 있다.

.github/workflows/ · 자동 생성된 액션 (발췌)

# claude.yml — @claude 멘션을 처리
on:
  issue_comment:
    types: [created]      # 댓글에 @claude 가 있으면 실행

# claude-code-review.yml — PR 을 자동 리뷰
on:
  pull_request:
    types: [opened, synchronize]

워크플로 커스터마이즈

setup · custom instructions · MCP

멘션 워크플로를 손봐, 액션 안에서 앱을 띄우고 Playwright MCP로 브라우저까지 쓰게 만듭니다. 변경을 로컬로 pull 한 뒤 설정 파일을 고칩니다.

.github/workflows/claude.yml · 커스터마이즈

steps:
  # 1) Claude 가 실행되기 전에 앱을 setup 하고 개발 서버를 띄움
  - run: npm install && npm run dev &

  - uses: anthropics/claude-code-action@v1
    with:
      # 2) 커스텀 지시 — Claude 에게 직접 전달되는 맥락
      custom_instructions: "개발 서버가 이미 실행 중입니다. 필요하면 Playwright MCP 로 브라우저에서 앱을 확인하세요."
      # 3) Playwright MCP 서버 구성
      mcp_config: { ... playwright 서버 ... }
      # 4) 권한은 전부 명시 — MCP 도구는 하나하나(단축키 없음)
      allowed_tools: mcp__playwright__browser_navigate, mcp__playwright__browser_click, mcp__playwright__browser_snapshot, ...

까다로운 점 · 권한

액션 안에서는 권한을 모두 명시적으로 나열해야 합니다. 특히 MCP 서버를 쓰면 도구 하나하나를 개별로 적어야 합니다 — 로컬에서 본 mcp__playwright 같은 단축키가 없습니다. Playwright는 도구가 많아 길어집니다. 다 적었으면 커밋·푸시합니다.

돌려 보기 & 점검

Try it & check

버튼을 스크린샷으로 찍어 이슈를 만들고 @claude 로 "두 버튼이 의도대로 동작하는지 확인해 줘"라고 멘션합니다. 1~2분 뒤 액션이 앱을 띄우고 Claude가 응답합니다.

멘션 워크플로 시연 · 단계를 눌러 보세요

버튼은 멀쩡히 동작했기에 Claude는 발견을 문서화하고 일찍 끝냅니다. 핵심은 — @claude 멘션 → 액션이 앱을 setup·실행 → Claude가 브라우저로 직접 확인, 이 흐름이 GitHub 안에서 자동으로 돈다는 점입니다.

핵심 정리

/install-github-app → 앱 설치·API 키·자동 PR → 액션 2개(멘션·PR 리뷰).
설정 파일은 .github/workflows/ 에서 커스터마이즈한다.
Claude 실행 전 setup 단계, 커스텀 지시, Playwright MCP 구성을 더할 수 있다.
액션에선 권한을 전부 명시 — MCP 도구는 하나하나 나열(단축키 없음).

Q1GitHub 통합을 설정하는 명령은?

Q2자동 생성된 PR이 더하는 두 액션은?

Q3액션 안에서 MCP 서버 권한을 줄 때의 주의점은?

다음 장

직접 해보기 섹션을 마쳤습니다. 이제 작업 자동화를 한 단계 끌어올리는 훅(hooks)으로 넘어갑니다. → 훅 소개