출처 대조 B게시 2026-10-16최종 확인 2026-10-16읽기 5분

workflow 파일 push 거부 해결: fine-grained PAT의 Workflows 권한

git push가 'refusing to allow a Personal Access Token to create or update workflow'로 거부될 때, fine-grained PAT에 Workflows 권한을 주고 확인하는 방법.

30초 요약

  • .github/workflows/ 아래 파일을 포함한 커밋을 PAT로 push하면 GitHub가 refusing to allow a Personal Access Token to create or update workflow … without 'workflow' scope로 거부한다.
  • fine-grained PAT에서는 Contents: Read and write만으로 부족하다. 토큰에 Workflows 저장소 권한을 줘야 한다. 이 권한은 write만 있다.
  • 권한을 고친 뒤에도 같은 에러면 키체인·자격 증명 관리자에 남은 옛 토큰이나 원격 URL에 박힌 토큰을 확인한다.

증상/목표

워크플로 파일을 고치고 push하면 다음과 같은 줄에서 멈춘다. 커뮤니티 토론에 올라온 원문은 이렇게 시작한다.

! [remote rejected] ok -> ok (refusing to allow a Personal Access Token to create or update workflow
error: failed to push some refs to

메시지 뒷부분에는 거부된 파일 경로와 without 'workflow' scope가 이어진다. 같은 브랜치에 워크플로 파일이 없는 커밋만 있을 때는 같은 토큰으로 push가 된다. 이 글의 목표는 워크플로 파일이 든 커밋을 fine-grained PAT로 push하는 것이다.

원인

push 내용에 .github/workflows/ 파일의 추가·수정이 들어 있으면, GitHub는 토큰에 워크플로를 바꿀 권한이 있는지 따로 본다. 클래식 PAT에서는 workflow 스코프가 그 권한이다.

fine-grained PAT에서 대응하는 것은 Workflows 저장소 권한이다. Workflows는 write 접근만 있고, 파일 내용을 쓰는 PUT /repos/{owner}/{repo}/contents/{path}, 레퍼런스를 만드는 POST /repos/{owner}/{repo}/git/refs 같은 엔드포인트에 추가 권한으로 표시된다. 그래서 Contents 쓰기 권한이 있어도 워크플로 파일이 든 변경은 따로 허용해야 한다.

push에 .github/workflows 파일이 있으면 Workflows 권한을 확인하고, 없으면 거부되며 있으면 push가 통과한다아니오예없음있음git push변경에 .github/workflows파일이 있나Contents 쓰기 권한만 확인토큰에 Workflows권한이 있나refusing to allow …push 거부push 통과
워크플로 파일이 든 push만 Workflows 권한을 추가로 요구한다 (보라 = 사람 · 초록 = 외부 · 회색 = 조건)

워크플로 안에서 쓰는 토큰의 다른 제약은 GitHub Actions PR이 다른 워크플로를 트리거하지 않을 때 (GITHUB_TOKEN과 GitHub App 토큰)에서 다룬다.

해결 방법

1. 거부된 커밋이 워크플로 파일을 건드리는지 확인한다

push할 커밋 범위에서 워크플로 파일이 바뀌었는지 본다.

Terminal window
git diff --name-only origin/main..HEAD | grep '^\.github/workflows/'

출력이 있으면 그 파일 때문에 거부된 것이다. 아무것도 나오지 않는데 같은 에러가 나면 다른 커밋이 범위에 들어 있는지 git log --name-only origin/main..HEAD로 본다.

2. 토큰에 Workflows 권한을 준다

GitHub의 Settings → Developer settings → Personal access tokens → Fine-grained tokens에서 토큰을 만들거나 연다. 접근 범위는 최소로 고른다.

  1. Repository access를 Only select repositories로 하고, push할 저장소만 고른다.
  2. Permissions → Repository permissions에서 Contents를 Read and write로 둔다.
  3. 같은 목록의 Workflows를 Read and write로 바꾼다.
  4. 토큰을 만든 뒤 새로 나온 값을 복사한다.

조직 소유 저장소라면 resource owner가 조직인 토큰을 만들어야 하고, 조직이 승인을 요구하면 승인 전까지 토큰이 pending이다.

토큰 설정 화면에서 권한을 바꿀 수 없으면 새 토큰을 만들어 교체한다.

3. git이 새 토큰을 쓰는지 확인한다

권한을 고쳤는데도 거부되는 경우가 보고돼 있다. 원인은 두 가지다.

  • 키체인(macOS)이나 자격 증명 관리자(Windows)에 workflow 권한이 없는 옛 토큰이 남아 있다. 저장된 항목을 지우거나 새 토큰으로 바꾼다.
  • 원격 URL에 옛 토큰이 이미 들어 있다. 다음 명령으로 URL을 확인한다.
Terminal window
git remote get-url origin

https://<토큰>@github.com/… 꼴이면 토큰이 .git/config에 평문으로 남아 있는 것이다. URL을 https://github.com/<owner>/<repo>.git으로 되돌리고 자격 증명 저장소에 새 토큰을 넣는다.

4. 다시 push한다

Terminal window
git push origin HEAD

확인

워크플로 파일이 든 커밋을 포함해 push가 [remote rejected] 없이 끝나면 성공이다. GitHub 서버의 거부는 러너에서 재현할 수 없으므로, 아래 실행 결과는 1단계의 탐지 명령과 원격 URL 점검이 의도대로 동작하는지만 보여 준다.

검증 범위: 워크플로 파일이 든 커밋을 가려내는 명령과 원격 URL의 토큰 점검은 러너의 임시 저장소에서 실행으로 확인했다. GitHub의 push 거부와 fine-grained PAT의 Workflows 권한 동작은 실행하지 못했고 공식 문서와 커뮤니티 토론으로 대조했다. 기존 토큰의 권한 변경 가능 여부는 문서에서 확인하지 못했다.

CI 실행 결과 · 5/5 단계 성공
검증 환경 3항목
OSUbuntu 24.04.5
Git2.55.0
실행 날짜2026-10-16
[PASS] 워크플로 파일이 없는 커밋은 탐지되지 않는다
[PASS] 탐지 결과가 비어 있지 않다
[PASS] 워크플로 파일이 든 커밋을 탐지한다
[PASS] 원격 URL에 박힌 토큰을 알아본다
[PASS] URL을 되돌리면 토큰이 없다
이 결과는 글의 명령어를 GitHub Actions의 깨끗한 환경에서 그대로 실행해 자동으로 붙인 것입니다.

주의

  • 토큰 권한은 필요한 저장소에만 준다. Workflows 쓰기 권한이 있으면 그 저장소의 CI 정의를 바꿀 수 있어서, 토큰이 새어 나가면 시크릿을 쓰는 워크플로를 바꿀 수 있다.
  • 토큰을 원격 URL에 넣는 방법은 쓰지 않는다. 토큰이 .git/config에 평문으로 남는다.
  • 클래식 PAT의 workflow 스코프를 쓰는 방법도 있지만, 클래식 토큰은 접근 범위를 저장소 단위로 줄일 수 없다. 새로 만든다면 fine-grained를 권한다.
  • 유효 기간은 기본 30일(조직 정책이 더 짧으면 그 값)이다. 만료되면 에러 메시지가 달라지므로 이 에러와 구분한다.

자주 묻는 질문

Contents를 Read and write로 줬는데도 왜 거부되나요?

워크플로 파일 변경은 Contents와 별개로 Workflows 권한이 필요하다. Workflows를 Read and write로 준 새 토큰을 쓴다.

권한을 줬는데 같은 에러가 계속 나요.

git이 이전 토큰을 쓰고 있을 가능성이 크다. macOS 키체인이나 Windows 자격 증명 관리자에 저장된 옛 토큰, 원격 URL에 박힌 토큰이 실제 원인으로 보고됐다. 두 곳을 모두 새 토큰으로 맞춘다.

GitHub CLI로 로그인했을 때는 어떻게 하나요?

gh auth login -s workflow로 다시 인증해 해결한 사례가 있다. 이 방식은 토큰을 직접 만들지 않고 CLI가 발급한 토큰에 workflow 스코프를 더한다.

참고 자료