GitHub Actions에서 시크릿(Secret) 사용하기

GitHub Actions에서 시크릿(Secret) 사용하기

저장소·환경·조직 레벨에서 GitHub Actions 워크플로용 시크릿을 만드는 방법을 알려드릴게요. 시크릿만 제대로 관리해도 워크플로 보안의 절반은 잡은 셈이에요.

출처: 문서

본문

GitHub Actions 워크플로용 시크릿을 저장소, 환경, 조직 레벨에서 만드는 방법을 알아봅니다.

저장소용 시크릿 만들기

GitHub에서 조직 저장소에 시크릿이나 변수를 만들려면 write 권한이 있어야 합니다. 개인 계정 저장소라면 저장소 협업자(collaborator)여야 합니다.

gh secret set SECRET_NAME

gh secret set SECRET_NAME < secret.txt

환경용 시크릿 만들기

개인 계정 저장소의 환경에 시크릿이나 변수를 만들려면 저장소 소유자여야 합니다. 조직 저장소의 환경에 시크릿이나 변수를 만들려면 admin 권한이 있어야 합니다. 환경에 대한 자세한 내용은 Managing environments for deployment를 참고하세요.

gh secret set --env ENV_NAME SECRET_NAME

gh secret list --env ENV_NAME

조직용 시크릿 만들기

[!NOTE] 조직 레벨의 시크릿과 변수는 GitHub Free에서 비공개 저장소가 접근할 수 없습니다. GitHub 구독을 업그레이드하는 방법에 대한 자세한 내용은 Upgrading your account's plan을 참고하세요.

조직에서 시크릿이나 변수를 만들 때 정책을 사용해서 저장소별 접근을 제한할 수 있습니다. 예를 들어 모든 저장소에 접근을 허용하거나, 비공개 저장소만, 또는 지정된 저장소 목록으로만 제한할 수 있습니다.

조직 소유자는 조직 레벨에서 시크릿이나 변수를 만들 수 있습니다.

gh secret set --org ORG_NAME SECRET_NAME

gh secret set --org ORG_NAME SECRET_NAME --visibility all

gh secret set --org ORG_NAME SECRET_NAME --repos REPO-NAME-1, REPO-NAME-2

gh secret list --org ORG_NAME

조직 레벨 시크릿에 대한 접근 검토하기

조직에서 시크릿에 적용되는 접근 정책을 확인할 수 있습니다.

1. GitHub에서 조직의 메인 페이지로 이동합니다.

2. 조직 이름 아래에서 Settings를 클릭합니다.

   

3. 사이드바의 "Security" 섹션에서 Secrets and variables를 선택한 다음 Actions를 클릭합니다.

4. 시크릿 목록에는 구성된 권한과 정책이 포함되어 있습니다. 각 시크릿에 대해 구성된 권한에 대한 자세한 내용을 보려면 Update를 클릭합니다.

워크플로에서 시크릿 사용하기

[!NOTE]

• GITHUB_TOKEN을 제외하고, 시크릿은 포크된 저장소에서 워크플로가 트리거될 때 러너로 전달되지 않습니다.
• 시크릿은 재사용 가능한 워크플로(reusable workflow)에 자동으로 전달되지 않습니다. 자세한 내용은 Reuse workflows를 참고하세요.
• 시크릿은 Dependabot 이벤트로 트리거되는 워크플로에서는 사용할 수 없습니다. 자세한 내용은 Troubleshooting Dependabot on GitHub Actions를 참고하세요.
• GitHub Actions 워크플로가 OIDC(OpenID Connect)를 지원하는 클라우드 공급자의 리소스에 접근해야 한다면, 워크플로가 클라우드 공급자에 직접 인증하도록 구성할 수 있습니다. 그러면 이러한 자격 증명을 장기 유효 시크릿으로 저장하지 않아도 되고 다른 보안상 이점도 얻을 수 있습니다. 자세한 내용은 OpenID Connect를 참고하세요.

[!WARNING] GitHub 시크릿이 아닌 민감 정보는 ::add-mask::VALUE를 사용해서 모두 마스크 처리하세요. 이렇게 하면 해당 값이 시크릿으로 취급되어 로그에서 가려집니다.

