출처 대조 B · GitHub Actions ubuntu-latest, openssl 3

검증 환경: GitHub Actions ubuntu-latest, openssl 3 (GitHub App JWT 서명 부분만 재현)

게시 2026-09-24수정 2026-09-25최종 확인 2026-09-24읽기 10분

GitHub Actions PR이 다른 워크플로를 트리거하지 않을 때 (GITHUB_TOKEN과 GitHub App 토큰)

GitHub Actions에서 GITHUB_TOKEN으로 만든 PR·푸시가 다른 워크플로를 트리거하지 않는 이유와, GitHub App 토큰으로 해결하는 방법을 정리한다.

30초 요약

워크플로 안에서 기본 제공되는 GITHUB_TOKEN으로 커밋을 푸시하면 그 이벤트로는 다른 워크플로가 아예 실행되지 않는다. GITHUB_TOKEN으로 PR을 만들거나 갱신(opened·synchronize·reopened)하면 pull_request 워크플로 실행 자체는 생성되지만 “승인 필요(approval-required)” 상태로 멈춰 있어 사람이 승인해야 돈다. 승인 없이 항상 실행되는 예외는 workflow_dispatch와 repository_dispatch 두 이벤트뿐이다(공식 문서). 자동으로 만든 PR에서도 pull_request 워크플로가 사람이 만든 PR과 같이 승인 없이 돌게 하려면 GITHUB_TOKEN 대신 GitHub App 설치 토큰이나 개인 접근 토큰(PAT)을 써야 한다.

증상/목표

워크플로 안에서 gh pr create나 peter-evans/create-pull-request 같은 액션으로 PR을 만든다. 그런데 그 저장소에 on: pull_request로 등록해 둔 CI·린트 워크플로가 이 PR에서는 정상적으로 돌지 않는다. 증상은 두 가지로 나뉜다.

  • 실행이 아예 없음: push 같은 이벤트를 GITHUB_TOKEN으로 발생시키면 대부분 새 워크플로 실행 자체가 만들어지지 않는다. Actions 탭에 실행 기록조차 남지 않는다
  • 승인 대기로 멈춤: GITHUB_TOKEN으로 만들거나 갱신한 PR의 pull_request 실행은 생성되지만 “승인 필요(approval-required)” 상태로 멈춰서, 저장소에 쓰기 권한이 있는 사람이 승인하기 전까지는 돌지 않는다

필수 상태 검사(required status checks)를 켜 둔 저장소에서는 이 검사가 “Expected — Waiting for status to be reported”로 멈춰서 병합 자체가 막힌다. 승인 대기 상태인 실행은 결과를 보고하지 않으므로 검사가 영영 끝나지 않는 것처럼 보인다.

같은 브랜치로 사람이 직접 PR을 열면 워크플로가 정상적으로 도는데, 워크플로가 만든 PR에서만 이런 문제가 생긴다.

목표는 자동화가 만든 PR에서도 pull_request 워크플로가 사람이 만든 PR과 동일하게, 승인 없이 실행되게 하는 것이다.

이 블로그는 초안을 PR로 올리는 봇을 이 제한 때문에 처음부터 GitHub App 토큰으로 만들었고, 봇이 연 PR에서 필수 build 검사가 자동으로 실행되는 것을 확인했다. 다만 PR 댓글로 수정을 요청하는 워크플로에서는 checkout에 토큰을 넘기지 않아 push가 403으로 막혔고, checkout에 App 토큰을 넘겨 해결했다(주의 섹션 참고).

원인

GitHub 공식 문서는 이렇게 밝히고 있다.

events triggered by the GITHUB_TOKEN will not create a new workflow run

즉 GITHUB_TOKEN으로 발생시킨 push 같은 이벤트는 새 워크플로 실행을 만들지 않는다. 다만 PR 관련 이벤트는 따로 다룬다.

pull_request events with the opened, synchronize, or reopened activity types: when a workflow using GITHUB_TOKEN creates or updates a pull request, the resulting pull_request event creates workflow runs in an approval-required state

즉 GITHUB_TOKEN으로 PR을 만들거나 갱신하면 pull_request 워크플로 실행은 생성되지만 “승인 필요(approval-required)” 상태로 멈추고, 저장소에 쓰기 권한이 있는 사람이 “Approve workflows to run”으로 승인해야 실제로 돈다(GITHUB_TOKEN 문서). 실행이 아예 생성되지 않는 것과는 다른 증상이다.

승인 없이 항상 실행을 만드는 예외는 다음 두 이벤트뿐이다.

workflow_dispatch and repository_dispatch events always create workflow runs

이 제한은 워크플로가 스스로 워크플로를 계속 다시 트리거하는 무한 루프를 막기 위한 설계다(같은 문서). GITHUB_TOKEN의 권한을 permissions:에서 아무리 넓혀도 이 제한 자체는 바뀌지 않는다. 권한(permission)과 트리거 억제는 별개의 규칙이다.

