إثبات مصدر البناء

actions/attest-build-provenance

إنشاء شهادات مصدر البناء الموقعة لعناصر سير العمل. يتم تشغيله داخليًا بواسطة حزمة @actions/attest.

تربط الشهادات بعض الموضوعات (قطعة أثرية مسماة مع ملخصها) بمسند أصل بناء SLSA باستخدام التنسيق الشامل.

يتم إنشاء توقيع يمكن التحقق منه للتصديق باستخدام شهادة توقيع قصيرة الأجل صادرة عن Sigstore. إذا كان المستودع الذي يبدأ سير عمل GitHub Actions عامًا، فسيتم استخدام مثيل الصالح العام لـ Sigstore لإنشاء توقيع التصديق. إذا كان المستودع خاصًا/داخليًا، فسوف يستخدم مثيل GitHub الخاص Sigstore.

بمجرد إنشاء الشهادة وتوقيعها، سيتم تحميلها إلى واجهة برمجة تطبيقات شهادات GH وربطها بالمستودع الذي تم بدء سير العمل منه.

يمكن التحقق من الشهادات باستخدام أمر attestation في GitHub CLI.

راجع استخدام شهادات القطع الأثرية لتحديد مصدر التصميمات للحصول على مزيد من المعلومات حول شهادات القطع الأثرية.

الاستخدام

ضمن سير عمل GitHub Actions الذي ينشئ بعض العناصر التي ترغب في التصديق عليها:

1. تأكد من تعيين الأذونات التالية:

    permissions :
     id-token : write
     attestations : write

   يمنح إذن id-token الإجراء القدرة على سك رمز OIDC المميز اللازم لطلب شهادة توقيع Sigstore. إذن attestations ضروري لاستمرار التصديق.

2. أضف ما يلي إلى سير العمل الخاص بك بعد إنشاء القطعة الأثرية الخاصة بك:

   - uses : actions/attest-build-provenance@v1
     with :
       subject-path : '  '

   يجب أن تحدد معلمة subject-path الموضوع المنتج الذي تريد إنشاء شهادة له.

المدخلات

راجع 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 :

النواتج

اسم	وصف	مثال
bundle-path	المسار المطلق للملف الذي يحتوي على الشهادة التي تم إنشاؤها	/tmp/attestation.jsonl

يتم حفظ الشهادات بتنسيق حزمة Sigstore المتسلسلة JSON.

إذا تم التصديق على موضوعات متعددة في نفس الوقت، فسيتم كتابة كل شهادة في ملف الإخراج على سطر منفصل (باستخدام تنسيق خطوط JSON).

حدود التصديق

حدود الموضوع

لا يمكن التصديق على أكثر من 2500 موضوع في نفس الوقت. ستتم معالجة الموضوعات على دفعات 50. بعد المجموعة الأولية المكونة من 50 شخصًا، ستتحمل كل دفعة لاحقة قدرًا متزايدًا من التأخير (بحد أقصى دقيقة واحدة من التأخير لكل دفعة) لتجنب إرباك واجهة برمجة التطبيقات للتصديق.

أمثلة

تحديد الموضوع عن طريق المسار

بالنسبة لحالة الاستخدام الأساسية، ما عليك سوى إضافة إجراء attest-build-provenance إلى سير عملك وتوفير المسار إلى العنصر الذي تريد إنشاء مصادقة له.

 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 '

تحديد مواضيع متعددة

إذا كنت تقوم بإنشاء العديد من العناصر، فيمكنك إنشاء شهادة مصدر لكل منها باستخدام حرف البدل في إدخال subject-path .

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

للحصول على أحرف البدل المدعومة بالإضافة إلى السلوك والوثائق، راجع @actions/glob الذي يتم استخدامه داخليًا للبحث عن الملفات.

بدلاً من ذلك، يمكنك إدراج موضوعات متعددة بشكل صريح باستخدام قائمة مفصولة بفاصلة أو سطر جديد:

- 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

صورة الحاوية

عند العمل باستخدام صور الحاوية، يمكنك استدعاء الإجراء باستخدام مدخلات subject-name subject-digest .

إذا كنت تريد نشر الشهادة على سجل الحاوية باستخدام خيار push-to-registry ، فمن المهم أن يحدد subject-name اسم الصورة المؤهل بالكامل (على سبيل المثال "ghcr.io/user/app" أو "acme. azurecr.io/user/app"). لا تقم بتضمين علامة كجزء من اسم الصورة - فالصورة المحددة التي يتم التصديق عليها يتم تحديدها من خلال الملخص المرفق.

يتم تخزين حزم التصديق في سجل OCI وفقًا لمواصفات حزمة Cosign.

ملاحظة : عند الدفع إلى Docker Hub، يرجى استخدام "index.docker.io" باعتباره جزء التسجيل من اسم الصورة.

 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