可信发布 nuget.org

受信任的发布是发布 NuGet 包的更好方法。 不再需要管理长期 API 密钥。 反而使用由您的 CI/CD 系统（如 GitHub Actions）颁发的短期凭证。

这样一来，发布过程会降低凭据泄露的风险，从而更安全。 它还使自动化更加轻松，因为无需轮换或存储机密。 这种方法是更广泛的行业向安全、无密钥发布转变的一部分。 如果你好奇，请查看 OpenSSF 计划： https://repos.openssf.org/trusted-publishers-for-all-package-repositories

⚠️ 请注意： 如果你在 nuget.org 帐户中看不到 “受信任的发布” 选项，则它可能尚不可用。 我们正在逐步推出它。

工作原理

GitHub Actions 工作流运行时，它会从 github.com 请求加密的 OIDC 令牌。 此令牌包含有关存储库和工作流的信息，并由 GitHub Actions 加密签名以防止篡改。 工作流将此令牌转发到 nuget.org，该令牌使用行业标准加密方法通过 github.com 安全地验证令牌的真实性。 然后，nuget.org 上的令牌交换终结点检查令牌的详细信息是否与你配置的受信任发布策略匹配。 如果一切匹配，nuget.org 将发放一个生存期较短的 API 密钥供工作流在发布包时使用。

下面是基本流

1. CI/CD 系统（如 GitHub Actions）运行工作流。
2. 它颁发生存期较短的令牌。
3. 该令牌将发送到 nuget.org。
4. NuGet 会验证它并返回临时 API 密钥。
5. 工作流使用该密钥推送这个包。

NuGet 的临时 API 密钥有效期 为 1 小时，因此工作流应在发布前不久请求密钥。 如果请求时间过早，可能会在推送发生之前失效。

每个生存期较短的令牌只能使用一次来获取单个临时 API 密钥-一个令牌，一个 API 密钥。

此设置提供一种安全且自动化的方式来发布包，而不会带来长期机密的风险。

“GitHub Actions” 设置

开始之前：

1. 登录到 nuget.org。
2. 单击用户名并选择 “受信任的发布”。
3. 添加新的受信任发布策略。 对于包含工作流文件的 https://github.com/contoso/contoso-sdk GitHub 存储库.github/workflows/build.yml，请输入以下受信任的策略详细信息（不区分大小写）：
   • 存储库所有者：contoso
   • 存储 库：contoso-sdk
   • 工作流文件：build.yml

     这对应于您的工作流.github/workflows/build.yml。 仅输入 文件名 （build.yml）-不包括 .github/workflows/ 路径。

   • 环境（可选）：release

     如果工作流使用环境，例如 environment: release ，并且希望将此策略限制为该环境，请输入环境。 如果不使用 GitHub Actions 环境，请将此保留为空。

4. 在 GitHub 存储库中，更新工作流以请求生存期较短的 API 密钥并推送包。
   下面是一个基本示例：

jobs:
  build-and-publish:
    permissions:
      id-token: write  # enable GitHub OIDC token issuance for this job
    
    steps:
      # Build your artifacts/my-sdk.nupkg package here
    
      # Get a short-lived NuGet API key
      - name: NuGet login (OIDC → temp API key)
        uses: NuGet/login@v1
        id: login
        with:
          user: contoso-bot # Recommended: use a secret like ${{ secrets.NUGET_USER }} for your nuget.org username (profile name), NOT your email address
    
      # Push the package
      - name: NuGet push
        run: dotnet nuget push artifacts/my-sdk.nupkg --api-key ${{steps.login.outputs.NUGET_API_KEY}} --source https://api.nuget.org/v3/index.json

策略所有权

创建受信任的发布策略时，需要选择拥有该策略的人员。 所有者可以是：

• 你（单个用户）
• 你所属的组织

该策略将应用于所选所有者拥有的所有包。 这意味着它控制谁可以使用受信任的发布来发布或修改这些包。

如果选择组织，请确保你是活动成员。 如果将来你离开组织，该策略可能会变为非活动状态，直到你重新被添加到组织中。

选择正确的所有者有助于确保发布设置保持安全，并与团队的结构保持一致。

待完全激活的策略

有时，当您创建受信任的发布策略时，它会被临时激活，持续 7 天。 这通常发生在专用 GitHub 存储库中。 UI 中会显示此状态。 在此期间，它的行为类似于常规策略。 但是，如果没有在 7 天内发布，则策略将自动变为非活动状态。 你可以随时重启 7 天窗口，即使它过期也是如此。

为什么需要此临时期限？ 由于 NuGet 需要 GitHub 存储库和所有者 ID 来将策略锁定到原始存储库和所有者。 这有助于防止复活攻击。 如果没有这些 ID，有人可以删除存储库，使用同名重新创建它，并尝试发布，就好像没有发生任何更改一样。

成功发布后（作为 GitHub 短生存期令牌的一部分）提供 ID 后，策略将永久处于活动状态。

策略所有权警告

受信任的发布策略与特定所有者（单个用户或组织）相关联。 如果所有权发生更改，策略可能会变为非活动状态。 发生这种情况时，UI 中会显示警告。

常见情况

• 从组织中删除的用户
  如果策略由组织拥有，并且创建策略的用户稍后将从该组织中删除，则策略将变为非活动状态。
  如果用户被添加回组织，策略将自动激活。

• 组织不再处于活动状态
  如果拥有策略的组织被锁定或删除，该策略将变为非活动状态。

这些警告有助于确保在发布包时，仅使用活跃且安全的策略。