engineerd / configurator

Cross-platform GitHub Action to download, extract, and add to path statically compiled tools

@engineerd/configurator

Cross-platform GitHub Action for downloading statically compiled tools (or archives) and adding them to the path. This has been tested on ubuntu-latest, windows-latest, and macos-latest.

This action can be used in two modes:

• directly providing a download URL (or a URL per-platform, using a configuration matrix)
• providing a URL template and a semver version or range to be selected from GitHub releases. In this mode, the action iterates through the GitHub releases to find the latest version that satisfies the version (or range) constraint, constructs the download URL, and adds the tool to the path.

Directly downloading tools based on URL

Inputs:

• name: name your tool will be configured with (required)
• url: URL to download your tool from (required)
• pathInArchive: if the URL points to an archive, this field is required, and points to the path of the tool to configure, relative to the archive root

Examples - a cross-platform action that downloads, extracts, and adds Helm v3.3.0 to the path:

jobs:
  configurator:
    runs-on: ${{ matrix.config.os }}
    strategy:
      matrix:
        config:
          - {
              os: "ubuntu-latest",
              url: "https://get.helm.sh/helm-v3.3.0-linux-amd64.tar.gz",
              name: "h3",
              pathInArchive: "linux-amd64/helm",
            }
          - {
              os: "windows-latest",
              url: "https://get.helm.sh/helm-v3.3.0-windows-amd64.zip",
              name: "h3.exe",
              pathInArchive: "windows-amd64/helm.exe",
            }
    steps:
      - uses: engineerd/[email protected]
        with:
          name: ${{ matrix.config.name }}
          url: ${{ matrix.config.url }}
          pathInArchive: ${{ matrix.config.pathInArchive }}
      - name: Testing
        run: |
          h3 --help

Selecting versions from GitHub Releases

Inputs:

• name: name your tool will be configured with (required)
• pathInArchive: if the URL points to an archive, this field is required, and points to the path of the tool to configure, relative to the archive root
• fromGitHubReleases: if true, the action will attempt to get the latest version from the specified repository's GitHub Releases that matches the given semver version or range provided, and then construct the download URL using the provided urlTemplate.
• repo: GitHub repository of the tool. Used to list all releases and select the proper version. Required if fromGitHubReleases is true.
• version: an exact semver version or version range (specified with ^ or ~, as defined and used by NPM). If using semver ranges with v0.x.x releases, be sure to understand the semver behavior here. If latest is provided, the action will download the latest release (respecting the includePrereleases flag), which, can break your action. Required if fromGitHubReleases is true.
• token: GitHub token used only to list the GitHub releases for the supplied repository. For most cases, its value should be ${{ secrets.GITHUB_TOKEN }}. Required if fromGitHubReleases is true.
• urlTemplate: a URL template used to construct the download URL, together with the desired version acquired from a GitHub release. For example, https://get.helm.sh/helm-{{version}}-linux-amd64.tar.gz (the version inserted here is the exact tag name from GitHub - check whether the tag name contains any v before the version when constructing the URL template). Note that this is Mustache template (completely separate from the GitHub Actions templating system - the template must be {{version}}). Note that if the version tag has a leading v, a {{rawVersion}} variable that doesn't contain the leading v can be used in the urlTemplate. Required if fromGitHubReleases is true.
• includePrereleases: if true, the action will include pre-releases when selecting a version from GitHub Releases.

Example - a cross-platform action that selects the latest Helm version that satisfies the ^3.1.2 release constraint - meaning it selects any minor and patch update, or, in other words, the latest v3.x.x version:

jobs:
  configurator:
    runs-on: ${{ matrix.config.os }}
    strategy:
      matrix:
        config:
          - {
              os: "ubuntu-latest",
              urlTemplate: "https://get.helm.sh/helm-{{version}}-linux-amd64.tar.gz",
              name: "h3",
              pathInArchive: "linux-amd64/helm",
            }
          - {
              os: "windows-latest",
              urlTemplate: "https://get.helm.sh/helm-{{version}}-windows-amd64.zip",
              name: "h3.exe",
              pathInArchive: "windows-amd64/helm.exe",
            }
    steps:
      - uses: engineerd/[email protected]
        with:
          name: ${{ matrix.config.name }}
          pathInArchive: ${{ matrix.config.pathInArchive }}
          fromGitHubReleases: "true"
          repo: "helm/helm"
          version: "^v3.1.2"
          urlTemplate: ${{ matrix.config.urlTemplate }}
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Testing
        run: |
          h3 --help

Example - an action that selects the latest non-pre-release (as marked in the GitHub release) of Kind:

jobs:
  kind:
    runs-on: ubuntu-latest
    steps:
      - uses: engineerd/[email protected]
        with:
          name: "kind"
          fromGitHubReleases: "true"
          repo: "kubernetes-sigs/kind"
          urlTemplate: "https://github.com/kubernetes-sigs/kind/releases/download/{{version}}/kind-linux-amd64"
          version: "latest"
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Testing
        run: |
          kind --help

