upload artifact

@actions/upload-artifact

تحذير

action/upload-artifact@v3 من المقرر إيقافه في 30 نوفمبر 2024 . يتعلم أكثر. وبالمثل، تمت جدولة إيقاف الإصدار 1/الإصدار 2 في 30 يونيو 2024 . يرجى تحديث سير العمل الخاص بك لاستخدام الإصدار 4 من الإجراءات المصطنعة. لن يؤثر هذا الإيقاف على أي إصدارات موجودة من GitHub Enterprise Server يستخدمها العملاء.

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

انظر أيضًا تنزيل قطعة أثرية.

• @actions/upload-artifact
  • v4 - ما الجديد
    • التحسينات
    • كسر التغييرات
  • الاستخدام
    • المدخلات
    • النواتج
  • أمثلة
    • تحميل ملف فردي
    • تحميل دليل كامل
    • تحميل باستخدام نمط Wildcard
    • التحميل باستخدام مسارات واستثناءات متعددة
    • تغيير مستوى الضغطات (السرعة مقابل الحجم)
    • التخصيص في حالة عدم العثور على ملفات
    • (لا) التحميل على نفس القطعة الأثرية
    • متغيرات البيئة وتوسيع التلدة
    • فترة الاحتفاظ
    • استخدام المخرجات
      • مثال الإخراج بين الخطوات
      • مثال الإخراج بين الوظائف
    • الكتابة فوق قطعة أثرية
  • القيود
    • عدد القطع الأثرية
    • أرشيفات مضغوطة
    • فقدان الإذن
  • أين يذهب التحميل؟

v4 - ما الجديد

مهم

upload-artifact@v4+ غير مدعوم حاليًا على GHES حتى الآن. إذا كنت تستخدم GHES، فيجب عليك استخدام الإصدار 3.

يعد إصدار upload-artifact@v4 وdownload-artifact@v4 بمثابة تغييرات كبيرة في بنية الواجهة الخلفية لـ Artifacts. لديهم العديد من التحسينات في الأداء والسلوك.

لمزيد من المعلومات، راجع وثائق @actions/artifact .

هناك أيضًا إجراء فرعي جديد، actions/upload-artifact/merge . لمزيد من المعلومات، راجع الملف التمهيدي الخاص بهذا الإجراء.

التحسينات

1. أصبحت عمليات التحميل أسرع بشكل ملحوظ، وتحسنت بنسبة تصل إلى 90% في أسوأ السيناريوهات.
2. بمجرد التحميل، يتم إرجاع معرف القطعة الأثرية وتكون القطع الأثرية متاحة على الفور في واجهة المستخدم وREST API. في السابق، كان يتعين عليك الانتظار حتى يكتمل التشغيل قبل أن يتوفر المعرف أو يمكن استخدام أي واجهات برمجة التطبيقات.
3. يتم تحميل محتويات القطعة الأثرية معًا في أرشيف غير قابل للتغيير . ولا يمكن تغييرها من خلال المهام اللاحقة ما لم يتم حذف القطع الأثرية وإعادة إنشائها (حيث سيكون لها معرف جديد). يساعد كلا هذين العاملين على تقليل احتمالية إتلاف ملفات Artifact عن طريق الخطأ.
4. يمكن تعديل مستوى ضغط القطعة الأثرية يدويًا لتقليل السرعة أو الحجم.

كسر التغييرات

1. في برامج التشغيل المستضافة ذاتيًا، قد تكون هناك حاجة إلى قواعد إضافية لجدار الحماية.

2. التحميل إلى نفس القطعة الأثرية المسماة عدة مرات.

   نظرًا لكيفية إنشاء القطع الأثرية في هذا الإصدار الجديد، لم يعد من الممكن التحميل على نفس القطعة الأثرية عدة مرات. يجب عليك إما تقسيم التحميلات إلى عناصر متعددة بأسماء مختلفة، أو التحميل مرة واحدة فقط. وإلا سوف تواجه خطأ.

