or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

caching.mddiscovery.mddownload.mdextraction.mdindex.mdmanifest.mdversions.md
tile.json

index.mddocs/

Actions Tool Cache

Actions Tool Cache is a comprehensive TypeScript library that provides essential functionality for downloading, extracting, caching, and retrieving tools within GitHub Actions workflows. It offers cross-platform support for downloading files from URLs with authentication, platform-specific extraction capabilities for various archive formats, intelligent caching system for storing tools locally, and efficient tool discovery through semantic version matching.

Package Information

  • Package Name: @actions/tool-cache
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @actions/tool-cache

Core Imports

import {
  downloadTool,
  extractZip,
  extractTar,
  extract7z,
  extractXar,
  cacheDir,
  cacheFile,
  find,
  findAllVersions
} from "@actions/tool-cache";

For CommonJS:

const {
  downloadTool,
  extractZip,
  extractTar,
  extract7z,
  extractXar,
  cacheDir,
  cacheFile,
  find,
  findAllVersions
} = require("@actions/tool-cache");

Basic Usage

import * as tc from "@actions/tool-cache";
import * as core from "@actions/core";

// Download, extract, cache, and use a tool
async function setupNode() {
  // Download tool
  const downloadPath = await tc.downloadTool(
    "https://nodejs.org/dist/v18.17.0/node-v18.17.0-linux-x64.tar.gz"
  );
  
  // Extract archive
  const extractedPath = await tc.extractTar(downloadPath);
  
  // Cache the tool
  const cachedPath = await tc.cacheDir(extractedPath, "node", "18.17.0");
  
  // Add to PATH
  core.addPath(cachedPath);
}

// Find previously cached tool
const nodePath = tc.find("node", "18.x");
if (nodePath) {
  core.addPath(nodePath);
}

Architecture

Actions Tool Cache is built around several key components:

  • Download System: HTTP client with retry logic, authentication support, and robust error handling for reliable tool acquisition
  • Extraction Engines: Platform-specific extraction support for ZIP, tar (with compression), 7z, and XAR archive formats
  • Caching Layer: Persistent tool storage with semantic versioning, architecture awareness, and efficient lookup mechanisms
  • Discovery Engine: Semantic version matching with range support for finding cached tools and versions
  • Manifest System: GitHub repository-based tool manifest support for automated tool discovery and selection

Capabilities

Tool Download

HTTP-based tool downloading with authentication, retry logic, and error handling. Supports custom headers and destinations.

function downloadTool(
  url: string,
  dest?: string,
  auth?: string,
  headers?: OutgoingHttpHeaders
): Promise<string>;

class HTTPError extends Error {
  constructor(readonly httpStatusCode: number | undefined);
}

Download Tools

Archive Extraction

Archive extraction supporting multiple formats including ZIP, tar with various compression schemes, 7z (Windows only), and XAR (macOS).

function extractZip(file: string, dest?: string): Promise<string>;
function extractTar(
  file: string,
  dest?: string,
  flags?: string | string[]
): Promise<string>;
function extract7z(
  file: string,
  dest?: string,
  _7zPath?: string
): Promise<string>;
function extractXar(
  file: string,
  dest?: string,
  flags?: string | string[]
): Promise<string>;

Archive Extraction

Tool Caching

Persistent tool storage system with semantic versioning and architecture support for efficient tool management across workflow runs.

function cacheDir(
  sourceDir: string,
  tool: string,
  version: string,
  arch?: string
): Promise<string>;
function cacheFile(
  sourceFile: string,
  targetFile: string,
  tool: string,
  version: string,
  arch?: string
): Promise<string>;

Tool Caching

Tool Discovery

Semantic version-aware tool discovery for finding cached tools with support for version ranges and architecture filtering.

function find(
  toolName: string,
  versionSpec: string,
  arch?: string
): string;
function findAllVersions(toolName: string, arch?: string): string[];

Tool Discovery

Manifest-Based Resolution

GitHub repository-based tool manifest system for automated tool discovery, version resolution, and platform-specific downloads.

function getManifestFromRepo(
  owner: string,
  repo: string,
  auth?: string,
  branch?: string
): Promise<IToolRelease[]>;
function findFromManifest(
  versionSpec: string,
  stable: boolean,
  manifest: IToolRelease[],
  archFilter?: string
): Promise<IToolRelease | undefined>;

interface IToolRelease {
  version: string;
  stable: boolean;
  release_url: string;
  files: IToolReleaseFile[];
}

interface IToolReleaseFile {
  filename: string;
  platform: string;
  platform_version?: string;
  arch: string;
  download_url: string;
}

Manifest System

Version Utilities

Semantic version evaluation and validation utilities for working with version specifications and ranges.

function isExplicitVersion(versionSpec: string): boolean;
function evaluateVersions(
  versions: string[],
  versionSpec: string
): string;

Version Utilities

Types

import { OutgoingHttpHeaders } from "http";

class HTTPError extends Error {
  constructor(readonly httpStatusCode: number | undefined);
}

interface IToolRelease {
  version: string;
  stable: boolean;
  release_url: string;
  files: IToolReleaseFile[];
}

interface IToolReleaseFile {
  filename: string;
  platform: string;
  platform_version?: string;
  arch: string;
  download_url: string;
}