Artifact Download

/**
 * Downloads an artifact and extracts its contents to the filesystem.
 * @param artifactId - The unique ID of the artifact to download
 * @param options - Optional configuration for download behavior and cross-repo access
 * @returns Promise resolving to download response with path and verification info
 */
downloadArtifact(
  artifactId: number,
  options?: DownloadArtifactOptions & FindOptions
): Promise<DownloadArtifactResponse>;

interface DownloadArtifactOptions {
  /** Local path where artifact contents will be extracted (defaults to GITHUB_WORKSPACE) */
  path?: string;
  /** Expected SHA256 hash for integrity verification */
  expectedHash?: string;
}

interface DownloadArtifactResponse {
  /** Path where the artifact was downloaded and extracted */
  downloadPath?: string;
  /** True if digest verification failed (only when expectedHash provided) */
  digestMismatch?: boolean;
}

interface FindOptions {
  /** Configuration for accessing artifacts from other repositories/runs */
  findBy?: {
    /** GitHub token with actions:read permissions */
    token: string;
    /** ID of the workflow run containing the artifact */
    workflowRunId: number;
    /** Repository owner (e.g., 'actions') */
    repositoryOwner: string;
    /** Repository name (e.g., 'toolkit') */
    repositoryName: string;
  };
}

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

const artifact = new DefaultArtifactClient();

// Basic download to default location (GITHUB_WORKSPACE)
const result = await artifact.downloadArtifact(12345);
console.log(`Downloaded to: ${result.downloadPath}`);

// Download to specific directory
const customResult = await artifact.downloadArtifact(12345, {
  path: "/tmp/artifacts"
});

// Download with hash verification
const verifiedResult = await artifact.downloadArtifact(12345, {
  path: "./downloads",
  expectedHash: "sha256:abcd1234..."
});

if (verifiedResult.digestMismatch) {
  console.warn("Downloaded artifact hash does not match expected value!");
}

// Download from another repository
const crossRepoResult = await artifact.downloadArtifact(67890, {
  path: "./external-artifacts",
  findBy: {
    token: process.env.GITHUB_TOKEN!,
    workflowRunId: 987654321,
    repositoryOwner: "actions",
    repositoryName: "toolkit"
  }
});

// Get expected hash from upload response
const uploadResult = await artifact.uploadArtifact("test", files, root);
const expectedDigest = uploadResult.digest;

// Verify during download
const downloadResult = await artifact.downloadArtifact(uploadResult.id!, {
  expectedHash: expectedDigest
});

if (downloadResult.digestMismatch) {
  throw new Error("Artifact integrity check failed");
}

const findBy = {
  token: process.env.GITHUB_TOKEN!,     // Token with actions:read scope
  workflowRunId: 123456789,             // Target workflow run ID
  repositoryOwner: "microsoft",         // Repository owner
  repositoryName: "TypeScript"          // Repository name
};

await artifact.downloadArtifact(artifactId, { findBy });

import { 
  ArtifactNotFoundError, 
  NetworkError,
  InvalidResponseError,
  GHESNotSupportedError 
} from "@actions/artifact";

try {
  await artifact.downloadArtifact(artifactId, options);
} catch (error) {
  if (error instanceof ArtifactNotFoundError) {
    console.error("Artifact not found or no longer available");
  } else if (error instanceof NetworkError) {
    console.error("Network connectivity issue:", error.code);
  } else if (error instanceof InvalidResponseError) {
    console.error("Invalid server response:", error.message);
  } else if (error instanceof GHESNotSupportedError) {
    console.error("GitHub Enterprise Server not supported");
  }
}