� 密机密

关于� 密密� �

机密是在组织、存储库或存储库环境中创建的� 密环境变量。 您创建的机密可用于 GitHub Actions 工作流程。 在机密到达 GitHub 之前，GitHub 使用 libsodium 密封盒对机密� 密，并且在您于工作流程中使用它们之前一直保持� 密状态。

对于存储在组织级别的密� �，可以使用访问策略来控制哪些仓库可以使用组织密� �。 组织级密� �允许在多个仓库之间共享密� �，从而减少创建重复密� �的需要。 在一个位置更新组织密� �还可确保更改在使用该密� �的所有仓库工作流程中生效。

对于存储在环境级别的机密，您可以启用所需的审查者来控制对机密的访问。 在必要的审查者授予批准之前，工作流程作业� 法访问环境机密。

命名您的密� �

以下规则适用于密� �名称：

• 密� �名称只能包含字母数字字符（[a-z]、[A-Z]、[0-9]）或下划线 (_)。 不允许空� �。

• 密� �名称不能以 GITHUB_ 前缀开头。

• 密� �名称不能以数字开头。

• 机密名称不区分大小写。

• 密� �名称在所创建的级别上必须是唯一的。

  例如，在环境级别创建的机密必须在环境中具有唯一的名称，在仓库级别创建的机密必须在该仓库中具有唯一的名称，而在组织级别创建的机密必须在该级别具有独特的名称。

  如果具有相同名称的机密存在于多个级别，则最低级别的机密优先。 例如，如果组织级别密� �的名称与仓库级别的密� �相同，则仓库级别的密� �优先。 同� �，如果组织、存储库和环境都具有同名的机密，则环境级机密优先。

为帮助确保 GitHub 在日志中编写密� �，请勿将结构化数据用作密� �的值。 例如，避免创建包含 JSON 或编� � Git blob 的密� �。

访问您的密� �

为使密� �用于操作，必须将密� �设置为工作流程文件中的输入或环境变量。 查看操作的自述文件以了解操作预期的输入和环境变量。 更多信息请参阅“GitHub Actions 的工作流程语法”。

如果您拥有编辑文件的权限，便可在工作流程文件中使用和读取� 密密� �。 更多信息请参阅“GitHub 上的访问权限”。

当工作流程运行排队时读取组织和仓库机密，在引用环境的作业开始时读取环境机密。

您还可以使用 REST API 管理密� �。 更多信息请参阅“机密”。

限制凭据权限

生成凭据时，建议尽可能授予最低的权限。 例如，不使用个人凭据，而使用部署密钥或服务帐户。 请考虑授予只读权限（如果这是所需的全部权限）并尽可能限制访问。 生成个人访问令牌 (PAT) 时，选择所需的最小范围。

为仓库创建� 密密� �

To create secrets for a personal account repository, you must be the repository owner. 要为组织仓库创建密� �，您必须具有管理员访问权限。

gh secret set secret-name

gh secret set secret-name < secret.txt

为环境创建� 密密� �

要为个人帐户仓库中的环境创建密� �，您必须是仓库所有者。 要为组织仓库中的环境创建密� �，您必须具有管理员访问权限。

gh secret set --env environment-name secret-name

gh secret list --env environment-name

为组织创建� 密密� �

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

要在组织级别创建密� �，必须具有管理员访问权限。

gh auth login --scopes "admin:org"

gh secret set --org organization-name secret-name

gh secret set --org organization-name secret-name --visibility all

gh secret set --org organization-name secret-name --repos repo-name-1,repo-name-2"

gh secret list --org organization-name

审查对组织级别密� �的访问权限

您可以检查哪些访问策略正被应用于组织中的密� �。

1. 在 您的 GitHub Enterprise Server 实例 上，导航到组织的主页面。
2. 在组织名称下，单击 设置.

1. 在左侧边� �中，单击 Secrets（密� �）。

2. 密� �列表包括任何已配置的权限和策略。 例如：

3. 有关已为每个密� �配置的权限的更多信息，请单击 Update（更新）。

在工作流程中使用� 密密� �

要提供以密� �作为输入或环境变量的操作，可以使用 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 个环境机密。

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

存储大型机密

要使用大于 64 KB 的密� �，可以使用解决方法将� 密的密� �存储在仓库中，并将解密短语在 GitHub 上存储为密� �。 例如，您可以使用 gpg 在本地� 密包含密钥的文件，然后再将� 密文件签入 GitHub 上的存储库。 更多信息请参阅“gpg manpage”。

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。

   警告：请确保复制以 .gpg 文件扩展名结尾的� 密 my_secret.json.gpg 文件，而非未� 密的 my_secret.json 文件。

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

5. 在存储库中创建一个 shell 脚本来解密机密文件。 在此示例中，脚本名为 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. 确保 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@v2
         - 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 存储为机密。 然后，您可以在工作流程中引用该机密，并对其进行解� �以在运行器上使用。 有关大小限制，请参阅机密限制。

1. 使用 base64 将文件编� �为 Base64 字符串。 例如：

   $ base64 -i cert.der -o 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@v2
         - 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