같은 문서는 우회 방법도 명시한다.

you can use a GitHub App installation access token or a personal access token instead of GITHUB_TOKEN

GITHUB_TOKEN의 권한은 애초에 그 워크플로가 있는 저장소로 한정돼 있고, GitHub 호스티드 러너에서는 최대 6시간 뒤 만료된다(GITHUB_TOKEN 문서). 여러 저장소를 넘나들거나 조직 단위로 자동화를 운영한다면 이 한계도 함께 걸린다.

GITHUB_TOKEN으로 만든 push는 새 실행을 만들지 않고, pull_request는 승인 필요 상태로 멈추며, GitHub App 설치 토큰이나 PAT로 만들면 다른 워크플로가 실행된다GITHUB_TOKENGITHUB_TOKENGitHub App 설치 토큰·PAT워크플로가 push하거나 PR을 만든다어떤 토큰으로?push 등: 새 워크플로 실행이 생기지 않는다pull_request: 실행은 생기지만 승인 필요상태다른 워크플로가 실행된다
토큰에 따라 다른 워크플로가 실행되는지 (파랑 = 자동 · 초록 = 외부 · 회색 = 조건)

해결 방법

GitHub App을 만들어 설치 토큰을 발급받고, 그 토큰으로 체크아웃·PR 생성을 하는 방법을 기준으로 적는다. GitHub App 생성과 시크릿 등록은 웹 UI에서 하는 작업이라 이 문서를 그대로 옮긴 것이다(문서 대조, B등급).

1. GitHub App 만들기

GitHub 공식 절차는 다음과 같다(App 등록 문서).

  1. GitHub 프로필 → Settings → Developer settings → GitHub Apps로 이동한다. 조직 소유로 등록하려면 조직 페이지 → Settings → Developer settings → GitHub Apps로 이동한다
  2. “New GitHub App”을 누른다
  3. 앱 이름, Homepage URL 등 필수 항목을 채운다
  4. Repository permissions에서 이 앱이 실제로 필요로 하는 권한만 켠다. PR을 만들고 브랜치를 푸시하려면 최소 Contents: Read and write, Pull requests: Read and write가 필요하다
  5. Webhook은 이 용도(다른 워크플로 트리거용)라면 꺼 둬도 된다
  6. “Create GitHub App”으로 생성한다
  7. 생성된 앱 설정 화면에서 App ID를 적어 두고, “Generate a private key”로 개인 키(.pem)를 내려받는다

2. 리포지토리에 App 설치하고 자격 증명을 시크릿으로 등록하기

앱 설정 화면의 “Install App”에서 이 워크플로가 PR을 만들 저장소(들)에 설치한다. 그다음 저장소나 조직의 Actions 시크릿·변수에 App ID(변수)와 private key(시크릿)를 등록한다. 이 단계도 웹 UI 작업이라 문서 대조로 표시한다.

3. 워크플로에서 설치 토큰 발급받기

actions/create-github-app-token 액션은 App ID(또는 client ID)와 private key를 받아 설치 접근 토큰을 발급한다(액션 문서).

- uses: actions/create-github-app-token@v3
id: app-token
with:
client-id: ${{ vars.APP_CLIENT_ID }}
private-key: ${{ secrets.APP_PRIVATE_KEY }}

발급된 토큰은 1시간 뒤 만료되고, 작업이 끝나면 자동으로 취소된다(같은 문서). 필요한 권한만 permission-<이름> 입력으로 좁히는 쪽을 권장한다고 문서에 적혀 있다.

4. 발급받은 토큰으로 체크아웃하거나 PR 만들기

GITHUB_TOKEN 대신 이 토큰을 체크아웃과 gh pr create에 넘긴다.

permissions:
contents: read # PR 생성은 App 토큰이 하므로 GITHUB_TOKEN 권한을 올릴 필요 없음
jobs:
open-pr:
runs-on: ubuntu-latest
steps:
- uses: actions/create-github-app-token@v3
id: app-token
with:
client-id: ${{ vars.APP_CLIENT_ID }}
private-key: ${{ secrets.APP_PRIVATE_KEY }}
- uses: actions/checkout@v7
with:
token: ${{ steps.app-token.outputs.token }}
# ... 커밋 생성 단계 ...
- name: PR 만들기
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
run: gh pr create --title "자동 생성 PR" --body "자동화가 만든 변경"

이렇게 만든 PR은 GitHub App 설치 토큰이 발생시킨 이벤트이므로 on: pull_request 워크플로가 사람이 만든 PR과 동일하게 실행된다(트리거 문서).

이 검사를 main 보호 규칙의 필수 검사로 거는 방법은 GitHub Ruleset으로 main 보호하기에 있다.

확인