Other examples

• download an executable from a given URL and move it to a folder in path with the given name:

name: "Test plain file"
on: [pull_request, push]

jobs:
  kind:
    runs-on: ubuntu-latest
    steps:
      - uses: engineerd/[email protected]
        with:
          name: "kind"
          url: "https://github.com/kubernetes-sigs/kind/releases/download/v0.8.1/kind-linux-amd64"
      - name: Testing
        run: |
          kind --help

• download a .tar.gz archive from a given URL, and move a certain file from the archive directory to a folder in path, with a given name:

name: "Test .tar.gz"
on: [pull_request, push]

jobs:
  kind:
    runs-on: ubuntu-latest
    steps:
      - uses: engineerd/[email protected]
        with:
          name: "h3"
          url: "https://get.helm.sh/helm-v3.3.0-linux-amd64.tar.gz"
          pathInArchive: "linux-amd64/helm"
      - name: Testing
        run: |
          h3 --help

• download a .zip archive on Windows from a given URL, and move a certain file from the archive directory to a folder in path, with a given name:

name: "Test .zip"
on: [pull_request, push]

jobs:
  kind:
    runs-on: windows-latest
    steps:
      - uses: engineerd/[email protected]
        with:
          name: "h3.exe"
          url: "https://get.helm.sh/helm-v3.3.0-windows-amd64.zip"
          pathInArchive: "windows-amd64/helm.exe"
      - name: Testing
        run: |
          h3 --help

Note: usually, Windows-specific tooling uses .zip archives - and the tar utility on Windows doesn't seem to handle .tar.gz files properly. Note: for Linux, chmod +x is called on the target file before moving it to the path, ensuring it is executable. On Windows this is skipped.

configurator's Issues

Feature Request: Option to disable `chmod +x` on file

