https://github.com/pbrisbin/setup-tool-action

Generic action for installation of any tool that offers pre-compiled binaries for download
https://github.com/pbrisbin/setup-tool-action

actions

Last synced: 3 months ago
JSON representation

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

Host: GitHub
URL: https://github.com/pbrisbin/setup-tool-action
Owner: pbrisbin
License: mit
Created: 2022-12-05T14:55:46.000Z (over 2 years ago)
Default Branch: main
Last Pushed: 2024-10-30T01:15:29.000Z (7 months ago)
Last Synced: 2024-10-30T03:53:36.541Z (7 months ago)
Topics: actions
Language: TypeScript
Homepage:
Size: 905 KB
Stars: 4
Watchers: 3
Forks: 2
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

# Setup Tool Action

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

## Motivation

[`@actions/tool-cache`][tc] 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".

[tc]: https://github.com/actions/toolkit/tree/main/packages/tool-cache

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`](action-types.yml) allows using this action with
[github-workflows-kt][kt], which allows writing workflow files in a type-safe
Kotlin DSL.

[kt]: https://github.com/typesafegithub/github-workflows-kt

## 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:

```yaml
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`:

```yaml
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`:

- `--`
- `-`
- `-`
- ``

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:

```yaml
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:

```yaml
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

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.

Subdirectory within the archive to find the executable(s). Supports the same interpolations as url.

| `false` | `""` |
| `os` |

{os} to use instead of process.platform

{arch} to use instead of process.arch

| `false` | `""` |
| `ext` |

{ext} to use instead of inferring

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

url when platform==darwin

url when platform==linux

url when platform==win32

url when arch==x64

url when platform==darwin and arch==x64

url when platform==darwin and arch==arm64

url when platform==linux and arch==x64

url when platform==win33 and arch==x64

subdir when platform==darwin

subdir when platform==linux

subdir when platform==win32

subdir when arch==x64

subdir when arch==arm64

subdir when platform==darwin and arch==x64

subdir when platform==darwin and arch==arm64

subdir when platform==linux and arch==x64

subdir when platform==win33 and arch==x64

{os} to use when platform==darwin

{os} to use when platform==linux

{os} to use when platform==win32

| `false` | `""` |
| `os-x64` |

{os} to use when arch==x64

{os} to use when arch==arm64

{os} to use when platform==darwin and arch==x64

{os} to use when platform==darwin and arch==arm64

{os} to use when platform==linux and arch==x64

{os} to use when platform==win32 and arch==x64

{arch} to use when platform==darwin

{arch} to use when platform==linux

{arch} to use when platform==win32

{arch} to use when arch==x64

{arch} to use when arch==arm64

{arch} to use when platform==darwin and arch==x64

{arch} to use when platform==darwin and arch==arm64

{arch} to use when platform==linux and arch==x64

{arch} to use when platform==win32 and arch==x64

{ext} to use when platform==darwin

{ext} to use when platform==linux

{ext} to use when platform==win32

{ext} to use when arch==x64

{ext} to use when arch==arm64

{ext} to use when platform==darwin and arch==x64

{ext} to use when platform==darwin and arch==arm64

{ext} to use when platform==linux and arch==x64

{ext} to use when platform==win33 and arch==x64

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

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

```yaml
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

```yaml
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

```yaml
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](./LICENSE) | [CHANGELOG](./CHANGELOG.md)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/pbrisbin/setup-tool-action

Awesome Lists containing this project

README