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

@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.

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

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:

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.

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}

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.

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.

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.

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

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

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

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

LICENSE | CHANGELOG