I was pleased to find this is it seemed to do what I wanted, but reading more carefully it looks like a chmod +x is performed on every file (which I don't want).

I want to use this for not only executable binaries, but also the associated man files and often also bash completion files and these obviously should not be made executable.

When I extract the files manually I find that the execute permissions on binaries are already set anyway.

Does anybody know of anything similar which I could use for these files? Or should I use another action to change chmod the files again afterwards?

Add support for .tgz suffix

Hi

Some projects uses a ".tgz" file name suffix for gzipped tar archives.
Could you possibly add support for .tgz suffix for archive extraction?

Error: Not Found using urlTemplate

Hello,

I am able to use your action using the old url property, but when I try to use the urlTemplate I have an error.

Here's the step in the job :

    - uses: engineerd/[email protected]
      with:
        name: docfx.exe
        pathInArchive: docfx.exe
        fromGitHubReleases: true
        includePrereleases: false
        version: latest
        repo: https://github.com/dotnet/docfx.git
        urlTemplate: https://github.com/dotnet/docfx/releases/download/{{version}}/docfx.zip
        token: ${{ secrets.GITHUB_TOKEN }}

Also I know it won't work anyway because there's no support for the directory property yet, but I would know why I got this error. Thank you!

Allow for different bin folder executables

I was trying to do

      - uses: engineerd/[email protected]
        with:
          name: /home/runner/.cargo/bin/cargo-binstall
          url: https://github.com/ryankurte/cargo-binstall/releases/download/v0.11.1/cargo-binstall-x86_64-unknown-linux-musl.tgz
          pathInArchive: cargo-binstall

and it installed to /home/runner/configurator/bin/home/runner/.cargo/bin/cargo-binstall not the folder I expected!

Does not handle non-standard versions

I've been trying to use engineerd/configurator to install the latest version of kubernetes-sigs/kustomize, following the example given for kubernetes-sigs/kind.

kind github release versions follow the expected convention (e.g. v0.11.1) however kustomize github release versions contain the name of the binary as well (e.g. kustomize/v4.4.0). I've found that both the {{version}} and {{rawVersion}} template variables contain values like kustomize/v4.4.0 and as such I've been unable to construct a proper urlTemplate.

How can I use this action to download releases like kustomize that have more complex version number formats?

Aqua

Hey

i had the same need and use aqua inside GitHub as well as laptop and server.

https://github.com/aquaproj/aqua

It’s a registry and a proxy so you can setup your config and any binary you need is gotten and invoked.

there is a large GitHub registry which just holds a link to binaries on other GitHub repo releases.

Even works on windows !

Explore moving the entire archive and remove the restriction of statically compiled tools

Adding an optional type: directory input might allow us to move the entire directory and add it to the path.

executable tool with dependencies

When executing the tool defined in PathInArchive, its dependent binary can't be loaded and error out.
Is this by design? I Briefly looked at the code but would including binary path to PATH environment be effective instead of move?

tag `v0.0.9` doesn't match branch `v0.0.9`

See the title.

Input parameters based on matrix value

Since this is a cross-platform action, and GitHub Actions supports a build matrix, it would be really nice to be able to set all action parameters based on the OS from the matrix.

However, I'm not sure if it is possible to have a set of inputs enabled only for a specific OS (rather than running all possible combinations of inputs from the matrix).

Infer some values for Github Release

Having used this action a few times now, I think there's some possibility to make the action a bit less boilerplate-y.

Specifically, if the user specifies a urlTemplate that matches ^https:\/\/github\.com\/(?<repo>.*\/.*)\/releases\/download\/, infer the following:

fromGithubReleases: true
repo: <repo from regex>
version: latest

So that this:

      - uses: engineerd/[email protected]
        with:
          name: "kind"
          fromGitHubReleases: "true"
          repo: "kubernetes-sigs/kind"
          urlTemplate: "https://github.com/kubernetes-sigs/kind/releases/download/{{version}}/kind-linux-amd64"
          version: "latest"
          token: ${{ secrets.GITHUB_TOKEN }}

would become this:

      - uses: engineerd/[email protected]
        with:
          name: "kind"
          urlTemplate: "https://github.com/kubernetes-sigs/kind/releases/download/{{version}}/kind-linux-amd64"
          token: ${{ secrets.GITHUB_TOKEN }}

Hardcoded drive letter (Win32)

https://github.com/engineerd/configurator/blob/master/src/configurator.ts#L87

export function binPath(): string {
    let baseLocation: string;
    if (process.platform === 'win32') {
        // On windows use the USERPROFILE env variable
        baseLocation = process.env['USERPROFILE'] || 'C:\\';

There's no guarantee there will be such a thing as a C: drive on Windows. I'd say play it safe, use %TEMP%, %TMP% or %HOMEDRIVE%, these are usually sane and point to a valid location.

Input Validation

Was testing out the new GitHub Releases feature (thanks!), and twice do to some still-waking-up issues managed to misspell or malform the with. Would be nice to get some basic validation. Like if fromGithubReleases is provided, error if either repo, version, or urlTemplate is not present.

Feature request: Support downloading from Github releases with version selection support

Thanks for this action. I wonder if this can be further extended to download binaries from GitHub releases with version selection.

Here is my use-case. I have quite a few workflow files like this: https://github.com/stashed/CHANGELOG/blob/master/.github/workflows/release.yml#L21-L43

As you can see, I am downloading binaries from GitHub releases. The problem for me is that everytime I cut a new release, I have to update the files manually. What will be really helpful if I could use something like this:

    steps:
      - uses: engineerd/[email protected]
        with:
          repo: appscodelabs/hugo-tools
          version: latest # v0.2.* etc semver constraint to automatically pick the version
          file: hugo-tools-linux-amd64
		  exe: hugo-tools

I am just making up this example. But the key point is that this action list Github releases and selects the one based on the version constraint and then installs the binary from that release.

Do you think this action can do that? If not, will you be willing to add support for something like this? Do you know any other action that can do this?

Thanks!

Update to Node.js 20

Node.js 16 actions are deprecated. Please update the following actions to use Node.js 20: engineerd/[email protected]. For more information see: https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/.

Update vulnerable `minimist` dev dependency

Note that this is a vulnerability of a dev dependency, so no vulnerable packages are part of the action when executed in production.

We should mitigate this nonetheless.

See CVE-2020-7598

GitHub deprecating old add-path

FYI: https://github.blog/changelog/2020-10-01-github-actions-deprecating-set-env-and-add-path-commands/

The only change ya'll should have to make is bump you @actions/core package.

Configure multiple tools with a single action invocation

Right now, if you want to setup N tools, you need to invoke this action N times - it would be really helpful if a list of the inputs could be provided - not sure this is possible with the current GitHub Actions metadata schema.

Fix action running in macOS

Handle compressed binaries

Some github projects provide their releases as compressed, but not archived, binaries.

One such example being Shopify's Javy.

It would be swell if configurator was able decompress such a binary and then install it in the same manner it does uncompressed binaries.

command "##[add-path]" is depreated

Error: Unable to process command '##[add-path]/home/runner/configurator/bin' successfully.
Error: The `add-path` command is disabled. Please upgrade to using Environment Files or opt into unsecure command execution by setting the `ACTIONS_ALLOW_UNSECURE_COMMANDS` environment variable to `true`. For more information see: https://github.blog/changelog/2020-10-01-github-actions-deprecating-set-env-and-add-path-commands/

Node.js 12 Deprecated

WIth Node.js 12 deprecated in Github Actions, this action needs to be upgraded to node 16 to continue to be compatible.

Are there plans to do this? It seems like this action may be unmaintained. Does anyone know of an alternative? Thanks!