attest build provenance

actions/attest-build-provenance

Hasilkan pengesahan asal bangunan yang ditandatangani untuk artefak alur kerja. Didukung secara internal oleh paket @actions/attest.

Pengesahan mengikat beberapa subjek (artefak bernama beserta intisarinya) ke predikat asal build SLSA menggunakan format in-toto.

Tanda tangan yang dapat diverifikasi dihasilkan untuk pengesahan menggunakan sertifikat penandatanganan yang diterbitkan oleh Sigstore yang berumur pendek. Jika repositori yang memulai alur kerja GitHub Actions bersifat publik, instance Sigstore yang merupakan barang publik akan digunakan untuk menghasilkan tanda tangan pengesahan. Jika repositori bersifat pribadi/internal, ia akan menggunakan instans Sigstore pribadi GitHub.

Setelah pengesahan dibuat dan ditandatangani, pengesahan tersebut akan diunggah ke API pengesahan GH dan dikaitkan dengan repositori tempat alur kerja dimulai.

Pengesahan dapat diverifikasi menggunakan perintah attestation di GitHub CLI.

Lihat Menggunakan pengesahan artefak untuk menetapkan asal bangunan untuk informasi selengkapnya tentang pengesahan artefak.

Penggunaan

Dalam alur kerja Tindakan GitHub yang membuat beberapa artefak yang ingin Anda buktikan:

1. Pastikan izin berikut telah ditetapkan:

    permissions :
     id-token : write
     attestations : write

   Izin id-token memberikan tindakan kemampuan untuk mencetak token OIDC yang diperlukan untuk meminta sertifikat penandatanganan Sigstore. Izin attestations diperlukan untuk mempertahankan pengesahan.

2. Tambahkan yang berikut ini ke alur kerja Anda setelah artefak Anda dibuat:

   - uses : actions/attest-build-provenance@v1
     with :
       subject-path : ' <PATH TO ARTIFACT> '

   Parameter subject-path harus mengidentifikasi artefak yang ingin Anda buatkan pengesahannya.

masukan

Lihat action.yml

- uses : actions/attest-build-provenance@v1
  with :
    # Path to the artifact serving as the subject of the attestation. Must
    # specify exactly one of "subject-path" or "subject-digest". May contain a
    # glob pattern or list of paths (total subject count cannot exceed 2500).
    subject-path :

    # SHA256 digest of the subject for the attestation. Must be in the form
    # "sha256:hex_digest" (e.g. "sha256:abc123..."). Must specify exactly one
    # of "subject-path" or "subject-digest".
    subject-digest :

    # Subject name as it should appear in the attestation. Required unless
    # "subject-path" is specified, in which case it will be inferred from the
    # path.
    subject-name :

    # Whether to push the attestation to the image registry. Requires that the
    # "subject-name" parameter specify the fully-qualified image name and that
    # the "subject-digest" parameter be specified. Defaults to false.
    push-to-registry :

    # Whether to attach a list of generated attestations to the workflow run
    # summary page. Defaults to true.
    show-summary :

    # The GitHub token used to make authenticated API requests. Default is
    # ${{ github.token }}
    github-token :

Keluaran

Nama	Keterangan	Contoh
bundle-path	Jalur absolut ke file yang berisi pengesahan yang dihasilkan	/tmp/attestation.jsonl

Pengesahan disimpan dalam format paket Sigstore berseri JSON.

Jika beberapa subjek dibuktikan secara bersamaan, setiap pengesahan akan ditulis ke file keluaran pada baris terpisah (menggunakan format JSON Lines).

Batas Pengesahan

Batasan Subjek

Tidak lebih dari 2500 mata pelajaran dapat dibuktikan pada saat yang bersamaan. Subjek akan diproses dalam kelompok 50. Setelah kelompok awal yang terdiri dari 50 orang, setiap kelompok berikutnya akan mengalami jumlah penundaan yang meningkat secara eksponensial (dibatasi pada penundaan 1 menit per kelompok) untuk menghindari API pengesahan yang berlebihan.

Contoh

Identifikasi Subjek berdasarkan Jalur

Untuk kasus penggunaan dasar, cukup tambahkan tindakan attest-build-provenance ke alur kerja Anda dan berikan jalur ke artefak yang ingin Anda buatkan pengesahannya.

 name : build-attest

on :
  workflow_dispatch :

jobs :
  build :
    permissions :
      id-token : write
      contents : read
      attestations : write

    steps :
      - name : Checkout
        uses : actions/checkout@v4
      - name : Build artifact
        run : make my-app
      - name : Attest
        uses : actions/attest-build-provenance@v1
        with :
          subject-path : ' ${{ github.workspace }}/my-app '

Identifikasi Banyak Subjek

Jika Anda membuat beberapa artefak, Anda dapat membuat pengesahan asal untuk masing-masing artefak dengan menggunakan karakter pengganti di input subject-path .

- uses : actions/attest-build-provenance@v1
  with :
    subject-path : ' dist/**/my-bin-* '

Untuk wildcard yang didukung beserta perilaku dan dokumentasinya, lihat @actions/glob yang digunakan secara internal untuk mencari file.

Alternatifnya, Anda dapat secara eksplisit membuat daftar beberapa subjek dengan daftar yang dibatasi koma atau baris baru:

- uses : actions/attest-build-provenance@v1
  with :
    subject-path : ' dist/foo, dist/bar ' 

- uses : actions/attest-build-provenance@v1
  with :
    subject-path : |
      dist/foo
      dist/bar

Gambar Kontainer

Saat bekerja dengan gambar kontainer, Anda dapat menjalankan tindakan dengan input subject-name dan subject-digest .

Jika Anda ingin memublikasikan pengesahan ke registri kontainer dengan opsi push-to-registry , subject-name harus menentukan nama gambar yang sepenuhnya memenuhi syarat (mis. "ghcr.io/user/app" atau "acme. azurecr.io/user/app"). JANGAN sertakan tag sebagai bagian dari nama gambar -- gambar spesifik yang dibuktikan diidentifikasi oleh intisari yang disediakan.

Bundel pengesahan disimpan dalam registri OCI sesuai dengan Spesifikasi Bundel Cosign.

CATATAN : Saat mendorong ke Docker Hub, harap gunakan "index.docker.io" sebagai bagian registri dari nama gambar.

 name : build-attested-image

on :
  push :
    branches : [main]

jobs :
  build :
    runs-on : ubuntu-latest
    permissions :
      id-token : write
      packages : write
      contents : read
      attestations : write
    env :
      REGISTRY : ghcr.io
      IMAGE_NAME : ${{ github.repository }}

    steps :
      - name : Checkout
        uses : actions/checkout@v4
      - name : Login to GitHub Container Registry
        uses : docker/login-action@v3
        with :
          registry : ${{ env.REGISTRY }}
          username : ${{ github.actor }}
          password : ${{ secrets.GITHUB_TOKEN }}
      - name : Build and push image
        id : push
        uses : docker/[email protected]
        with :
          context : .
          push : true
          tags : ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
      - name : Attest
        uses : actions/attest-build-provenance@v1
        id : attest
        with :
          subject-name : ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          subject-digest : ${{ steps.push.outputs.digest }}
          push-to-registry : true