注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。
关于� 密密� �
机密是在组织、存储库或存储库环境中创建的� 密环境变量。 您创建的机密可用于 GitHub Actions 工作流程。 在机密到达 GitHub 之前,GitHub 使用 libsodium 密封盒对机密� 密,并且在您于工作流程中使用它们之前一直保持� 密状态。
对于存储在组织级别的密� �,可以使用访问策略来控制哪些仓库可以使用组织密� �。 组织级密� �允许在多个仓库之间共享密� �,从而减少创建重复密� �的需要。 在一个位置更新组织密� �还可确保更改在使用该密� �的所有仓库工作流程中生效。
对于存储在环境级别的机密,您可以启用所需的审查者来控制对机密的访问。 在必要的审查者授予批准之前,工作流程作业� 法访问环境机密。
命名您的密� �
以下规则适用于密� �名称:
-
密� �名称只能包含字母数字字符(
[a-z]
、[A-Z]
、[0-9]
)或下划线 (_
)。 不允许空� �。 -
密� �名称不能以
GITHUB_
前缀开头。 -
密� �名称不能以数字开头。
-
机密名称不区分大小写。
-
密� �名称在所创建的级别上必须是唯一的。
例如,在环境级别创建的机密必须在环境中具有唯一的名称,在仓库级别创建的机密必须在该仓库中具有唯一的名称,而在组织级别创建的机密必须在该级别具有独特的名称。
如果具有相同名称的机密存在于多个级别,则最低级别的机密优先。 例如,如果组织级别密� �的名称与仓库级别的密� �相同,则仓库级别的密� �优先。 同� �,如果组织、存储库和环境都具有同名的机密,则环境级机密优先。
为帮助确保 GitHub 在日志中编写密� �,请勿将结构化数据用作密� �的值。 例如,避免创建包含 JSON 或编� � Git blob 的密� �。
访问您的密� �
为使密� �用于操作,必须将密� �设置为工作流程文件中的输入或环境变量。 查看操作的自述文件以了解操作预期的输入和环境变量。 更多信息请参阅“GitHub Actions 的工作流程语法”。
如果您拥有编辑文件的权限,便可在工作流程文件中使用和读取� 密密� �。 更多信息请参阅“GitHub 上的访问权限”。
警告:GitHub 自动将密� �编写到日志,但您应避免有意将密� �打印到日志。
当工作流程运行排队时读取组织和仓库机密,在引用环境的作业开始时读取环境机密。
您还可以使用 REST API 管理密� �。 更多信息请参阅“机密”。
限制凭据权限
生成凭据时,建议尽可能授予最低的权限。 例如,不使用个人凭据,而使用部署密钥或服务帐户。 请考虑授予只读权限(如果这是所需的全部权限)并尽可能限制访问。 生成个人访问令牌 (PAT) 时,选择所需的最小范围。
注意: 您可以使用 REST API 来管理机密。 更多信息请参阅“GitHub Actions 密� � API”。
为仓库创建� 密密� �
To create secrets for a personal account repository, you must be the repository owner. 要为组织仓库创建密� �,您必须具有管理员
访问权限。
-
在 您的 GitHub Enterprise Server 实例 上,导航到仓库的主页面。
-
在仓库名称下,单击 Settings(设置)。
-
在左侧边� �中,单击 Secrets(密� �)。
-
单击 New repository secret(新仓库机密)。
-
在 Name(名称)输入框中键入密� �的名称。
-
输入密� �的值。
-
单击 Add secret(添� 密� �)。
如果您的存储库具有环境机密或可以访问上级组织的机密,则这些机密也会在此页面上列出。
要了解有关 GitHub CLI 的更多信息,请参阅“关于 GitHub CLI”。
要添� 仓库机密,请使用 gh secret set
子命令。 将 secret-name
替换为机密的名称。
gh secret set secret-name
CLI 将提示您输入一个机密值。 或者,您可以从文件中读取机密的值。
gh secret set secret-name < secret.txt
要列出仓库的所有机密,请使用 gh secret list
子命令。
为环境创建� 密密� �
要为个人帐户仓库中的环境创建密� �,您必须是仓库所有者。 要为组织仓库中的环境创建密� �,您必须具有管理员
访问权限。
- 在 您的 GitHub Enterprise Server 实例 上,导航到仓库的主页面。
- 在仓库名称下,单击 Settings(设置)。
- 在左侧边� �中,单击 Environments(环境)。
- 单击要向其添� 机密的环境。
- 在 Environment secrets(环境机密)下,单击 Add secret(添� 机密)。
- 在 Name(名称)输入框中键入密� �的名称。
- 输入密� �的值。
- 单击 Add secret(添� 密� �)。
要为环境添� 机密,请使用 gh secret set
子命令与 - env
或 - e
� �志,后接环境名称。
gh secret set --env environment-name secret-name
要列出环境的所有机密,请使用 gh secret list
子命令与 - env
或 - e
� �志,后接环境名称。
gh secret list --env environment-name
为组织创建� 密密� �
在组织中创建密� �时,可以使用策略来限制可以访问该密� �的仓库。 例如,您可以将访问权限授予所有仓库,也可以限制仅私有仓库或指定的仓库列表拥有访问权限。
要在组织级别创建密� �,必须具有管理员
访问权限。
- 在 您的 GitHub Enterprise Server 实例 上,导航到组织的主页面。
- 在组织名称下,单击 设置.
-
在左侧边� �中,单击 Secrets(密� �)。
-
单击 New organization secret(新组织机密)。
-
在 Name(名称)输入框中键入密� �的名称。
-
输入密� �的 Value(值)。
-
从 Repository access(仓库访问权限)下拉列表,选择访问策略。
-
单击 Add secret(添� 密� �)。
注意: 默认情况下, GitHub CLI 使用 repo
和 read:org
范围进行身份验证。 要管理组织机密,您还必须授权 admin:org
范围。
gh auth login --scopes "admin:org"
要为组织添� 机密,请使用 gh secret set
子命令与 --org
或 -o
� �志,后接组织名称。
gh secret set --org organization-name secret-name
默认情况下,机密仅对私有仓库可用。 要指定该机密应该提供给组织内的所有仓库,请使用 --visible
或 -v
� �志。
gh secret set --org organization-name secret-name --visibility all
要指定该秘密应提供给组织内选定的仓库,请使用 --repos
或 -r
� �志。
gh secret set --org organization-name secret-name --repos repo-name-1,repo-name-2"
要列出组织的所有机密,请使用 gh secret list
子命令与 --org
或 -o
� �志,后接组织名称。
gh secret list --org organization-name
审查对组织级别密� �的访问权限
您可以检查哪些访问策略正被应用于组织中的密� �。
- 在 您的 GitHub Enterprise Server 实例 上,导航到组织的主页面。
- 在组织名称下,单击 设置.
-
在左侧边� �中,单击 Secrets(密� �)。
-
密� �列表包括任何已配置的权限和策略。 例如:
-
有关已为每个密� �配置的权限的更多信息,请单击 Update(更新)。
在工作流程中使用� 密密� �
注意: 除了 GITHUB_TOKEN
以外,从复刻的仓库触发工作流程时密� �不会� 递给运行程序。
要提供以密� �作为输入或环境变量的操作,可以使用 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”。
警告:请注意,在工作流程运行时不会打印您的机密。 使用此解决方法时,GitHub 不会编写日志中印出的密� �。
-
从终端运行以下命令,使用
gpg
和 AES256 密� �算法� 密包含密钥的文件。 在此示例中,my_secret.json
是包含密钥的文件。gpg --symmetric --cipher-algo AES256 my_secret.json
-
将会提示您输入密� �短语。 请记住该密� �短语,� 为需要在使用该密� �短语作为值的 GitHub 上创建新密� �。
-
创建包含密� �短语的新密� �。 例如,使用名称
LARGE_SECRET_PASSPHRASE
创建新密� �,并将密� �的值设为上一步使用的密� �短语。 -
将� 密文件复制到存储库中的路径并提交。 在本例中,� 密的文件是
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"
-
在存储库中创建一个 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
-
确保 shell 脚本在检入仓库之前可执行。
chmod +x decrypt_secret.sh git add decrypt_secret.sh git commit -m "Add new decryption script" git push
-
在 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 存储为机密。 然后,您可以在工作流程中引用该机密,并对其进行解� �以在运行器上使用。 有关大小限制,请参阅机密限制。
注意:请注意,Base64 只是将二进制转换为文本,不能替代实际� 密。
-
使用
base64
将文件编� �为 Base64 字符串。 例如:$ base64 -i cert.der -o cert.base64
-
创建包含 Base64 字符串的机密。 例如:
$ gh secret set CERTIFICATE_BASE64 < cert.base64 ✓ Set secret CERTIFICATE_BASE64 for octocat/octorepo
-
要从运行器访问 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