release-downloader GitHub Action

The robinraju/release-downloader action allows you to download assets from GitHub releases, including files from both private and public repositories. You can target specific tags, release IDs, or the latest release, and support wildcard patterns for filenames. It also supports downloading and automatically extracting archives like .zip, .tar, or .tar.gz.

- uses: robinraju/release-downloader@v1
  with:
    repository: 'owner/repo'
    latest: true
    fileName: 'foo.zip'

The repository input must follow the exact format {owner}/{repo}. If the input does not contain exactly two parts separated by a forward slash, or if either the owner or the repository name is empty, the action will fail with a ConfigError.

Example of valid format: owner/repository-name

Common usage patterns for the release downloader:

Download from latest release in current repository

- uses: robinraju/release-downloader@v1
  with:
    latest: true
    fileName: 'foo.zip'

Download from a specific tag

- uses: robinraju/release-downloader@v1
  with:
    repository: 'owner/repo'
    tag: 'v1.0.0'
    fileName: 'foo.zip'

Download and extract archives

- uses: robinraju/release-downloader@v1
  with:
    fileName: 'foo.zip'
    latest: true
    extract: true

Download using wildcard patterns (e.g., all .deb files)

- uses: robinraju/release-downloader@v1
  with:
    repository: 'owner/repo'
    latest: true
    fileName: '*.deb'

Download latest pre-release

- uses: robinraju/release-downloader@v1
  with:
    repository: 'owner/repo'
    fileName: 'foo.zip'
    latest: true
    preRelease: true

The action provides several outputs that can be used by subsequent steps in your workflow:

• tag_name: The tag used to download the release.
• release_name: The name/title of the release.
• downloaded_files: An array of the paths to the downloaded files.

To use these in subsequent steps, use the following syntax:

# Access tag_name
${{ steps.<step-id>.outputs.tag_name }}

# Access release_name
${{ steps.<step-id>.outputs.release_name }}

# Access the first file in the downloaded_files array
${{ fromJson(steps.<step-id>.outputs.downloaded_files)[0] }}

The getHttpErrorReason function converts GitHub HTTP status codes into human-readable error messages. This is useful for troubleshooting network or permission issues during the download process.

import { getHttpErrorReason } from './errors';

const reason = getHttpErrorReason(404);
// returns 'Not found - verify the repository/tag/release exists'

The package provides a top-level run() function that serves as the main entrypoint to initiate the release downloading process. When called, it executes the core logic of the downloader based on the provided configuration or environment settings.

import { run } from './main.js';

run();

The run() function serves as the main entrypoint for this GitHub Action. It orchestrates the downloading of assets from a GitHub release based on provided inputs.

To use this action, you must provide the following inputs in your workflow file:

• token: A GitHub authentication token (required for private repositories or to avoid rate limits).
• github-api-url: The base URL for the GitHub API.

The execution flow is:

1. Retrieves download settings from inputs.
2. Initializes an authenticated HttpClient using the provided token.
3. Uses ReleaseDownloader to download assets.
4. If extractAssets is enabled in the settings, it automatically unarchives the downloaded files to the specified extractPath.

// This is the main entrypoint called by the GitHub Action runner
export async function run(): Promise<void> {}

The following mappings are used by getHttpErrorReason to provide context for HTTP failures:

400: Bad request - the request was malformed
401: Authentication failed - check your token is valid
403: Access denied - check your token has the required permissions
404: Not found - verify the repository/tag/release exists
422: Unprocessable entity - the request was valid but could not be processed
429: Rate limited - too many requests, try again later
500: GitHub server error - this is likely temporary, try again
502: Bad gateway - GitHub may be experiencing issues
503: Service unavailable - GitHub may be experiencing issues

The project uses the following TypeScript interfaces to represent data retrieved from the GitHub API and processed for downloads:

• GithubRelease: Represents a full GitHub release object, including its name, ID, tag name, prerelease status, and associated assets.
• GhAsset: Represents an individual asset attached to a GitHub release.
• DownloadMetaData: Represents the processed information required to perform a download, identifying the filename, the direct download URL, and whether the target is a tarball or zipball.

interface GhAsset {
  name: string
  url: string
}

export interface GithubRelease {
  name: string
  id: number
  tag_name: string
  prerelease: boolean
  assets: GhAsset[]
  tarball_url: string
  zipball_url: string
}

export interface DownloadMetaData {
  fileName: string
  url: string
  isTarBallOrZipBall: boolean
}