Setup Tool Action

Generic action for installation of any tool that offers pre-compiled binaries for download.

Motivation

@actions/tool-cache exists to help download pre-compiled binaries and add them to $PATH. However, its ergonomics are such that distinct actions for specific tools are necessary to wrap it into something useful. For the most part, the wrapping is required to manage variation in the release URLs such as the position and names used for things like "os" or "architecture".

This doesn't scale. Instead, this action abstracts over that and offers good ergonomics for users to specify any variation directly via inputs. This should allow the action to be used easily for any such case, and obviate any tool-specific actions or support cases for which a tool-specific action doesn't exist, without having to create one.

Types

The action-types allows using this action with github-workflows-kt, which allows writing workflow files in a type-safe Kotlin DSL.

Usage

Look at the typical URLs for the binary assets you intend to install. Compare what you see to the default values for os, arch, and ext for the runners you plan to use:

Runner	Platform / {os}	Arch / {arch}	{ext}
ubuntu-latest	linux	x64	tar.gz
macos-latest	darwin	arm64	tar.gz
windows-latest	win32	x64	zip

If the values are correct across all the runners you use, you can do the following:

steps:
  - uses: pbrisbin/setup-tool-action@v2
    with:
      name: my-tool
      version: 1.0.0
      url: "http://releases.my-tool.com/{name}-{version}.{os}-{arch}.{ext}"

If the values are not correct, you can supply additional inputs to correct them.

Let's say you are only installing on Linux, and it uses x86_64 for arch:

steps:
  - uses: pbrisbin/setup-tool-action@v2
    with:
      name: my-tool
      version: 1.0.0
      url: "http://releases.my-tool.com/{name}-{version}.{os}-{arch}.{ext}"
      arch: x86_64

All inputs besides name and version have suffixed versions that can be used to supply different values by platform and/or arch:

• <input>-<platform>-<arch>
• <input>-<arch>
• <input>-<platform>
• <input>

The first match found is used.

Now let's say you were installing on Linux and MacOS, and you only want to change the arch for Linux, that would look like:

steps:
  - uses: pbrisbin/setup-tool-action@v2
    with:
      name: my-tool
      version: 1.0.0
      url: "http://releases.my-tool.com/{name}-{version}.{os}-{arch}.{ext}"
      arch-linux: x86_64

As a final example, let's also say this tool uses the legacy term osx for MacOS artifacts:

steps:
  - uses: pbrisbin/setup-tool-action@v2
    with:
      name: my-tool
      version: 1.0.0
      url: "http://releases.my-tool.com/{name}-{version}.{os}-{arch}.{ext}"
      os-darwin: osx
      arch-linux: x86_64

For more complex examples, see below or the project's test suite.

Inputs

