내멋스레 사는 이야기

🔍 검색 키워드: GitHub Actions permission denied 해결, GITHUB_TOKEN permissions 에러, GitHub Actions resource not accessible by integration, GitHub Actions write permission 설정, GitHub Actions contents read write

GitHub Actions 워크플로우를 처음 구성하거나 레포지토리 설정이 바뀐 뒤에 갑자기 이런 에러가 나는 경우가 있다.

Error: Resource not accessible by integration
Error: HttpError: 403 — The requested URL returned error: 403
remote: Permission to owner/repo.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/...': The requested URL returned error: 403

모두 GITHUB_TOKEN의 권한이 부족해서 발생하는 에러다.

증상

actions/checkout에서 push 실패
GitHub Pages 배포 단계에서 403 에러
PR에 코멘트 달기, 라벨 붙이기 등 GitHub API 호출 실패
Release 생성, 태그 푸시 등 쓰기 작업에서 403

원인

GitHub는 기본적으로 GITHUB_TOKEN의 권한을 read-only로 설정한다. 이는 2023년 이후 새로 만들어진 레포지토리의 기본 정책이고, 조직 설정에 따라 강제될 수도 있다.

해결방법

방법 1: 워크플로우 파일에 permissions 추가 (권장)

name: Deploy

on:
  push:
    branches: [main]

# ✅ 필요한 권한만 명시
permissions:
  contents: write      # 코드 push, 태그 생성
  pull-requests: write # PR 코멘트
  pages: write         # GitHub Pages 배포
  id-token: write      # OIDC 토큰

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh

특정 job에만 적용하는 것도 가능하다:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read    # 읽기만 필요한 빌드 단계
    steps:
      - uses: actions/checkout@v4
      - run: npm run build

  deploy:
    runs-on: ubuntu-latest
    needs: build
    permissions:
      contents: write   # 쓰기 필요한 배포 단계만
      pages: write
      id-token: write
    steps:
      - uses: actions/deploy-pages@v4

방법 2: 레포지토리 설정 변경

레포지토리 → Settings → Actions → General → Workflow permissions 에서 "Read and write permissions"로 변경. 단, 이 방법은 모든 워크플로우에 쓰기 권한을 부여하므로 보안상 권장하지 않는다.

자주 쓰는 permissions 조합

# GitHub Pages 배포
permissions:
  contents: read
  pages: write
  id-token: write

# 릴리즈 생성 + 태그 푸시
permissions:
  contents: write

# PR 자동 코멘트
permissions:
  pull-requests: write
  issues: write

# GitHub Packages / GHCR 푸시
permissions:
  contents: read
  packages: write

# Security 스캔 결과 업로드
permissions:
  security-events: write
  contents: read

사용 가능한 권한 종류

권한	설명
`contents`	레포 코드 읽기/쓰기, 태그, 릴리즈
`pull-requests`	PR 생성, 코멘트, 라벨
`packages`	GitHub Packages (GHCR)
`pages`	GitHub Pages 배포
`id-token`	OIDC JWT 토큰 (AWS, GCP 인증)
`checks`	체크 결과 생성/업데이트
`security-events`	코드 스캐닝 결과

Next.js → GitHub Pages 배포 완성 예시

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./out

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

점검 체크리스트

항목	확인
에러 메시지	`403` 또는 `Resource not accessible`인지 확인
워크플로우 permissions 블록	필요한 권한이 명시됐는지
레포 기본 설정	Settings → Actions → Workflow permissions 확인
조직 설정	조직 레벨에서 강제 제한되지 않는지
최소 권한 원칙	필요한 권한만 최소한으로 부여

정리

GITHUB_TOKEN permission denied는 거의 항상 워크플로우 파일에 permissions 블록을 추가하는 것으로 해결된다. 레포 설정을 "Read and write permissions"로 바꾸는 방법도 있지만, 모든 워크플로우에 넓은 권한을 주는 것이라 권장하지 않는다.

필요한 권한을 최소한으로 명시하는 습관을 들이면 보안도 챙기면서 에러도 예방할 수 있다.