Merge pull request #505 from actions/robherley/merge-artifacts

Add sub-action to merge artifacts

.github/workflows/test.yml

@@ -141,12 +141,16 @@ jobs:
         }
       shell: pwsh
 
+    - name: 'Alter file 1 content'
+      run: |
+        echo "This file has changed" > path/to/dir-1/file1.txt
+
     # Replace the contents of Artifact #1
-    - name: 'Overwrite artifact #1 again'
+    - name: 'Overwrite artifact #1'
       uses: ./
       with:
         name: 'Artifact-A-${{ matrix.runs-on }}'
-        path: path/to/dir-2/file2.txt
+        path: path/to/dir-1/file1.txt
         overwrite: true
 
     # Download replaced Artifact #1 and verify the correctness of the content
@@ -158,13 +162,90 @@ jobs:
 
     - name: 'Verify Artifact #1 again'
       run: |
-        $file = "overwrite/some/new/path/file2.txt"
+        $file = "overwrite/some/new/path/file1.txt"
         if(!(Test-Path -path $file))
         {
             Write-Error "Expected file does not exist"
         }
-        if(!((Get-Content $file) -ceq "Hello world from file #2"))
+        if(!((Get-Content $file) -ceq "This file has changed"))
         {
-            Write-Error "File contents of downloaded artifacts are incorrect"
+            Write-Error "File contents of downloaded artifact are incorrect"
         }
       shell: pwsh
+  merge:
+    name: Merge
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    # Merge all artifacts from previous jobs
+    - name: Merge all artifacts in run
+      uses: ./merge/
+      with:
+        # our matrix produces artifacts with the same file, this prevents "stomping" on each other, also makes it
+        # easier to identify each of the merged artifacts
+        separate-directories: true
+    - name: 'Download merged artifacts'
+      uses: actions/download-artifact@v4
+      with:
+        name: merged-artifacts
+        path: all-merged-artifacts
+    - name: 'Check merged artifact has directories for each artifact'
+      run: |
+        $artifacts = @(
+          "Artifact-A-ubuntu-latest",
+          "Artifact-A-macos-latest",
+          "Artifact-A-windows-latest",
+          "Artifact-Wildcard-ubuntu-latest",
+          "Artifact-Wildcard-macos-latest",
+          "Artifact-Wildcard-windows-latest",
+          "Multi-Path-Artifact-ubuntu-latest",
+          "Multi-Path-Artifact-macos-latest",
+          "Multi-Path-Artifact-windows-latest"
+        )
+
+        foreach ($artifact in $artifacts) {
+          $path = "all-merged-artifacts/$artifact"
+          if (!(Test-Path $path)) {
+            Write-Error "$path does not exist."
+          }
+        }
+      shell: pwsh
+
+    # Merge Artifact-A-* from previous jobs
+    - name: Merge all Artifact-A
+      uses: ./merge/
+      with:
+        name: Merged-Artifact-As
+        pattern: 'Artifact-A-*'
+        separate-directories: true
+
+    # Download merged artifacts and verify the correctness of the content
+    - name: 'Download merged artifacts'
+      uses: actions/download-artifact@v4
+      with:
+        name: Merged-Artifact-As
+        path: merged-artifact-a
+
+    - name: 'Verify merged artifacts'
+      run: |
+        $files = @(
+          "merged-artifact-a/Artifact-A-ubuntu-latest/file1.txt",
+          "merged-artifact-a/Artifact-A-macos-latest/file1.txt",
+          "merged-artifact-a/Artifact-A-windows-latest/file1.txt"
+        )
+
+        foreach ($file in $files) {
+          if (!(Test-Path $file)) {
+            Write-Error "$file does not exist."
+          }
+
+          if (!((Get-Content $file) -ceq "This file has changed")) {
+            Write-Error "$file has incorrect content."
+          }
+        }
+      shell: pwsh
+

README.md

