upload artifact

@actions/upload-artifact

警告

actions/upload-artifact@v3 預定於2024 年 11 月 30 日棄用。了解更多。同樣，v1/v2 計劃於2024 年 6 月 30 日棄用。請更新您的工作流程以使用工件操作的 v4。此棄用不會影響客戶正在使用的 GitHub Enterprise Server 的任何現有版本。

從工作流程運行中上傳操作工件。由 @actions/artifact 套件內部供電。

另請參閱下載工件。

• @actions/upload-artifact
  • v4 - 新功能
    • 改進
    • 重大變化
  • 用法
    • 輸入
    • 輸出
  • 範例
    • 上傳個人文件
    • 上傳整個目錄
    • 使用通配符模式上傳
    • 使用多個路徑和排除上傳
    • 改變按壓等級（速度與大小）
    • 如果沒有找到文件則自訂
    • （不）上傳到同一個工件
    • 環境變數和波形符擴展
    • 保留期限
    • 使用輸出
      • 步驟之間的輸出範例
      • 作業之間的輸出範例
    • 覆蓋工件
  • 限制
    • 文物數量
    • 郵編檔案
    • 權限遺失
  • 上傳到哪裡？

v4 - 新功能

重要的

GHES 目前尚不支援 upload-artifact@v4+。如果您使用 GHES，則必須使用 v3。

upload-artifact@v4和download-artifact@v4的發布是Artifacts後端架構的重大改變。他們有許多性能和行為的改進。

有關更多信息，請參閱@actions/artifact文件。

還有一個新的子操作actions/upload-artifact/merge 。有關更多信息，請查看該操作的自述文件。

改進

1. 上傳速度顯著加快，在最壞的情況下可提高 90% 以上。
2. 上傳後，系統會傳回 Artifact ID，並且 Artifacts 會立即在 UI 和 REST API 中可用。以前，您必須等待運行完成才能獲得可用的 ID 或使用任何 API。
3. 工件的內容一起上傳到不可變的檔案。它們不能被後續作業更改，除非工件被刪除並重新建立（它們將具有新的 ID）。這兩個因素都有助於降低意外損壞 Artifact 檔案的可能性。
4. 可以手動調整工件的壓縮等級以提高速度或減少尺寸。

重大變化

1. 在自架運行器上，可能需要額外的防火牆規則。

2. 多次上傳到同名的 Artifact。

   由於在此新版本中建立工件的方式，無法再多次上傳到同名工件。您必須將上傳的內容分割為多個具有不同名稱的工件，或只上傳一次。否則你會遇到錯誤。

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 ID，可由 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

使用通配符模式上傳

- 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

但是，如果您上傳易於壓縮的資料（如純文字、程式碼等），則可以透過更高的壓縮等級來節省空間和成本。但這會加重 CPU 負擔，因此上傳速度會變慢：

- 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輸出可用。此 ID 是可與 Artifact REST API 一起使用的唯一識別碼。

步驟之間的輸出範例

    - 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"

覆蓋工件

雖然不可能變異神器，但可以完全覆蓋神器。但請注意，這將為 Artifact 提供一個新的 ID，先前的 ID 將不再存在：

 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 小時計算一次。請參閱文件以取得更多資訊。

郵編檔案

上傳 Artifact 後，所有檔案都會被組裝到一個不可變的 Zip 檔案中。目前無法以 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在上傳過程中所建立的 zip 的大小。