Claude Code Action 403 권한 오류 해결

@claude 댓글이나 prompt 로 돌린 워크플로가 403 Resource not accessible by integration 으로 끝났다면, 어느 토큰이 어떤 권한으로 요청했는지부터 가립니다.

[1] 워크플로의 uses: anthropics/claude-code-action@v1 단계에 github_token 입력이 있는지 봅니다. 없으면 액션은 Claude GitHub App 으로 인증하고, 있으면 그 토큰으로 동작합니다. 점검할 곳이 달라집니다.

[2] permissions: 블록을 공식 예시와 맞춥니다. GitHub 은 권한을 하나라도 적으면 적지 않은 나머지를 none 으로 만들기 때문에, contents: read 한 줄만 있는 블록은 쓰기 권한을 전부 뺀 것과 같습니다. @claude 에 응답하는 워크플로의 공식 예시는 다음과 같습니다.

jobs:  claude:    runs-on: ubuntu-latest    permissions:      contents: write      pull-requests: write      issues: write      id-token: write      actions: read

id-token: write 는 기본 인증(Claude GitHub App)에 필요합니다. 빠지면 FAQ 의 OIDC 인증 오류 항목에 해당합니다. actions: read 는 PR 의 CI 결과를 읽게 하는 줄이고, 필요 없으면 뺍니다.

[3] 하려는 일에 맞게 쓰기 권한을 고릅니다. 문서가 밝힌 앱 권한의 용도는 다음과 같습니다.

문서의 코드 리뷰 예시는 contents·pull-requests·issues 를 read 로 두고 id-token: write 만 올렸는데도 --comment 로 PR 에 리뷰를 답니다. 반면 파일을 고치고 푸시하는 @claude 예시는 셋 다 write 입니다. 댓글만 받을 워크플로라면 read 로 시작해 보고, 푸시가 필요해지면 올립니다.

[4] 저장소 Settings → Actions → General → Workflow permissions 를 엽니다. 선택지는 모든 권한에 읽기·쓰기를 주는 쪽과 contents·packages 읽기만 주는 쪽입니다. 저장소가 조직 소속이고 조직이 더 엄격한 기본값을 골랐다면 저장소에서도 같은 값이 선택되고 허용 쪽 옵션은 비활성화됩니다. 이때는 조직 관리자에게 부탁해야 합니다.

[5] 오타를 actionlint 로 거릅니다. 1.7.12 에서 pull-requests 를 pull-request 로 잘못 쓴 파일을 검사한 결과입니다.

$ actionlint typo.ymltypo.yml:13:7: unknown permission scope "pull-request". all available permission scopes are "actions", "artifact-metadata", "attestations", "checks", "contents", "deployments", "discussions", "id-token", "issues", "models", "packages", "pages", "pull-requests", "repository-projects", "security-events", "statuses" [permissions]   |13 |       pull-request: write   |       ^~~~~~~~~~~~~

id-token: read 처럼 허용되지 않는 값도 잡습니다.

$ actionlint badvalue.ymlbadvalue.yml:15:17: "read" is invalid as permission of scope "id-token". available values are "write", "none" [permissions]

[6] 그래도 403 이면 상황별로 봅니다.

• 포크에서 온 PR: 포크 PR 로 도는 워크플로(pull_request_target 제외)는 Send write tokens to workflows from pull requests 를 켜지 않았다면 쓰기 권한이 읽기로 낮아집니다. 공개 저장소에서는 포크 PR 실행에 시크릿도 전달되지 않습니다.
• **prompt 를 쓰는 자동화 모드**: FAQ 는 앱 토큰으로 /user 를 조회하다 403 이 나는 경우를 설명합니다. 액션이 bot_id 와 bot_name 기본값을 쓰므로 @v1 이 최신인지 확인하고, 직접 만든 봇이면 두 입력을 함께 지정합니다.
• 워크플로 파일을 고치게 한 경우: Claude GitHub App 에는 워크플로 쓰기 권한이 없다고 FAQ 가 밝힙니다. .github/workflows/ 아래 수정은 사람이 합니다.
• 댓글 작성자: 이슈·PR 이벤트는 트리거한 사용자에게 저장소 쓰기 권한이 있어야 합니다.
• 앱 미설치: Claude GitHub App 이 그 저장소에 설치됐는지 확인합니다.