GitHub Actions Secret이 빈 값일 때 원인 5가지와 안전한 확인법

GitHub Actions 실행 기록은 생겼지만 인증 단계에서 401, 필수 입력 누락,
빈 환경 변수 같은 오류가 난다면 Secret 값을 다시 출력하지 말고 전달 여부만
검사하는 단계를 먼저 추가하세요. 검사 결과가 비어 있다면 저장 위치,
실행 이벤트, environment 연결, 재사용 workflow 전달 순서로 확인하면 됩니다.

먼저 Secret 값을 노출하지 않고 전달 여부만 확인하세요

GitHub는 설정되지 않은 Secret을 참조하면 오류 대신 빈 문자열을 반환합니다.
따라서 배포 명령을 바로 실행하면 Secret 문제인지 외부 서비스 문제인지 구분하기
어렵습니다. GitHub의 Secret 사용 문서는
설정되지 않은 Secret 표현식이 빈 문자열을 반환한다고 명시합니다.

Ubuntu runner에서는 배포 단계 앞에 다음 검사를 넣을 수 있습니다.

- name: Check required secret
  shell: bash
  env:
    DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
  run: |
    if [ -z "$DEPLOY_TOKEN" ]; then
      echo "::error::DEPLOY_TOKEN is unavailable in this run"
      exit 1
    fi
    echo "DEPLOY_TOKEN is available"

Windows runner에서 PowerShell을 사용한다면 검사 부분만 다음처럼 바꿉니다.

- name: Check required secret
  shell: pwsh
  env:
    DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
  run: |
    if ([string]::IsNullOrEmpty($env:DEPLOY_TOKEN)) {
      Write-Error "DEPLOY_TOKEN is unavailable in this run"
      exit 1
    }
    Write-Output "DEPLOY_TOKEN is available"

두 예시는 Secret의 실제 값이나 길이를 출력하지 않습니다. echo
"$DEPLOY_TOKEN", Write-Output $env:DEPLOY_TOKEN, env처럼 환경 변수
전체를 로그에 쓰는 명령은 진단용으로도 사용하지 마세요. GitHub의 자동 마스킹이
있어도 변형된 값이나 별도로 만든 민감 정보까지 항상 가려진다고 가정해서는
안 됩니다.

증상으로 원인을 먼저 좁히세요

확인 결과	가능성이 큰 원인	다음 확인
모든 실행에서 검사 단계가 실패	Secret 이름 또는 저장 범위 불일치	저장소·조직·environment Secret 목록
직접 push에서는 통과하고 외부 PR에서 실패	fork PR의 보안 제한	실행 이벤트와 PR 출처
일반 PR은 통과하고 Dependabot PR만 실패	Actions Secret 대신 Dependabot Secret이 필요	실행 주체와 Dependabot 설정
일반 workflow에서는 통과하고 재사용 workflow에서 실패	호출 workflow가 Secret을 전달하지 않음	jobs.<job_id>.secrets
같은 job도 environment 지정 여부에 따라 달라짐	environment Secret 범위 또는 같은 이름의 우선순위	jobs.<job_id>.environment
workflow가 시작되기 전에 문법 오류가 남	if:에서 secrets를 직접 참조	env로 옮긴 뒤 step 조건에서 검사

원인 1. Secret을 다른 범위에 저장했습니다

Actions Secret은 저장소, environment, 조직 수준에 만들 수 있지만 접근 범위가
서로 다릅니다.

• 저장소 Secret: 해당 저장소의 workflow에서 사용
• environment Secret: 그 environment를 참조하는 job에서만 사용
• 조직 Secret: 조직에서 접근을 허용한 저장소에서만 사용

이 구분은 GitHub Secret 유형 문서에
정리되어 있습니다. 먼저 workflow가 있는 저장소에서 다음 경로를 엽니다.

Repository
→ Settings
→ Secrets and variables
→ Actions
→ Secrets

목록에서 DEPLOY_TOKEN이라는 이름이 존재하는지만 확인하세요. GitHub는
저장한 값을 다시 보여주지 않으므로, 값이 의심되면 기존 값을 알아내려 하지
말고 발급처에서 새 자격 증명을 만든 뒤 Secret을 갱신하는 편이 안전합니다.

조직 Secret이라면 조직 설정의 Repository access에 현재 저장소가 포함됐는지
확인해야 합니다. 2026년 7월 26일 기준 GitHub 공식 문서는 GitHub Free에서
조직 수준 Secret과 변수를 비공개 저장소가 사용할 수 없다고 안내합니다.
현재 조건은 GitHub의 조직 Secret 안내에서
다시 확인하세요.

원인 2. environment Secret인데 job이 environment를 참조하지 않습니다

production environment에 만든 Secret은 이름이 같더라도 일반 job에 자동으로
전달되지 않습니다. 배포 job이 해당 environment를 명시해야 합니다.

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Check required secret
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          test -n "$DEPLOY_TOKEN" || {
            echo "::error::DEPLOY_TOKEN is unavailable in this run"
            exit 1
          }

