클로드 코드 GitHub Actions 사용법: /install-github-app 설치부터 @claude 로 이슈·PR 맡기기

이 글 순서

1. 깃허브 Actions 가 뭔가요
2. 한국에서, 무슨 요금제
3. 처음이라면: 준비물
4. 처음이라면: 빠른 설정
5. 처음이라면: 호출해 보기
6. 손으로 설정하기
7. 워크플로 파일 읽기
8. 익숙해졌다면: 이슈를 PR 로
9. 리뷰 워크플로
10. 더 깊이: 정해 둔 때 돌리기
11. claude_args 로 고르기
12. 비용과 아끼는 법
13. 보안: 누가 호출하나
14. 막힐 때
15. 지우는 법
16. 비슷한 것과 차이
17. 코덱스·제미나이 CLI 는
18. 누구에게 맞을까
19. 다시 확인할 날짜
20. 참고한 자료

깃허브에 올려 둔 프로젝트가 있으면 “이 오류 좀 고쳐 줘”, “이 이슈대로 만들어 줘” 같은 요청을 이슈에 적어 두게 돼요. 클로드 코드 GitHub Actions 는 그 자리에서 댓글로 @claude 를 호출하면, 깃허브 서버가 클로드 코드를 대신 돌려 코드를 읽고 고치고 답을 다는 기능이에요. 내 PC 를 켜 두지 않아도 되고, 휴대폰으로 댓글 한 줄만 달아도 일이 시작돼요.

이 글은 Anthropic 클로드 코드 공식 문서 “Claude Code GitHub Actions”(한국어 버전·영어 버전), “Authentication”, “Commands”와 액션 저장소의 보안 문서를 2026년 10월 10일에 읽고 옮긴 거예요. 깃허브 Actions 기초 설명은 깃허브 공식 문서에서, 비교하려고 코덱스 “Codex GitHub Action”과 구글 run-gemini-cli 안내도 같은 날 읽었어요. 메뉴·명령 이름은 화면에 나오는 영어 그대로 두었어요.

깃허브 Actions 가 뭔가요

단어부터 풀게요. 깃허브는 코드 폴더를 인터넷에 올려 두고 수정 기록까지 남기는 곳이고, 거기 올린 폴더 하나가 저장소예요. 이슈는 저장소에 남기는 할 일·오류 메모, PR(풀 리퀘스트)은 따로 고친 브랜치를 원본에 병합해 달라는 요청이에요. 커밋·브랜치·PR 이 낯설면 클로드 코드 깃 커밋·PR 맡기는 법의 단어 풀이를 먼저 보세요.

깃허브 Actions 는 깃허브가 주는 자동 실행 장치예요. 깃허브 문서는 이것을 “빌드·테스트·배포를 자동으로 돌리는 CI/CD 플랫폼”이라고 소개해요. CI/CD 는 코드를 올릴 때마다 시험하고 내보내는 일을 사람 손 없이 하게 하는 방식이에요. 비유하면 “이 일이 생기면 이걸 해 둬” 하고 적어 둔 업무 지시서를 깃허브가 대신 집행해 주는 거예요.

• 워크플로: 그 업무 지시서 파일이에요. 저장소의 .github/workflows 폴더에 YAML(들여쓰기로 항목을 적는 설정 파일 형식) 파일로 둬요.
• 이벤트: 워크플로를 깨우는 일이에요. 문서 예로 누가 PR 을 만들거나, 이슈를 열거나, 커밋을 올릴 때예요. 정해 둔 시각(schedule)에 돌게 할 수도 있어요.
• 러너: 워크플로를 실제로 돌리는 서버예요. 깃허브가 빌려주는 빈 컴퓨터라고 보면 돼요.
• 액션: 워크플로 안에서 가져다 쓰는 미리 만든 부품이에요. 클로드 코드 쪽 부품 이름이 anthropics/claude-code-action 이에요.
• 시크릿: 저장소 설정에 숨겨 두는 비밀 값이에요. API 키(프로그램이 내 계정을 대신 쓰게 하는 키 문자열) 같은 걸 파일에 적지 않고 여기에 넣어요.

그러니까 클로드 코드 GitHub Actions 는 “댓글에 @claude 가 보이면(이벤트) 러너를 하나 빌려 저장소를 받고, 시크릿의 키로 클로드 코드를 돌려라”라고 적은 워크플로 파일이에요. 문서는 이것으로 이슈를 PR 로 바꾸고, 댓글로 버그를 고치고, 반복 작업을 자동으로 돌릴 수 있다고 적었어요.

한국에서, 무슨 요금제

