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 workflowerror: 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 쓰기 권한이 있어도 워크플로 파일이 든 변경은 따로 허용해야 한다.
워크플로 안에서 쓰는 토큰의 다른 제약은 GitHub Actions PR이 다른 워크플로를 트리거하지 않을 때 (GITHUB_TOKEN과 GitHub App 토큰)에서 다룬다.
해결 방법
1. 거부된 커밋이 워크플로 파일을 건드리는지 확인한다
push할 커밋 범위에서 워크플로 파일이 바뀌었는지 본다.
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에서 토큰을 만들거나 연다. 접근 범위는 최소로 고른다.
- Repository access를
Only select repositories로 하고, push할 저장소만 고른다. - Permissions → Repository permissions에서
Contents를Read and write로 둔다. - 같은 목록의
Workflows를Read and write로 바꾼다. - 토큰을 만든 뒤 새로 나온 값을 복사한다.
조직 소유 저장소라면 resource owner가 조직인 토큰을 만들어야 하고, 조직이 승인을 요구하면 승인 전까지 토큰이 pending이다.
토큰 설정 화면에서 권한을 바꿀 수 없으면 새 토큰을 만들어 교체한다.
3. git이 새 토큰을 쓰는지 확인한다
권한을 고쳤는데도 거부되는 경우가 보고돼 있다. 원인은 두 가지다.
- 키체인(macOS)이나 자격 증명 관리자(Windows)에
workflow권한이 없는 옛 토큰이 남아 있다. 저장된 항목을 지우거나 새 토큰으로 바꾼다. - 원격 URL에 옛 토큰이 이미 들어 있다. 다음 명령으로 URL을 확인한다.
git remote get-url originhttps://<토큰>@github.com/… 꼴이면 토큰이 .git/config에 평문으로 남아 있는 것이다. URL을 https://github.com/<owner>/<repo>.git으로 되돌리고 자격 증명 저장소에 새 토큰을 넣는다.
4. 다시 push한다
git push origin HEAD확인
워크플로 파일이 든 커밋을 포함해 push가 [remote rejected] 없이 끝나면 성공이다. GitHub 서버의 거부는 러너에서 재현할 수 없으므로, 아래 실행 결과는 1단계의 탐지 명령과 원격 URL 점검이 의도대로 동작하는지만 보여 준다.
검증 범위: 워크플로 파일이 든 커밋을 가려내는 명령과 원격 URL의 토큰 점검은 러너의 임시 저장소에서 실행으로 확인했다. GitHub의 push 거부와 fine-grained PAT의 Workflows 권한 동작은 실행하지 못했고 공식 문서와 커뮤니티 토론으로 대조했다. 기존 토큰의 권한 변경 가능 여부는 문서에서 확인하지 못했다.
검증 환경 3항목
| OS | Ubuntu 24.04.5 |
|---|---|
| Git | 2.55.0 |
| 실행 날짜 | 2026-10-16 |
[PASS] 워크플로 파일이 없는 커밋은 탐지되지 않는다 [PASS] 탐지 결과가 비어 있지 않다 [PASS] 워크플로 파일이 든 커밋을 탐지한다 [PASS] 원격 URL에 박힌 토큰을 알아본다 [PASS] URL을 되돌리면 토큰이 없다
주의
- 토큰 권한은 필요한 저장소에만 준다. 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 스코프를 더한다.