|
| 1 | +--- |
| 2 | +title: Developing a third party CLI action |
| 3 | +shortTitle: CLI setup action |
| 4 | +intro: 'Learn how to develop an action to set up a CLI on {% data variables.product.prodname_actions %} runners.' |
| 5 | +product: '{% data reusables.gated-features.actions %}' |
| 6 | +redirect_from: [] |
| 7 | +versions: |
| 8 | + fpt: '*' |
| 9 | +type: tutorial |
| 10 | +topics: |
| 11 | + - Actions |
| 12 | +--- |
| 13 | + |
| 14 | +## Introduction |
| 15 | + |
| 16 | +You can write an action to provide a way for users to access your servers via a configured CLI environment on {% data variables.product.prodname_actions %} runners. |
| 17 | + |
| 18 | +Your action should: |
| 19 | + |
| 20 | +- Make it simple for users to specify the version of the CLI to install |
| 21 | +- Support multiple operating systems |
| 22 | +- Run in an efficient fashion to minimize run-time and associated costs |
| 23 | +- Work across {% data variables.product.product_name %}-hosted and self-hosted runners |
| 24 | +- Leverage community tooling when possible |
| 25 | + |
| 26 | +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 named `setup-$TOOL`. |
| 27 | + |
| 28 | +## Prerequisites |
| 29 | + |
| 30 | +You should have an understanding of how to write a custom action. For more information, see "[About custom actions](/actions/creating-actions/about-custom-actions)". For a more detailed guide on how to write a custom action, see "[Creating a JavaScript action](/actions/creating-actions/creating-a-javascript-action)." |
| 31 | + |
| 32 | +## Example |
| 33 | + |
| 34 | +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. |
| 35 | + |
| 36 | +{% data variables.product.prodname_dotcom %} provides [`actions/toolkit`](https://github.com/actions/toolkit), which is a set of packages that helps you create actions. This example uses the [`actions/core`](https://github.com/actions/toolkit/tree/main/packages/core) and [`actions/tool-cache`](https://github.com/actions/toolkit/tree/main/packages/tool-cache) packages. |
| 37 | + |
| 38 | +{% raw %} |
| 39 | +```javascript{:copy} |
| 40 | +const core = require('@actions/core'); |
| 41 | +const tc = require('@actions/tool-cache'); |
| 42 | +
|
| 43 | +async function setup() { |
| 44 | + // Get version of tool to be installed |
| 45 | + const version = core.getInput('version'); |
| 46 | +
|
| 47 | + // Download the specific version of the tool, e.g. as a tarball |
| 48 | + const pathToTarball = await tc.downloadTool(getDownloadURL()); |
| 49 | +
|
| 50 | + // Extract the tarball onto the runner |
| 51 | + const pathToCLI = await tc.extractTar(pathToTarball); |
| 52 | +
|
| 53 | + // Expose the tool by adding it to the PATH |
| 54 | + core.addPath(pathToCLI) |
| 55 | +} |
| 56 | +
|
| 57 | +module.exports = setup |
| 58 | +``` |
| 59 | +{% endraw %} |
| 60 | + |
| 61 | +To use this script, replace `getDownloadURL` with a function that downloads your CLI. You will also need to create an actions metadata file (`action.yml`) that accepts a `version` input and that runs this script. For full details about how to create an action, see "[Creating a JavaScript action](/actions/creating-actions/creating-a-javascript-action)." |
| 62 | + |
| 63 | +For a full example of how to set up this action, see [example-setup-gh](https://github.com/github-developer/example-setup-gh). |
| 64 | + |
| 65 | +## Further reading |
| 66 | + |
| 67 | +This pattern is employed in several actions. For more examples, see: |
| 68 | + |
| 69 | +* [`ruby/setup-ruby`](https://github.com/ruby/setup-ruby) |
| 70 | +* [`google-github-actions/setup-gcloud`](https://github.com/google-github-actions/setup-gcloud) |
| 71 | +* [`hashicorp/setup-terraform`](https://github.com/hashicorp/setup-terraform) |
| 72 | + |
0 commit comments