Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

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

actions

Last synced: 19 days ago
JSON representation

Generic action for cached 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 (almost 2 years ago)
Default Branch: main
Last Pushed: 2024-05-29T01:04:47.000Z (6 months ago)
Last Synced: 2024-05-29T15:09:55.253Z (6 months ago)
Topics: actions
Language: TypeScript
Homepage:
Size: 1.26 MB
Stars: 4
Watchers: 2
Forks: 1
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

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

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

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

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