질문	답
한국에서 되나	됨(Anthropic 지원 국가에 South Korea)
API 키로	됨(Claude Console 키, 토큰만큼 요금)
구독으로	Pro·Max·Team·Enterprise(구독 토큰)
깃허브 쪽 값	Actions 시간(공개 저장소 무료)
저장소 권한	관리자(admin) 권한 필요

출처: 클로드 코드 문서 “Claude Code GitHub Actions”·”Authentication”, Anthropic 지원 국가 목록, 깃허브 문서 Actions 요금. 10월 10일 확인.

구독으로 쓰려면 CLAUDE_CODE_OAUTH_TOKEN 이라는 구독 토큰을 써요. 문서는 이 토큰이 Pro·Max·Team·Enterprise 요금제에서 된다고 적었어요. 토큰으로 로그인하면 “API 요금 대신 Claude 구독을 쓴다”고 했으니, 돌린 만큼 구독 사용량이 줄어들어요. 사용량 보는 법은 클로드 코드 사용량 확인하는 법에 있어요.

처음이라면: 준비물

1. github.com 에 올린 저장소: 문서는 /install-github-app 이 github.com 저장소에서만 된다고 적었어요. 깃랩(gitlab.com)·비트버킷 저장소면 알림만 내고 끝나요. 처음이면 연습용 저장소를 하나 만드세요.
2. 그 저장소의 관리자 권한: 빠른 설정·손 설정 모두 필요해요. 내가 만든 저장소면 이미 있어요.
3. 클로드 코드: 내 PC 에 깔려 있어야 빠른 설정을 할 수 있어요. 처음이면 클로드 코드 설치 윈도우 초보용부터 보세요.
4. 깃허브 CLI(gh): 터미널에서 깃허브를 다루는 공식 프로그램이에요. 문서는 시작 전에 깔고 gh auth login 으로 로그인해 두라고 적었어요. 없으면 클로드 코드가 경고해요.
5. Claude 구독이나 API 키: 둘 중 하나예요. 구독이면 설정 중에 토큰을 만들 수 있어요.

gh auth login

깃허브 CLI 에 내 깃허브 계정으로 로그인하는 줄이에요. 묻는 대로 고르면 브라우저가 열리고, 거기서 승인하면 끝나요.

처음이라면: 빠른 설정

가장 쉬운 길이에요. 연결할 저장소 폴더에서 클로드 코드를 열고 명령 하나를 쳐요.

/install-github-app

클로드 코드 안에서 치는 명령이에요. 문서는 “저장소를 고르고 연결을 설정하는 과정을 차례로 안내한다”고 적었어요.

문서가 적은 흐름을 순서대로 옮기면 이래요.

1. 깃허브 앱 설치: Claude GitHub App(깃허브에 붙이는 Anthropic 프로그램)을 저장소에 깔아요. 이 앱이 저장소 파일·이슈·PR 을 읽고 쓰게 돼요.
2. 계속할지 묻기: 앱을 깐 뒤 GitHub Actions 설정을 이어 갈지 물어요. Skip for now 를 고르면 앱만 깔린 채 멈추고, 나중에 /install-github-app 을 다시 치면 이어서 할 수 있어요.
3. 키 정하기: 클로드 코드에 이미 API 키가 있으면 그 키를 다시 써요. 저장소에 ANTHROPIC_API_KEY 시크릿이 이미 있으면 그대로 둘지도 물어요. 없으면 “구독으로 오래 쓰는 토큰 만들기”와 “API 키 붙여넣기” 가운데 골라요.
4. 시크릿 저장: 고른 키를 저장소 시크릿으로 넣어요. 이름은 API 키면 ANTHROPIC_API_KEY, 구독 토큰이면 CLAUDE_CODE_OAUTH_TOKEN 이에요.
5. 워크플로 파일 PR: 고른 워크플로 파일을 새 브랜치로 올리고, PR 을 만들 준비가 된 깃허브 화면을 브라우저로 열어요.
6. PR 만들고 병합하기: 그 PR 을 만들고 병합하면(merge) 그 저장소에서 @claude 가 돌아요.

중간에 멈추고 싶으면 Esc 를 눌러요. 문서는 “하던 단계는 끝내고 다음 단계는 시작하지 않는다”고 했고, 마지막 안내에 이미 일어난 일(올라간 브랜치, 저장된 시크릿 등)을 적어 준다고 했어요. 반쯤 하다 멈췄으면 그 안내를 보고 지울 것을 지우면 돼요.

워크플로를 고를 때 리뷰 워크플로도 함께 고를 수 있어요. 이건 아래 “리뷰 워크플로”에서 짧게 다뤄요.

처음이라면: 호출해 보기

병합까지 끝났으면 저장소에서 이슈를 하나 열거나, 아무 PR 에 댓글을 달아 봐요. 문서 예시는 이래요.