name	description	required	default
name	Name of the tool	true	""
version	Version of the tool Required unless url is to a GitHub release asset, in which case the latest release will be looked up if left blank.	false	""
url	URL to installation archive. This value may contain interpolations for name, version, os, arch, and extension. http://example.com/binaries/{name}/{version}.{os}_{arch}.{ext} {name} and {version} will match the other inputs. {os}, {arch} and {ext}, will be inferred, but can be changed by setting additional inputs.	false	""
subdir	Subdirectory within the archive to find the executable(s). Supports the same interpolations as url.	false	""
os	{os} to use instead of process.platform	false	""
arch	{arch} to use instead of process.arch	false	""
ext	{ext} to use instead of inferring	false	""
no-extract	Do not extract the asset as an archive. Rather, expect that it represents the (only) binary itself. It will be downloaded, cached, and available on $PATH as {name}.	false	""
url-darwin	url when platform==darwin	false	""
url-linux	url when platform==linux	false	""
url-win32	url when platform==win32	false	""
url-x64	url when arch==x64	false	""
url-darwin-x64	url when platform==darwin and arch==x64	false	""
url-darwin-arm64	url when platform==darwin and arch==arm64	false	""
url-linux-x64	url when platform==linux and arch==x64	false	""
url-win32-x64	url when platform==win33 and arch==x64	false	""
subdir-darwin	subdir when platform==darwin	false	""
subdir-linux	subdir when platform==linux	false	""
subdir-win32	subdir when platform==win32	false	""
subdir-x64	subdir when arch==x64	false	""
subdir-arm64	subdir when arch==arm64	false	""
subdir-darwin-x64	subdir when platform==darwin and arch==x64	false	""
subdir-darwin-arm64	subdir when platform==darwin and arch==arm64	false	""
subdir-linux-x64	subdir when platform==linux and arch==x64	false	""
subdir-win32-x64	subdir when platform==win33 and arch==x64	false	""
os-darwin	{os} to use when platform==darwin	false	""
os-linux	{os} to use when platform==linux	false	""
os-win32	{os} to use when platform==win32	false	""
os-x64	{os} to use when arch==x64	false	""
os-arm64	{os} to use when arch==arm64	false	""
os-darwin-x64	{os} to use when platform==darwin and arch==x64	false	""
os-darwin-arm64	{os} to use when platform==darwin and arch==arm64	false	""
os-linux-x64	{os} to use when platform==linux and arch==x64	false	""
os-win32-x64	{os} to use when platform==win32 and arch==x64	false	""
arch-darwin	{arch} to use when platform==darwin	false	""
arch-linux	{arch} to use when platform==linux	false	""
arch-win32	{arch} to use when platform==win32	false	""
arch-x64	{arch} to use when arch==x64	false	""
arch-arm64	{arch} to use when arch==arm64	false	""
arch-darwin-x64	{arch} to use when platform==darwin and arch==x64	false	""
arch-darwin-arm64	{arch} to use when platform==darwin and arch==arm64	false	""
arch-linux-x64	{arch} to use when platform==linux and arch==x64	false	""
arch-win32-x64	{arch} to use when platform==win32 and arch==x64	false	""
ext-darwin	{ext} to use when platform==darwin	false	""
ext-linux	{ext} to use when platform==linux	false	""
ext-win32	{ext} to use when platform==win32	false	""
ext-x64	{ext} to use when arch==x64	false	""
ext-arm64	{ext} to use when arch==arm64	false	""
ext-darwin-x64	{ext} to use when platform==darwin and arch==x64	false	""
ext-darwin-arm64	{ext} to use when platform==darwin and arch==arm64	false	""
ext-linux-x64	{ext} to use when platform==linux and arch==x64	false	""
ext-win32-x64	{ext} to use when platform==win33 and arch==x64	false	""
github-token	If present, and url is to a GitHub release asset, we will assume it's private and use this token to download the asset through the GitHub API. https://docs.github.com/en/rest/releases/assets?apiVersion=2022-11-28#get-a-release-asset	false	""
github-token-for-latest	Token used for looking up a latest release when version is blank, url is to a GitHub release asset, and github-token is not set. This is to avoid rate limits when interacting with public releases.	false	${{ github.token }}

Outputs

name	description
directory	Directory that was added to $PATH as result of setup.
file	This is always outputs.directory/inputs.name, which will usually match the path to the downloaded and extracted binary. Only use this output if you expect that to be the case.

GitHub Release Assets

One common use-case for this action is to download assets attached to GitHub releases. Two additional features are supported for this use case:

1. Private GitHub Repositories
2. Downloading "Latest"

Both features are available if-and-only-if the url input matches:

https://github.com/{owner}/{repo}/releases/download/{tag}/{name}

Releases in Private GitHub Repositories

If url matches the given pattern, and the github-token input is set, the action will parse the url for owner/repo, tag and asset name, then use the GitHub API to find the correct /releases/assets/{asset-id} URL and then download that, all using the given token.

Downloading "Latest"

If url matches the given pattern, and version is left blank, the action will parse the url for owner/repo and query the /releases/latest API endpoint, using the returned release's tag_name as version.

Important

The tag_name will have any v-prefix dropped. This is because it's common to have release tags with a v prefix, but to need to use the unprefixed value within the download URLs. See the HLint example in our own CI.

This API request will be made with github-token if set (i.e if it's a private repository) or the github-token-for-latest input, which defaults to github.token. You shouldn't have to change this default as the token in that case is only necessary to avoid rate limits on public resources.

Examples

HLint

with:
  name: "hlint"
  version: "3.5"
  url: "https://github.com/ndmitchell/{name}/releases/download/v{version}/{name}-{version}-{arch}-{os}.{ext}"
  subdir: "{name}-{version}"
  os-darwin: osx
  os-win32: windows
  arch-x64: x86_64

Can replace: https://github.com/haskell-actions/hlint-setup

Dead Man's Snitch Field Agent

with:
  name: dms
  version: latest
  url: "https://releases.deadmanssnitch.com/field-agent/{version}/{name}_{os}_{arch}.{ext}"
  os-darwin: macos
  os-win32: windows
  arch-x64: amd64

Can replace: N/A

Pandoc

with:
  name: pandoc
  version: 2.19.2
  url: "https://github.com/jgm/{name}/releases/download/{version}/{name}-{version}-{os}-{arch}.{ext}"
  url-darwin: "https://github.com/jgm/{name}/releases/download/{version}/{name}-{version}-macOS.zip"
  subdir: "{name}-{version}/bin"
  subdir-win32: "{name}-{version}"
  os-win32: windows
  arch-x64: x86_64
  arch-linux-x64: amd64

Can replace: https://github.com/r-lib/actions/tree/v2-branch/setup-pandoc

More...

If you use this action successfully for another tool, please open a PR adding it to the CI matrix and this README.

---

LICENSE | CHANGELOG