GitHub Actions Toolkit (@actions/artifact)

@actions/artifact is the official TypeScript/Node.js client for GitHub Actions’ Artifacts API, the library that powers the widely used actions/upload-artifact and actions/download-artifact actions. It lets custom GitHub Actions and workflow scripts upload build outputs, test reports, and other files as immutable, versioned artifacts, then retrieve them later — from the same run, another job, or even another repository given a suitable token.

Internally it wraps a Twirp-based RPC client for GitHub’s internal Actions Results backend, streaming files into zip archives (or, for single files, uploading them raw) and pushing them to Azure Blob Storage via signed URLs, with configurable compression, concurrency, and retention. Version 2+ rearchitected the backend for far faster uploads/downloads and immediate artifact availability, at the cost of dropping support for GitHub Enterprise Server and no longer allowing re-uploads to the same artifact name within a run.

What You Get

• A DefaultArtifactClient class with uploadArtifact, downloadArtifact, listArtifacts, getArtifact, and deleteArtifact methods
• Automatic zip archiving and streaming upload with configurable Zlib compression levels (0-9)
• Cross-repository and cross-run artifact lookups via a findBy option backed by a scoped GitHub token
• SHA-256 digest generation and verification so downloads can be checked against the uploaded artifact’s hash
• A skipArchive mode for uploading a single file without zipping it

Common Use Cases

• Custom build actions - a JavaScript/TypeScript action uploads compiled binaries or coverage reports as an artifact instead of shelling out to actions/upload-artifact
• Cross-job artifact sharing - a later job in the same workflow run downloads an artifact a previous job produced, using just the artifact ID
• Cross-repository artifact retrieval - a release or deploy workflow in one repo downloads an artifact built by a workflow run in a different repository, using a token with actions:read on the target repo
• Artifact cleanup automation - a scheduled workflow deletes named artifacts across recent runs to reclaim storage before the default retention window expires

Under The Hood

Architecture client.ts is a thin facade (DefaultArtifactClient) delegating to internal/{upload,download,find,delete} modules that each split into a “public” variant (cross-run/repo, via the REST API) and an “internal” variant (current-run, via Twirp RPC) selected by whether options.findBy is present. artifact-twirp-client.ts wraps a generated Twirp client (src/generated, protobuf-ts) hitting GitHub’s internal Actions Results backend, while blob-upload.ts/stream.ts/zip.ts handle streaming bytes to Azure Blob Storage. isGhes() in shared/config.ts gates the whole client off for GitHub Enterprise Server since the v2 backend isn’t available there. The public/internal split cleanly separates two very different API surfaces behind one client interface, though it means retry and backend-ID logic has to be kept consistent across both branches independently.

Tech Stack Strict TypeScript compiled to Node ESM (“type”: “module”, exports pointing at compiled lib/artifact.js) from a Lerna/Nx-orchestrated monorepo. It talks to GitHub’s Artifacts backend via a generated Twirp RPC client (@protobuf-ts/runtime and protobuf definitions under src/generated), uploads bytes to Azure Blob Storage via @azure/storage-blob, and falls back to the public REST API via @octokit/core with plugin-retry/plugin-request-log for cross-run/repo access. archiver handles zipping and unzip-stream handles extraction, composing with the sibling @actions/core, @actions/github, and @actions/http-client toolkit packages. CI runs Jest unit tests, ESLint (eslint-plugin-github, @typescript-eslint), an npm audit workflow, and CodeQL scanning on every change.

Code Quality The tests directory mirrors the src layout one-to-one — upload, download, list, get, delete, config, util, stream, zip, retention, and path-validation each have a dedicated Jest test file, with @azure/storage-blob mocked and real temp-file fixtures used for archive round-trips. Error handling is explicit and typed via custom classes (FilesNotFoundError, InvalidResponseError, GHESNotSupportedError) in shared/errors.ts, and every public client method wraps its call in try/catch, logging a warning through @actions/core before rethrowing rather than swallowing the error. TypeScript strict mode is enabled at the repo level, though the root tsconfig sets noImplicitAny to false, loosening that slightly. Naming and formatting are enforced via ESLint and Prettier in CI.

What Makes It Unique The public surface is deliberately small — one ArtifactClient interface with five verbs — and getting started requires no explicit configuration, since runtime credentials (ACTIONS_RUNTIME_TOKEN, ACTIONS_RESULTS_URL) are read implicitly from the Actions environment. The same five methods transparently support two very different backends (in-run Twirp API vs. cross-run/repo REST API) behind one findBy option, so callers don’t need a second client for artifacts from another run. Digest verification (expectedHash/digestMismatch) and a skipArchive escape hatch for raw single-file uploads are practical touches many artifact-handling SDKs skip. It is a well-scoped wrapper around a purpose-built internal API rather than a novel technical approach.