GitHub Actions 보안 설정법: PR 제목의 스크립트 삽입 위험과 환경변수 전달 방식

GitHub Actions 보안 설정법의 핵심은 PR 제목을 실행 코드에 직접 넣지 않고 환경변수로 전달하는 것이다. 제목을 출력하거나 규칙에 맞는지 확인하는 짧은 워크플로에서도 스크립트 삽입이 발생할 수 있다. 수정할 위치는 저장소의 비밀키 설정이 아니라, 워크플로 YAML의 run:과 env: 사이에 있다.

📌 핵심 요약

  • PR 제목처럼 외부에서 정할 수 있는 값은 신뢰하지 않는 입력으로 취급한다.
  • Bash에서는 단계의 env:로 전달하고 "$TITLE"로 참조한다.
  • 환경변수로 받았더라도 재실행하거나 환경 파일에 그대로 기록하면 새로운 삽입 경로가 생길 수 있다.
  • 입력 처리 수정과 함께 토큰 최소 권한, 외부 액션의 전체 커밋 SHA 고정을 점검한다.

1. PR 제목 스크립트 삽입이 발생하는 위치 찾기

스크립트 삽입은 외부 입력이 프로그램의 데이터가 아니라 실행할 코드의 일부로 해석되는 문제다. GitHub Actions에서는 ${{ }} 표현식이 셸 실행 전에 평가되므로, PR 제목을 run: 안에 직접 넣으면 제목이 임시 스크립트의 문법을 바꿀 수 있다.

먼저 .github/workflows/ 아래 YAML에서 github.event.pull_request.title을 검색한다. 다음처럼 표현식이 run: 본문 안에 있으면 수정 대상으로 볼 수 있다. 아래 코드는 취약한 구조를 설명하기 위한 예제다.

- name: Check PR title
  shell: bash
  run: |
    title="${{ github.event.pull_request.title }}"
    if [[ "$title" == octocat* ]]; then
      printf '%s\n' 'Title accepted'
    else
      exit 1
    fi

GitHub 공식 문서의 공격 예시 제목은 a"; ls $GITHUB_WORKSPACE"이다. 이 값이 위 할당문에 치환되면 다음과 같은 셸 코드가 만들어진다.

title="a"; ls $GITHUB_WORKSPACE""