@claude implement this feature based on the issue description
@claude how should I implement user authentication for this endpoint?
@claude fix the TypeError in the user dashboard component

첫째는 “이슈 설명대로 이 기능을 만들어 줘”, 둘째는 “이 주소에 사용자 로그인을 어떻게 넣으면 좋을까?”, 셋째는 “사용자 화면 부품의 TypeError(값의 종류가 맞지 않아 나는 오류)를 고쳐 줘”예요. 문서 예시는 영어예요. 클로드는 같은 이슈나 PR 에 댓글로 답하고, 일하는 동안 그 댓글을 고쳐 가며 진행 상황을 보여 줘요.

처음엔 작은 요청이 좋아요. 비개발자라면 “README 의 설치 순서를 번호 목록으로 정리해 줘”, 초급 개발자라면 “이 함수에서 빈 값이 들어오면 멈추는 곳을 찾아 고쳐 줘” 정도로 시작해 보세요. 문서도 요청을 구체적으로 적을수록 클로드가 더 적은 턴으로 끝내 비용이 준다고 적었어요.

호출 문구는 정확히 @claude 여야 해요. 문서는 “/claude 나 @claude-bot 이 아니라 @claude 가 하나의 단어로 들어 있는지 보라”고 적었어요.

손으로 설정하기

/install-github-app 이 실패하거나, 내 PC 에서 클로드 코드를 쓰지 않거나, 워크플로 파일을 직접 다루고 싶을 때 쓰는 길이에요. 할 일은 세 가지예요.

1. Claude GitHub App 설치: github.com/apps/claude 에서 저장소에 깔아요. 액션이 쓰는 권한은 Contents(파일), Issues(이슈), Pull requests(PR) 세 가지의 읽기·쓰기예요.
2. 시크릿 넣기: 저장소의 Settings → Secrets and variables → Actions 에서 새 시크릿을 만들어요. API 키면 이름을 ANTHROPIC_API_KEY(값은 Claude Console 에서 받은 키), 구독이면 CLAUDE_CODE_OAUTH_TOKEN 으로 해요.
3. 워크플로 파일 복사: 액션 저장소의 examples/claude.yml 을 내 저장소 .github/workflows/ 폴더에 넣어요. 문서는 이 파일이 “그냥 예시가 아니라 바로 도는 워크플로”라고 적었어요.

구독 토큰은 내 PC 에서 이 명령으로 만들어요.

claude setup-token

구독으로 1년 쓰는 토큰을 만드는 줄이에요. 문서는 /login 과 같은 브라우저 승인 창이 열리고, 승인하면 토큰이 터미널에 찍힌다고 적었어요. 토큰을 어디에도 저장하지 않으니 바로 복사해 시크릿에 넣어요.

그림은 이 PC 의 테스트 폴더에서 로그인 없이 도움말만 돌려 옮긴 거예요. 도움말 첫 줄도 “구독이 필요한, 오래 쓰는 인증 토큰을 설정한다”예요. 실제 토큰 만들기는 계정 승인이 필요해 돌리지 않았어요.

구독 토큰을 넣었다면 워크플로 파일의 anthropic_api_key 줄을 이렇게 바꿔야 해요.

claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

“구독 토큰 시크릿을 꺼내 액션에 넘겨라”는 뜻이에요. 문서는 이 토큰이 모델에 묻는 일만 할 수 있다고 적었어요. 그래서 Remote Control 이나 claude.ai 커넥터는 이 토큰으로 안 돼요.

워크플로 파일 읽기

문서에 실린 가장 짧은 형식이에요. 처음엔 다 외울 필요 없고, 줄마다 무슨 뜻인지만 보면 돼요.

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

• on: 아래 두 줄: 이슈·PR 에 댓글이 새로 달리거나, PR 의 줄 사이에 리뷰 댓글이 달릴 때 깨어나요.
• if:: 댓글에 @claude 가 없으면 러너를 아예 빌리지 않아요. 문서는 이 줄이 “@claude 가 없는 댓글에 러너가 뜨지 않게 한다”고 적었어요. 액션도 답하기 전에 호출 문구를 한 번 더 봐요.
• runs-on: ubuntu-latest: 리눅스 러너에서 돌아요.
• permissions:: 이 일에 주는 권한이에요. 파일·PR·이슈는 쓰기, actions: read 는 PR 의 CI 결과를 읽게 하고, id-token: write 는 깃허브 앱 인증에 필요하다고 문서에 적혀 있어요.
• actions/checkout: 러너에 저장소를 받아 오는 단계예요. 클로드가 일할 복사본이 생겨요.
• anthropics/claude-code-action@v1: 클로드 코드를 돌리는 단계예요. ${{ secrets.… }} 는 시크릿 값을 꺼내 넣는 자리예요.

