From 57b9dd45138045d97786ff3c50303beca14f3056 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Tue, 5 Dec 2023 21:10:48 +0000 Subject: [PATCH 01/18] update contributing docs --- CONTRIBUTIONS.md | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTIONS.md b/CONTRIBUTIONS.md index c614728..67a017f 100644 --- a/CONTRIBUTIONS.md +++ b/CONTRIBUTIONS.md @@ -1,6 +1,6 @@ # Contributions -This package is used internally by the v2+ versions of [upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact). This package can also be used by other actions to interact with artifacts. Any changes or updates to this package will propagate updates to these actions so it is important that major changes or updates get properly tested. +This package is used internally by the v4 versions of [upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact). This package can also be used by other actions to interact with artifacts. Any changes or updates to this package will propagate updates to these actions so it is important that major changes or updates get properly tested. Any issues or feature requests that are related to the artifact actions should be filled in the appropriate repo. @@ -8,23 +8,36 @@ A limited range of unit tests run as part of each PR when making changes to the If making large changes, there are a few scenarios that should be tested. -- Uploading very large artifacts (large artifacts get compressed using gzip so compression/decompression must be tested) -- Uploading artifacts with lots of small files (each file is uploaded with its own HTTP call, timeouts and non-success HTTP responses can be expected so they must be properly handled) +- Uploading very large artifacts +- Uploading artifacts with lots of small files - Uploading artifacts using a self-hosted runner (uploads and downloads behave differently due to extra latency) - Downloading a single artifact (large and small, if lots of small files are part of an artifact, timeouts and non-success HTTP responses can be expected) - Downloading all artifacts at once Large architectural changes can impact upload/download performance so it is important to separately run extra tests. We request that any large contributions/changes have extra detailed testing so we can verify performance and possible regressions. -It is not possible to run end-to-end tests for artifacts as part of a PR in this repo because certain env variables such as `ACTIONS_RUNTIME_URL` are only available from the context of an action as opposed to a shell script. These env variables are needed in order to make the necessary API calls. +Tests will run for every push/pull_request [via Actions](https://github.com/actions/toolkit/blob/main/.github/workflows/artifact-tests.yml). # Testing -Any easy way to test changes is to fork the artifact actions and to use `npm link` to test your changes. +## Package tests -1. Fork the [upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) repos -2. Clone the forks locally -3. With your local changes to the toolkit repo, type `npm link` after ensuring there are no errors when running `tsc` -4. In the locally cloned fork, type `npm link @actions/artifact` -4. Create a new release for your local fork using `tsc` and `npm run release` (this will create a new `dist/index.js` file using `@vercel/ncc`) -5. Commit and push your local changes, you will then be able to test your changes with your forked action +To run unit tests for the `@actions/artifact` package: + +1. Clone `actions/toolkit` locally +2. Install dependencies: `npm bootstrap` +3. Change working directory to `packages/artifact` +4. Run jest tests: `npm run test` + +## Within upload-artifact or download-artifact actions + +Any easy way to test changes for the official upload/download actions is to fork them, compile changes and run them. + +1. For your local `actions/toolkit` changes: + 1. Change directory to `packages/artifact` + 2. Compile the changes: `npm run tsc` + 3. Symlink your package change: `npm link` +2. Fork and clone either [upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) + 1. In the locally cloned fork, link to your local toolkit changes: `npm link @actions/artifact` + 2. Then, compile your changes with: `npm run release`. The local `dist/index.js` should be updated with your changes. + 3. Commit and push to your fork, you can then test with a `uses:` in your workflow pointed at your fork. From f3097c8cb4a6381801ee04ceb6c8ee0f63dc69de Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Tue, 5 Dec 2023 21:55:22 +0000 Subject: [PATCH 02/18] readme & error updates --- README.md | 56 +++++++++++++++++++++++++++++++---- src/internal/shared/errors.ts | 2 +- 2 files changed, 51 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index fee9a6a..040d2f0 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,57 @@ # `@actions/artifact` -## Usage +Interact programmatically with [Actions Artifacts](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts). -You can use this package to interact with the Actions artifacts. +This is the core library that powers the [`@actions/upload-artifact`](https://github.com/actions/upload-artifact) and [`@actions/download-artifact`](https://github.com/actions/download-artifact) actions. -This most recently published version of this package (`1.1.1`) can be found [here](https://github.com/actions/toolkit/tree/@actions/artifact@1.1.1/packages/artifact) -## 🚧 Under construction 🚧 +- [`@actions/artifact`](#actionsartifact) + - [v2 - Major Performance and Behavioral Improvements](#v2---major-performance-and-behavioral-improvements) + - [Improvements](#improvements) + - [Breaking changes](#breaking-changes) + - [Example scenarios](#example-scenarios) + - [Basic Upload and Download](#basic-upload-and-download) + - [Using `actions/github-script`](#using-actionsgithub-script) + - [Downloading from other runs or repos](#downloading-from-other-runs-or-repos) + - [Speeding up large uploads](#speeding-up-large-uploads) -This package is currently undergoing a major overhaul in preparation for `v4` versions of `upload-artifact` and `download-artifact` (these Actions will use a new `2.0.0` version of `@actions/artifact` that will soon be released). The upcoming version of `@actions/artifact` will take advantage of a major re-architecture with entirely new APIs. -The upcoming `2.0.0` package and `v4` artifact Actions aim to solve some of the major pain-points that have made artifact usage difficult up until now. +## v2 - Major Performance and Behavioral Improvements + +> [!IMPORTANT] +> @actions/artifact v2+, download-artifact@v4+ download-artifact@v4+ are not currently supported on GHES yet. The previous version of this package can be found at [this tag](https://github.com/actions/toolkit/tree/@actions/artifact@1.1.2/packages/artifact) and [on npm](https://www.npmjs.com/package/@actions/artifact/v/1.1.2). + +The release of `@actions/artifact@v2` (including `download-artifact@v4` and `download-artifact@v4`) are major changes to the backend architecture of Artifacts. They have numerous performance and behavioral improvements. + +### Improvements + +1. All upload and download operations are exponentially faster, up to 80% faster download times and 96% faster upload times in worst case scenarios. +2. Once uploaded, Artifacts becoming immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28). Previously, you would have to wait for the run to be completed. +3. Artifacts are _immutable_ once they are uploaded. They cannot be altered by subsequent jobs. (Digest/integrity hash coming soon in API!) +4. This library (and `actions/download-artifact`) now support downloading Artifacts from _other_ repositories and runs if a `GITHUB_TOKEN` with sufficient `actions:read` permissions are provided. + +### Breaking changes + +1. Firewall rules required for self-hosted runners. + + If you are using self-hosted runners behind a firewall, you must have flows open to [Actions endpoints](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-between-self-hosted-runners-and-github). If you cannot use wildcard rules for your firewall, see the GitHub [meta endpoint](https://api.github.com/meta) for specific endpoints. + + e.g. + + ``` + curl https://api.github.com/meta | jq .domains.actions + ``` + +2. Uploading to the same named Artifact multiple times. + + Due to the behavior of how Artifacts are created in this new version, it is no longer possible to upload to the same named Artifact multiple times. You must either split the uploads into multiple names Artifacts, or only upload once. + +## Example scenarios + +### Basic Upload and Download + +### Using `actions/github-script` + +### Downloading from other runs or repos + +### Speeding up large uploads diff --git a/src/internal/shared/errors.ts b/src/internal/shared/errors.ts index a46a01f..841c44a 100644 --- a/src/internal/shared/errors.ts +++ b/src/internal/shared/errors.ts @@ -29,7 +29,7 @@ export class ArtifactNotFoundError extends Error { export class GHESNotSupportedError extends Error { constructor( - message = '@actions/artifact v2.0.0+ and download-artifact@v4+ are not currently supported on GHES.' + message = '@actions/artifact v2.0.0+, upload-artifact@v4+ and download-artifact@v4+ are not currently supported on GHES.' ) { super(message) this.name = 'GHESNotSupportedError' From e1314b246df6a8afc8ea7d6d2cdfd14327cac2a7 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 04:00:07 +0000 Subject: [PATCH 03/18] initalize artifact client as default export --- src/artifact.ts | 12 ++++------ src/internal/client.ts | 39 +++++++++++-------------------- src/internal/shared/interfaces.ts | 2 +- 3 files changed, 18 insertions(+), 35 deletions(-) diff --git a/src/artifact.ts b/src/artifact.ts index 3ba3844..f5d9144 100644 --- a/src/artifact.ts +++ b/src/artifact.ts @@ -1,12 +1,8 @@ -import {ArtifactClient, Client} from './internal/client' +import {ArtifactClient, DefaultArtifactClient} from './internal/client' -/** - * Exported functionality that we want to expose for any users of @actions/artifact - */ export * from './internal/shared/interfaces' export * from './internal/shared/errors' -export {ArtifactClient} +export * from './internal/client' -export function create(): ArtifactClient { - return Client.create() -} +const client: ArtifactClient = new DefaultArtifactClient() +export default client diff --git a/src/internal/client.ts b/src/internal/client.ts index 4dd40b8..c4971d9 100644 --- a/src/internal/client.ts +++ b/src/internal/client.ts @@ -19,9 +19,12 @@ import {getArtifactPublic, getArtifactInternal} from './find/get-artifact' import {listArtifactsPublic, listArtifactsInternal} from './find/list-artifacts' import {GHESNotSupportedError} from './shared/errors' +/** + * Generic interface for the artifact client. + */ export interface ArtifactClient { /** - * Uploads an artifact + * Uploads an artifact. * * @param name The name of the artifact, required * @param files A list of absolute or relative paths that denote what files should be uploaded @@ -40,7 +43,7 @@ export interface ArtifactClient { * Lists all artifacts that are part of the current workflow run. * This function will return at most 1000 artifacts per workflow run. * - * If options.findBy is specified, this will call the public List-Artifacts API which can list from other runs. + * If `options.findBy` is specified, this will call the public List-Artifacts API which can list from other runs. * https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#list-workflow-run-artifacts * * @param options Extra options that allow for the customization of the list behavior @@ -55,10 +58,10 @@ export interface ArtifactClient { * If there are multiple artifacts with the same name in the same workflow run, this will return the latest. * If the artifact is not found, it will throw. * - * If options.findBy is specified, this will use the public List Artifacts API with a name filter which can get artifacts from other runs. + * If `options.findBy` is specified, this will use the public List Artifacts API with a name filter which can get artifacts from other runs. * https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#list-workflow-run-artifacts - * @actions/artifact > 2.0.0 does not allow for creating multiple artifacts with the same name in the same workflow run. - * It is possible to have multiple artifacts with the same name in the same workflow run by using old versions of upload-artifact (v1,v2 and v3), @actions/artifact < v2.0.0 or it is a rerun. + * `@actions/artifact` v2+ does not allow for creating multiple artifacts with the same name in the same workflow run. + * It is possible to have multiple artifacts with the same name in the same workflow run by using old versions of upload-artifact (v1,v2 and v3), @actions/artifact < v2 or it is a rerun. * If there are multiple artifacts with the same name in the same workflow run this function will return the first artifact that matches the name. * * @param artifactName The name of the artifact to find @@ -72,7 +75,7 @@ export interface ArtifactClient { /** * Downloads an artifact and unzips the content. * - * If options.findBy is specified, this will use the public Download Artifact API https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#download-an-artifact + * If `options.findBy` is specified, this will use the public Download Artifact API https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#download-an-artifact * * @param artifactId The name of the artifact to download * @param options Extra options that allow for the customization of the download behavior @@ -84,17 +87,10 @@ export interface ArtifactClient { ): Promise } -export class Client implements ArtifactClient { - /** - * Constructs a Client - */ - static create(): Client { - return new Client() - } - - /** - * Upload Artifact - */ +/** + * The default artifact client that is used by the artifact action(s). + */ +export class DefaultArtifactClient implements ArtifactClient { async uploadArtifact( name: string, files: string[], @@ -120,9 +116,6 @@ If the error persists, please check whether Actions is operating normally at [ht } } - /** - * Download Artifact - */ async downloadArtifact( artifactId: number, options?: DownloadArtifactOptions & FindOptions @@ -161,9 +154,6 @@ If the error persists, please check whether Actions and API requests are operati } } - /** - * List Artifacts - */ async listArtifacts( options?: ListArtifactsOptions & FindOptions ): Promise { @@ -200,9 +190,6 @@ If the error persists, please check whether Actions and API requests are operati } } - /** - * Get Artifact - */ async getArtifact( artifactName: string, options?: FindOptions diff --git a/src/internal/shared/interfaces.ts b/src/internal/shared/interfaces.ts index dfd3e1d..e40fb66 100644 --- a/src/internal/shared/interfaces.ts +++ b/src/internal/shared/interfaces.ts @@ -127,7 +127,7 @@ export interface Artifact { } // FindOptions are for fetching Artifact(s) out of the scope of the current run. -// Must specify a PAT with actions:read scope for cross run/repo lookup otherwise these will be ignored. +// Must specify a token with actions:read scope for cross run/repo lookup otherwise these will be ignored. export interface FindOptions { findBy?: { // Token with actions:read permissions From ef9c6b453399c5d45aab37616bde6de564b16761 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 04:10:46 +0000 Subject: [PATCH 04/18] more readme updates --- README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 94 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 040d2f0..580c4ae 100644 --- a/README.md +++ b/README.md @@ -6,17 +6,16 @@ This is the core library that powers the [`@actions/upload-artifact`](https://gi - [`@actions/artifact`](#actionsartifact) - - [v2 - Major Performance and Behavioral Improvements](#v2---major-performance-and-behavioral-improvements) + - [v2 - What's New](#v2---whats-new) - [Improvements](#improvements) - [Breaking changes](#breaking-changes) - - [Example scenarios](#example-scenarios) - - [Basic Upload and Download](#basic-upload-and-download) - - [Using `actions/github-script`](#using-actionsgithub-script) - - [Downloading from other runs or repos](#downloading-from-other-runs-or-repos) + - [Quick Start](#quick-start) + - [Examples](#examples) + - [Upload and Download](#upload-and-download) + - [Downloading from other workflow runs or repos](#downloading-from-other-workflow-runs-or-repos) - [Speeding up large uploads](#speeding-up-large-uploads) - -## v2 - Major Performance and Behavioral Improvements +## v2 - What's New > [!IMPORTANT] > @actions/artifact v2+, download-artifact@v4+ download-artifact@v4+ are not currently supported on GHES yet. The previous version of this package can be found at [this tag](https://github.com/actions/toolkit/tree/@actions/artifact@1.1.2/packages/artifact) and [on npm](https://www.npmjs.com/package/@actions/artifact/v/1.1.2). @@ -25,8 +24,8 @@ The release of `@actions/artifact@v2` (including `download-artifact@v4` and `dow ### Improvements -1. All upload and download operations are exponentially faster, up to 80% faster download times and 96% faster upload times in worst case scenarios. -2. Once uploaded, Artifacts becoming immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28). Previously, you would have to wait for the run to be completed. +1. All upload and download operations are much quicker, up to 80% faster download times and 96% faster upload times in worst case scenarios. +2. Once uploaded, Artifacts becoming immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts). Previously, you would have to wait for the run to be completed. 3. Artifacts are _immutable_ once they are uploaded. They cannot be altered by subsequent jobs. (Digest/integrity hash coming soon in API!) 4. This library (and `actions/download-artifact`) now support downloading Artifacts from _other_ repositories and runs if a `GITHUB_TOKEN` with sufficient `actions:read` permissions are provided. @@ -46,12 +45,94 @@ The release of `@actions/artifact@v2` (including `download-artifact@v4` and `dow Due to the behavior of how Artifacts are created in this new version, it is no longer possible to upload to the same named Artifact multiple times. You must either split the uploads into multiple names Artifacts, or only upload once. -## Example scenarios +## Quick Start -### Basic Upload and Download +Install the package: -### Using `actions/github-script` +``` +npm i @actions/artifact +``` -### Downloading from other runs or repos +Import the module: + +```js +// ES6 module +import artifact from '@actions/artifact' + +// CommonJS +const {default: artifact} = require('@actions/artifact') +``` + +ℹī¸ For a comprehensive list of classes, interfaces, functions and more, see the [generated documentation](./docs/generated/README.md). + +## Examples + +### Upload and Download + +This is the most basic scenario, uploading one or more files to an Artifact, then downloading it. Downloads are based on the Artifact ID, which can be obtained in the response of `uploadArtifact`, `getArtifact`, `listArtifacts` or via the [REST API](https://docs.github.com/en/rest/actions/artifacts). + +```js +const {id, size} = await artifact.uploadArtifact( + // name of the artifact + 'my-artifact', + // files to include (supports absolute and relative paths) + ['/absolute/path/file1.txt', './relative/file2.txt'], + { + // optional: how long to retain the artifact + // if unspecified, defaults to repository/org retention settings (the limit of this value) + retentionDays: 10 + } +) + +console.log(`Created artifact with id: ${id} (bytes: ${size}`) + +const {downloadPath} = await artifact.downloadArtifact(id, { + // optional: download destination path. otherwise defaults to $GITHUB_WORKSPACE + path: '/tmp/dst/path', +}) + +console.log(`Downloaded artifact ${id} to: ${downloadPath}`) +``` + +### Downloading from other workflow runs or repos + +It may be useful to download Artifacts from other workflow runs, or even other repositories. By default, the permissions are scoped so they can only download Artifacts within the current workflow run. To elevate permissions for this scenario, you must specify `options.findBy` to `downloadArtifact`. + +```ts +const findBy = { + // must have actions:read permission on target repository + token: process.env['GITHUB_TOKEN'], + workflowRunId: 123, + repositoryOwner: 'actions', + repositoryName: 'toolkit' +} + +await artifact.downloadArtifact(1337, { + findBy +}) + +// can also be used in other methods + +await artifact.getArtifact('my-artifact', { + findBy +}) + +await artifact.listArtifacts({ + findBy +}) +``` ### Speeding up large uploads + +If you have large files that need to be uploaded (or file types that don't compress well), you may benefit from changing the compression level of the Artifact archive. NOTE: This is a tradeoff between artifact upload time and stored data size. + +```ts +await artifact.uploadArtifact('my-massive-artifact', ['big_file.bin'], { + // The level of compression for Zlib to be applied to the artifact archive. + // - 0: No compression + // - 1: Best speed + // - 6: Default compression (same as GNU Gzip) + // - 9: Best compression + compressionLevel: 0 +}) +``` From 960e149e117ae6afcdf90afdabaeb8082e1e06ba Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 04:22:18 +0000 Subject: [PATCH 05/18] add faq, update releases --- README.md | 7 +++++++ RELEASES.md | 5 +++++ docs/docs.md | 1 - docs/faq.md | 35 +++++++++++++++++++++++++++++++++++ 4 files changed, 47 insertions(+), 1 deletion(-) delete mode 100644 docs/docs.md create mode 100644 docs/faq.md diff --git a/README.md b/README.md index 580c4ae..7075228 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ This is the core library that powers the [`@actions/upload-artifact`](https://gi - [Upload and Download](#upload-and-download) - [Downloading from other workflow runs or repos](#downloading-from-other-workflow-runs-or-repos) - [Speeding up large uploads](#speeding-up-large-uploads) + - [Additional Resources](#additional-resources) ## v2 - What's New @@ -136,3 +137,9 @@ await artifact.uploadArtifact('my-massive-artifact', ['big_file.bin'], { compressionLevel: 0 }) ``` + +## Additional Resources + +- [Releases](./RELEASES.md) +- [Contribution Guide](./CONTRIBUTIONS.md) +- [Frequently Asked Questions](./docs/faq.md) diff --git a/RELEASES.md b/RELEASES.md index 580d840..53a8dda 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -94,3 +94,8 @@ ### 1.1.1 - Fixed a bug in Node16 where if an HTTP download finished too quickly (<1ms, e.g. when it's mocked) we attempt to delete a temp file that has not been created yet [#1278](https://github.com/actions/toolkit/pull/1278/commits/b9de68a590daf37c6747e38d3cb4f1dd2cfb791c) + +### 2.0.0 + +Major release. Supports new Artifact backend for improved speed, reliability and behavior. +Numerous API changes, some breaking. diff --git a/docs/docs.md b/docs/docs.md deleted file mode 100644 index e0fa311..0000000 --- a/docs/docs.md +++ /dev/null @@ -1 +0,0 @@ -Docs will be added here once development of version `2.0.0` has finished \ No newline at end of file diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..8700787 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,35 @@ +# Frequently Asked Questions + +- [Frequently Asked Questions](#frequently-asked-questions) + - [Supported Characters](#supported-characters) + - [Compression? ZIP? How is my artifact stored?](#compression-zip-how-is-my-artifact-stored) + +## Supported Characters + +When uploading an artifact, the inputted `name` parameter along with the files specified in `files` cannot contain any of the following characters. They will be rejected by the server if attempted to be sent over and the upload will fail. These characters are not allowed due to limitations and restrictions with certain file systems such as NTFS. To maintain platform-agnostic behavior, all characters that are not supported by an individual filesystem/platform will not be supported on all filesystems/platforms. + +- " +- : +- < +- \> +- | +- \* +- ? + +In addition to the aforementioned characters, the inputted `name` also cannot include the following +- \ +- / + +## Compression? ZIP? How is my artifact stored? + +When creating an Artifact, the files are dynamically compressed and streamed into a ZIP archive. Since they are stored in a ZIP, they can be compressed by Zlib in varying levels. + +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. From 192c80a3b3e607a9e940177f4aca0323b5ddd0d8 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 09:30:20 -0500 Subject: [PATCH 06/18] Update packages/artifact/README.md Co-authored-by: Bethany --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7075228..0ff82b9 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ The release of `@actions/artifact@v2` (including `download-artifact@v4` and `dow ### Improvements 1. All upload and download operations are much quicker, up to 80% faster download times and 96% faster upload times in worst case scenarios. -2. Once uploaded, Artifacts becoming immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts). Previously, you would have to wait for the run to be completed. +2. Once uploaded, Artifacts are immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts). Previously, you would have to wait for the run to be completed. 3. Artifacts are _immutable_ once they are uploaded. They cannot be altered by subsequent jobs. (Digest/integrity hash coming soon in API!) 4. This library (and `actions/download-artifact`) now support downloading Artifacts from _other_ repositories and runs if a `GITHUB_TOKEN` with sufficient `actions:read` permissions are provided. From 490191f724e756bc1affb07024c46d35ff8a8fe0 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 09:30:35 -0500 Subject: [PATCH 07/18] Update packages/artifact/README.md Co-authored-by: Bethany --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0ff82b9..e1867d0 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ The release of `@actions/artifact@v2` (including `download-artifact@v4` and `dow 1. All upload and download operations are much quicker, up to 80% faster download times and 96% faster upload times in worst case scenarios. 2. Once uploaded, Artifacts are immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts). Previously, you would have to wait for the run to be completed. -3. Artifacts are _immutable_ once they are uploaded. They cannot be altered by subsequent jobs. (Digest/integrity hash coming soon in API!) +3. Artifacts are _immutable_ once they are uploaded. They cannot be altered by subsequent jobs. (Digest/integrity hash coming soon in the API!) 4. This library (and `actions/download-artifact`) now support downloading Artifacts from _other_ repositories and runs if a `GITHUB_TOKEN` with sufficient `actions:read` permissions are provided. ### Breaking changes From 54d33e027b03fc28d5d1e03bd982240840aa2669 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 09:30:53 -0500 Subject: [PATCH 08/18] Update packages/artifact/README.md Co-authored-by: Bethany --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e1867d0..edda74e 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ The release of `@actions/artifact@v2` (including `download-artifact@v4` and `dow 2. Uploading to the same named Artifact multiple times. - Due to the behavior of how Artifacts are created in this new version, it is no longer possible to upload to the same named Artifact multiple times. You must either split the uploads into multiple names Artifacts, or only upload once. + Due to how Artifacts are created in this new version, it is no longer possible to upload to the same named Artifact multiple times. You must either split the uploads into multiple Artifacts with different names, or only upload once. ## Quick Start From 1995e60172c8e33f025ed26f2fd41a329c3d7aed Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 09:31:09 -0500 Subject: [PATCH 09/18] Update packages/artifact/README.md Co-authored-by: Bethany --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index edda74e..0f2b61d 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ const {default: artifact} = require('@actions/artifact') ### Upload and Download -This is the most basic scenario, uploading one or more files to an Artifact, then downloading it. Downloads are based on the Artifact ID, which can be obtained in the response of `uploadArtifact`, `getArtifact`, `listArtifacts` or via the [REST API](https://docs.github.com/en/rest/actions/artifacts). +The most basic scenario is uploading one or more files to an Artifact, then downloading that Artifact. Downloads are based on the Artifact ID, which can be obtained in the response of `uploadArtifact`, `getArtifact`, `listArtifacts` or via the [REST API](https://docs.github.com/en/rest/actions/artifacts). ```js const {id, size} = await artifact.uploadArtifact( From 92ec1c9eeeed151b0877caf0428a0b3a12927383 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 09:31:55 -0500 Subject: [PATCH 10/18] Update packages/artifact/docs/faq.md Co-authored-by: Bethany --- docs/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index 8700787..c88d5c1 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -6,7 +6,7 @@ ## Supported Characters -When uploading an artifact, the inputted `name` parameter along with the files specified in `files` cannot contain any of the following characters. They will be rejected by the server if attempted to be sent over and the upload will fail. These characters are not allowed due to limitations and restrictions with certain file systems such as NTFS. To maintain platform-agnostic behavior, all characters that are not supported by an individual filesystem/platform will not be supported on all filesystems/platforms. +When uploading an artifact, the inputted `name` parameter along with the files specified in `files` cannot contain any of the following characters. If they are present in `name` or `files`, the Artifact will be rejected by the server and the upload will fail. These characters are not allowed due to limitations and restrictions with certain file systems such as NTFS. To maintain platform-agnostic behavior, characters that are not supported by an individual filesystem/platform will not be supported on all filesystems/platforms. - " - : From 13605c996c2378c423f04251541ed665011afc3a Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 14:52:49 +0000 Subject: [PATCH 11/18] releases.md: link to breaking v2 changes --- RELEASES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RELEASES.md b/RELEASES.md index 53a8dda..cd10f57 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -98,4 +98,4 @@ ### 2.0.0 Major release. Supports new Artifact backend for improved speed, reliability and behavior. -Numerous API changes, some breaking. +Numerous API changes, [some breaking](./README.md#breaking-changes). From 772c27dfca373aa80b0a3bb66b7498ce2653eda8 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 15:38:59 +0000 Subject: [PATCH 12/18] fix typo --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0f2b61d..ac393d8 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,9 @@ This is the core library that powers the [`@actions/upload-artifact`](https://gi ## v2 - What's New > [!IMPORTANT] -> @actions/artifact v2+, download-artifact@v4+ download-artifact@v4+ are not currently supported on GHES yet. The previous version of this package can be found at [this tag](https://github.com/actions/toolkit/tree/@actions/artifact@1.1.2/packages/artifact) and [on npm](https://www.npmjs.com/package/@actions/artifact/v/1.1.2). +> @actions/artifact v2+, upload-artifact@v4+ download-artifact@v4+ are not currently supported on GHES yet. The previous version of this package can be found at [this tag](https://github.com/actions/toolkit/tree/@actions/artifact@1.1.2/packages/artifact) and [on npm](https://www.npmjs.com/package/@actions/artifact/v/1.1.2). -The release of `@actions/artifact@v2` (including `download-artifact@v4` and `download-artifact@v4`) are major changes to the backend architecture of Artifacts. They have numerous performance and behavioral improvements. +The release of `@actions/artifact@v2` (including `upload-artifact@v4` and `download-artifact@v4`) are major changes to the backend architecture of Artifacts. They have numerous performance and behavioral improvements. ### Improvements From db8de67b0287802823302d44e656380025dd6036 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 12:19:49 -0500 Subject: [PATCH 13/18] Update packages/artifact/README.md Co-authored-by: Konrad Pabjan --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ac393d8..436173b 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ The release of `@actions/artifact@v2` (including `upload-artifact@v4` and `downl ### Improvements 1. All upload and download operations are much quicker, up to 80% faster download times and 96% faster upload times in worst case scenarios. -2. Once uploaded, Artifacts are immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts). Previously, you would have to wait for the run to be completed. +2. Once uploaded, an Artifact ID is returned and Artifacts are immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts). Previously, you would have to wait for the run to be completed before an ID was available or any APIs could be utilized. 3. Artifacts are _immutable_ once they are uploaded. They cannot be altered by subsequent jobs. (Digest/integrity hash coming soon in the API!) 4. This library (and `actions/download-artifact`) now support downloading Artifacts from _other_ repositories and runs if a `GITHUB_TOKEN` with sufficient `actions:read` permissions are provided. From c15e3f5a6ea8e904fc6f7e8fe81b4de95f2c0ca0 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 17:28:03 +0000 Subject: [PATCH 14/18] pr feedback --- README.md | 5 +++-- RELEASES.md | 2 ++ 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 436173b..8ea5814 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,9 @@ The release of `@actions/artifact@v2` (including `upload-artifact@v4` and `downl 1. All upload and download operations are much quicker, up to 80% faster download times and 96% faster upload times in worst case scenarios. 2. Once uploaded, an Artifact ID is returned and Artifacts are immediately available in the UI and [REST API](https://docs.github.com/en/rest/actions/artifacts). Previously, you would have to wait for the run to be completed before an ID was available or any APIs could be utilized. -3. Artifacts are _immutable_ once they are uploaded. They cannot be altered by subsequent jobs. (Digest/integrity hash coming soon in the API!) -4. This library (and `actions/download-artifact`) now support downloading Artifacts from _other_ repositories and runs if a `GITHUB_TOKEN` with sufficient `actions:read` permissions are provided. +3. Artifacts can now be downloaded and deleted from the UI _before_ the entire workflow run finishes. +4. The contents of an Artifact are uploaded together into an _immutable_ archive. They cannot be altered by subsequent jobs. Both of these factors help reduce the possibility of accidentally corrupting Artifact files. (Digest/integrity hash coming soon in the API!) +5. This library (and `actions/download-artifact`) now support downloading Artifacts from _other_ repositories and runs if a `GITHUB_TOKEN` with sufficient `actions:read` permissions are provided. ### Breaking changes diff --git a/RELEASES.md b/RELEASES.md index cd10f57..ce3ed43 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -99,3 +99,5 @@ Major release. Supports new Artifact backend for improved speed, reliability and behavior. Numerous API changes, [some breaking](./README.md#breaking-changes). + +Blog post with more info: TBD From 0f978310c3b199b76d6839bf163b411103876461 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 17:30:13 +0000 Subject: [PATCH 15/18] mention job limit --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 8ea5814..e68fc26 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,10 @@ The release of `@actions/artifact@v2` (including `upload-artifact@v4` and `downl Due to how Artifacts are created in this new version, it is no longer possible to upload to the same named Artifact multiple times. You must either split the uploads into multiple Artifacts with different names, or only upload once. +3. Limit of Artifacts for an individual job. + + Each job in a workflow run now has a limit of 10 artifacts. + ## Quick Start Install the package: From c22e811e61ccf0d6b2e11d8a3788b851eea1ee74 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 13:19:32 -0500 Subject: [PATCH 16/18] Update packages/artifact/README.md Co-authored-by: Konrad Pabjan --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e68fc26..4dcee38 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ The release of `@actions/artifact@v2` (including `upload-artifact@v4` and `downl e.g. - ``` + ```bash curl https://api.github.com/meta | jq .domains.actions ``` From 849722c17570dd5418901d630d115ffade0ffae2 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 13:19:38 -0500 Subject: [PATCH 17/18] Update packages/artifact/README.md Co-authored-by: Konrad Pabjan --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4dcee38..d03dfc2 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ The release of `@actions/artifact@v2` (including `upload-artifact@v4` and `downl Install the package: -``` +```bash npm i @actions/artifact ``` From ab90611ab052afb726b69d5d0826c7f2464c6b71 Mon Sep 17 00:00:00 2001 From: Rob Herley Date: Wed, 6 Dec 2023 14:05:38 -0500 Subject: [PATCH 18/18] Update packages/artifact/CONTRIBUTIONS.md Co-authored-by: Mattia Richetto --- CONTRIBUTIONS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTIONS.md b/CONTRIBUTIONS.md index 67a017f..23ede98 100644 --- a/CONTRIBUTIONS.md +++ b/CONTRIBUTIONS.md @@ -6,7 +6,7 @@ Any issues or feature requests that are related to the artifact actions should b A limited range of unit tests run as part of each PR when making changes to the artifact packages. For small contributions and fixes, they should be sufficient. -If making large changes, there are a few scenarios that should be tested. +If making large changes, there are a few scenarios that should be tested: - Uploading very large artifacts - Uploading artifacts with lots of small files