# 在 GitHub Actions 中使用机密
了解如何在 GitHub Actions 工作流的存储库、环境和组织级别创建机密。
## 为存储库创建机密
要在 GitHub 上为组织存储库创建机密或变量，你必须拥有 `write` 访问权限。对于个人帐户存储库，你必须是存储库协作者。
若要添加存储库机密，请使用 `gh secret set` 子命令。 将 `secret-name` 替换为机密的名称。
```shell
gh secret set SECRET_NAME
```
CLI 将提示您输入一个机密值。 或者，您可以从文件中读取机密的值。
```shell
gh secret set SECRET_NAME < secret.txt
```
若要列出存储库的所有机密，请使用 `gh secret list` 子命令。
## 为环境创建机密
要为个人帐户存储库中的环境创建密码或变量，你必须是存储库所有者。 要为组织存储库中的环境创建密码或变量，必须具有 `admin` 访问权限。 有关环境的详细信息，请参阅“[管理部署环境](/zh/actions/deployment/targeting-different-environments/managing-environments-for-deployment)”。
若要为环境添加机密，请使用 `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 的专用存储库无法访问组织级机密和变量。 有关升级 GitHub 订阅的详细信息，请参阅 [升级您的帐户套餐](/zh/billing/managing-billing-for-your-github-account/upgrading-your-github-subscription)。
在组织中创建机密或变量时，可以使用策略来限制存储库的访问。 例如，您可以将访问权限授予所有仓库，也可以限制仅私有仓库或指定的仓库列表拥有访问权限。
组织所有者可以在组织级别创建机密或变量。
> \[!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. 在组织名称下，单击 “Settings”\*\*\*\*。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”\*\*\*\*\*\*\*\*。
3. 在边栏的“Security”部分中，选择“ Secrets and variables”，然后单击“Actions”\*\*\*\*\*\*\*\*。
4. 密码列表包括任何已配置的权限和策略。 若要详细了解已为每个机密配置的权限，请单击“更新”。
## 在工作流中使用机密
> \[!NOTE]
>
> * 除 `GITHUB_TOKEN` 外，当从分支存储库触发工作流时，机密不会传递给运行器。
> * 机密不会自动传递到可重用工作流。 有关详细信息，请参阅“[重用工作流](/zh/actions/using-workflows/reusing-workflows#passing-inputs-and-secrets-to-a-reusable-workflow)”。
> * 机密不适用于事件触发的 Dependabot 工作流。 有关详细信息，请参阅“[对 GitHub Actions 上的 Dependabot 进行故障排除](/zh/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-on-github-actions#accessing-secrets)”。
> * 如果 GitHub Actions 工作流需要访问支持 OpenID Connect (OIDC) 的云提供商提供的资源，则可以将工作流配置为直接向云提供商进行身份验证。 这样就可以停止将这些凭据存储为长期存在的机密，并提供其他安全优势。 有关详细信息，请参阅“[OpenID Connect](/zh/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)”。
> \[!WARNING] 使用GitHub对所有不是机密的敏感信息进行掩码`::add-mask::VALUE`。 这会导致值被处理为机密信息并从日志中删除。
要提供以机密作为输入或环境变量的操作，可以使用 `secrets` 上下文访问你在存储库中创建的密码。 有关详细信息，请参阅 [上下文参考](/zh/actions/learn-github-actions/contexts) 和 [GitHub Actions 的工作流语法](/zh/actions/using-workflows/workflow-syntax-for-github-actions)。
```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:` 条件中引用机密。 而应考虑将机密设置为作业级环境变量，然后引用环境变量以有条件地运行作业中的步骤。 有关详细信息，请参阅“[上下文参考](/zh/actions/learn-github-actions/contexts#context-availability)”和 [`jobs..steps[*].if`](/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif)。
如果未设置机密，则引用机密的表达式的返回值（如 `${{ secrets.SuperSecret }}` 示例中）将为空字符串。
尽可能避免使用命令行在进程之间传递密码。 命令行进程可能对其他用户可见（使用 `ps` 命令）或通过[安全审计事件](https://docs.microsoft.com/windows-server/identity/ad-ds/manage/component-updates/command-line-process-auditing)捕获。 为帮助保护密码，请考虑使用环境变量 `STDIN` 或目标进程支持的其他机制。
如果必须在命令行中传递密码，则将它们包含在适当的引用规则中。 密钥通常包含可能会不经意间影响 shell 的特殊字符。 要转义这些特殊字符，请引用环境变量。 例如：
### 使用 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%"
```
## 存储大型机密
若要使用大于 48 KB 的机密，可以使用解决方法将机密存储在存储库中，并将解密通行短语保存为机密 GitHub。 例如，您可以在本地加密包含秘密的文件，然后将加密文件签入`gpg`上的存储库GitHub。 有关详细信息，请参阅“[gpg 手册页](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` 加密文件，而不是未加密的 \*\*\*\* 文件`my_secret.json`。
```shell
git add my_secret.json.gpg
git commit -m "Add new secret JSON file"
```
5. 在存储库中创建 shell 脚本来解密机密文件。 在本例中，脚本命名为 `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 脚本在提交到您的仓库之前可执行。
```shell
chmod +x decrypt_secret.sh
git add decrypt_secret.sh
git commit -m "Add new decryption script"
git push
```
7. 在您的GitHub Actions工作流中，使用`step`调用Shell脚本并解密密钥。 若要在运行工作流的环境中创建存储库的副本，需要使用 [`actions/checkout`](https://github.com/actions/checkout) 操作。 使用与存储库根目录相关的 `run` 命令引用你的 shell 脚本。
```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 存储为机密。 然后，您可以在工作流程中引用该机密，并对其进行解码以在运行器上使用。 有关大小限制，请参阅“[在 GitHub Actions 中使用机密](/zh/actions/security-guides/using-secrets-in-github-actions#limits-for-secrets)”。
> \[!NOTE]
>
> * Base64 仅将二进制转换为文本，并不能替代实际加密。
> * 使用另一个 shell 可能需要不同的命令才能将机密解码为文件。 在 Windows 运行器上，我们建议[将 bash shell](/zh/actions/using-workflows/workflow-syntax-for-github-actions#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
```
## 后续步骤
有关参考信息，请参阅 [机密参考](/zh/actions/reference/secrets-reference)。