将存储和部署数据上传到 linked artifacts page

将组织中的包和构建与存储和部署数据相关联。

谁可以使用此功能？

Anyone with write access to an organization-owned repository

Organization accounts on any plan

本文内容

linked artifacts page 包含你在组织中构建的项目的存储记录和部署记录。 您的组织通过以下方法之一为每个工件提供元数据：

  • 包含 GitHub 用于项目证明的操作之一的工作流
  • 与 JFrog Artifactory 或 Microsoft Defender for Cloud 集成
  • 使用项目元数据 REST API 的自定义脚本

可用方法取决于是上传存储记录还是部署记录。 有关记录类型的详细信息，请参阅 关于关联的项目。

上传存储记录

可以通过创建 项目证明 或启用与 JFrog Artifactory 的集成来上传存储记录。 如果不想使用这些选项，则必须设置与 REST API 的自定义集成。

使用 GitHub Actions 进行认证

可以使用 GitHub 的第一方项目证明操作上传项目的存储记录。 可以在用于构建工件的同一工作流中执行此操作。 这些操作会为你构建的软件创建已签名的溯源和完整性保证，并自动将存储记录上传到 linked artifacts page。

证明和证明生成证明作会在 linked artifacts page 上自动创建存储记录（如果两者都）：

  • 选项 push-to-registry 设置为 true
  • 包含该操作的工作流具有artifact-metadata: write权限

有关使用这些操作的详细信息，请参阅 使用项目证明确立生成的来源。

如果项目不需要证明，或者想要上传部署记录或其他存储元数据，请参阅以下部分。

使用 JFrog 集成功能

此双向集成会自动使 GitHub 上的存储记录与 JFrog 上的项目保持同步。 例如，在 GitHub 上创建的证明会自动上传到 JFrog，而在 JFrog 上将项目提升到生产环境时，会自动将生产上下文添加到 GitHub 上的记录中。

有关设置说明，请参阅 JFrog 文档中的 JFrog Artifactory 和 GitHub 集成入门 。

使用 REST API

对于不需要证明且不存储在 JFrog 上的项目，可以使用 “创建项目元数据存储记录 API 终结点”创建自定义集成。 应将系统配置为在项目发布到所选的软件包存储库时调用该终结点。

注意

如果项目未与 GitHub 上的溯源证明关联，则 github_repository 参数为必需项。

上传部署记录

如果将项目存储在 Microsoft Defender for Cloud (MDC) 中，可以使用集成将数据自动同步到 linked artifacts page。 否则，必须设置与 REST API 的自定义集成。

使用 Microsoft Defender for Cloud 集成功能

可以将 MDC 实例连接到 GitHub 组织。 MDC 会自动将部署和运行时数据发送到 GitHub。

有关设置说明，请参阅 快速入门：将您的 GitHub 环境连接到 Microsoft Defender for Cloud，该文档位于 MDC 中。

注意

与 Microsoft Defender for Cloud 的集成位于 公共预览版 中，并可能会更改。

使用 REST API

          [创建项目部署记录](/rest/orgs/artifact-metadata#create-an-artifact-deployment-record) API 终结点允许系统将特定项目的部署数据发送到 GitHub，例如其名称、摘要、环境、群集和部署。 每当将工件部署到新的过渡或生产环境时，都应调用此端点。

注意

如果项目未与 GitHub 上的溯源证明关联，则 github_repository 参数为必需项。

验证上传

若要检查是否已成功上传记录，可以在组织设置中查看更新的项目。 请参阅“审核组织在 linked artifacts page 上的构建”。

删除不需要的记录

无法从 linked artifacts page 中删除项目。 但是，可以更新存储记录或部署记录以反映项目的状态。 请参阅“从 linked artifacts page 中删除工件”。

GitHub Actions 案例

可以在用于构建和发布项目的同一工作流中，将数据上传到 linked artifacts page。

生成证明

在以下示例中，我们生成并发布 Docker 映像，然后使用 ${{ steps.push.outputs.digest }} 下一步中的输出生成证明证明。

当设置 push-to-registry: true 且工作流包含 artifact-metadata: write 权限时，attest-build-provenance 操作会自动将存储记录上传到 linked artifacts page。


env:
  IMAGE_NAME: my-container-image
  ACR_ENDPOINT: my-registry.azurecr.io

jobs:
  generate-build:
    name: Build and publish Docker image
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      attestations: write
      packages: write
      artifact-metadata: write

    steps:
      - name: Build and push Docker image
        id: push
        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83
        with:
          context: .
          push: true
          tags: |
            ${{ env.ACR_ENDPOINT }}/${{ env.IMAGE_NAME }}:latest
            ${{ env.ACR_ENDPOINT }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

      - name: Generate artifact attestation
        uses: actions/attest-build-provenance@v3
        with:
          subject-name: ${{ env.ACR_ENDPOINT }}/${{ env.IMAGE_NAME }}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true

使用 REST API

或者，如果未生成证明，可以直接调用项目元数据 API。


env:
  IMAGE_NAME: my-container-image
  IMAGE_VERSION: 1.1.2
  ACR_ENDPOINT: my-registry.azurecr.io

jobs:
  generate-build:
    name: Build and publish Docker image
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      packages: write
      artifact-metadata: write

    steps:
      - name: Build and push Docker image
        id: push
        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83
        with:
          context: .
          push: true
          tags: |
              ${{ env.ACR_ENDPOINT }}/${{ env.IMAGE_NAME }}:latest
              ${{ env.ACR_ENDPOINT }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

      - name: Create artifact metadata storage record
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          jq -n --arg artifactName "${{ env.IMAGE_NAME }}" --arg artifactVersion "${{ env.IMAGE_VERSION }}" --arg artifactDigest "${{ steps.push.outputs.digest }}" '{"name": $artifactName, "digest": $artifactDigest, "version": $artifactVersion, "registry_url": "https://azurecr.io", "repository": "my-repository"}' > create-record.json

          gh api -X POST orgs/${{ github.repository_owner }}/artifacts/metadata/storage-record --input create-record.json
        shell: bash

后续步骤

上传数据后，组织中的团队可以使用存储和部署数据的上下文来确定安全警报的优先级。 请参阅“使用生产上下文确定 Dependabot 和代码扫描警报的优先级”。