Upload files and directories to create new GitHub Actions artifacts with configurable retention periods and compression levels.
Creates a new artifact by uploading files from the local filesystem.
/**
* Uploads an artifact containing the specified files.
* @param name - The name of the artifact (must be unique within the workflow run)
* @param files - Array of file paths to include in the artifact (absolute or relative)
* @param rootDirectory - Root directory path for resolving relative file paths
* @param options - Optional configuration for upload behavior
* @returns Promise resolving to upload response with artifact metadata
*/
uploadArtifact(
name: string,
files: string[],
rootDirectory: string,
options?: UploadArtifactOptions
): Promise<UploadArtifactResponse>;
interface UploadArtifactOptions {
/** Duration in days after which artifact will expire (1-90, defaults to repo settings) */
retentionDays?: number;
/** Zlib compression level 0-9 (0=none, 1=fastest, 6=default, 9=best) */
compressionLevel?: number;
}
interface UploadArtifactResponse {
/** Total size of uploaded artifact in bytes */
size?: number;
/** Unique identifier for the created artifact */
id?: number;
/** SHA256 hash digest of the artifact contents */
digest?: string;
}Usage Examples:
import { DefaultArtifactClient } from "@actions/artifact";
const artifact = new DefaultArtifactClient();
// Basic upload with default settings
const result = await artifact.uploadArtifact(
"build-artifacts",
["dist/app.js", "dist/app.css", "README.md"],
process.cwd()
);
console.log(`Uploaded artifact ${result.id} (${result.size} bytes)`);
// Upload with custom retention and compression
const customResult = await artifact.uploadArtifact(
"large-dataset",
["/data/large-file.bin", "/data/metadata.json"],
"/",
{
retentionDays: 7, // Keep for 1 week only
compressionLevel: 0 // No compression for faster upload
}
);
// Upload entire directory contents
import { glob } from "glob";
const files = await glob("build/**/*", { nodir: true });
const buildArtifact = await artifact.uploadArtifact(
"build-output",
files,
"build"
);Controls how long the artifact will be stored before automatic deletion.
Controls the Zlib compression applied to the artifact archive.
Recommendation: Use 0 for files that don't compress well (images, archives) or when upload speed is critical.
Common errors that can occur during upload:
import {
FilesNotFoundError,
NetworkError,
UsageError,
GHESNotSupportedError
} from "@actions/artifact";
try {
await artifact.uploadArtifact("my-artifact", files, rootDir);
} catch (error) {
if (error instanceof FilesNotFoundError) {
console.error("Files not found:", error.files);
} else if (error instanceof NetworkError) {
console.error("Network error:", error.code);
} else if (error instanceof UsageError) {
console.error("Storage quota exceeded");
} else if (error instanceof GHESNotSupportedError) {
console.error("GHES not supported for v2+ artifacts");
}
}