3. الحد من القطع الأثرية لوظيفة فردية. أصبح الآن لكل مهمة في مسار سير العمل حدًا يبلغ 500 قطعة أثرية.

4. مع v4.4 والإصدارات الأحدث، يتم استبعاد الملفات المخفية افتراضيًا.

للحصول على مساعدة بشأن التغييرات العاجلة، راجع MIGRATION.md.

الاستخدام

المدخلات

- uses : actions/upload-artifact@v4
  with :
    # Name of the artifact to upload.
    # Optional. Default is 'artifact'
    name :

    # A file, directory or wildcard pattern that describes what to upload
    # Required.
    path :

    # The desired behavior if no files are found using the provided path.
    # Available Options:
    #   warn: Output a warning but do not fail the action
    #   error: Fail the action with an error message
    #   ignore: Do not output any warnings or errors, the action does not fail
    # Optional. Default is 'warn'
    if-no-files-found :

    # Duration after which artifact will expire in days. 0 means using default retention.
    # Minimum 1 day.
    # Maximum 90 days unless changed from the repository settings page.
    # Optional. Defaults to repository settings.
    retention-days :

    # The level of compression for Zlib to be applied to the artifact archive.
    # The value can range from 0 to 9.
    # For large files that are not easily compressed, a value of 0 is recommended for significantly faster uploads.
    # Optional. Default is '6'
    compression-level :

    # If true, an artifact with a matching name will be deleted before a new one is uploaded.
    # If false, the action will fail if an artifact for the given name already exists.
    # Does not fail if the artifact does not exist.
    # Optional. Default is 'false'
    overwrite :

    # Whether to include hidden files in the provided path in the artifact
    # The file contents of any hidden files in the path should be validated before
    # enabled this to avoid uploading sensitive information.
    # Optional. Default is 'false'
    include-hidden-files :

النواتج

اسم	وصف	مثال
artifact-id	يمكن استخدام معرف GitHub الخاص بالقطعة الأثرية بواسطة REST API	1234
artifact-url	عنوان URL لتنزيل قطعة أثرية. يمكن استخدامه في العديد من السيناريوهات مثل الارتباط بالعناصر الموجودة في المشكلات أو طلبات السحب. يجب على المستخدمين تسجيل الدخول حتى يعمل عنوان URL هذا. عنوان URL هذا صالح طالما لم تنته صلاحية العنصر أو لم يتم حذف العنصر أو التشغيل أو المستودع	https://github.com/example-org/example-repo/actions/runs/1/artifacts/1234

أمثلة

تحميل ملف فردي

 steps :
- run : mkdir -p path/to/artifact
- run : echo hello > path/to/artifact/world.txt
- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : path/to/artifact/world.txt

تحميل دليل كامل

- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : path/to/artifact/ # or path/to/artifact

تحميل باستخدام نمط Wildcard

- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : path/**/[abc]rtifac?/*

التحميل باستخدام مسارات واستثناءات متعددة

- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : |
      path/output/bin/
      path/output/test-results
      !path/**/*.tmp

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

