tessl/npm-actions--artifact

TypeScript library for GitHub Actions artifact management enabling upload, download, list, get, and delete operations with cross-repository support.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

@actions/artifact

Name: tessl/npm-actions--artifact
Author: tessl

The @actions/artifact package provides a TypeScript library for programmatically interacting with GitHub Actions Artifacts. It enables upload, download, list, get, and delete operations for workflow artifacts, with support for cross-repository access and advanced configuration options.

Package Information

Package Name: @actions/artifact
Package Type: npm
Language: TypeScript
Installation: npm install @actions/artifact
Version: 2.3.2

Core Imports

import { DefaultArtifactClient, ArtifactClient } from "@actions/artifact";

For CommonJS:

const { DefaultArtifactClient, ArtifactClient } = require("@actions/artifact");

You can also import the default client instance directly:

import artifact from "@actions/artifact";

Or import specific interfaces and error types:

import {
  DefaultArtifactClient,
  UploadArtifactOptions,
  DownloadArtifactOptions,
  Artifact,
  ArtifactNotFoundError,
  NetworkError
} from "@actions/artifact";

Basic Usage

import { DefaultArtifactClient } from "@actions/artifact";

const artifact = new DefaultArtifactClient();

// Upload an artifact
const uploadResponse = await artifact.uploadArtifact(
  "my-artifact",
  ["/path/to/file1.txt", "./relative/file2.txt"],
  "/root/directory",
  { retentionDays: 30 }
);

console.log(`Uploaded artifact ID: ${uploadResponse.id}`);

// Download the artifact
const downloadResponse = await artifact.downloadArtifact(uploadResponse.id!, {
  path: "/download/destination"
});

console.log(`Downloaded to: ${downloadResponse.downloadPath}`);

Architecture

The @actions/artifact package is structured around several key components:

Client Interface: ArtifactClient interface defines the complete API surface for artifact operations
Default Implementation: DefaultArtifactClient class provides the main implementation with error handling and GHES validation
Type System: Comprehensive TypeScript interfaces for all requests, responses, and configuration options
Error Handling: Specialized error classes for different failure scenarios
Cross-Repository Support: Optional FindOptions parameter enables artifact access across different repositories and workflow runs
Internal APIs: Separate internal and public API implementations for different access contexts

Capabilities

Artifact Upload

Upload files to create new artifacts with configurable retention and compression settings.

uploadArtifact(
  name: string,
  files: string[],
  rootDirectory: string,
  options?: UploadArtifactOptions
): Promise<UploadArtifactResponse>;

interface UploadArtifactOptions {
  retentionDays?: number;
  compressionLevel?: number;
}

interface UploadArtifactResponse {
  size?: number;
  id?: number;
  digest?: string;
}

Artifact Upload

Artifact Download

Download artifacts by ID with optional destination path and hash verification.

downloadArtifact(
  artifactId: number,
  options?: DownloadArtifactOptions & FindOptions
): Promise<DownloadArtifactResponse>;

interface DownloadArtifactOptions {
  path?: string;
  expectedHash?: string;
}

interface DownloadArtifactResponse {
  downloadPath?: string;
  digestMismatch?: boolean;
}

Artifact Download

Artifact Discovery

List and find artifacts within the current workflow run or across repositories.

listArtifacts(
  options?: ListArtifactsOptions & FindOptions
): Promise<ListArtifactsResponse>;

getArtifact(
  artifactName: string,
  options?: FindOptions
): Promise<GetArtifactResponse>;

interface ListArtifactsOptions {
  latest?: boolean;
}

interface ListArtifactsResponse {
  artifacts: Artifact[];
}

interface GetArtifactResponse {
  artifact: Artifact;
}

Artifact Discovery

Artifact Deletion

Delete artifacts by name with support for cross-repository operations.

deleteArtifact(
  artifactName: string,
  options?: FindOptions
): Promise<DeleteArtifactResponse>;

interface DeleteArtifactResponse {
  id: number;
}

Artifact Deletion

Core Types

interface Artifact {
  name: string;
  id: number;
  size: number;
  createdAt?: Date;
  digest?: string;
}

interface FindOptions {
  findBy?: {
    token: string;
    workflowRunId: number;
    repositoryOwner: string;
    repositoryName: string;
  };
}

interface ArtifactClient {
  uploadArtifact(
    name: string,
    files: string[],
    rootDirectory: string,
    options?: UploadArtifactOptions
  ): Promise<UploadArtifactResponse>;
  
  listArtifacts(
    options?: ListArtifactsOptions & FindOptions
  ): Promise<ListArtifactsResponse>;
  
  getArtifact(
    artifactName: string,
    options?: FindOptions
  ): Promise<GetArtifactResponse>;
  
  downloadArtifact(
    artifactId: number,
    options?: DownloadArtifactOptions & FindOptions
  ): Promise<DownloadArtifactResponse>;
  
  deleteArtifact(
    artifactName: string,
    options?: FindOptions
  ): Promise<DeleteArtifactResponse>;
}

class DefaultArtifactClient implements ArtifactClient {
  // Implementation of all ArtifactClient methods
}

Error Types

class FilesNotFoundError extends Error {
  files: string[];
}

class InvalidResponseError extends Error {}

class ArtifactNotFoundError extends Error {}

class GHESNotSupportedError extends Error {}

class NetworkError extends Error {
  code: string;
  static isNetworkErrorCode(code?: string): boolean;
}

class UsageError extends Error {
  static isUsageErrorMessage(msg?: string): boolean;
}