From 199a58f54fa418c391917374e9d11f5a5e618ae9 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Mon, 22 Jan 2024 22:24:56 -0500 Subject: [PATCH] more docs --- docs/MIGRATION.md | 62 +++++++++++++++++++++ merge/README.md | 139 +++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 200 insertions(+), 1 deletion(-) diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 63d8b09..1b5ce69 100644 --- a/docs/MIGRATION.md +++ b/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). diff --git a/merge/README.md b/merge/README.md index ff75372..b2f390e 100644 --- a/merge/README.md +++ b/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,6 +19,10 @@ 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 @@ -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: + # ... ... + 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: + # ... ... + 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: + # ... ... + 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: + # ... ... + 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: + # ... ... + merge: + runs-on: ubuntu-latest + needs: upload + steps: + - name: Merge Artifacts + uses: actions/upload-artifact/merge@v4 + with: + retention-days: 1 + compression-level: 9 +```