전체를 실제로 확인하려면 이 App 토큰으로 PR을 하나 만들어 보고, 저장소의 Actions 탭에서 그 PR에 대해 pull_request 워크플로가 실행되는지 보면 된다. 이 부분은 실제 GitHub 저장소와 등록된 App이 있어야 하므로 이 글의 verify.sh로는 재현하지 않는다(문서 대조).

verify.sh는 그 대신 GitHub App 인증의 바탕이 되는 부분, 즉 App이 설치 토큰을 받기 전에 만드는 JWT를 실제로 만들고 서명을 검증한다. RS256 서명, iss(App ID), exp가 iat로부터 10분을 넘지 않아야 한다는 제약을 그대로 재현해서 확인한다(JWT 생성 문서).

CI 실행 결과 · 3/3 단계 성공
검증 환경 3항목
OSUbuntu 24.04.5
실행 날짜2026-09-24
작성자 기재 환경GitHub Actions ubuntu-latest, openssl 3 (GitHub App JWT 서명 부분만 재현)
[PASS] JWT가 header.payload.signature 3부분 형식
[PASS] exp가 iat로부터 10분(600초) 이내
[PASS] 개인키로 만든 서명이 공개키로 검증됨
이 결과는 글의 명령어를 GitHub Actions의 깨끗한 환경에서 그대로 실행해 자동으로 붙인 것입니다.

주의

  • private key(.pem)는 시크릿으로만 보관한다. 저장소에 커밋하지 않는다
  • App에는 실제로 쓰는 권한(Contents, Pull requests 등)만 켠다. create-github-app-token 문서도 필요한 권한만 명시적으로 지정하라고 권장한다(같은 문서)
  • PR이 .github/workflows/ 안의 파일을 바꾼다면 App에 Workflows: Read and write 권한도 켜야 한다. Contents 권한만으로는 워크플로 파일을 만들거나 수정할 수 없다(관련 REST API 문서)
  • App 토큰을 쓰는 워크플로에서 actions/checkout에 token을 지정하지 않으면 기본값인 읽기 전용 GITHUB_TOKEN이 git 자격 증명으로 로컬 git 설정에 저장된다. 이 상태에서는 이후 App 토큰으로 push해도 Write access to repository not granted(403)로 거부될 수 있다. checkout의 token 입력에 발급받은 App 토큰을 넘긴다(actions/checkout 문서)
  • App 토큰으로 실행된 워크플로가 같은 방식으로 또 커밋이나 PR을 만들면 반복 실행으로 이어질 수 있다. 조건(paths, 커밋 메시지 등)을 좁혀서 자기 자신을 다시 트리거하지 않게 설계한다
  • GitHub App의 JWT는 exp가 iat로부터 최대 10분 이내여야 한다는 제약이 있다(JWT 생성 문서). create-github-app-token 같은 액션을 쓰면 이 계산은 액션이 알아서 하므로 직접 만들 일은 거의 없다

자주 묻는 질문

GITHUB_TOKEN의 permissions를 write-all로 올리면 해결되지 않나?

아니다. 트리거 억제는 권한 범위와 무관하게 적용된다. push 같은 이벤트는 GITHUB_TOKEN으로 발생시키면 실행 자체가 생성되지 않고, pull_request(opened·synchronize·reopened)는 실행이 생성되긴 해도 “승인 필요(approval-required)” 상태로 멈춘다. 승인 없이 항상 실행되는 예외로 공식 문서에 명시된 것은 workflow_dispatch와 repository_dispatch 두 이벤트뿐이다(문서).

GitHub App 대신 개인 접근 토큰(PAT)을 써도 되나?

된다. 공식 문서도 GITHUB_TOKEN 대신 쓸 수 있는 것으로 “GitHub App installation access token”과 “personal access token” 둘 다 언급한다(문서). 다만 PAT는 그 토큰을 만든 개인 계정에 묶이는 반면, GitHub App 설치 토큰은 App 자체의 권한으로 동작한다는 차이가 있다.

workflow_dispatch로 우회하면 안 되나?

workflow_dispatch와 repository_dispatch는 GITHUB_TOKEN으로도 항상 새 실행을 만든다(문서). 하지만 이건 실행하고 싶은 워크플로의 트리거 자체를 pull_request가 아니라 workflow_dispatch/repository_dispatch로 바꿔야 한다는 뜻이다. 기존에 on: pull_request로 동작하는 워크플로를 그대로 두고 자동 생성 PR에서만 돌게 하려면 App 토큰이나 PAT 쪽이 더 간단하다.

JWT와 설치 토큰(installation token)은 뭐가 다른가?

JWT는 App 자신을 증명하기 위해 App의 private key로 서명하는 값이고, 이 JWT로 /app/installations/{id}/access_tokens를 호출해 실제로 API·git 작업에 쓰는 설치 토큰을 받는다. create-github-app-token 같은 액션은 이 과정을 대신 처리해서 설치 토큰만 돌려준다(액션 문서).

참고 자료