제목 안의 큰따옴표가 원래 문자열을 끝내고, 세미콜론 뒤의 ls가 별도 명령이 된다. 따라서 표현식 전체를 큰따옴표로 감싸거나, 이후 조건문에서 변수를 인용하는 것만으로는 앞서 생성된 악성 명령을 막을 수 없다. 이 치환 순서와 공격 문자열은 GitHub의 [Script injections 공식 문서](https://docs.github.com/en/actions/concepts/security/script-injections)에 제시되어 있다.

PR 제목 검사에 실패했더라도 앞선 명령은 이미 실행됐을 수 있다는 점도 중요하다. 검사 단계가 빨간색으로 끝났다는 사실만으로 러너에서 다른 명령이 실행되지 않았다고 판단해서는 안 된다.

GitHub Actions 보안 설정법: PR 제목의 스크립트 삽입 위험과 환경변수 전달 방식

2. run 직접 삽입을 env 환경변수 전달로 수정하기

수정 방법은 표현식을 단계의 env:로 옮기는 것이다. run:에는 고정된 셸 코드만 두고, Bash가 실행될 때 환경변수의 값을 데이터로 읽도록 만든다. GitHub가 인라인 스크립트에 권고하는 방식이다.

name: Check PR title

on:
  pull_request:
    types: [opened, edited, synchronize, reopened]

permissions: {}

jobs:
  check-title:
    runs-on: ubuntu-latest
    steps:
      - name: Validate title
        shell: bash
        env:
          TITLE: ${{ github.event.pull_request.title }}
        run: |
          if [[ "$TITLE" == octocat* ]]; then
            printf '%s\n' 'Title accepted'
          else
            printf '%s\n' 'Title must start with octocat'
            exit 1
          fi

이 예제는 제목의 접두어만 확인하므로 저장소 체크아웃이나 API 호출이 필요하지 않다. PR 제목 수정도 검사하도록 edited 이벤트를 포함했으며, 접두어 octocat은 실제 저장소의 제목 규칙에 맞게 바꾸면 된다.

핵심은 TITLE 값이 셸 소스 코드 생성 과정에 끼어들지 않는다는 점이다. 환경변수에 따옴표나 세미콜론이 들어 있어도, 일반적인 "$TITLE" 확장에서는 그 문자가 새로운 셸 명령으로 다시 파싱되지 않는다. GitHub의 [Secure use 공식 문서](https://docs.github.com/en/actions/reference/security/secure-use)는 이 전달 방식과 변수 인용을 함께 설명한다.

확인 지점 수정 전 수정 후
입력 위치 run 본문의 표현식 단계의 env 값
셸 참조 치환된 제목이 코드에 포함됨 "$TITLE"로 값 참조
검토 기준 따옴표 모양에 의존 코드와 입력의 전달 경로 분리

3. Bash 큰따옴표와 github-script 입력 처리 확인하기

환경변수 전달과 셸 인용은 역할이 다르다. env:는 입력이 스크립트 소스에 직접 삽입되는 경로를 없애고, "$TITLE"은 일반적인 명령 인수에서 공백에 따른 단어 분리와 파일명 확장을 방지한다. 둘을 함께 적용하는 편이 실수를 줄이기 쉽다.

제목을 출력할 때는 printf '%s\n' "$TITLE"처럼 서식 문자열을 고정한다. 반대로 eval "$TITLE"이나 bash -c "$TITLE"처럼 값을 다시 코드로 실행하면, 환경변수로 옮긴 효과가 사라진다. 파일명이나 명령 옵션으로 전달하는 경우에는 해당 명령의 인수 처리 규칙도 별도로 확인해야 한다.

JavaScript의 script 본문에도 같은 원칙 적용

actions/github-script에서도 JavaScript 문자열 안에 PR 제목 표현식을 직접 넣으면 코드 생성 단계의 문제가 생긴다. 공식 README는 단계의 환경변수로 전달하고 process.env.TITLE로 읽도록 안내한다. 다음은 해당 액션 단계에 적용할 입력 처리 부분이다.

env:
  TITLE: ${{ github.event.pull_request.title }}
with:
  script: |
    const title = process.env.TITLE ?? '';
    if (!title.startsWith('octocat')) {
      core.setFailed('Title must start with octocat');
    }

이 조각은 완전한 워크플로가 아니므로 기존 uses: actions/github-script@… 단계 아래에 맞춰 적용해야 한다. 실제 액션 참조는 검토한 전체 커밋 SHA로 고정하고, JavaScript 내부에서도 입력을 동적 코드 실행 함수에 넘기지 않는다. 근거는 [actions/github-script 공식 README](https://github.com/actions/github-script/blob/main/README.md)의 입력 전달 안내다.

4. GITHUB_ENV에 기록할 때 생기는 후속 삽입 점검하기

환경변수로 안전하게 받은 값도 다음 단계로 옮기는 과정에서 다시 문제가 될 수 있다. 특히 GITHUB_ENV는 후속 단계의 환경변수를 정의하는 파일이므로, 외부 입력을 단순한 이름=값 형식으로 붙여 쓰는 코드를 살펴봐야 한다.

GitHub의 CodeQL 설명에는 PR 제목을 가공한 다중 행 값이 환경 파일에 기록되면서 추가 환경변수를 주입하는 사례가 나온다. 줄바꿈 뒤의 내용이 별도의 변수 정의로 해석될 수 있기 때문이다. 이는 최초의 셸 코드 삽입을 고쳤더라도 후속 데이터 전달 경로를 계속 검토해야 한다는 의미다. [GitHub의 워크플로 CodeQL 분석 설명](https://github.blog/security/application-security/how-to-secure-your-github-actions-workflows-with-codeql/)에서 해당 유형을 다룬다.

제목을 현재 단계에서만 사용한다면 단계의 env:에 두는 것이 가장 단순하다. 후속 단계로 전달해야 한다면 단일 행만 허용할지 먼저 정하고, 다중 행이 필요하면 GitHub 환경 파일 형식과 구분자 충돌 가능성을 검토해야 한다. 임의 텍스트는 파일로 보관하고 경로만 전달하는 설계도 고려할 수 있다.

💡 검토 팁: 입력이 처음 들어오는 줄부터 마지막 소비 지점까지 따라가면 놓치는 부분이 줄어든다. PR 제목 → 환경변수 → 가공 명령 → 환경 파일 → 후속 명령의 각 경계에서 값이 코드나 제어 형식으로 해석되는지 확인한다.

5. GITHUB_TOKEN 최소 권한과 액션 SHA 고정 설정하기

입력 처리 수정이 명령 실행 경로를 막는 작업이라면, 최소 권한은 다른 취약점이 남았을 때 피해 범위를 줄이는 작업이다. 앞선 제목 검사 예제는 GitHub API를 호출하지 않으므로 permissions: {}로 토큰 권한을 제한했다. 저장소 파일 읽기가 필요한 작업은 contents: read처럼 필요한 권한을 명시하고, 쓰기 권한은 실제로 사용하는 작업에만 부여한다.

PR 제목 검사를 위해 배포용 자격증명을 전달하거나 권한이 높은 실행 경로를 사용할 이유도 없다. 특히 pull_request_target을 사용하는 워크플로는 외부 PR의 코드 체크아웃과 실행 여부를 별도로 검토해야 한다. 토큰 권한 제한은 앞서 인용한 GitHub Secure use 문서에서도 권고하는 방어 수단이다.

2026년 운영 기준에서 함께 확인할 정책은 액션의 전체 커밋 SHA 고정이다. GitHub는 2025년 8월 15일 액션 차단과 SHA 고정 강제 정책 지원을 발표했다. 해당 정책을 활성화하면 전체 커밋 SHA로 고정하지 않은 액션을 사용하는 워크플로는 실패한다. 이는 2026년에 새로 발표된 기능이 아니라, 이미 제공된 통제를 현재 운영에 반영하는 항목이다. [GitHub 공식 변경 기록](https://github.blog/changelog/2025-08-15-github-actions-policy-now-supports-blocking-and-sha-pinning-actions/)에 발표 날짜와 동작이 명시되어 있다.

SHA 고정은 태그가 다른 커밋을 가리키도록 변경되는 위험을 줄인다. 다만 선택한 커밋 자체의 안전성을 보증하지 않으므로, 공식 저장소의 변경 내용과 업데이트 PR을 검토하는 절차도 필요하다.

보안 검토 관점에서 비밀키 스캐닝과 워크플로 입력 검사는 서로 다른 질문을 다룬다. 비밀키가 저장소에 남아 있는지 확인하는 것과, 외부 문자열이 러너의 실행 코드를 바꿀 수 있는지 확인하는 것은 별도의 검토다. 따라서 비밀키 탐지 결과가 깨끗하더라도 워크플로 YAML의 입력 경로는 직접 확인해야 한다.

6. PR 제목 보안 수정 후 적용할 검증 체크리스트

수정 후에는 정상 제목이 통과하는지와 특수문자가 포함된 제목을 데이터로 처리하는지 함께 확인한다. 검증은 비밀정보가 없고 권한을 제한한 테스트 환경에서 수행하며, 취약한 예제를 운영 워크플로에 추가해 재현하지 않는다.

  1. 직접 삽입 제거: run:과 script:에 PR 제목 표현식이 남아 있는지 확인한다.
  2. 입력 전달 확인: 단계의 env:에서 값을 받고 Bash 또는 JavaScript 변수로 읽는지 확인한다.
  3. 제목 수정 반영: PR 제목 변경 후에도 검사 단계가 다시 실행되는지 확인한다.
  4. 특수문자 처리: 공백·따옴표·세미콜론이 포함된 제목이 추가 명령 실행 없이 처리되는지 확인한다.
  5. 후속 경로 확인: 재실행 함수, 환경 파일, 출력 파일에 입력을 전달하는 부분을 검토한다.
  6. 권한과 의존성 확인: 불필요한 토큰 쓰기 권한을 없애고 외부 액션의 전체 커밋 SHA 고정을 확인한다.

이 주제의 우선순위는 복잡한 보안 도구 도입보다 명확하다. 먼저 PR 제목이 코드에 들어가는 지점을 없애고, 이후 전달 경로와 실행 권한을 좁혀야 한다. 입력을 받는 위치와 사용하는 위치가 분명한 워크플로는 코드 리뷰에서도 문제를 발견하기 쉽다.

가장 먼저 적용할 변경은 run: 속 제목 표현식을 단계의 env:로 옮기는 것이다. 여기에 셸 인용, 후속 환경 파일 검토, 토큰 최소 권한, 액션 SHA 고정을 이어 붙이면 PR 제목 처리부터 의존성 실행까지 일관된 보안 기준을 만들 수 있다.