A toolkit for building GitHub Actions in Node.js
Usage •
API •
Actions using actions-toolkit •
FAQ
After building a GitHub Action in Node.js, it was clear to me that I was writing code that other actions will want to use. Reading files from the repository, making requests to the GitHub API, or running arbitrary executables on the project, etc.
So, I thought it'd be useful to build those out into library to help you build actions in Node.js 🎉
$ npm install actions-toolkitconst { Toolkit } = require('actions-toolkit')
const tools = new Toolkit()$ npx actions-toolkit my-cool-action
This will create a new folder my-cool-action with the following files:
├── Dockerfile
├── entrypoint.js
└── package.json
- The Toolkit class
- Authenticated GitHub API client
- Parsing arguments
- Reading files
- Run a CLI command
- In-repo configuration
- Pass information to another action
- End the action's process
- Inspect the webhook event payload
An optional list of events that this action works with. If omitted, the action will run for any event - if present, the action will exit with a failing status code for any event that is not allowed.
const tools = new Toolkit({
event: ['issues', 'pull_requests']
})You can also pass a single string:
const tools = new Toolkit({
event: 'issues'
})And/or strings that include an action (what actually happened to trigger this event) for even more specificity:
const tools = new Toolkit({
event: ['issues.created']
})Returns an Octokit SDK client authenticated for this repository. See https://octokit.github.io/rest.js for the API.
const newIssue = await tools.github.issues.create(tools.context.repo({
title: 'New issue!',
body: 'Hello Universe!'
}))You can also make GraphQL requests:
const result = await tools.github.graphql(query, variables)Get the configuration settings for this action in the project workspace. This method can be used in three different ways:
// Get the .rc file, parsed as JSON
const cfg = tools.config('.myactionrc')
// Get the YAML file, parsed as JSON
const cfg = tools.config('myaction.yml')
// Get the property in package.json
const cfg = tools.config('myaction')If the filename looks like .myfilerc it will look for that file. If it's a YAML file, it will parse that file as a JSON object. Otherwise, it will return the value of the property in the package.json file of the project.
Get the package.json file in the project root and returns it as an object.
const pkg = tools.getPackageJSON()Get the contents of a file in the repository.
const contents = tools.getFile('example.md')Run a CLI command in the workspace. This uses execa under the hood so check there for the full options. For convenience, args can be a string or an array of strings.
const result = await tools.runInWorkspace('npm', ['audit'])An object of the parsed arguments passed to your action. This uses minimist under the hood.
When inputting arguments into your workflow file (like main.workflow) in an action as shown in the Actions Docs, you can enter them as an array of strings or as a single string:
args = ["container:release", "--app", "web"]
# or
args = "container:release --app web"In actions-toolkit, tools.arguments will be an object:
console.log(tools.arguments)
// => { _: ['container:release'], app: 'web' }The GitHub API token being used to authenticate requests.
A path to a clone of the repository.
A collection of methods to end the action's process and tell GitHub what status to set (success, neutral or failure). Internally, these methods call process.exit with the appropriate exit code. You can pass an optional message to each one to be logged before exiting. This can be used like an early return:
if (someCheck) tools.exit.neutral('No _action_ necessary!')
if (anError) tools.exit.failure('We failed!')
tools.exit.success('We did it team!')Actions can pass information to each other by writing to a file that is shared across the workflow. tools.store is a modified instance of flat-cache:
Store a value:
tools.store.set('foo', true)Then, in a later action (or even the same action):
const foo = tools.store.get('foo')
console.log(foo)
// -> trueNote: the file is only saved to disk when the process ends and your action completes. This is to prevent conflicts while writing to file. It will only write to a file if at least one key/value pair has been set. If you need to write to disk, you can do so with tools.store.save().
The name of the action
The actor that triggered the workflow (usually a user's login)
The name of the event that triggered the workflow
A JSON object of the webhook payload object that triggered the workflow
The Git ref at which the action was triggered
The Git sha at which the action was triggered
The name of the workflow that was triggered.
Return the owner, repo, and number params for making API requests against an issue or pull request. The object passed in will be merged with the repo params.
const params = context.issue({body: 'Hello World!'})
// Returns: {owner: 'username', repo: 'reponame', number: 123, body: 'Hello World!'}Return the owner and repo params for making API requests against a repository.
const params = context.repo({path: '.github/config.yml'})
// Returns: {owner: 'username', repo: 'reponame', path: '.github/config.yml'}Can you get me into the GitHub Actions beta?
I'm sorry, but I cannot.
Aren't these just wrappers around existing functions?
Yep! I just didn't want to rewrite them for my next Action, so here we are.