# GitHub Actions에서 비밀 사용
워크플로에 대한 GitHub Actions 리포지토리, 환경 및 조직 수준에서 비밀을 만드는 방법을 알아봅니다.
## 리포지토리에 대한 비밀 만들기
조직 리포지토리에 대한 GitHub에 비밀 또는 변수를 만들려면 `write` 액세스 권한이 있어야 합니다. 개인 계정 리포지토리의 경우 리포지토리 공동 작업자여야 합니다.
1. GitHub에서 리포지토리의 기본 페이지로 이동합니다.
2. 리포지토리 이름 아래에서 ** Settings**를 클릭합니다. "설정" 탭이 표시되지 않으면 **** 드롭다운 메뉴를 선택한 다음 **설정**을 클릭합니다.
3. 사이드바의 "Security" 섹션에서 ** Secrets and variables**를 선택하고 **Actions**를 클릭합니다.
4. **비밀** 탭을 클릭합니다.
1. **새 리포지토리 비밀**을 선택합니다.
2. **이름** 필드에 비밀의 이름을 입력합니다.
3. **비밀** 필드에 비밀 값을 입력합니다.
4. **비밀 추가**를 클릭합니다.
리포지토리에 환경 비밀이 있거나 부모 조직의 비밀에 액세스할 수 있는 경우 해당 비밀도 이 페이지에 나열됩니다.
리포지토리 비밀을 추가하려면 `gh secret set` 하위 명령을 사용합니다.
`secret-name`을 비밀의 이름으로 바꿉니다.
```shell
gh secret set SECRET_NAME
```
CLI는 비밀 값을 입력하라는 메시지를 표시합니다. 또는 파일에서 비밀 값을 읽을 수 있습니다.
```shell
gh secret set SECRET_NAME < secret.txt
```
리포지토리에 대한 모든 비밀을 나열하려면 `gh secret list` 하위 명령을 사용합니다.
## 환경에 대한 비밀 만들기
개인 계정 리포지토리에서 환경에 대한 비밀 또는 변수를 만들려면 리포지토리 소유자여야 합니다. 조직 리포지토리에서 환경에 대한 비밀 또는 변수를 만들려면 `admin` 액세스 권한이 있어야 합니다. 환경에 대한 자세한 내용은 [배포 환경 관리](/ko/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)을(를) 참조하세요.
1. GitHub에서 리포지토리의 기본 페이지로 이동합니다.
2. 리포지토리 이름 아래에서 ** Settings**를 클릭합니다. "설정" 탭이 표시되지 않으면 **** 드롭다운 메뉴를 선택한 다음 **설정**을 클릭합니다.
3. 왼쪽 사이드바에서 **환경**을 클릭합니다.
4. 비밀을 추가할 환경을 클릭합니다.
5. **환경 비밀**에서 **비밀 추가**를 클릭합니다.
6. **이름** 입력 상자에 비밀의 이름을 입력합니다.
7. 비밀 값을 입력합니다.
8. **비밀 추가**를 클릭합니다.
환경에 대한 비밀을 추가하려면 환경 이름 뒤에 `gh secret set`또는 `--env` 플래그가 있는 `-e` 하위 명령을 사용합니다.
```shell
gh secret set --env ENV_NAME SECRET_NAME
```
환경에 대한 비밀을 나열하려면 환경 이름 뒤에 `gh secret list`또는 `--env` 플래그가 있는 `-e` 하위 명령을 사용합니다.
```shell
gh secret list --env ENV_NAME
```
## 조직에 대한 비밀 만들기
> \[!NOTE]
> 조직 수준 비밀 및 변수는 프라이빗 리포지 GitHub Free토리에서 액세스할 수 없습니다. 구독 업그레이드에 대한 자세한 내용은 [계정 요금제 업그레이드하기](/ko/billing/how-tos/manage-plan-and-licenses/upgrade-plan)을 참조하세요GitHub.
조직에서 비밀 또는 변수를 만들 때, 정책을 사용하여 리포지토리별로 액세스를 제한할 수 있습니다. 예를 들어 모든 리포지토리에 대한 액세스 권한을 부여하거나 프라이빗 리포지토리 또는 지정된 리포지토리 목록에 대해서만 액세스를 제한할 수 있습니다.
조직 소유자는 조직 수준에서 비밀 또는 변수를 만들 수 있습니다.
1. GitHub에서 조직의 기본 페이지로 이동합니다.
2. 조직 이름에서 ** 설정**을 클릭합니다. "설정" 탭이 표시되지 않으면 **** 드롭다운 메뉴를 선택한 다음 **설정**을 클릭합니다.
3. 사이드바의 "Security" 섹션에서 ** Secrets and variables**를 선택하고 **Actions**를 클릭합니다.
4. **비밀** 탭을 클릭합니다.
5. **새 조직 비밀**을 클릭합니다.
6. **이름** 입력 상자에 비밀의 이름을 입력합니다.
7. **값** 필드에 비밀 값을 입력합니다.
8. **리포지토리 액세스** 드롭다운 목록에서 액세스 정책을 선택합니다.
9. **비밀 추가**를 클릭합니다.
> \[!NOTE]
> 기본적으로 GitHub CLI은/는 `repo` 및 `read:org` 범위로 인증합니다. 조직 비밀을 관리하려면 `admin:org` 범위에 추가로 권한을 부여해야 합니다.
>
> ```shell
> gh auth login --scopes "admin:org"
> ```
조직에 대한 비밀을 추가하려면 조직 이름 뒤에 `gh secret set` 또는 `--org` 플래그가 있는 `-o` 하위 명령을 사용합니다.
```shell
gh secret set --org ORG_NAME SECRET_NAME
```
기본적으로 비밀은 프라이빗 리포지토리에서만 사용할 수 있습니다. 조직 내의 모든 리포지토리에서 비밀을 사용할 수 있도록 지정하려면 `--visibility` 또는 `-v` 플래그를 사용합니다.
```shell
gh secret set --org ORG_NAME SECRET_NAME --visibility all
```
조직 내의 선택된 리포지토리에서 비밀을 사용할 수 있도록 지정하려면 `--repos` 또는 `-r` 플래그를 사용합니다.
```shell
gh secret set --org ORG_NAME SECRET_NAME --repos REPO-NAME-1, REPO-NAME-2
```
조직에 대한 비밀을 나열하려면 조직 이름 뒤에 `gh secret list` 또는 `--org` 플래그가 있는 `-o` 하위 명령을 사용합니다.
```shell
gh secret list --org ORG_NAME
```
## 조직 수준 비밀에 대한 액세스 검토
조직의 비밀에 적용되는 액세스 정책을 확인할 수 있습니다.
1. GitHub에서 조직의 기본 페이지로 이동합니다.
2. 조직 이름에서 ** 설정**을 클릭합니다. "설정" 탭이 표시되지 않으면 **** 드롭다운 메뉴를 선택한 다음 **설정**을 클릭합니다.
3. 사이드바의 "Security" 섹션에서 ** Secrets and variables**를 선택하고 **Actions**를 클릭합니다.
4. 비밀 목록에는 구성된 사용 권한 및 정책이 포함됩니다. 각 비밀에 대해 구성된 권한에 대한 자세한 내용을 보려면 **업데이트**를 클릭하세요.
## 워크플로에서 비밀 사용
> \[!NOTE]
>
> * `GITHUB_TOKEN`의 예외를 제외하고 포크된 리포지토리에서 워크플로가 트리거될 때 비밀이 실행기에게 전달되지 않습니다.
> * 비밀은 재사용 가능한 워크플로에 자동으로 전달되지 않습니다. 자세한 내용은 [워크플로 재사용](/ko/actions/how-tos/reuse-automations/reuse-workflows#passing-inputs-and-secrets-to-a-reusable-workflow)을(를) 참조하세요.
> * 이벤트에 의해 Dependabot 트리거되는 워크플로에는 비밀을 사용할 수 없습니다. 자세한 내용은 [GitHub Actions의 Dependabot 문제 해결](/ko/code-security/reference/supply-chain-security/troubleshoot-dependabot/dependabot-on-actions#accessing-secrets)을(를) 참조하세요.
> * GitHub Actions 워크플로가 OIDC(OpenID Connect)를 지원하는 클라우드 공급자의 리소스에 액세스해야 하는 경우 클라우드 공급자에 직접 인증하도록 워크플로를 구성할 수 있습니다. 이렇게 하면 이러한 자격 증명을 수명이 긴 비밀로 저장하지 않을 수 있고 다른 보안 이점을 제공할 수 있습니다. 자세한 내용은 [OpenID Connect](/ko/actions/concepts/security/openid-connect)을(를) 참조하세요.
> \[!WARNING] 를 사용하여 GitHub비밀이 아닌 `::add-mask::VALUE` 모든 중요한 정보를 마스킹합니다. 이렇게 하면 값이 비밀로 처리되고 로그에서 수정됩니다.
입력 또는 환경 변수로 비밀을 사용하여 작업을 제공하려면 `secrets` 컨텍스트를 사용하여 리포지토리에서 만든 비밀에 액세스할 수 있습니다. 자세한 내용은 [문맥 참조](/ko/actions/reference/workflows-and-actions/contexts) 및 [GitHub Actions에 대한 워크플로 구문](/ko/actions/reference/workflows-and-actions/workflow-syntax)을(를) 참조하세요.
```yaml
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:` 조건에서 직접 참조할 수 없습니다. 대신 비밀을 작업 수준 환경 변수로 설정한 다음 환경 변수를 참조하여 작업의 단계를 조건부로 실행하는 것이 좋습니다. 자세한 내용은 [문맥 참조](/ko/actions/reference/workflows-and-actions/contexts#context-availability) 및 [`jobs..steps[*].if`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsif)을(를) 참조하세요.
비밀을 설정하지 않은 경우 예제와 같이 `${{ secrets.SuperSecret }}` 비밀을 참조하는 식의 반환 값은 빈 문자열이 됩니다.
가능하면 명령줄에서 프로세스 간에 비밀을 전달하지 마세요. 명령줄 프로세스는 다른 사용자에게 표시되거나(`ps` 명령을 사용) [보안 감사 이벤트](https://docs.microsoft.com/windows-server/identity/ad-ds/manage/component-updates/command-line-process-auditing)에 의해 캡처될 수 있습니다. 비밀을 보호하려면 환경 변수, `STDIN` 또는 대상 프로세스에서 지원하는 기타 메커니즘을 사용하는 것이 좋습니다.
명령줄 내에서 비밀을 전달해야 한다면, 적절한 따옴표 규칙을 준수하여 묶으십시오. 비밀에는 의도치 않게 셸에 영향을 줄 수 있는 특수 문자가 포함되어 있는 경우가 많습니다. 특수 문자를 이스케이프하려면 환경 변수와 함께 따옴표를 사용합니다. 예시:
### Bash를 사용한 예제
```yaml
steps:
- shell: bash
env:
SUPER_SECRET: ${{ secrets.SuperSecret }}
run: |
example-command "$SUPER_SECRET"
```
### PowerShell을 사용한 예제
```yaml
steps:
- shell: pwsh
env:
SUPER_SECRET: ${{ secrets.SuperSecret }}
run: |
example-command "$env:SUPER_SECRET"
```
### Cmd.exe를 사용한 예제
```yaml
steps:
- shell: cmd
env:
SUPER_SECRET: ${{ secrets.SuperSecret }}
run: |
example-command "%SUPER_SECRET%"
```
## 큰 비밀 저장
48KB보다 큰 비밀을 사용하려면 해결 방법을 사용하여 리포지토리에 비밀을 저장하고 암호 해독 암호를 비밀 GitHub로 저장할 수 있습니다. 예를 들어, `gpg`를 사용하여 비밀이 포함된 파일을 로컬에서 암호화한 후, 암호화된 파일을 GitHub의 리포지토리에 체크 인할 수 있습니다. 자세한 내용은 [gpg manpage](https://www.gnupg.org/gph/de/manual/r1023.html)를 참조하세요.
> \[!WARNING]
> 워크플로가 실행될 때 비밀이 인쇄되지 않도록 주의하세요. 이 해결 방법을 GitHub 사용하는 경우 로그에 인쇄된 비밀을 수정하지 않습니다.
1. 터미널에서 다음 명령을 실행하여 `gpg` 및 AES256 암호 알고리즘을 사용하여 암호가 포함된 파일을 암호화합니다. 이 예제에서 `my_secret.json`은 비밀을 포함하는 파일입니다.
```shell
gpg --symmetric --cipher-algo AES256 my_secret.json
```
2. 암호 문구를 입력하라는 메시지가 표시됩니다. 암호 구문을 기억하세요. 암호 구문을 값으로 사용하는 새 비밀을 GitHub에서 만들어야 합니다.
3. 암호를 포함하는 새 비밀을 만듭니다. 예를 들어 `LARGE_SECRET_PASSPHRASE`라는 이름으로 새 비밀을 만들고 비밀 값을 위 단계에서 사용한 암호로 설정합니다.
4. 암호화된 파일을 리포지토리의 경로에 복사하고 커밋합니다. 이 예제에서 암호화된 파일은 `my_secret.json.gpg`입니다.
> \[!WARNING]
> 암호화된 `my_secret.json.gpg` 파일을 `.gpg` 파일 확장자로 끝나는 파일로 복사하고, 암호화되지 않은 \*\*\*\* 파일은 복사하지 마십시오.
```shell
git add my_secret.json.gpg
git commit -m "Add new secret JSON file"
```
5. 리포지토리에서 비밀 파일의 암호를 해독하는 셸 스크립트를 만듭니다. 이 예제에서 스크립트 이름은 `decrypt_secret.sh`입니다.
```shell copy
#!/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. 리포지토리에 체크 인하기 전에 셸 스크립트가 실행 가능한지 확인합니다.
```shell
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`](https://github.com/actions/checkout) 작업을 사용해야 합니다. 리포지토리 루트에 대해 `run` 명령을 사용하여 셸 스크립트를 참조하세요.
```yaml
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 이진 블롭을 비밀 데이터로 저장
Base64 인코딩을 사용하여 작은 이진 BLOB을 비밀로 저장할 수 있습니다. 그런 다음 워크플로에서 비밀을 참조하고 실행기에서 사용하기 위해 디코딩할 수 있습니다. 크기 제한에 대해서는 [시크릿 참조](/ko/actions/reference/security/secrets#limits-for-secrets)을(를) 참조하세요.
> \[!NOTE]
>
> * Base64는 이진 파일만 텍스트로 변환하며 실제 암호화를 대체할 수 없습니다.
> * 다른 셸을 사용하면 비밀을 파일로 디코딩하기 위해 다른 명령이 필요할 수 있습니다. Windows 실행기에서는 위의 [](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsshell) 단계의 명령을 사용하기 위해 `shell: bash`과 함께 `run`을 권장합니다.
1. 파일을 Base64 문자열로 인코딩하는 데 `base64`를 사용합니다. 예시:
macOS에서는 다음을 실행할 수 있습니다.
```shell
base64 -i cert.der -o cert.base64
```
Linux에서는 다음을 실행할 수 있습니다.
```shell
base64 -w 0 cert.der > cert.base64
```
2. Base64 문자열을 포함하는 비밀을 만듭니다. 예시:
```shell
$ gh secret set CERTIFICATE_BASE64 < cert.base64
✓ Set secret CERTIFICATE_BASE64 for octocat/octorepo
```
3. 실행기에서 Base64 문자열에 액세스하려면 비밀을 `base64 --decode`으로 파이프합니다. 예시:
```yaml
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
```
## 다음 단계
참조 정보는 [시크릿 참조](/ko/actions/reference/security/secrets)을(를) 참조하세요.