Artifact Discovery

/**
 * Lists all artifacts for the current workflow run or specified external run.
 * Returns at most 1000 artifacts per workflow run.
 * @param options - Optional filtering and cross-repository access configuration
 * @returns Promise resolving to list of found artifacts
 */
listArtifacts(
  options?: ListArtifactsOptions & FindOptions
): Promise<ListArtifactsResponse>;

interface ListArtifactsOptions {
  /** Filter to only the latest artifact for each name (useful for workflow reruns) */
  latest?: boolean;
}

interface ListArtifactsResponse {
  /** Array of found artifacts with metadata */
  artifacts: Artifact[];
}

interface Artifact {
  /** Name of the artifact */
  name: string;
  /** Unique identifier for the artifact */
  id: number;
  /** Size of the artifact in bytes */
  size: number;
  /** Timestamp when the artifact was created */
  createdAt?: Date;
  /** SHA256 digest of the artifact contents */
  digest?: string;
}

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

const artifact = new DefaultArtifactClient();

// List all artifacts in current workflow run
const allArtifacts = await artifact.listArtifacts();
console.log(`Found ${allArtifacts.artifacts.length} artifacts`);

allArtifacts.artifacts.forEach(art => {
  console.log(`- ${art.name} (ID: ${art.id}, Size: ${art.size} bytes)`);
});

// List only the latest artifacts (useful for reruns)
const latestArtifacts = await artifact.listArtifacts({ 
  latest: true 
});

// List artifacts from another repository
const externalArtifacts = await artifact.listArtifacts({
  latest: true,
  findBy: {
    token: process.env.GITHUB_TOKEN!,
    workflowRunId: 987654321,
    repositoryOwner: "actions",
    repositoryName: "toolkit"
  }
});

/**
 * Finds an artifact by name within the current or specified workflow run.
 * If multiple artifacts exist with the same name, returns the latest one.
 * @param artifactName - Name of the artifact to find
 * @param options - Optional cross-repository access configuration
 * @returns Promise resolving to artifact metadata
 * @throws ArtifactNotFoundError if no artifact found with the specified name
 */
getArtifact(
  artifactName: string,
  options?: FindOptions
): Promise<GetArtifactResponse>;

interface GetArtifactResponse {
  /** Metadata for the found artifact */
  artifact: Artifact;
}

// Find artifact by name in current workflow
try {
  const result = await artifact.getArtifact("build-output");
  console.log(`Found artifact: ${result.artifact.name}`);
  console.log(`ID: ${result.artifact.id}, Size: ${result.artifact.size}`);
} catch (error) {
  if (error instanceof ArtifactNotFoundError) {
    console.error("build-output artifact not found");
  }
}

// Find artifact in external repository
const externalArtifact = await artifact.getArtifact("test-results", {
  findBy: {
    token: process.env.GITHUB_TOKEN!,
    workflowRunId: 456789123,
    repositoryOwner: "microsoft",
    repositoryName: "vscode"
  }
});

// Use found artifact for download
await artifact.downloadArtifact(externalArtifact.artifact.id);

interface FindOptions {
  /** Configuration for accessing artifacts from other repositories/runs */
  findBy?: {
    /** GitHub token with actions:read permissions on target repository */
    token: string;
    /** ID of the workflow run to search within */
    workflowRunId: number;
    /** Owner of the target repository */
    repositoryOwner: string;
    /** Name of the target repository */
    repositoryName: string;
  };
}

// 1. List available workflow runs (using GitHub API or @actions/github)
import { getOctokit } from "@actions/github";

const octokit = getOctokit(process.env.GITHUB_TOKEN!);
const runs = await octokit.rest.actions.listWorkflowRuns({
  owner: "actions",
  repo: "toolkit",
  workflow_id: "ci.yml"
});

// 2. Find artifacts in a specific run
const findBy = {
  token: process.env.GITHUB_TOKEN!,
  workflowRunId: runs.data.workflow_runs[0].id,
  repositoryOwner: "actions",
  repositoryName: "toolkit"
};

const artifacts = await artifact.listArtifacts({ findBy });

// 3. Get specific artifact details
const buildArtifact = await artifact.getArtifact("build-artifacts", { findBy });

// Without latest filter - may return duplicate names from reruns
const allRuns = await artifact.listArtifacts();

// With latest filter - only most recent artifact for each name
const uniqueArtifacts = await artifact.listArtifacts({ latest: true });

// Group artifacts by type
const artifacts = await artifact.listArtifacts();
const byType = artifacts.artifacts.reduce((acc, art) => {
  const type = art.name.split('-')[0]; // e.g., "build-", "test-", "docs-"
  acc[type] = acc[type] || [];
  acc[type].push(art);
  return acc;
}, {} as Record<string, Artifact[]>);

// Find largest artifacts
const sorted = artifacts.artifacts
  .sort((a, b) => b.size - a.size)
  .slice(0, 5);

console.log("Largest artifacts:");
sorted.forEach(art => {
  console.log(`${art.name}: ${(art.size / 1024 / 1024).toFixed(2)} MB`);
});

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

try {
  const result = await artifact.getArtifact("missing-artifact");
} catch (error) {
  if (error instanceof ArtifactNotFoundError) {
    console.log("Artifact not found - this is expected for optional artifacts");
  } else if (error instanceof NetworkError) {
    console.error("Network issue accessing GitHub API:", error.code);
    // Implement retry logic if needed
  }
}