하나 알아 둘 게 있어요. 문서 본문의 이 예시는 댓글 두 가지에만 반응해요. 그런데 손 설정에서 복사하는 실제 examples/claude.yml 은 10월 10일 기준 issues(이슈를 열거나 담당자를 정할 때)와 pull_request_review(PR 리뷰를 낼 때)도 받아요. 그래서 그 파일을 쓰면 새 이슈의 제목이나 본문에 @claude 를 적어도 불려요. 문서도 대화 모드가 “새로 연 이슈의 본문이나 제목”에도 반응한다고 적었어요.

익숙해졌다면: 이슈를 PR 로

문서 첫 줄이 “이슈를 PR 로 바꾼다”예요. 쓰는 법은 이슈에 할 일을 적고 @claude 를 호출하는 거예요.

@claude 이 이슈대로 고쳐 줘. 바꾼 파일과 이유를 답에 적어 줘.

여기서 처음 쓰는 분이 헷갈리는 곳이 있어요. 액션 저장소의 보안 문서는 “기본 설정에서 클로드는 @claude 에 답할 때 PR 을 스스로 만들지 않는다”고 적었어요. 실제로는 이렇게 가요.

1. 클로드가 바꾼 것을 새 브랜치에 커밋해요.
2. 답 댓글에 깃허브의 PR 만들기 화면으로 가는 링크를 달아요.
3. 사람이 그 링크를 눌러 PR 을 만들어요.

문서는 이렇게 둔 이유를 “병합하자고 내놓는 코드를 사람이 먼저 보게 하려고”라고 적었어요. 이미 있는 PR 에 댓글로 호출하면 문서 앞부분 말대로 클로드가 코드를 살피고, 고치고, 커밋을 올려요.

클로드가 올린 커밋에 CI(올릴 때마다 시험을 돌리는 다른 워크플로)가 안 돌면 “막힐 때”를 보세요. 문서는 깃허브가 기본 GITHUB_TOKEN 으로 만든 커밋에는 워크플로를 돌리지 않는다고 적었어요.

클로드가 어떻게 일할지는 저장소 맨 위의 CLAUDE.md 에 적어 두면 돼요. 문서는 여기에 코드 스타일·리뷰 기준·프로젝트 규칙을 적으면 클로드가 PR 을 만들고 답할 때 따른다고 했어요. 다만 매번 읽으니 짧게 두라고 했어요(CLAUDE.md 쓰는 법).

리뷰 워크플로

/install-github-app 에서 리뷰 워크플로까지 고르면 PR 마다 클로드가 리뷰를 달아요. 문서는 문제를 찾으면 그 줄에 댓글로, 못 찾으면 요약 댓글 하나로 PR 에 올린다고 적었어요. 초안(draft) PR, 닫힌 PR, 자동으로 만든 PR 처럼 리뷰가 필요 없다고 본 PR, 이미 클로드 댓글이 있는 PR 은 건너뛰어요. 공개 저장소라면 깃허브가 포크(남이 복사해 간 저장소)에서 온 PR 의 실행에 시크릿을 주지 않아, 같은 저장소 브랜치에서 연 PR 에서만 리뷰가 돈다고 문서에 적혀 있어요.

2.1.229 버전보다 앞서 만든 리뷰 워크플로는 리뷰를 실행 기록에만 남겼어요. 그때 만든 파일을 고치려면 /install-github-app 을 다시 치고 Update workflow file with latest version 을 고르면 새 파일이 PR 로 올라와요. 직접 고쳐 둔 데가 있으면 문서 예시의 --comment 인수와 claude_args 줄만 손으로 더해도 돼요.

워크플로 없이 관리형으로 도는 Code Review(Team·Enterprise), 코덱스·제미나이 리뷰와 비교한 이야기는 코덱스 깃허브 코드 리뷰 받는 법의 “클로드 코드는” 절에 적어 두었어요.

더 깊이: 정해 둔 때 돌리기

워크플로에 prompt(시킬 말)를 적으면 @claude 를 기다리지 않고 바로 돌아요. 문서는 이걸 자동화 모드라고 불러요. 시킬 말이 없으면 대화 모드로, 호출 문구를 기다려요.

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Generate a summary of yesterday's commits and open issues"
          claude_args: |
            --model claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

문서 예시예요. 매일 협정 세계시 9시(한국 시각 18시)에 “어제 커밋과 열린 이슈를 요약하라”를 돌려요. cron 은 “분 시 날 달 요일” 순으로 때를 적는 형식이에요.

