Carga de los datos de almacenamiento y despliegue en linked artifacts page

Asocie paquetes y compilaciones en su organización con datos de almacenamiento e implementación.

¿Quién puede utilizar esta característica?

Anyone with write access to an organization-owned repository

Organization accounts on any plan

En este artículo

linked artifacts page incluye registros de almacenamiento y de implementación para los artefactos que se compilen en tu organización. La organización proporciona metadatos para cada artefacto mediante uno de los métodos siguientes:

  • Un flujo de trabajo que contiene una de las acciones de GitHub para las atestaciones de artefactos
  • Integración con JFrog Artifactory o Microsoft Defender for Cloud
  • Un script personalizado mediante la API REST de metadatos de artefacto

Los métodos disponibles dependen de si está cargando un registro de almacenamiento o un registro de implementación. Para obtener más información sobre los tipos de registro, vea Acerca de los artefactos vinculados.

Carga de un registro de almacenamiento

Puede cargar un registro de almacenamiento mediante la creación de una atestación de artefactos o la habilitación de una integración con JFrog Artifactory. Si no desea usar estas opciones, debe configurar una integración personalizada con la API REST.

Verificación con GitHub Actions

Puede cargar un registro de almacenamiento para un artefacto usando las acciones de primera parte de GitHub para las atestaciones de artefactos. Puede hacerlo en el mismo flujo de trabajo que se utiliza para construir el artefacto. Estas acciones crean garantías de integridad y procedencia firmadas para el software que construye, así como cargan automáticamente un registro de almacenamiento de datos en linked artifacts page.

Las acciones certificar y compilar-generar-procedencia crean automáticamente registros de almacenamiento en el linked artifacts page si se cumplen ambas condiciones:

  • La push-to-registry opción se establece en true
  • El flujo de trabajo que incluye la acción tiene el artifact-metadata: write permiso.

Para obtener más información sobre el uso de estas acciones, consulte Utilización de atestaciones de artefactos para establecer la procedencia de las compilaciones.

Si el artefacto no requiere atestación o si desea cargar registros de implementación o metadatos de almacenamiento adicionales, consulte las secciones siguientes.

Uso de la integración de JFrog

Esta integración bidireccional mantiene automáticamente los registros de almacenamiento en GitHub actualizados con el artefacto en JFrog. Por ejemplo, las atestaciones que cree en GitHub se cargan automáticamente en JFrog y la promoción de un artefacto en producción en JFrog agrega automáticamente el contexto de producción al registro en GitHub.

Para obtener instrucciones de configuración, consulte Introducción a JFrog Artifactory e integración de GitHub en la documentación de JFrog.

Uso de la API REST

En el caso de los artefactos que no necesitan ser atestiguados y no se almacenan en JFrog, puede crear una integración personalizada utilizando el punto de conexión de la API Create artifact metadata storage record. Debe configurar el sistema para que llame al punto de conexión cada vez que se publique un artefacto en el repositorio de paquetes elegido.

Nota:

Si el artefacto no está asociado a una atestación de procedencia en GitHub, el github_repository parámetro es obligatorio.

Carga de un registro de implementación

Si almacena artefactos en Microsoft Defender for Cloud (MDC), puede usar una integración para sincronizar automáticamente los datos con el linked artifacts page. De lo contrario, debe configurar una integración personalizada con la API REST.

Uso de la integración de Microsoft Defender for Cloud

Puede conectar su instancia de MDC a su organización de GitHub. MDC enviará automáticamente datos de implementación y tiempo de ejecución a GitHub.

Para obtener instrucciones de configuración, consulte Guía rápida: Conectar el entorno de GitHub a Microsoft Defender for Cloud en la documentación de MDC.

Nota:

La integración con Microsoft Defender for Cloud está en versión preliminar pública y sujeta a cambios.

Uso de la API REST

El punto de conexión de API Crear un registro de implementación de artefactos permite a los sistemas enviar datos de implementación para un artefacto específico a GitHub, como su nombre, resumen, entornos, clúster e implementación. Debe llamar a este endpoint cada vez que se implementa un artefacto en un nuevo entorno de preparación o producción.

Nota:

Si el artefacto no está asociado a una atestación de procedencia en GitHub, el github_repository parámetro es obligatorio.

Comprobación de una carga

Para comprobar que un registro se ha cargado correctamente, puede ver el artefacto actualizado en la configuración de su organización. Consulta Auditando las compilaciones de la organización en el linked artifacts page.

Eliminación de registros no deseados

No es posible eliminar un artefacto de linked artifacts page. Sin embargo, puede actualizar un registro de almacenamiento o un registro de implementación para reflejar el estado de un artefacto. Consulta Uploading storage and deployment data to the linked artifacts page.

Ejemplos de GitHub Actions

Puede cargar datos en linked artifacts page en el mismo flujo de trabajo que utilizas para crear y publicar un artefacto.

Generación de una atestación

En el ejemplo siguiente, compilamos y publicamos una imagen de Docker y, a continuación, usamos la ${{ steps.push.outputs.digest }} salida en el paso siguiente para generar una atestación de procedencia.

La attest-build-provenance acción carga automáticamente un registro de almacenamiento en linked artifacts page cuando push-to-registry: true se establece y el flujo de trabajo incluye el artifact-metadata: write permiso.


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

Uso de la API REST

Como alternativa, si no genera una atestación, puede llamar directamente a la API de metadatos del artefacto.


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

Pasos siguientes

Una vez cargados los datos, los equipos de su organización pueden usar el contexto de los datos de almacenamiento e implementación para priorizar las alertas de seguridad. Consulta Priorización de alertas de análisis de código y Dependabot mediante el contexto de producción.