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	`true`	`""`
`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`	`""`

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.

Releases in Private GitHub Repositories

To download an asset from a Release in a private GitHub repository,

Use the URL to the asset as if you were in an authenticated browser (i.e. as if it were public)
Set github-token to a token with access to the private repository

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.

NOTE: This currently only works for URLs on github.com. PRs welcome if there's a way to support enterprise or other setups.

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