إذا تم استخدام نمط حرف البدل، فسيتم الحفاظ على التسلسل الهرمي للمسار بعد نمط حرف البدل الأول:

 path/to/*/directory/foo?.txt =>
    ∟ path/to/some/directory/foo1.txt
    ∟ path/to/some/directory/foo2.txt
    ∟ path/to/other/directory/foo1.txt

would be flattened and uploaded as =>
    ∟ some/directory/foo1.txt
    ∟ some/directory/foo2.txt
    ∟ other/directory/foo1.txt

إذا تم توفير مسارات متعددة كمدخل، فسيتم استخدام السلف المشترك الأقل لجميع مسارات البحث كدليل جذر للعنصر. لا يؤثر استبعاد المسارات على بنية الدليل.

يُسمح بمسارات الملفات النسبية والمطلقة. يتم تجذير المسارات النسبية مقابل دليل العمل الحالي. يجب أن يتم اقتباس المسارات التي تبدأ بحرف بدل لتجنب تفسيرها على أنها أسماء مستعارة لـ YAML.

تغيير مستوى الضغطات (السرعة مقابل الحجم)

إذا كنت تقوم بتحميل بيانات كبيرة أو قابلة للضغط بسهولة إلى العنصر الخاص بك، فقد تستفيد من تعديل مستوى الضغط. افتراضيًا، مستوى الضغط هو 6 ، وهو نفس مستوى GNU Gzip.

يمكن أن تتراوح القيمة من 0 إلى 9:

• 0: لا يوجد ضغط
• 1: أفضل سرعة
• 6: الضغط الافتراضي (مثل GNU Gzip)
• 9: أفضل ضغط

ستؤدي المستويات الأعلى إلى ضغط أفضل، ولكنها ستستغرق وقتًا أطول حتى تكتمل. بالنسبة للملفات الكبيرة التي لا يمكن ضغطها بسهولة، يوصى باستخدام القيمة 0 لعمليات تحميل أسرع بشكل ملحوظ.

على سبيل المثال، إذا كنت تقوم بتحميل بيانات ثنائية عشوائية، فيمكنك توفير الكثير من الوقت عن طريق إلغاء الاشتراك تمامًا، حيث لن يكون ذلك مفيدًا:

- name : Make a 1GB random binary file
  run : |
    dd if=/dev/urandom of=my-1gb-file bs=1M count=1000
- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : my-1gb-file
    compression-level : 0 # no compression

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

- name : Make a file with a lot of repeated text
  run : |
    for i in {1..100000}; do echo -n 'foobar' >> foobar.txt; done
- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : foobar.txt
    compression-level : 9 # maximum compression

التخصيص في حالة عدم العثور على ملفات

إذا أدى المسار (أو المسارات) إلى عدم العثور على ملفات للعنصر، فسينجح الإجراء ولكن سيطبع تحذيرًا. في بعض السيناريوهات، قد يكون من المرغوب فيه فشل الإجراء أو منع التحذير. يتيح لك خيار if-no-files-found تخصيص سلوك الإجراء في حالة عدم العثور على ملفات:

- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : path/to/artifact/
    if-no-files-found : error # 'warn' or 'ignore' are also available, defaults to `warn`

(لا) التحميل على نفس القطعة الأثرية

على عكس الإصدارات السابقة من upload-artifact ، فإن التحميل إلى نفس العنصر عبر مهام متعددة غير مدعوم في v4 .

- run : echo hi > world.txt
- uses : actions/upload-artifact@v4
  with :
    # implicitly named as 'artifact'
    path : world.txt

- run : echo howdy > extra-file.txt
- uses : actions/upload-artifact@v4
  with :
    # also implicitly named as 'artifact', will fail here!
    path : extra-file.txt

يجب أن تكون أسماء القطع الأثرية فريدة نظرًا لأن كل قطعة أثرية تم إنشاؤها تكون غير فعالة، لذا لا يمكن للوظائف المتعددة تعديل نفس القطعة الأثرية.

في سيناريوهات المصفوفة، احرص على عدم التحميل عن طريق الخطأ إلى نفس العنصر، وإلا فسوف تواجه أخطاء تعارض. سيكون من الأفضل تسمية القطعة الأثرية ببادئة أو لاحقة من المصفوفة:

 jobs :
  upload :
    name : Generate Build Artifacts

    strategy :
      matrix :
        os : [ubuntu-latest, windows-latest]
        version : [a, b, c]

    runs-on : ${{ matrix.os }}

    steps :
    - name : Build
      run : ./some-script --version=${{ matrix.version }} > my-binary
    - name : Upload
      uses : actions/upload-artifact@v4
      with :
        name : binary-${{ matrix.os }}-${{ matrix.version }}
        path : my-binary

سيؤدي هذا إلى نتائج مثل: binary-ubuntu-latest-a و binary-windows-latest-b وما إلى ذلك.

في السابق، كان السلوك يسمح بأن تكون أسماء القطع الأثرية هي نفسها مما أدى إلى حدوث طفرات غير متوقعة وفساد عرضي. القطع الأثرية التي تم إنشاؤها بواسطة upload-artifact@v4 غير قابلة للتغيير.

متغيرات البيئة وتوسيع التلدة

يمكنك استخدام ~ في إدخال المسار كبديل لـ $HOME . يتم دعم توسيع التلدة الأساسية:

  - run : |
      mkdir -p ~/new/artifact
      echo hello > ~/new/artifact/world.txt
  - uses : actions/upload-artifact@v4
    with :
      name : my-artifacts
      path : ~/new/**/*

