Introduction

You can write an action to provide a way for users to access your servers via a configured CLI environment on GitHub Actions runners.

Your action should:

• Make it simple for users to specify the version of the CLI to install
• Support multiple operating systems
• Run in an efficient fashion to minimize run-time and associated costs
• Work across GitHub-hosted and self-hosted runners
• Leverage community tooling when possible

This article will demonstrate how to write an action that retrieves a specific version of your CLI, installs it, adds it to the path, and (optionally) caches it. This type of action (an action that sets up a tool) is often namedsetup-$TOOL.

Prerequisites

You should have an understanding of how to write a custom action. For more information, seeManaging custom actions.

Example

The following script demonstrates how you can get a user-specified version as input, download and extract the specific version of your CLI, then add the CLI to the path.

GitHub providesactions/toolkit, which is a set of packages that helps you create actions. This example uses theactions/core andactions/tool-cache packages.

const core = require('@actions/core');const tc = require('@actions/tool-cache');async function setup() {  // Get version of tool to be installed  const version = core.getInput('version');  // Download the specific version of the tool, e.g. as a tarball  const pathToTarball = await tc.downloadTool(getDownloadURL());  // Extract the tarball onto the runner  const pathToCLI = await tc.extractTar(pathToTarball);  // Expose the tool by adding it to the PATH  core.addPath(pathToCLI)}module.exports = setup

const core =require('@actions/core');const tc =require('@actions/tool-cache');asyncfunctionsetup() {// Get version of tool to be installedconst version = core.getInput('version');// Download the specific version of the tool, e.g. as a tarballconst pathToTarball =await tc.downloadTool(getDownloadURL());// Extract the tarball onto the runnerconst pathToCLI =await tc.extractTar(pathToTarball);// Expose the tool by adding it to the PATH  core.addPath(pathToCLI)}module.exports = setup

To use this script, replacegetDownloadURL with a function that downloads your CLI. You will also need to create an actions metadata file (action.yml) that accepts aversion input and that runs this script. For full details about how to create an action, seeCreating a JavaScript action.

Further reading

This pattern is employed in several actions. For more examples, see:

• ruby/setup-ruby
• google-github-actions/setup-gcloud
• hashicorp/setup-terraform