The actions-toolkit from banyan

GitHub Actions Toolkit

A toolkit for building GitHub Actions in Node.js
Usage • API • Actions using actions-toolkit • FAQ

Motivation

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 🎉

Usage

Installation

$ npm install actions-toolkit

const { Toolkit } = require('actions-toolkit')
const tools = new Toolkit()

Bootstrap a new action

$ npx actions-toolkit my-cool-action

This will create a new folder my-cool-action with the following files:

├── Dockerfile
├── entrypoint.js
└── package.json

Toolkit options

event (optional)

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']
})

tools.github

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)

tools.config(filename)

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.

tools.getPackageJSON()

Get the package.json file in the project root and returns it as an object.

const pkg = tools.getPackageJSON()

tools.getFile(path, [encoding = 'utf8'])

Get the contents of a file in the repository.

const contents = tools.getFile('example.md')

tools.runInWorkspace(command, [args], [ExecaOptions])

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'])

tools.arguments

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' }

tools.token

The GitHub API token being used to authenticate requests.

tools.workspace

A path to a clone of the repository.

tools.exit

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!')

tools.store

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)
// -> true

Note: 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().

tools.context

tools.context.action

The name of the action

tools.context.actor

The actor that triggered the workflow (usually a user's login)

tools.context.event

The name of the event that triggered the workflow

tools.context.payload

A JSON object of the webhook payload object that triggered the workflow

tools.context.ref

The Git ref at which the action was triggered

tools.context.sha

The Git sha at which the action was triggered

tools.context.workflow

The name of the workflow that was triggered.

tools.context.issue([object])

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!'}

tools.context.repo([object])

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'}

Actions using actions-toolkit

FAQ

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.

banyan / actions-toolkit Goto Github PK

actions-toolkit's Introduction