액션에 시크릿을 입력(input)이나 환경 변수로 제공하려면, 저장소에 만든 시크릿에 접근하기 위해 secrets 컨텍스트를 사용할 수 있습니다. 자세한 내용은 Contexts reference와 Workflow syntax for GitHub Actions를 참고하세요.

steps:
  - name: Hello world action
    with: # Set the secret as an input
      super_secret: ${{ secrets.SuperSecret }}
    env: # Or as an environment variable
      super_secret: ${{ secrets.SuperSecret }}

시크릿은 if: 조건에서 직접 참조할 수 없습니다. 대신 시크릿을 잡 레벨 환경 변수로 설정한 다음, 그 환경 변수를 참조해서 잡의 스텝을 조건부로 실행하는 방법을 고려하세요. 자세한 내용은 Contexts reference와 jobs.<job_id>.steps[*].if를 참고하세요.

시크릿이 설정되어 있지 않으면 해당 시크릿을 참조하는 표현식(예: 위 예시의 ${{ secrets.SuperSecret }})의 반환값은 빈 문자열이 됩니다.

가능하면 명령줄에서 프로세스 간에 시크릿을 전달하지 마세요. 명령줄 프로세스는 다른 사용자(ps 명령 사용)에게 보이거나 보안 감사 이벤트에 포착될 수 있습니다. 시크릿을 보호하려면 환경 변수, STDIN, 또는 대상 프로세스가 지원하는 다른 메커니즘을 사용하는 것을 고려하세요.

명령줄 안에서 시크릿을 전달해야 한다면 적절한 따옴표 규칙 안에 넣으세요. 시크릿에는 셸에 의도치 않게 영향을 줄 수 있는 특수 문자가 포함되는 경우가 많습니다. 이런 특수 문자를 이스케이프하려면 환경 변수에 따옴표를 사용하세요. 예를 들어:

Bash를 사용하는 예시

steps:
  - shell: bash
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$SUPER_SECRET"

PowerShell을 사용하는 예시

steps:
  - shell: pwsh
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "$env:SUPER_SECRET"

Cmd.exe를 사용하는 예시

steps:
  - shell: cmd
    env:
      SUPER_SECRET: ${{ secrets.SuperSecret }}
    run: |
      example-command "%SUPER_SECRET%"

대용량 시크릿 저장하기

48KB보다 큰 시크릿을 사용하려면, 저장소에 시크릿을 저장하고 복호화 비밀번호(passphrase)를 GitHub에 시크릿으로 저장하는 우회 방법을 사용할 수 있습니다. 예를 들어 gpg로 시크릿이 들어 있는 파일을 로컬에서 암호화한 다음, 암호화된 파일을 GitHub 저장소에 커밋할 수 있습니다. 자세한 내용은 gpg manpage를 참고하세요.

[!WARNING] 워크플로가 실행될 때 시크릿이 출력되지 않도록 주의하세요. 이 우회 방법을 사용하면 GitHub가 로그에 출력된 시크릿을 가려주지 않습니다.

1. 터미널에서 다음 명령을 실행해서 gpg와 AES256 암호 알고리즘으로 시크릿이 들어 있는 파일을 암호화합니다. 이 예시에서 my_secret.json이 시크릿이 들어 있는 파일입니다.

   gpg --symmetric --cipher-algo AES256 my_secret.json
   

2. 비밀번호를 입력하라는 프롬프트가 표시됩니다. 이 비밀번호를 기억해 두세요. GitHub에서 이 비밀번호를 값으로 사용하는 새 시크릿을 만들어야 하기 때문입니다.

3. 비밀번호가 들어 있는 새 시크릿을 만듭니다. 예를 들어 LARGE_SECRET_PASSPHRASE라는 이름의 새 시크릿을 만들고, 그 값에 위 단계에서 사용한 비밀번호를 설정합니다.

4. 암호화된 파일을 저장소의 경로에 복사하고 커밋합니다. 이 예시에서 암호화된 파일은 my_secret.json.gpg입니다.

   [!WARNING] .gpg 확장자로 끝나는 암호화된 my_secret.json.gpg 파일을 복사해야 하며, 암호화되지 않은 my_secret.json 파일을 복사하면 안 됩니다.

   git add my_secret.json.gpg
   git commit -m "Add new secret JSON file"
   