• 결과는 실행 기록에: 자동화 모드는 기본으로 댓글이 아니라 워크플로 실행 기록(log)에 결과를 남겨요. 저장소의 Actions 탭에서 봐요.
• 도구는 허락한 것만: 그냥 문장으로 시키면 셸(명령을 치는 창)이나 깃허브 API 를 쓸 수 없어요. --allowedTools 로 필요한 도구를 열어 줘야 해요. 위 예시는 커밋·이슈 목록을 읽는 도구 둘만 열었어요. 허락 규칙 형식은 권한 설정 allow·ask·deny와 같아요.
• 깃허브의 제약: 깃허브는 정해 둔 때 도는 워크플로를 기본 브랜치에서만 돌리고, 공개 저장소에서 60일 동안 저장소 활동이 없으면 그 일정을 꺼요.
• 스킬도 됨: prompt 에 /스킬이름 을 적으면 저장소의 .claude/skills/ 스킬을 돌려요. 이때는 액션 단계 앞에 checkout 이 있어야 해요.

내 PC 에서 클로드 코드를 화면 없이 돌리는 claude -p 와 비슷하다고 보면 돼요. 그쪽 이야기는 claude -p 사용법에 있어요.

claude_args 로 고르기

claude_args 에는 내 터미널에서 클로드 코드에 붙이던 인수를 그대로 적어요. 문서가 자주 쓴다고 꼽은 것은 다섯이에요.

인수	하는 일
--max-turns	주고받는 턴 수 제한
--model	쓸 모델(없으면 기본 모델)
--allowedTools	허락할 도구 목록
--mcp-config	MCP 설정 파일 위치
--debug	자세한 기록 남기기

출처: 클로드 코드 문서 “Claude Code GitHub Actions”의 Pass CLI arguments, 10월 10일 확인.

claude_args: "--max-turns 5 --model claude-sonnet-5"

“다섯 턴 안에 끝내고, Sonnet 5 모델로 하라”는 뜻이에요. MCP(클로드에 바깥 도구를 붙이는 규격)는 MCP 서버 연결하는 법에, 모델 고르기는 모델 바꾸는 법에 있어요.

예전 @beta 버전을 쓰던 워크플로라면 @v1 로 바꾸고, mode 줄을 지우고, direct_prompt 는 prompt 로, max_turns·model 같은 옵션은 claude_args 로 옮기라고 문서에 적혀 있어요.

비용과 아끼는 법

문서는 한 번 돌 때마다 두 가지가 든다고 적었어요.

• 깃허브 Actions 시간: 깃허브가 빌려주는 러너에서 도니 Actions 시간을 써요. 깃허브 문서는 공개 저장소가 표준 러너를 쓰면 무료라고 적었어요. 비공개 저장소는 요금제마다 한 달 기본 시간이 있어요(GitHub Free 2,000분, Pro·Team 3,000분). 넘으면 리눅스 2코어 러너가 1분에 0.006달러예요.
• 토큰: 시킨 말과 답의 길이, 일의 크기, 코드 양만큼 토큰(AI 가 글을 읽고 쓰는 단위)을 써요. API 키면 API 요금으로 나가고, 구독 토큰이면 구독 사용량에서 빠져요.

문서가 꼽은 아끼는 법은 여섯이에요.

1. @claude 요청을 구체적으로 적어 턴을 줄여요.
2. 이슈 템플릿(issue template)로 필요한 설명을 미리 받아요.
3. CLAUDE.md 는 짧게 둬요. 매번 읽어요.
4. claude_args 의 --max-turns 로 턴 수를 제한해요.
5. 워크플로에 시간 제한을 둬서 멈추지 않는 일을 막아요.
6. 깃허브의 동시 실행 제어(concurrency)로 여러 개가 한꺼번에 도는 걸 막아요.

시간 제한은 깃허브 기능이라 워크플로의 job 아래에 이렇게 적어요.

    timeout-minutes: 15

“이 일은 15분이 넘으면 끊어라”는 뜻이에요. 15 는 예로 든 숫자예요. 사용량 전반을 아끼는 법은 클로드 코드 사용량 아끼는 법 모음에 있어요.

보안: 누가 호출하나

남의 저장소가 아니어도 이 부분은 꼭 읽어 두세요. 댓글 한 줄로 코드를 고치는 기능이니, 누가 호출할 수 있는지가 가장 중요해요.

