GitHub 통합

Claude Code와 GitHub 통합하기

Claude Code에는 공식 GitHub 통합 기능이 있어, 손쉽게 Claude Code를 GitHub Actions 안에서 실행할 수 있습니다. Claude Code와 GitHub를 통합하면 크게 두 가지 워크플로우가 가능해집니다.

1. 이슈/PR에서 @claude 멘션 지원
2. 풀 리퀘스트 자동 리뷰

---

1. 통합 설정하기

설정을 시작하려면 Claude에서 다음 명령을 실행합니다. /install-github-app

이 명령어를 치면 다음 단계 따라하라는 안내가 나옵니다.

1. GitHub에 Claude Code 앱 설치
2. API 키 추가
3. 워크플로우 파일이 포함된 PR이 자동으로 생성됨

이 PR을 머지하면 .github/workflows 디렉터리에 워크플로우 파일이 추가됩니다.

---

2. 기본 제공되는 두 가지 GitHub Action

① 멘션 액션 (Mention Action)

이슈나 풀 리퀘스트에서 @claude 로 Claude를 멘션하면 Claude가 다음과 같이 동작합니다.

• 요청을 분석하고 작업 계획을 작성
• 코드베이스에 대한 전체 접근 권한을 가지고 계획한 작업 수행
• 결과를 해당 이슈/PR에 직접 댓글로 응답

② 풀 리퀘스트 리뷰 액션 (Pull Request Action)

PR을 생성할 때마다 Claude가 자동으로 다음을 수행합니다.

• 제안된 변경 사항 리뷰
• 변경의 영향 분석
• PR에 상세한 리포트 작성

두 액션 모두 커스터마이징 가능하며, 다른 이벤트가 트리거 되더라도 추가 액션이 실행되도록 확장할 수 있습니다.

---

3. 워크플로우 커스터마이징

머지된 워크플로우 파일을 프로젝트 상황에 맞게 수정하는 방법을 살펴봅시다. 멘션 워크플로우에서 Claude가 Playwright MCP 서버를 사용하도록 해서 브라우저가 앱에 접근하도록 만들어보겠습니다. 먼저 두 개의 액션 설정 파일이 머지된 변경 사항을 로컬로 pull 받습니다. .github/workflows 디렉터리에 두 개의 파일이 보일 것입니다.

① 프로젝트 셋업 단계 추가

Claude가 실행되기 전에 환경을 준비하는 단계를 추가합니다.

- name: Project Setup
  run: |
    npm run setup
    npm run dev:daemon

② 커스텀 지시 사항 (Custom Instructions) 추가

Claude에게 프로젝트 상태에 대한 컨텍스트를 직접 전달할 수 있습니다.

custom_instructions: |
  The project is already set up with all dependencies installed.
  The server is already running at localhost:3000. Logs from it
  are being written to logs.txt. If needed, you can query the
  db with the 'sqlite3' cli. If needed, use the mcp__playwright
  set of tools to launch a browser and interact with the app.

이렇게 하면 Claude는 "개발 서버가 이미 실행 중이며, 필요 시 Playwright MCP 서버를 사용해 브라우저에서 앱에 접근할 수 있다"는 사실을 알게 됩니다.

③ MCP 서버 설정

추가 능력을 부여하기 위해 MCP 서버를 구성합니다.

mcp_config: |
  {
    "mcpServers": {
      "playwright": {
        "command": "npx",
        "args": [
          "@playwright/mcp@latest",
          "--allowed-origins",
          "localhost:3000;cdn.tailwindcss.com;esm.sh"
        ]
      }
    }
  }

---

4. 도구 권한(Tool Permissions): GitHub Actions의 특이점

⚠️ 로컬 개발과 가장 큰 차이점입니다.

GitHub Actions에서 Claude Code를 실행할 때는 허용할 모든 도구를 명시적으로 나열해야 합니다. 특히 MCP 서버를 사용할 때 중요합니다. allowed_tools: "Bash(npm:*),Bash(sqlite3:*),mcp__playwright__browser_snapshot,mcp__playwright__browser_click,..."

로컬에서처럼 mcp__playwright 한 줄로 모든 도구를 허용하는 단축 표기는 사용할 수 없습니다. 각 MCP 서버의 각 도구를 개별적으로 나열해야 합니다. 안타깝게도 Playwright MCP 서버는 도구가 많아서, 각각을 모두 적어줘야 합니다. 설정 업데이트를 마치면 변경 사항을 커밋하고 푸시합니다.

---

5. 실전 테스트: 이슈에서 @claude 멘션해보기

업데이트된 워크플로우를 테스트해보겠습니다. 앱에는 미리보기/코드 패널을 전환하는 두 개의 버튼이 있다고 가정합시다. (실제로는 잘 동작하지만, 테스트를 위해 마치 문제가 있는 것처럼 가정합니다.)

1. 미리보기/코드 패널을 전환하는 두 개의 버튼을 스크린샷으로 찍음
2. GitHub에서 이슈를 생성하고 스크린샷을 붙여넣음
3. 이슈 내용에 @claude 멘션과 함께 "두 버튼이 정상 동작하는지 확인해줘"라고 요청
4. 이슈를 생성하고 대기

액션이 시작되고 Claude가 응답하기까지는 약 1~2분 정도 걸립니다.

우리가 워크플로우에 추가한 셋업 단계 덕분에 앱 전체가 셋업되고 실행된 뒤에야 Claude Code가 시작된다는 점을 기억하세요. 이윽고 Claude가 응답을 시작합니다. 보통 작업을 완수하기 위한 체크리스트를 작성한 뒤, 앱을 직접 방문해 버튼을 수동으로 테스트하고 발견한 이슈를 수정하려 합니다.

이 경우 Claude는 버튼이 정상적으로 동작한다는 사실을 발견하고, 그 결과를 정리한 메시지를 남기며 작업을 일찍 종료합니다.

---

6. 베스트 프랙티스

Claude와 GitHub을 통합해 워크플로우 자동화를 시도하는 경우, 다음과 같은 접근법이 권장됩니다.

---

핵심 요약

Claude와 GitHub을 통합하면 Claude가 단순한 개발 어시스턴트에서 자동화된 팀 멤버로 변모됩니다. 이슈를 처리하고, 코드를 리뷰하며, GitHub 워크플로우 내부에서 직접 인사이트를 제공해주는 동료가 되는 것이죠.