GitHub Actions 403 해결: GITHUB_TOKEN 권한·포크 PR·OIDC 점검

그림: GitHub Actions 403은 실행 이벤트, 토큰 권한, 외부 클라우드 역할을 차례로 분리해 점검합니다.

GitHub Actions에서 Resource not accessible by integration 또는 HTTP 403이 나오면 토큰 문자열을 새로 만드는 것부터 시작하기 쉽습니다. 그러나 대부분은 어떤 이벤트로 실행됐는지, 어떤 권한이 부여됐는지, 어느 API가 거부했는지를 구분해야 해결됩니다. 특히 포크 PR과 OIDC 배포는 일반 push와 권한 조건이 다릅니다.

1. 먼저 실패한 API와 실행 이벤트를 찾는다

로그에서 실패한 단계와 요청 대상이 GitHub API인지, 패키지 레지스트리인지, AWS 같은 외부 서비스인지 확인하세요. 이어 워크플로의 on: 이벤트, 저장소·조직의 Actions 설정, 실행 주체를 확인합니다. 외부 서비스가 반환한 403은 GITHUB_TOKEN 권한만 늘려도 해결되지 않습니다. 비밀 값 자체는 로그에 출력하지 마세요.

2. GITHUB_TOKEN에 필요한 권한만 선언한다

GitHub Actions 워크플로에는 permissions:를 선언해 토큰 범위를 지정할 수 있습니다. 예를 들어 이슈에 댓글을 작성하는 작업에는 해당 API가 요구하는 쓰기 권한이 필요합니다. 반면 소스를 읽고 테스트만 수행한다면 읽기 권한으로 충분한 경우가 많습니다. 권한을 하나라도 명시하면 나머지 권한은 기본적으로 none이 되므로, 실패한 단계에서 필요한 범위를 공식 API 문서와 함께 확인하세요.

permissions:
  contents: read
  issues: write

이 예시는 이슈 수정이 필요한 워크플로에만 적용하세요. 모든 워크플로에 쓰기 권한을 일괄 부여하는 방식은 피합니다.

3. 포크 PR과 OIDC는 별도로 판단한다

상황	확인 항목	방향
일반 push에서 GitHub API 403	API별 필요 권한과 워크플로 permissions	필요한 범위만 명시
포크 PR에서만 403	이벤트 유형과 포크 워크플로 제한	민감 작업을 신뢰된 이벤트로 분리
AWS 배포 단계 403	OIDC 토큰 권한, IAM 신뢰 정책·역할 권한	GitHub와 AWS 양쪽 설정 검증

포크에서 온 코드에 비밀 값이나 높은 권한을 제공하면 위험합니다. pull_request_target으로 무조건 전환하는 식의 우회는 피하고, 코드 검증과 배포를 분리하세요. AWS OIDC 연동에는 워크플로의 id-token: write뿐 아니라 AWS IAM 역할 신뢰 정책과 권한도 필요합니다.

4. 재현 가능한 최소 점검 순서

1. 실패한 job·step·API 응답을 기록합니다.
2. 실행 이벤트가 push, pull_request, 수동 실행 중 무엇인지 확인합니다.
3. permissions:의 워크플로 수준과 job 수준 설정을 비교합니다.
4. 포크 PR이면 토큰·비밀 값 제한을 확인합니다.
5. OIDC 사용 시 클라우드 역할 신뢰 조건과 권한 정책을 확인합니다.
6. 범위를 최소화해 수정하고 같은 이벤트로 다시 실행합니다.

민감한 인증 정보는 시크릿 매니저 비교 가이드의 회전·접근 제어 항목도 참고하세요.

5. 오류 예시로 원인을 좁힌다

예를 들어 PR 검증 job에서 이슈 라벨을 쓰려다 403이 났다면 이벤트가 포크 PR인지 먼저 확인합니다. 단순히 issues: write를 추가해도 포크 이벤트의 제한 때문에 성공하지 않을 수 있습니다. 반대로 신뢰된 push 이벤트에서 GitHub API 호출이 거부됐다면 필요한 세부 권한이 누락됐을 가능성을 점검합니다. 클라우드 배포 단계에서만 403이라면 GitHub API 권한보다 클라우드 역할 정책을 먼저 살펴보세요.

6. 자주 묻는 질문

Q. permissions: write-all을 넣으면 되나요?
문제가 가려질 수 있지만 권한을 과도하게 늘립니다. 실패 API에 필요한 권한만 선언하세요.

Q. 포크 PR에서도 배포 비밀 값을 사용할 수 있나요?
포크 PR에는 보안 제한이 적용됩니다. 신뢰되지 않은 코드를 실행하는 job과 민감한 배포 job을 분리하세요.

Q. id-token: write만 있으면 AWS 배포가 되나요?
아닙니다. AWS IAM 신뢰 정책과 역할 권한도 맞아야 합니다.

공식 자료: GitHub 워크플로 문법·권한 · GitHub AWS OIDC 가이드 · GitHub 403 오류 안내 (확인일: 2026-09-26)