• 쓰기 권한이 있는 사람만: 이슈·PR 에서 호출한 사람이 저장소 쓰기 권한이 없으면 실행이 실패해요. 그래서 공개 저장소에 아무나 @claude 를 달아도 돌지 않아요.
• 봇은 기본으로 막힘: 봇이 호출하면 거부해요. 봇끼리 서로 호출하며 끝없이 도는 걸 막으려는 거예요. 꼭 필요한 봇만 allowed_bots 에 이름으로 적어요. 보안 문서는 공개 저장소에서 '*'(모든 봇)를 쓰면 누가 만든 깃허브 앱이든 호출할 수 있다고 경고해요.
• allowed_non_write_users 는 위험: 쓰기 권한 없는 사람도 호출하게 하는 설정이에요. 보안 문서는 “큰 보안 위험”이라며 이슈 라벨 달기처럼 권한이 아주 좁은 워크플로에만 쓰라고 적었어요.
• 키는 시크릿에만: 문서 경고 그대로 옮기면 “API 키나 OAuth 토큰을 저장소에 직접 커밋하지 말고, 늘 GitHub Secrets 에 넣고 워크플로에서 불러 쓰라”예요.
• 권한은 필요한 만큼: “워크플로에는 필요한 권한만 주고, 병합하기 전에 클로드가 바꾼 것을 검토하라”고 적었어요.

바깥 사람의 글을 읽힐 때도 조심해야 해요. 보안 문서는 바깥 기여자가 HTML 주석, 보이지 않는 글자, 숨긴 속성 같은 걸로 몰래 지시를 넣을 수 있다고 경고해요. 이런 걸 프롬프트 주입이라고 해요. 액션이 주석·안 보이는 글자 등을 필터링하지만 “새 우회 방법이 나올 수 있다”며, 바깥에서 온 글은 클로드에게 넘기기 전에 원문을 먼저 보라고 권해요.

실행 기록도 조심할 데예요. show_full_output 은 기본으로 꺼져 있는데, 켜면 도구 출력·파일 내용까지 기록에 남고 “공개 저장소에서는 이 기록을 누구나 본다”고 적었어요. 깃허브 Actions 디버그 모드를 켜도 자동으로 켜진다고 하니, 공개 저장소에서는 켜지 않는 게 맞아요.

깔 때 주는 앱 권한도 알아 두세요. Claude GitHub App 은 이 액션뿐 아니라 Code Review·클라우드 세션의 PR 자동 수정 등이 같이 쓰는 앱이라, 액션이 안 쓰는 권한까지 한꺼번에 받아요(Actions·Workflows 쓰기 등 열세 가지). 깃허브는 일부만 고르게 해 주지 않아요. 회사에서 파일·이슈·PR 세 가지만 허락해야 하면 문서대로 내 깃허브 앱을 따로 만들어 쓰면 돼요. 그 앱은 이 액션에만 쓸 수 있어요.

막힐 때

@claude 를 달았는데 답이 없을 때 문서가 적은 순서로 봐요.

• 그 저장소에 Claude GitHub App 이 깔렸는지.
• 저장소에서 워크플로가 켜져 있는지(Actions 탭).
• API 키나 구독 토큰이 저장소 시크릿에 들어 있는지.
• 댓글에 @claude 가 하나의 단어로 있는지(/claude, @claude-bot 은 안 됨).
• 댓글 단 사람이 저장소 쓰기 권한이 있는지.

클로드 커밋에 CI 가 안 돌 때: 액션에 github_token: ${{ secrets.GITHUB_TOKEN }} 을 넘기고 있다면 그 줄을 지워 Claude GitHub App 으로 인증하게 하거나, 따로 만든 앱 토큰을 넘겨요. 그리고 CI 워크플로가 push·pull_request 같은 이벤트를 받는지 봐요.

인증 오류: 워크플로를 고치기 전에 그 API 키나 토큰을 내 PC 의 클로드 코드로 먼저 시험해 보라고 문서에 적혀 있어요. 클로드 코드 쪽 오류 메시지는 클로드 코드 오류 해결에 모아 두었어요.

/install-github-app 이 안 될 때: 저장소가 github.com 인지, gh 가 깔리고 로그인됐는지, 저장소 관리자 권한이 있는지 봐요. 그래도 안 되면 위 “손으로 설정하기”로 가요. 문서도 명령이 실패할 때 손 설정을 쓰라고 적었어요.

지우는 법

그만 쓰려면 깐 것을 하나씩 걷어요.

1. 워크플로 파일: .github/workflows/ 에서 anthropics/claude-code-action 을 쓰는 파일을 지워요. 빠른 설정이면 claude.yml, 리뷰를 골랐으면 claude-code-review.yml 도요. 이것만 지워도 액션은 더 돌지 않아요.
2. 시크릿: ANTHROPIC_API_KEY 나 CLAUDE_CODE_OAUTH_TOKEN 을 지워요. 문서는 시크릿을 지워도 키 자체는 살아 있다고 했어요. API 키를 아예 없애려면 Claude Console 에서도 지워요.
3. 깃허브 앱: 저장소나 조직 설정의 GitHub Apps 에서 지워요. 단 Code Review·PR 자동 수정 같은 다른 클로드 기능에 쓰고 있지 않을 때만요.

