πŸ›  A toolkit for building GitHub Actions in Node.js
Branch: master
Clone or download
Latest commit bb1535e Feb 19, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Use external validation action Feb 17, 2019
bin Add Dockerfile comments Feb 3, 2019
src Make it a calleable class Feb 15, 2019
tests Add a test Feb 15, 2019
.gitignore To typescript we go Nov 4, 2018
.npmignore Ignore .github in npmignore Jan 31, 2019
.travis.yml Tweak Travis and README Nov 6, 2018
LICENSE Init to winit Nov 4, 2018
README.md Make it a calleable class Feb 15, 2019
codecov.yml Init to winit Nov 4, 2018
package-lock.json Update ts-jest Feb 19, 2019
package.json Update ts-jest Feb 19, 2019
tsconfig.json Remove a comment Feb 2, 2019
tslint.json To typescript we go Nov 4, 2018

README.md

GitHub Actions Toolkit

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

NPM Build Status Codecov

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

API

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.log

This library comes with a slightly-customized instance of Signale, a great logging utility. Check out their docs for the full list of methods. You can use those methods in your action:

tools.log('Welcome to this example!')
tools.log.info('Gonna try this...')
try {
  risky()
  tools.log.success('We did it!')
} catch (error) {
  tools.log.fatal(error)
}

In the GitHub Actions output, this is the result:

β„Ή  info      Welcome to this example!
β„Ή  info      Gonna try this...
βœ–  fatal     Error: Something bad happened! 
    at Object.<anonymous> (/entrypoint.js:5:17)
    at Module._compile (internal/modules/cjs/loader.js:734:30)

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.