add 'merge' action

.github/workflows/check-dist.yml

@@ -34,7 +34,7 @@ jobs:
         run: npm ci
 
       - name: Rebuild the dist/ directory
-        run: npm run build
+        run: npm run release
 
       - name: Compare the expected and actual dist/ directories
         run: |

__tests__/search.test.ts

@@ -2,7 +2,7 @@ import * as core from '@actions/core'
 import * as path from 'path'
 import * as io from '@actions/io'
 import {promises as fs} from 'fs'
-import {findFilesToUpload} from '../src/search'
+import {findFilesToUpload} from '../src/shared/search'
 
 const root = path.join(__dirname, '_temp', 'search')
 const searchItem1Path = path.join(

action.yml

@@ -58,4 +58,4 @@ outputs:
       Common uses cases for such a download URL can be adding download links to artifacts in descriptions or comments on pull requests or issues.
 runs:
   using: 'node20'
-  main: 'dist/index.js'
+  main: 'dist/upload/index.js'

merge/README.md

@@ -0,0 +1,63 @@
+# `@actions/upload-artifact/merge`
+
+Merge multiple [Actions Artifacts](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts) in Workflow Runs. Internally powered by [@actions/artifact](https://github.com/actions/toolkit/tree/main/packages/artifact) package.
+
+- [`@actions/upload-artifact/merge`](#actionsupload-artifactmerge)
+  - [Usage](#usage)
+    - [Inputs](#inputs)
+    - [Outputs](#outputs)
+  - [Examples](#examples)
+
+## Usage
+
+> [!IMPORTANT]
+> upload-artifact/merge@v4+ is not currently supported on GHES.
+
+Note: this actions can only merge artifacts created with actions/upload-artifact@v4+
+
+### 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:
+
+    # A glob pattern matching the artifacts that should be merged.
+    # Optional. Default is '*'
+    pattern:
+
+    # If true, the artifacts will be merged into separate directories.
+    # If false, the artifacts will be merged into the root of the destination.
+    # Optional. Default is 'false'
+    separate-directories:
+
+    # If true, the artifacts that were merged will be deleted.
+    # If false, the artifacts will still exist.
+    # Optional. Default is 'false'
+    delete-merged:
+
+    # 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:
+```
+
+### Outputs
+
+| Name | Description | Example |
+| - | - | - |
+| `artifact-id` | GitHub ID of an Artifact, can be used by the REST API | `1234` |
+| `artifact-url` | URL to download an Artifact. Can be used in many scenarios such as linking to artifacts in issues or pull requests. Users must be logged-in in order for this URL to work. This URL is valid as long as the artifact has not expired or the artifact, run or repository have not been deleted | `https://github.com/example-org/example-repo/actions/runs/1/artifacts/1234` |
+
+## Examples
+
+TODO(robherley): add examples

merge/action.yml

@@ -0,0 +1,57 @@
+name: 'Merge Build Artifacts'
+description: 'Merge one or more build Artifacts'
+author: 'GitHub'
+inputs:
+  into:
+    description: 'The name of the artifact that the artifacts will be merged into.'
+    required: true
+    default: 'merged-artifact'
+  pattern:
+    description: 'A glob pattern matching the artifact names that should be merged.'
+    default: '*'
+  separate-directories:
+    description: 'When multiple artifacts are matched, this changes the behavior of how they are merged in the archive.
+      If true, the matched artifacts will be extracted into individual named directories within the specified path.
+      If false, the matched artifacts will combined in the same directory.'
+    default: 'false'
+  retention-days:
+    description: >
+      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.
+  compression-level:
+    description: >
+      The level of compression for Zlib to be applied to the artifact archive.
+      The value can range from 0 to 9:
+      - 0: No compression
+      - 1: Best speed
+      - 6: Default compression (same as GNU Gzip)
+      - 9: Best compression
+      Higher levels will result in better compression, but will take longer to complete.
+      For large files that are not easily compressed, a value of 0 is recommended for significantly faster uploads.
+    default: '6'
+  delete-merged:
+    description: >
+      If true, the artifacts that were merged will be deleted.
+      If false, the artifacts will still exist.
+    default: 'false'
+
+outputs:
+  artifact-id:
+    description: >
+      A unique identifier for the artifact that was just uploaded. Empty if the artifact upload failed.
+
+      This ID can be used as input to other APIs to download, delete or get more information about an artifact: https://docs.github.com/en/rest/actions/artifacts
+  artifact-url:
+    description: >
+      A download URL for the artifact that was just uploaded. Empty if the artifact upload failed.
+
+      This download URL only works for requests Authenticated with GitHub. Anonymous downloads will be prompted to first login. 
+      If an anonymous download URL is needed than a short time restricted URL can be generated using the download artifact API: https://docs.github.com/en/rest/actions/artifacts#download-an-artifact    
+
+      This URL will be valid for as long as the artifact exists and the workflow run and repository exists. Once an artifact has expired this URL will no longer work.
+      Common uses cases for such a download URL can be adding download links to artifacts in descriptions or comments on pull requests or issues.
+runs:
+  using: 'node20'
+  main: 'dist/merge/index.js'

package.json

@@ -2,10 +2,10 @@
   "name": "upload-artifact",
   "version": "4.2.0",
   "description": "Upload an Actions Artifact in a workflow run",
-  "main": "dist/index.js",
+  "main": "dist/upload/index.js",
   "scripts": {
     "build": "tsc",
-    "release": "ncc build src/upload-artifact.ts && git add -f dist/index.js",
+    "release": "ncc build src/upload/index.ts -o dist/upload && ncc build src/merge/index.ts -o dist/merge",
     "check-all": "concurrently \"npm:format-check\" \"npm:lint\" \"npm:test\" \"npm:build\"",
     "format": "prettier --write **/*.ts",
     "format-check": "prettier --check **/*.ts",
@@ -33,7 +33,8 @@
     "@actions/core": "^1.10.0",
     "@actions/github": "^6.0.0",
     "@actions/glob": "^0.3.0",
-    "@actions/io": "^1.1.2"
+    "@actions/io": "^1.1.2",
+    "minimatch": "^9.0.3"
   },
   "devDependencies": {
     "@types/jest": "^29.2.5",

src/merge/constants.ts

@@ -0,0 +1,9 @@
+/* eslint-disable no-unused-vars */
+export enum Inputs {
+  Into = 'into',
+  Pattern = 'pattern',
+  SeparateDirectories = 'separate-directories',
+  RetentionDays = 'retention-days',
+  CompressionLevel = 'compression-level',
+  DeleteMerged = 'delete-merged'
+}

src/merge/index.ts

@@ -0,0 +1,102 @@
+import * as path from 'path'
+import {mkdtemp, rm} from 'fs/promises'
+import * as core from '@actions/core'
+import {Minimatch} from 'minimatch'
+import artifactClient, {UploadArtifactOptions} from '@actions/artifact'
+import {getInputs} from './input-helper'
+import {uploadArtifact} from '../shared/upload-artifact'
+import {findFilesToUpload} from '../shared/search'
+
+const PARALLEL_DOWNLOADS = 5
+
+export const chunk = <T>(arr: T[], n: number): T[][] =>
+  arr.reduce((acc, cur, i) => {
+    const index = Math.floor(i / n)
+    acc[index] = [...(acc[index] || []), cur]
+    return acc
+  }, [] as T[][])
+
+async function run(): Promise<void> {
+  try {
+    const inputs = getInputs()
+    const tmpDir = await mkdtemp('merge-artifact')
+
+    const listArtifactResponse = await artifactClient.listArtifacts({
+      latest: true
+    })
+    const matcher = new Minimatch(inputs.pattern)
+    const artifacts = listArtifactResponse.artifacts.filter(artifact =>
+      matcher.match(artifact.name)
+    )
+    core.debug(
+      `Filtered from ${listArtifactResponse.artifacts.length} to ${artifacts.length} artifacts`
+    )
+
+    if (artifacts.length === 0) {
+      throw new Error(`No artifacts found matching pattern '${inputs.pattern}'`)
+    }
+
+    core.info(`Preparing to download the following artifacts:`)
+    artifacts.forEach(artifact => {
+      core.info(
+        `- ${artifact.name} (ID: ${artifact.id}, Size: ${artifact.size})`
+      )
+    })
+
+    const downloadPromises = artifacts.map(artifact =>
+      artifactClient.downloadArtifact(artifact.id, {
+        ...options,
+        path: inputs.separateDirectories
+          ? path.join(tmpDir, artifact.name)
+          : tmpDir
+      })
+    )
+
+    const chunkedPromises = chunk(downloadPromises, PARALLEL_DOWNLOADS)
+    for (const chunk of chunkedPromises) {
+      await Promise.all(chunk)
+    }
+
+    const options: UploadArtifactOptions = {}
+    if (inputs.retentionDays) {
+      options.retentionDays = inputs.retentionDays
+    }
+
+    if (typeof inputs.compressionLevel !== 'undefined') {
+      options.compressionLevel = inputs.compressionLevel
+    }
+
+    const searchResult = await findFilesToUpload(tmpDir)
+
+    await uploadArtifact(
+      inputs.into,
+      searchResult.filesToUpload,
+      searchResult.rootDirectory,
+      options
+    )
+
+    core.info(
+      `The ${artifacts.length} artifact(s) have been successfully merged!`
+    )
+
+    if (inputs.deleteMerged) {
+      const deletePromises = artifacts.map(artifact =>
+        artifactClient.deleteArtifact(artifact.name)
+      )
+      await Promise.all(deletePromises)
+      core.info(`The ${artifacts.length} artifact(s) have been deleted`)
+    }
+
+    try {
+      await rm(tmpDir, {recursive: true})
+    } catch (error) {
+      core.warning(
+        `Unable to remove temporary directory: ${(error as Error).message}`
+      )
+    }
+  } catch (error) {
+    core.setFailed((error as Error).message)
+  }
+}
+
+run()

src/merge/input-helper.ts

@@ -0,0 +1,44 @@
+import * as core from '@actions/core'
+import {Inputs} from './constants'
+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 pattern = core.getInput(Inputs.Pattern, {required: true})
+  const separateDirectories = core.getBooleanInput(Inputs.SeparateDirectories)
+  const deleteMerged = core.getBooleanInput(Inputs.DeleteMerged)
+
+  const inputs = {
+    into,
+    pattern,
+    separateDirectories,
+    deleteMerged,
+    retentionDays: 0,
+    compressionLevel: 6
+  } as MergeInputs
+
+  const retentionDaysStr = core.getInput(Inputs.RetentionDays)
+  if (retentionDaysStr) {
+    inputs.retentionDays = parseInt(retentionDaysStr)
+    if (isNaN(inputs.retentionDays)) {
+      core.setFailed('Invalid retention-days')
+    }
+  }
+
+  const compressionLevelStr = core.getInput(Inputs.CompressionLevel)
+  if (compressionLevelStr) {
+    inputs.compressionLevel = parseInt(compressionLevelStr)
+    if (isNaN(inputs.compressionLevel)) {
+      core.setFailed('Invalid compression-level')
+    }
+
+    if (inputs.compressionLevel < 0 || inputs.compressionLevel > 9) {
+      core.setFailed('Invalid compression-level. Valid values are 0-9')
+    }
+  }
+
+  return inputs
+}

src/merge/merge-inputs.ts

@@ -0,0 +1,33 @@
+export interface MergeInputs {
+  /**
+   * The name of the artifact that the artifacts will be merged into
+   */
+  into: string
+
+  /**
+   * A glob pattern matching the artifacts that should be merged.
+   */
+  pattern: string
+
+  /**
+   * Duration after which artifact will expire in days
+   */
+  retentionDays: number
+
+  /**
+   * The level of compression for Zlib to be applied to the artifact archive.
+   */
+  compressionLevel?: number
+
+  /**
+   * If true, the artifacts that were merged will be deleted.
+   * If false, the artifacts will still exist.
+   */
+  deleteMerged: boolean
+
+  /**
+   * If true, the artifacts will be merged into separate directories.
+   * If false, the artifacts will be merged into the root of the destination.
+   */
+  separateDirectories: boolean
+}

src/shared/upload-artifact.ts

@@ -0,0 +1,28 @@
+import * as core from '@actions/core'
+import * as github from '@actions/github'
+import artifact, {UploadArtifactOptions} from '@actions/artifact'
+
+export async function uploadArtifact(
+  artifactName: string,
+  filesToUpload: string[],
+  rootDirectory: string,
+  options: UploadArtifactOptions
+) {
+  const uploadResponse = await artifact.uploadArtifact(
+    artifactName,
+    filesToUpload,
+    rootDirectory,
+    options
+  )
+
+  core.info(
+    `Artifact ${artifactName} has been successfully uploaded! Final size is ${uploadResponse.size} bytes. Artifact ID is ${uploadResponse.id}`
+  )
+  core.setOutput('artifact-id', uploadResponse.id)
+
+  const repository = github.context.repo
+  const artifactURL = `${github.context.serverUrl}/${repository.owner}/${repository.repo}/actions/runs/${github.context.runId}/artifacts/${uploadResponse.id}`
+
+  core.info(`Artifact download URL: ${artifactURL}`)
+  core.setOutput('artifact-url', artifactURL)
+}

src/upload/index.ts

@@ -1,12 +1,12 @@
 import * as core from '@actions/core'
-import * as github from '@actions/github'
 import artifact, {
   UploadArtifactOptions,
   ArtifactNotFoundError
 } from '@actions/artifact'
-import {findFilesToUpload} from './search'
+import {findFilesToUpload} from '../shared/search'
 import {getInputs} from './input-helper'
 import {NoFileOptions} from './constants'
+import {uploadArtifact} from '../shared/upload-artifact'
 
 async function deleteArtifactIfExists(artifactName: string): Promise<void> {
   try {
@@ -68,23 +68,12 @@ async function run(): Promise<void> {
         options.compressionLevel = inputs.compressionLevel
       }
 
-      const uploadResponse = await artifact.uploadArtifact(
+      await uploadArtifact(
         inputs.artifactName,
         searchResult.filesToUpload,
         searchResult.rootDirectory,
         options
       )
-
-      core.info(
-        `Artifact ${inputs.artifactName} has been successfully uploaded! Final size is ${uploadResponse.size} bytes. Artifact ID is ${uploadResponse.id}`
-      )
-      core.setOutput('artifact-id', uploadResponse.id)
-
-      const repository = github.context.repo
-      const artifactURL = `${github.context.serverUrl}/${repository.owner}/${repository.repo}/actions/runs/${github.context.runId}/artifacts/${uploadResponse.id}`
-
-      core.info(`Artifact download URL: ${artifactURL}`)
-      core.setOutput('artifact-url', artifactURL)
     }
   } catch (error) {
     core.setFailed((error as Error).message)