add merge artifact sub-action

__tests__/merge.test.ts

@@ -0,0 +1,175 @@
+import * as core from '@actions/core'
+import artifact from '@actions/artifact'
+import {run} from '../src/merge/merge-artifacts'
+import {Inputs} from '../src/merge/constants'
+import * as search from '../src/shared/search'
+
+const fixtures = {
+  artifactName: 'my-merged-artifact',
+  tmpDirectory: '/tmp/merge-artifact',
+  filesToUpload: [
+    '/some/artifact/path/file-a.txt',
+    '/some/artifact/path/file-b.txt',
+    '/some/artifact/path/file-c.txt'
+  ],
+  artifacts: [
+    {
+      name: 'my-artifact-a',
+      id: 1,
+      size: 100,
+      createdAt: new Date('2024-01-01T00:00:00Z')
+    },
+    {
+      name: 'my-artifact-b',
+      id: 2,
+      size: 100,
+      createdAt: new Date('2024-01-01T00:00:00Z')
+    },
+    {
+      name: 'my-artifact-c',
+      id: 3,
+      size: 100,
+      createdAt: new Date('2024-01-01T00:00:00Z')
+    }
+  ]
+}
+
+jest.mock('@actions/github', () => ({
+  context: {
+    repo: {
+      owner: 'actions',
+      repo: 'toolkit'
+    },
+    runId: 123,
+    serverUrl: 'https://github.com'
+  }
+}))
+
+jest.mock('@actions/core')
+
+jest.mock('fs/promises', () => ({
+  mkdtemp: jest.fn().mockResolvedValue('/tmp/merge-artifact'),
+  rm: jest.fn().mockResolvedValue(undefined)
+}))
+
+/* eslint-disable no-unused-vars */
+const mockInputs = (overrides?: Partial<{[K in Inputs]?: any}>) => {
+  const inputs = {
+    [Inputs.Name]: 'my-merged-artifact',
+    [Inputs.Pattern]: '*',
+    [Inputs.SeparateDirectories]: false,
+    [Inputs.RetentionDays]: 0,
+    [Inputs.CompressionLevel]: 6,
+    [Inputs.DeleteMerged]: false,
+    ...overrides
+  }
+
+  ;(core.getInput as jest.Mock).mockImplementation((name: string) => {
+    return inputs[name]
+  })
+  ;(core.getBooleanInput as jest.Mock).mockImplementation((name: string) => {
+    return inputs[name]
+  })
+
+  return inputs
+}
+
+describe('merge', () => {
+  beforeEach(async () => {
+    mockInputs()
+
+    jest
+      .spyOn(artifact, 'listArtifacts')
+      .mockResolvedValue({artifacts: fixtures.artifacts})
+
+    jest.spyOn(artifact, 'downloadArtifact').mockResolvedValue({
+      downloadPath: fixtures.tmpDirectory
+    })
+
+    jest.spyOn(search, 'findFilesToUpload').mockResolvedValue({
+      filesToUpload: fixtures.filesToUpload,
+      rootDirectory: fixtures.tmpDirectory
+    })
+
+    jest.spyOn(artifact, 'uploadArtifact').mockResolvedValue({
+      size: 123,
+      id: 1337
+    })
+
+    jest
+      .spyOn(artifact, 'deleteArtifact')
+      .mockImplementation(async artifactName => {
+        const artifact = fixtures.artifacts.find(a => a.name === artifactName)
+        if (!artifact) throw new Error(`Artifact ${artifactName} not found`)
+        return {id: artifact.id}
+      })
+  })
+
+  it('merges artifacts', async () => {
+    await run()
+
+    for (const a of fixtures.artifacts) {
+      expect(artifact.downloadArtifact).toHaveBeenCalledWith(a.id, {
+        path: fixtures.tmpDirectory
+      })
+    }
+
+    expect(artifact.uploadArtifact).toHaveBeenCalledWith(
+      fixtures.artifactName,
+      fixtures.filesToUpload,
+      fixtures.tmpDirectory,
+      {compressionLevel: 6}
+    )
+  })
+
+  it('fails if no artifacts found', async () => {
+    mockInputs({[Inputs.Pattern]: 'this-does-not-match'})
+
+    expect(run()).rejects.toThrow()
+
+    expect(artifact.uploadArtifact).not.toBeCalled()
+    expect(artifact.downloadArtifact).not.toBeCalled()
+  })
+
+  it('supports custom compression level', async () => {
+    mockInputs({
+      [Inputs.CompressionLevel]: 2
+    })
+
+    await run()
+
+    expect(artifact.uploadArtifact).toHaveBeenCalledWith(
+      fixtures.artifactName,
+      fixtures.filesToUpload,
+      fixtures.tmpDirectory,
+      {compressionLevel: 2}
+    )
+  })
+
+  it('supports custom retention days', async () => {
+    mockInputs({
+      [Inputs.RetentionDays]: 7
+    })
+
+    await run()
+
+    expect(artifact.uploadArtifact).toHaveBeenCalledWith(
+      fixtures.artifactName,
+      fixtures.filesToUpload,
+      fixtures.tmpDirectory,
+      {retentionDays: 7, compressionLevel: 6}
+    )
+  })
+
+  it('supports deleting artifacts after merge', async () => {
+    mockInputs({
+      [Inputs.DeleteMerged]: true
+    })
+
+    await run()
+
+    for (const a of fixtures.artifacts) {
+      expect(artifact.deleteArtifact).toHaveBeenCalledWith(a.name)
+    }
+  })
+})

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-artifacts'
+    name:
+
+    # 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:
+  name:
+    description: 'The name of the artifact that the artifacts will be merged into.'
+    required: true
+    default: 'merged-artifacts'
+  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

@@ -1,11 +1,11 @@
 {
   "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": {
     "build": "tsc",
-    "release": "ncc build src/upload/index.ts -o dist/upload",
+    "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 {
+  Name = 'name',
+  Pattern = 'pattern',
+  SeparateDirectories = 'separate-directories',
+  RetentionDays = 'retention-days',
+  CompressionLevel = 'compression-level',
+  DeleteMerged = 'delete-merged'
+}

src/merge/index.ts

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

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 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 = {
+    name,
+    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-artifacts.ts

@@ -0,0 +1,93 @@
+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[][])
+
+export async function run(): Promise<void> {
+  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, {
+      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.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 =>
+      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}`
+    )
+  }
+}

src/merge/merge-inputs.ts

@@ -0,0 +1,33 @@
+export interface MergeInputs {
+  /**
+   * The name of the artifact that the artifacts will be merged into
+   */
+  name: 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
+}