비슷한 것과 차이

클로드가 깃허브에 붙는 길은 이것 말고도 있어요. 이름이 비슷해 헷갈리기 쉬워 한 줄씩 갈라 둘게요.

이름	어디서 도나·무엇
GitHub Actions(이 글)	내 깃허브 러너, 워크플로 파일로
Code Review	워크플로 없이 PR 리뷰, Team·Enterprise
클라우드 세션	Anthropic 클라우드, PR 자동 수정 등
루틴	Anthropic 클라우드, 깃허브 이벤트로 시작

출처: 클로드 코드 문서 “Claude Code GitHub Actions”·”Code Review”·”Automate work with routines”, 10월 10일 확인.

클라우드 세션은 클라우드 세션 사용법, 루틴은 예약 작업 하는 법에 있어요. 제 생각에는 저장소마다 파일로 남겨 두고 팀이 같이 고치고 싶으면 GitHub Actions, 파일 관리 없이 내 계정에서 돌리고 싶으면 루틴·클라우드 세션 쪽이 편해요.

코덱스·제미나이 CLI 는

코덱스와 제미나이 CLI 도 깃허브 Actions 에서 도는 공식 액션이 있어요. 다만 생김새가 꽤 달라요.

코덱스의 openai/codex-action@v1 은 OpenAI API 키로 돌고, 코덱스 CLI 를 깔아 codex exec 를 돌려요. 문서 예시는 PR 을 열 때 리뷰를 돌리고, 결과를 다음 단계에서 PR 댓글로 올리는 방식이에요. 댓글에 이름을 호출해 시키는 기능은 액션 문서에 없어요. PR 댓글의 @codex 는 액션이 아니라 코덱스 클라우드의 깃허브 연결이고, 챗GPT Plus 이상에서 돼요(코덱스 깃허브 코드 리뷰 글). 문서는 리눅스·맥 러너를 쓰라고 했고 윈도우면 safety-strategy: unsafe 를 둬야 한다고 적었어요.

제미나이 CLI 쪽은 구글의 google-github-actions/run-gemini-cli 예요. 제미나이 CLI 안에서 /setup-github 를 치면 워크플로를 깔아 주고(제미나이 CLI 명령 문서에도 “이슈 분류와 PR 리뷰용 GitHub Actions 설정”으로 실려 있어요), 댓글에 @gemini-cli 를 달아 시켜요. 키는 구글 AI Studio 에서 받은 제미나이 API 키를 GEMINI_API_KEY 시크릿으로 넣거나 구글 클라우드 인증을 써요. 규칙은 저장소의 GEMINI.md 에 적어요. 코덱스 리뷰 글에서 끝났다고 적은 Gemini Code Assist 개인용 깃허브 앱과는 다른 것이에요.

항목	클로드 코드	코덱스	제미나이 CLI
깔기 명령	/install-github-app	공식 안내 없음	/setup-github
댓글로 호출	@claude	액션엔 없음	@gemini-cli
키	API 키·구독 토큰	OpenAI API 키	제미나이 API 키·구글 클라우드
호출할 수 있는 사람	쓰기 권한	쓰기 권한(allow-users)	예시 파일: 소유자·멤버·협업자
규칙 파일	CLAUDE.md	공식 안내 없음	GEMINI.md
윈도우 러너	공식 안내 없음	unsafe 로 둬야 함	공식 안내 없음
한국(API)	됨	됨	됨

출처: 클로드 코드 문서 “Claude Code GitHub Actions”, OpenAI 코덱스 문서 “Codex GitHub Action”, 구글 run-gemini-cli 저장소 안내와 예시 파일 gemini-dispatch.yml, 제미나이 CLI 명령 문서, Anthropic·OpenAI API·제미나이 API 지원 국가 목록. 모두 10월 10일 확인.

표의 제미나이 “호출할 수 있는 사람”은 문서 규칙이 아니라 구글이 내놓은 예시 워크플로 파일(gemini-dispatch.yml)의 조건이에요. 그 파일은 댓글 쓴 사람이 저장소 소유자(OWNER)·조직 멤버(MEMBER)·협업자(COLLABORATOR)일 때만 받고, 포크(남이 복사해 간 저장소)에서 온 PR 은 건너뛰어요. 코덱스 액션 문서에는 저장소 규칙 파일 이야기가 없어요. 대신 시킬 말을 담은 파일(prompt-file)을 .github/codex/prompts/ 에 두라고 권해요. 세 CLI 를 다른 기능까지 비교한 표는 클로드 코드·코덱스·제미나이 CLI 비교에 있어요.