يمكن أيضًا استخدام متغيرات البيئة جنبًا إلى جنب مع تعبيرات السياق للإدخال. للحصول على التوثيق، راجع السياق وبناء جملة التعبير:

    env :
      name : my-artifact
    steps :
    - run : |
        mkdir -p ${{ github.workspace }}/artifact
        echo hello > ${{ github.workspace }}/artifact/world.txt
    - uses : actions/upload-artifact@v4
      with :
        name : ${{ env.name }}-name
        path : ${{ github.workspace }}/artifact/**/*

بالنسبة لمتغيرات البيئة التي تم إنشاؤها في خطوات أخرى، تأكد من استخدام صيغة تعبير env

    steps :
    - run : |
        mkdir testing
        echo "This is a file to upload" > testing/file.txt
        echo "artifactPath=testing/file.txt" >> $GITHUB_ENV
    - uses : actions/upload-artifact@v4
      with :
        name : artifact
        path : ${{ env.artifactPath }} # this will resolve to testing/file.txt at runtime

فترة الاحتفاظ

يتم الاحتفاظ بالقطع الأثرية لمدة 90 يومًا بشكل افتراضي. يمكنك تحديد فترة احتفاظ أقصر باستخدام إدخال retention-days :

  - name : Create a file
    run : echo "I won't live long" > my_file.txt

  - name : Upload Artifact
    uses : actions/upload-artifact@v4
    with :
      name : my-artifact
      path : my_file.txt
      retention-days : 5

يجب أن تكون فترة الاحتفاظ بين 1 و90 ضمناً. لمزيد من المعلومات، راجع سياسات الاحتفاظ بالعناصر والسجلات.

استخدام المخرجات

إذا نجح تحميل قطعة أثرية، فسيكون مخرج artifact-id متاحًا. هذا المعرف هو معرف فريد يمكن استخدامه مع Artifact REST APIs.

مثال الإخراج بين الخطوات

    - uses : actions/upload-artifact@v4
      id : artifact-upload-step
      with :
        name : my-artifact
        path : path/to/artifact/content/

    - name : Output artifact ID
      run :  echo 'Artifact ID is ${{ steps.artifact-upload-step.outputs.artifact-id }}' 

مثال الإخراج بين الوظائف

 jobs :
  job1 :
    runs-on : ubuntu-latest
    outputs :
      output1 : ${{ steps.artifact-upload-step.outputs.artifact-id }}
    steps :
      - uses : actions/upload-artifact@v4
        id : artifact-upload-step
        with :
          name : my-artifact
          path : path/to/artifact/content/
  job2 :
    runs-on : ubuntu-latest
    needs : job1
    steps :
      - env :
          OUTPUT1 : ${{needs.job1.outputs.output1}}
        run : echo "Artifact ID from previous job is $OUTPUT1"

الكتابة فوق قطعة أثرية