또한 같은 이름의 조직, 저장소, environment Secret이 모두 있으면 더 낮은
범위가 우선합니다. 즉 environment Secret이 저장소 Secret보다 우선합니다.
Secret을 읽는 시점과 우선순위는
GitHub Secrets 참고 문서에
정리되어 있습니다.

원인 3. fork PR 또는 Dependabot 이벤트에서 실행됐습니다

외부 fork에서 온 pull request가 workflow를 실행하면 GITHUB_TOKEN을 제외한
Secret은 runner에 전달되지 않습니다. 이는 오타가 아니라 외부 코드가
자격 증명을 읽지 못하게 하는 보안 경계입니다.

Dependabot이 만든 이벤트에도 일반 Actions Secret은 제공되지 않습니다.
GitHub의 Dependabot Actions 제한 문서에
따르면 이런 실행에서는 Dependabot Secret이 사용되고 GITHUB_TOKEN 권한도
기본적으로 읽기 전용입니다.

이 경우에는 다음처럼 설계를 나누세요.

1. 외부 PR과 Dependabot PR에서는 Secret이 필요 없는 빌드·정적 검사만 실행
2. 실제 배포는 신뢰할 수 있는 브랜치에 병합된 뒤 별도 workflow에서 실행
3. Dependabot이 비공개 레지스트리에 접근해야 한다면 같은 이름의 Dependabot
   Secret을 별도로 설정

Secret을 받기 위해 검토되지 않은 PR 코드를 pull_request_target에서
checkout해 실행하는 방식은 권한 상승 위험이 있으므로 단순 해결책으로 바꾸지
마세요.

원인 4. 재사용 workflow에 Secret을 전달하지 않았습니다

재사용 workflow는 호출했다고 해서 caller의 Secret을 자동으로 받지 않습니다.
호출하는 job에서 명시적으로 매핑하거나 같은 조직·엔터프라이즈 범위에서
secrets: inherit를 사용해야 합니다.

호출하는 workflow:

jobs:
  call-deploy:
    uses: ./.github/workflows/deploy.yml
    secrets:
      deploy_token: ${{ secrets.DEPLOY_TOKEN }}

호출되는 .github/workflows/deploy.yml:

on:
  workflow_call:
    secrets:
      deploy_token:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check required secret
        shell: bash
        env:
          DEPLOY_TOKEN: ${{ secrets.deploy_token }}
        run: |
          test -n "$DEPLOY_TOKEN" || {
            echo "::error::deploy_token is unavailable"
            exit 1
          }

여러 단계로 재사용 workflow가 이어질 때도 Secret은 직접 호출한 다음
workflow까지만 전달됩니다. A가 B에 전달하고 B가 C를 호출한다면 B도 C에
다시 전달해야 합니다. 자세한 매핑 규칙은
GitHub의 재사용 workflow 문서에서
확인할 수 있습니다.

원인 5. if:에서 secrets를 직접 검사했습니다

GitHub Actions는 if: 조건에서 secrets를 직접 참조하는 방식을 지원하지
않습니다. Secret을 job의 환경 변수로 옮긴 뒤 step 조건에서 환경 변수를
검사해야 합니다.

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    steps:
      - name: Deploy only when the secret is available
        if: ${{ env.DEPLOY_TOKEN != '' }}
        run: ./deploy.sh

배포에 반드시 필요한 Secret이라면 조건으로 조용히 건너뛰기보다 글 앞의
Check required secret 단계처럼 명확한 오류를 남기고 실패시키는 편이
원인을 찾기 쉽습니다. 선택 기능에만 필요한 Secret일 때는 조건부 실행이
적합합니다.

Secret 문제를 고친 뒤에도 인증이 실패한다면

검사 단계가 available로 통과했는데 외부 서비스가 401 또는 403을
반환한다면 이제 빈 값 문제가 아니라 자격 증명의 유효성·권한·대상 환경을
확인해야 합니다.

• 토큰이 만료되거나 발급처에서 폐기되지 않았는지
• 테스트용과 운영용 서비스 주소를 혼동하지 않았는지
• 필요한 최소 권한이 토큰에 포함됐는지
• Secret을 갱신한 뒤 새 workflow 실행으로 확인했는지

이때도 값을 로그에 출력해 비교하지 마세요. 자격 증명을 새로 발급하고 Secret을
갱신한 뒤, 값이 아닌 API의 성공·실패 상태로 확인합니다.

별도 테스트 저장소의 Ubuntu 및 Windows runner에서 Secret 이름, 재사용
workflow 매핑, environment 지정 여부에 따른 동작을 확인했으며, 검사
과정에서 Secret 값은 로그에 출력하지 않았습니다.

정리

GitHub Actions Secret이 빈 값이라면 먼저 값 노출 없는 검사 단계로 증상을
확정하세요. 그다음 저장 범위, environment 연결, fork·Dependabot 이벤트,
재사용 workflow 매핑, if: 사용 순서로 확인하면 원인을 구분할 수 있습니다.

실행 자체가 만들어지지 않았다면 Secret보다 workflow 트리거를 먼저 진단해야
합니다. 이 경우에는 GitHub Actions가 push 후 실행되지 않을 때 확인할
7가지부터
확인하세요.