@@ -41,6 +41,8 @@ The release of upload-artifact@v4 and download-artifact@v4 are major changes to
 
 For more information, see the [`@actions/artifact`](https://github.com/actions/toolkit/tree/main/packages/artifact) documentation.
 
+There is also a new sub-action, `actions/upload-artifact/merge`. For more info, check out that action's [README](./merge/README.md).
+
 ### Improvements
 
 1. Uploads are significantly faster, upwards of 90% improvement in worst case scenarios.

__tests__/merge.test.ts

@@ -1,6 +1,6 @@
 import * as core from '@actions/core'
 import artifact from '@actions/artifact'
-import {run} from '../src/merge/merge-artifact'
+import {run} from '../src/merge/merge-artifacts'
 import {Inputs} from '../src/merge/constants'
 import * as search from '../src/shared/search'
 
@@ -55,7 +55,7 @@ jest.mock('fs/promises', () => ({
 /* eslint-disable no-unused-vars */
 const mockInputs = (overrides?: Partial<{[K in Inputs]?: any}>) => {
   const inputs = {
-    [Inputs.Into]: 'my-merged-artifact',
+    [Inputs.Name]: 'my-merged-artifact',
     [Inputs.Pattern]: '*',
     [Inputs.SeparateDirectories]: false,
     [Inputs.RetentionDays]: 0,

dist/merge/index.js

@@ -129402,7 +129402,7 @@ exports.Inputs = void 0;
 /* eslint-disable no-unused-vars */
 var Inputs;
 (function (Inputs) {
-    Inputs["Into"] = "into";
+    Inputs["Name"] = "name";
     Inputs["Pattern"] = "pattern";
     Inputs["SeparateDirectories"] = "separate-directories";
     Inputs["RetentionDays"] = "retention-days";
@@ -129443,8 +129443,8 @@ var __importStar = (this && this.__importStar) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 const core = __importStar(__nccwpck_require__(42186));
-const merge_artifact_1 = __nccwpck_require__(30863);
-(0, merge_artifact_1.run)().catch(error => {
+const merge_artifacts_1 = __nccwpck_require__(41636);
+(0, merge_artifacts_1.run)().catch(error => {
     core.setFailed(error.message);
 });
 
@@ -129487,12 +129487,12 @@ const constants_1 = __nccwpck_require__(80746);
  * Helper to get all the inputs for the action
  */
 function getInputs() {
-    const into = core.getInput(constants_1.Inputs.Into, { required: true });
+    const name = core.getInput(constants_1.Inputs.Name, { required: true });
     const pattern = core.getInput(constants_1.Inputs.Pattern, { required: true });
     const separateDirectories = core.getBooleanInput(constants_1.Inputs.SeparateDirectories);
     const deleteMerged = core.getBooleanInput(constants_1.Inputs.DeleteMerged);
     const inputs = {
-        into,
+        name,
         pattern,
         separateDirectories,
         deleteMerged,
@@ -129523,7 +129523,7 @@ exports.getInputs = getInputs;
 
 /***/ }),
 
-/***/ 30863:
+/***/ 41636:
 /***/ (function(__unused_webpack_module, exports, __nccwpck_require__) {
 
 "use strict";
@@ -129614,7 +129614,7 @@ function run() {
             options.compressionLevel = inputs.compressionLevel;
         }
         const searchResult = yield (0, search_1.findFilesToUpload)(tmpDir);
-        yield (0, upload_artifact_1.uploadArtifact)(inputs.into, searchResult.filesToUpload, searchResult.rootDirectory, options);
+        yield (0, upload_artifact_1.uploadArtifact)(inputs.name, searchResult.filesToUpload, searchResult.rootDirectory, options);
         core.info(`The ${artifacts.length} artifact(s) have been successfully merged!`);
         if (inputs.deleteMerged) {
             const deletePromises = artifacts.map(artifact => artifact_1.default.deleteArtifact(artifact.name));

docs/MIGRATION.md

@@ -3,6 +3,7 @@
 - [Migration](#migration)
   - [Multiple uploads to the same named Artifact](#multiple-uploads-to-the-same-named-artifact)
   - [Overwriting an Artifact](#overwriting-an-artifact)
+  - [Merging multiple artifacts](#merging-multiple-artifacts)
 
 Several behavioral differences exist between Artifact actions `v3` and below vs `v4`. This document outlines common scenarios in `v3`, and how they would be handled in `v4`.
 
@@ -142,3 +143,64 @@ jobs:
 ```
 
 Note that this will create an _entirely_ new Artifact, with a different ID from the previous.
+
+## Merging multiple artifacts
+
+In `v3`, multiple uploads from multiple jobs could be done to the same Artifact. This would result in a single archive, which could be useful for sending to upstream systems outside of Actions via API or UI downloads.
+
+```yaml
+jobs:
+  upload:
+    strategy:
+      matrix:
+        runs-on: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.runs-on }}
+    steps:
+      - name: Create a File
+        run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: all-my-files # NOTE: same artifact name
+          path: file-${{ matrix.runs-on }}.txt
+```
+
+The single `all-my-files` artifact would contain the following:
+
+```
+.
+  ∟ file-ubuntu-latest.txt
+  ∟ file-macos-latest.txt
+  ∟ file-windows-latest.txt
+```
+
+To achieve the same in `v4` you can change it like so:
+
+```diff
+jobs:
+  upload:
+    strategy:
+      matrix:
+        runs-on: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.runs-on }}
+    steps:
+      - name: Create a File
+        run: echo "hello from ${{ matrix.runs-on }}" > file-${{ matrix.runs-on }}.txt
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v3
+        with:
+-         name: all-my-files
++         name: my-artifact-${{ matrix.runs-on }}
+          path: file-${{ matrix.runs-on }}.txt
++ merge:
++   runs-on: ubuntu-latest
++   needs: upload
++   steps:
++     - name: Merge Artifacts
++       uses: actions/upload-artifact/merge@v4
++       with:
++         name: all-my-files
++         pattern: my-artifact-*
+```
+
+Note that this will download all artifacts to a temporary directory and reupload them as a single artifact. For more information on inputs and other use cases for `actions/upload-artifact/merge@v4`, see [the action documentation](../merge/README.md).

merge/README.md

@@ -7,6 +7,10 @@ Merge multiple [Actions Artifacts](https://docs.github.com/en/actions/using-work
     - [Inputs](#inputs)
     - [Outputs](#outputs)
   - [Examples](#examples)
+    - [Combining all artifacts in a workflow run](#combining-all-artifacts-in-a-workflow-run)
+    - [Prefix directories in merged artifact](#prefix-directories-in-merged-artifact)
+    - [Deleting artifacts after merge](#deleting-artifacts-after-merge)
+    - [Retention and Compression Level](#retention-and-compression-level)
 
 ## Usage
 
@@ -15,14 +19,18 @@ Merge multiple [Actions Artifacts](https://docs.github.com/en/actions/using-work
 
 Note: this actions can only merge artifacts created with actions/upload-artifact@v4+
 
+This sub-action is a helper to merge multiple artifacts after they are created. To do so, it will download multiple artifacts to a temporary directory and reupload them as a single artifact.
+
+For most cases, this may not be the most efficient solution. See [the migration docs](../docs/MIGRATION.md#multiple-uploads-to-the-same-named-artifact) on how to download multiple artifacts to the same directory on a runner. This action should only be necessary for cases where multiple artifacts will need to be downloaded outside the runner environment, like downloads via the UI or REST API.
+
 ### Inputs
 
 ```yaml
 - uses: actions/upload-artifact/merge@v4
   with:
     # The name of the artifact that the artifacts will be merged into
-    # Optional. Default is 'merged-artifact'
-    into:
+    # Optional. Default is 'merged-artifacts'
+    name:
 
     # A glob pattern matching the artifacts that should be merged.
     # Optional. Default is '*'
@@ -60,4 +68,133 @@ Note: this actions can only merge artifacts created with actions/upload-artifact
 
 ## Examples
 
-TODO(robherley): add examples
+For each of these examples, assume we have a prior job matrix that generates three artifacts: `my-artifact-a`, `my-artifact-b` and `my-artifact-c`.
+
+e.g.
+
+```yaml
+jobs:
+  upload:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        foo: [a, b, c]
+
+    steps:
+      - name: Run a one-line script
+        run: echo "hello from job ${{ matrix.foo }}" > file-${{ matrix.foo }}.txt
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: my-artifact-${{ matrix.foo }}
+          path: file-${{ matrix.foo }}.txt
+```
+
+Each of the following examples will use the `needs: upload` as a prerequesite before any merging operations.
+
+### Combining all artifacts in a workflow run
+
+By default (with no inputs), calling this action will take all the artifacts in the workflow run and combined them into a single artifact called `merged-artifacts`:
+
+```yaml
+jobs:
+  # ... <upload job> ...
+  merge:
+    runs-on: ubuntu-latest
+    needs: upload
+    steps:
+      - name: Merge Artifacts
+        uses: actions/upload-artifact/merge@v4
+```
+
+This will result in an artifact called `merged-artifacts` with the following content:
+
+```
+.
+  ∟ file-a.txt
+  ∟ file-b.txt
+  ∟ file-c.txt
+```
+
+To change the name of the artifact and filter on what artifacts are added, you can use the `name` and `pattern` inputs:
+
+```yaml
+jobs:
+  # ... <upload job> ...
+  merge:
+    runs-on: ubuntu-latest
+    needs: upload
+    steps:
+      - name: Merge Artifacts
+        uses: actions/upload-artifact/merge@v4
+        with:
+          name: my-amazing-merged-artifact
+          pattern: my-artifact-*
+```
+
+### Prefix directories in merged artifact
+
+To prevent overwriting files in artifacts that may have the same name, you can use the `separate-directories` to prefix the extracted files with directories (named after the original artifact):
+
+```yaml
+jobs:
+  # ... <upload job> ...
+  merge:
+    runs-on: ubuntu-latest
+    needs: upload
+    steps:
+      - name: Merge Artifacts
+        uses: actions/upload-artifact/merge@v4
+        with:
+          separate-directories: true
+```
+
+This will result in the following artifact structure:
+
+```
+.
+  ∟ my-artifact-a
+    ∟ file-a.txt
+  ∟ my-artifact-b
+    ∟ file-b.txt
+  ∟ my-artifact-c
+    ∟ file-c.txt
+```
+
+### Deleting artifacts after merge
+
+After merge, the old artifacts may no longer be required. To automatically delete them after they are merged into a new artifact, you can use `delete-merged` like so:
+
+```yaml
+jobs:
+  # ... <upload job> ...
+  merge:
+    runs-on: ubuntu-latest
+    needs: upload
+    steps:
+      - name: Merge Artifacts
+        uses: actions/upload-artifact/merge@v4
+        with:
+          delete-merged: true
+```
+
+After this runs, the matching artifact (`my-artifact-a`, `my-artifact-b` and `my-artifact-c`) will be merged.
+
+### Retention and Compression Level
+
+Similar to actions/upload-artifact, both [`retention-days`](../README.md#retention-period) and [`compression-level`](../README.md#altering-compressions-level-speed-v-size) are supported:
+
+```yaml
+jobs:
+  # ... <upload job> ...
+  merge:
+    runs-on: ubuntu-latest
+    needs: upload
+    steps:
+      - name: Merge Artifacts
+        uses: actions/upload-artifact/merge@v4
+        with:
+          retention-days: 1
+          compression-level: 9
+```

merge/action.yml

@@ -2,10 +2,10 @@ name: 'Merge Build Artifacts'
 description: 'Merge one or more build Artifacts'
 author: 'GitHub'
 inputs:
-  into:
+  name:
     description: 'The name of the artifact that the artifacts will be merged into.'
     required: true
-    default: 'merged-artifact'
+    default: 'merged-artifacts'
   pattern:
     description: 'A glob pattern matching the artifact names that should be merged.'
     default: '*'

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "upload-artifact",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "upload-artifact",
-      "version": "4.2.0",
+      "version": "4.3.0",
       "license": "MIT",
       "dependencies": {
         "@actions/artifact": "^2.1.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "upload-artifact",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Upload an Actions Artifact in a workflow run",
   "main": "dist/upload/index.js",
   "scripts": {

src/merge/constants.ts

@@ -1,6 +1,6 @@
 /* eslint-disable no-unused-vars */
 export enum Inputs {
-  Into = 'into',
+  Name = 'name',
   Pattern = 'pattern',
   SeparateDirectories = 'separate-directories',
   RetentionDays = 'retention-days',

src/merge/index.ts

@@ -1,5 +1,5 @@
 import * as core from '@actions/core'
-import {run} from './merge-artifact'
+import {run} from './merge-artifacts'
 
 run().catch(error => {
   core.setFailed((error as Error).message)

src/merge/input-helper.ts

@@ -6,13 +6,13 @@ import {MergeInputs} from './merge-inputs'
  * Helper to get all the inputs for the action
  */
 export function getInputs(): MergeInputs {
-  const into = core.getInput(Inputs.Into, {required: true})
+  const name = core.getInput(Inputs.Name, {required: true})
   const pattern = core.getInput(Inputs.Pattern, {required: true})
   const separateDirectories = core.getBooleanInput(Inputs.SeparateDirectories)
   const deleteMerged = core.getBooleanInput(Inputs.DeleteMerged)
 
   const inputs = {
-    into,
+    name,
     pattern,
     separateDirectories,
     deleteMerged,

src/merge/merge-artifacts.ts

@@ -65,7 +65,7 @@ export async function run(): Promise<void> {
   const searchResult = await findFilesToUpload(tmpDir)
 
   await uploadArtifact(
-    inputs.into,
+    inputs.name,
     searchResult.filesToUpload,
     searchResult.rootDirectory,
     options

src/merge/merge-inputs.ts

@@ -2,7 +2,7 @@ export interface MergeInputs {
   /**
    * The name of the artifact that the artifacts will be merged into
    */
-  into: string
+  name: string
 
   /**
    * A glob pattern matching the artifacts that should be merged.