在 GitHub Actions 中使用机密

有关机密的一般信息，请参阅 关于机密。

为存储库创建机密

若要在 GitHub 上为个人帐户存储库创建机密或变量，你必须是存储库所有者。 若要在 GitHub 上为组织存储库创建机密或变量，你必须拥有 admin 访问权限。 最后，若要通过 REST API 为个人帐户存储库或组织存储库创建机密或变量，你必须拥有协作者访问权限。

gh secret set SECRET_NAME

gh secret set SECRET_NAME < secret.txt

为环境创建机密

要为个人帐户存储库中的环境创建密码或变量，你必须是存储库所有者。 要为组织存储库中的环境创建密码或变量，必须具有 admin 访问权限。 有关环境的详细信息，请参阅“管理部署环境”。

gh secret set --env ENV_NAME SECRET_NAME

gh secret list --env ENV_NAME

为组织创建机密

在组织中创建机密或变量时，可以使用策略来限制存储库的访问。 例如，您可以将访问权限授予所有仓库，也可以限制仅私有仓库或指定的仓库列表拥有访问权限。

组织所有者和拥有“管理组织操作变量”或“管理组织操作机密”权限的用户可以在组织级别创建机密或变量。

有关详细信息，请参阅“关于自定义组织角色”。

gh auth login --scopes "admin:org"

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. 在组织名称下，单击 “设置”****。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”********。

   

3. 在边栏的“安全性”部分中，选择 机密和变量，然后单击 操作。

4. 密码列表包括任何已配置的权限和策略。 若要详细了解已为每个机密配置的权限，请单击“更新”。

在工作流中使用机密

要提供以机密作为输入或环境变量的操作，可以使用 secrets 上下文访问你在存储库中创建的密码。 有关详细信息，请参阅 访问有关工作流运行的上下文信息 和 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: 条件中引用机密。 而应考虑将机密设置为作业级环境变量，然后引用环境变量以有条件地运行作业中的步骤。 有关详细信息，请参阅“访问有关工作流运行的上下文信息”和 jobs.<job_id>.steps[*].if。

如果尚未设置机密，则引用该机密的表达式的返回值（例如示例中的 ${{ secrets.SuperSecret }}）将为空字符串。

尽可能避免使用命令行在进程之间传递密码。 命令行进程可能对其他用户可见（使用 ps 命令）或通过安全审计事件捕获。 为帮助保护密码，请考虑使用环境变量 STDIN 或目标进程支持的其他机制。

如果必须在命令行中传递密码，则将它们包含在适当的引用规则中。 密码通常包含可能意外影响 shell 的特殊字符。 要转义这些特殊字符，请引用环境变量。 例如：

使用 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%"

密码的限制

最多可以存储 1,000 个组织机密、100 个存储库机密和 100 个环境机密。

在仓库中创建的工作流程可以访问以下数量的密钥：

• 所有100个仓库密钥。
• 如果分配仓库访问超过 100 个组织密钥，则工作流程只能使用前 100 个组织密钥（按密钥名称字母顺序排序）。
• 所有 100 个环境机密。

密码大小限于 48 KB。 若要存储较大的机密，请参阅下面的“存储大型机密”解决方法。

存储大型机密

若要使用大于 48 KB 的机密，可按照解决方法将机密存储在存储库中，并在 GitHub 上将解密短语保存为机密。 例如，在将加密文件签入 GitHub 上的存储库之前，可在本地使用 gpg 加密包含机密的文件。 有关详细信息，请参阅“gpg 手册页”。

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

   请务必复制以 my_secret.json.gpg 文件扩展名结尾的 .gpg 加密文件，而不是未加密的 my_secret.json 文件****。

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

5. 在存储库中创建 shell 脚本来解密机密文件。 在本例中，机密命名为 decrypt_secret.sh。

   Shell

   #!/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 调用 shell 脚本并解密机密。 若要在运行工作流的环境中创建存储库的副本，需要使用 actions/checkout 操作。 使用与存储库根目录相关的 run 命令引用 shell 脚本。

   name: Workflows with large secrets
   
   on: push
   
   jobs:
     my-job:
       name: My Job
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - 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 存储为机密。 然后，您可以在工作流程中引用该机密，并对其进行解码以在运行器上使用。 有关大小限制，请参阅“在 GitHub Actions 中使用机密”。

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@v4
         - 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
   

编辑工作流运行日志中的机密

GitHub Actions 会自动对打印到工作流日志的所有 GitHub 机密的内容进行修订。

GitHub Actions 还会对识别为敏感数据但未存储为机密的信息进行修订。 目前，GitHub 支持以下内容：

• 32 字节和 64 字节 Azure 密钥
• Azure AD 客户端应用密码
• Azure 缓存密钥
• Azure 容器注册表密钥
• Azure 函数主机密钥
• Azure 搜索密钥
• 数据库连接字符串
• HTTP 持有者令牌标头
• JWT
• NPM 作者令牌
• NuGet API 密钥
• v1 GitHub 安装令牌
• v2 GitHub 安装令牌（ghp、gho、ghu、ghs、ghr）
• v2 GitHub PAT

最佳做法是，应通过使用 ::add-mask::VALUE 来屏蔽不是 GitHub 机密的所有敏感信息。 这会导致值被视为机密并从日志中修订。 有关屏蔽数据的详细信息，请参阅“GitHub Actions 的工作流命令”。

工作流运行器执行机密的修订。 这意味着只有在作业中使用并且运行器可以访问的情况下，才会对机密进行修订。 如果将未修订的机密发送到工作流运行日志，则应删除日志并轮换机密。 有关删除日志的信息，请参阅“使用工作流运行日志”。