5. 저장소에 시크릿 파일을 복호화하는 셸 스크립트를 만듭니다. 이 예시에서 스크립트 이름은 decrypt_secret.sh입니다.

   #!/bin/sh
   
   # Decrypt the file
   mkdir $HOME/secrets
   # --batch to prevent interactive command
   # --yes to assume "yes" for questions
   gpg --quiet --batch --yes --decrypt --passphrase="$LARGE_SECRET_PASSPHRASE" \
   --output $HOME/secrets/my_secret.json my_secret.json.gpg
   

6. 저장소에 커밋하기 전에 셸 스크립트가 실행 가능한지 확인합니다.

   chmod +x decrypt_secret.sh
   git add decrypt_secret.sh
   git commit -m "Add new decryption script"
   git push
   

7. GitHub Actions 워크플로에서 step을 사용해서 셸 스크립트를 호출하고 시크릿을 복호화합니다. 워크플로가 실행되는 환경에 저장소의 복사본을 가지려면 actions/checkout 액션을 사용해야 합니다. 저장소 루트를 기준으로 run 명령을 사용해서 셸 스크립트를 참조합니다.

   name: Workflows with large secrets
   
   on: push
   
   jobs:
     my-job:
       name: My Job
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v6
         - name: Decrypt large secret
           run: ./decrypt_secret.sh
           env:
             LARGE_SECRET_PASSPHRASE: ${{ secrets.LARGE_SECRET_PASSPHRASE }}
         # This command is just an example to show your secret being printed
         # Ensure you remove any print statements of your secrets. GitHub does
         # not hide secrets that use this workaround.
         - name: Test printing your secret (Remove this step in production)
           run: cat $HOME/secrets/my_secret.json
   

Base64 바이너리 blob을 시크릿으로 저장하기

Base64 인코딩을 사용해서 작은 바이너리 blob을 시크릿으로 저장할 수 있습니다. 그다음 워크플로에서 시크릿을 참조하고 러너에서 사용할 수 있도록 디코딩하면 됩니다. 크기 제한에 대해서는 Secrets reference를 참고하세요.

[!NOTE]

• Base64는 바이너리를 텍스트로 변환할 뿐이며 실제 암호화를 대체하지 않는다는 점에 유의하세요.
• 다른 셸을 사용하면 시크릿을 파일로 디코딩하는 명령이 달라질 수 있습니다. Windows 러너에서는 위 run 스텝의 명령을 사용하려면 shell: bash로 bash 셸을 사용하는 것을 권장합니다.

1. base64를 사용해서 파일을 Base64 문자열로 인코딩합니다. 예를 들어:

   macOS에서는 다음과 같이 실행할 수 있습니다:

   base64 -i cert.der -o cert.base64
   

   Linux에서는 다음과 같이 실행할 수 있습니다:

   base64 -w 0 cert.der > cert.base64
   

2. Base64 문자열이 들어 있는 시크릿을 만듭니다. 예를 들어:

   $ gh secret set CERTIFICATE_BASE64 < cert.base64
   ✓ Set secret CERTIFICATE_BASE64 for octocat/octorepo
   

3. 러너에서 Base64 문자열에 접근하려면 시크릿을 base64 --decode로 파이프합니다. 예를 들어:

   name: Retrieve Base64 secret
   on:
     push:
       branches: [ octo-branch ]
   jobs:
     decode-secret:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v6
         - name: Retrieve the secret and decode it to a file
           env:
             CERTIFICATE_BASE64: ${{ secrets.CERTIFICATE_BASE64 }}
           run: |
             echo $CERTIFICATE_BASE64 | base64 --decode > cert.der
         - name: Show certificate information
           run: |
             openssl x509 -in cert.der -inform DER -text -noout
   

다음 단계

참고 자료는 Secrets reference를 참고하세요.

더 알아보기 (Learn more)

• Secrets reference
• Contexts reference
• Workflow syntax for GitHub Actions