누구에게 맞을까

여기서부터는 제 생각이에요. 클로드 Pro·Max 를 이미 쓰고 깃허브에 저장소가 있다면, 구독 토큰으로 바로 시작할 수 있는 클로드 코드 쪽이 가장 손이 덜 가요. /install-github-app 하나로 앱·시크릿·파일까지 이어 주고, 댓글 한 줄로 호출하는 방식이 처음 쓰는 분께도 익숙해요. 혼자 하는 프로젝트라면 이슈에 할 일을 쌓아 두고 휴대폰으로 @claude 를 호출해 두는 식으로 쓰기 좋아요.

팀·회사 저장소라면 키부터 정하세요. 문서는 여러 저장소가 같이 쓰는 시크릿이면 구독 토큰 대신 Claude Console 의 API 키를 쓰라고 했어요. 구독 토큰은 그 토큰을 만든 사람의 구독에 묶이기 때문이에요. 코덱스는 API 키로 도는 리뷰·자동 작업 쪽, 제미나이 CLI 는 이슈 분류·PR 리뷰 예시가 잘 갖춰진 쪽이에요. 셋 다 “병합 전에 사람이 본다”는 점은 같아요. 세 회사 요금제와 한도는 AI 비교 2026에 한 표로 모아 두었어요.

다시 확인할 날짜

• 10월 24일: /install-github-app 흐름과 리뷰 워크플로가 바뀌었는지, examples/claude.yml 이 받는 이벤트.
• 11월 10일: 깃허브 Actions 기본 시간·1분 값, 구독 토큰이 되는 요금제, 코덱스·제미나이 액션 문서.

이 글의 내용은 2026년 10월 10일 공식 문서 기준이에요. 설정 이름과 요금제는 자주 바뀌어요. 글과 다르게 보이면 공식 문서의 지금 내용을 먼저 보세요.

같이 보면 좋은 글: 클로드 코드 깃 커밋·PR 맡기는 법: 연습 폴더부터 /diff·push 막기·서명 줄까지

같이 보면 좋은 글: 코덱스 깃허브 코드 리뷰 받는 법: @codex review 부터 자동 리뷰·AGENTS.md 규칙까지

같이 보면 좋은 글: 클로드 코드 claude -p 사용법: 화면 없이 시키고 답만 받기

같이 보면 좋은 글: 클로드 코드 클라우드 세션 사용법: PC 를 꺼도 도는 웹 세션

같이 보면 좋은 글: 클로드 코드 사용량 아끼는 법 모음

같이 보면 좋은 글: AI 비교 2026: 클로드·챗GPT·제미나이 요금제·한도·기능 표

이 글이 들어간 총정리: 클로드 코드에 일 맡기는 법

같이 보면 좋은 글: 클로드 코드 /security-review 사용법: 보안 검토 한 줄부터 깃허브 PR 자동 검사까지

같이 보면 좋은 글: 클로드 코드 /code-review 사용법: 코드 리뷰 한 줄부터 --fix·클라우드 ultra 리뷰까지

참고한 자료

2026년 10월 10일에 확인했어요.

• Claude Code GitHub Actions (클로드 코드 공식 문서 한국어 버전, 빠른 설정·수동 설정·모드·비용·문제 해결)
• Claude Code GitHub Actions (클로드 코드 공식 문서 영어 버전, 메뉴 이름·앱 권한·지우기)
• Authentication (클로드 코드 공식 문서, claude setup-token)
• Commands (클로드 코드 공식 문서, /install-github-app)
• Automate work with routines (클로드 코드 공식 문서, 깃허브 트리거)
• Changelog (클로드 코드 공식 변경 기록, 2.1.292)
• Security (Anthropic claude-code-action 저장소 공식 문서, PR 만들기·프롬프트 주입·전체 출력)
• examples/claude.yml (Anthropic claude-code-action 저장소, 받는 이벤트)
• Supported countries and regions (Anthropic, South Korea)
• Understanding GitHub Actions (깃허브 공식 문서, 워크플로·이벤트·러너)
• GitHub Actions billing (깃허브 공식 문서, 공개 저장소 무료·한 달 기본 시간·1분 값)
• Codex GitHub Action (OpenAI 코덱스 공식 문서)
• Supported countries and territories (OpenAI API, South Korea)
• run-gemini-cli (구글 google-github-actions 저장소 안내)
• gemini-dispatch.yml (구글 run-gemini-cli 예시 워크플로, 호출할 수 있는 사람 조건)
• CLI commands (제미나이 CLI 공식 문서, /setup-github)
• Available regions for Google AI Studio and Gemini API (구글 공식 문서, South Korea)