على الرغم من أنه ليس من الممكن تحوير قطعة أثرية، إلا أنه يمكن استبدالها بالكامل. لكن لاحظ أن هذا سيعطي القطعة الأثرية معرفًا جديدًا، ولن يكون المعرف السابق موجودًا بعد الآن:

 jobs :
  upload :
    runs-on : ubuntu-latest
    steps :
      - name : Create a file
        run : echo "hello world" > my-file.txt
      - name : Upload Artifact
        uses : actions/upload-artifact@v4
        with :
          name : my-artifact # NOTE: same artifact name
          path : my-file.txt
  upload-again :
    needs : upload
    runs-on : ubuntu-latest
    steps :
      - name : Create a different file
        run : echo "goodbye world" > my-file.txt
      - name : Upload Artifact
        uses : actions/upload-artifact@v4
        with :
          name : my-artifact # NOTE: same artifact name
          path : my-file.txt
          overwrite : true

تحميل الملفات المخفية

افتراضيًا، يتم تجاهل الملفات المخفية من خلال هذا الإجراء لتجنب تحميل معلومات حساسة عن غير قصد.

إذا كنت بحاجة إلى تحميل الملفات المخفية، يمكنك استخدام إدخال include-hidden-files . يمكن استبعاد أي ملفات تحتوي على معلومات حساسة لا ينبغي أن تكون في العنصر الذي تم تحميله باستخدام path :

- uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    include-hidden-files : true
    path : |
      path/output/
      !path/output/.production.env

يتم تعريف الملفات المخفية على أنها أي ملف يبدأ بـ . أو الملفات الموجودة داخل المجلدات التي تبدأ بـ . . في نظام التشغيل Windows، لا تعتبر الملفات والأدلة التي تحتوي على السمة المخفية ملفات مخفية إلا إذا كانت تحتوي على الملحق . بادئة.

القيود

عدد القطع الأثرية

ضمن الوظيفة الفردية، يوجد حد 500 قطعة أثرية يمكن إنشاؤها لهذه المهمة.

قد تكون أيضًا مقيدًا بالمصنوعات إذا تجاوزت حصة التخزين المشتركة الخاصة بك. يتم حساب التخزين كل 6-12 ساعة. راجع الوثائق لمزيد من المعلومات.

أرشيفات مضغوطة

عندما يتم تحميل قطعة أثرية، يتم تجميع كافة الملفات في أرشيف مضغوط غير قابل للتغيير. لا توجد حاليًا طريقة لتنزيل العناصر بتنسيق آخر غير ملف Zip أو لتنزيل محتويات العناصر الفردية.

فقدان الإذن

لا يتم الاحتفاظ بأذونات الملف أثناء تحميل العناصر. ستحتوي جميع الدلائل على 755 وستحتوي جميع الملفات على 644 . على سبيل المثال، إذا قمت بإنشاء ملف قابل للتنفيذ باستخدام chmod ثم قمت بتحميل هذا الملف، فلن يكون من المضمون تعيين الملف بعد التنزيل كملف قابل للتنفيذ.

إذا كان يجب عليك الحفاظ على الأذونات، فيمكنك tar كل ملفاتك معًا قبل تحميل العناصر. بعد التنزيل، سيحتفظ ملف tar بأذونات الملف وحساسية حالة الأحرف.

- name : ' Tar files '
  run : tar -cvf my_files.tar /path/to/my/directory

- name : ' Upload Artifact '
  uses : actions/upload-artifact@v4
  with :
    name : my-artifact
    path : my_files.tar 

أين يذهب التحميل؟

يوجد في أسفل صفحة ملخص سير العمل قسم مخصص للعناصر. إليك لقطة شاشة لشيء قد تراه:

هناك أيقونة سلة المهملات التي يمكن استخدامها لحذف القطعة الأثرية. سيظهر هذا الرمز فقط للمستخدمين الذين لديهم أذونات الكتابة إلى المستودع.

يتم الإشارة إلى حجم القطعة الأثرية بالبايت. يشير حجم القطعة الأثرية المعروضة إلى حجم الملف المضغوط الذي تنشئه upload-artifact أثناء التحميل.