Creating a JavaScript action

Introduction

In this guide, you'll learn about the basic components needed to create and use a packaged JavaScript action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" in the logs or "Hello [who-to-greet]" if you provide a custom name.

This guide uses the GitHub Actions Toolkit Node.js module to speed up development. For more information, see the actions/toolkit repository.

Once you complete this project, you should understand how to build your own JavaScript action and test it in a workflow.

To ensure your JavaScript actions are compatible with all GitHub-hosted runners (Ubuntu, Windows, and macOS), the packaged JavaScript code you write should be pure JavaScript and not rely on other binaries. JavaScript actions run directly on the runner and use binaries that already exist in the runner image.

Prerequisites

Before you begin, you'll need to download Node.js and create a public GitHub repository.

1. Download and install Node.js 16.x, which includes npm.

   https://nodejs.org/en/download/

2. Create a new public repository on your GitHub Enterprise Server instance and call it "hello-world-javascript-action". For more information, see "Creating a new repository."

3. Clone your repository to your computer. For more information, see "Cloning a repository."

4. From your terminal, change directories into your new repository.

   Shell

   cd hello-world-javascript-action
   

5. From your terminal, initialize the directory with npm to generate a package.json file.

   Shell

   npm init -y
   

Creating an action metadata file

Create a new file named action.yml in the hello-world-javascript-action directory with the following example code. For more information, see "Metadata syntax for GitHub Actions."

name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
  who-to-greet:  # id of input
    description: 'Who to greet'
    required: true
    default: 'World'
outputs:
  time: # id of output
    description: 'The time we greeted you'
runs:
  using: 'node16'
  main: 'index.js'

name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
  who-to-greet:  # id of input
    description: 'Who to greet'
    required: true
    default: 'World'
outputs:
  time: # id of output
    description: 'The time we greeted you'
runs:
  using: 'node16'
  main: 'index.js'

This file defines the who-to-greet input and time output. It also tells the action runner how to start running this JavaScript action.

Adding actions toolkit packages

The actions toolkit is a collection of Node.js packages that allow you to quickly build JavaScript actions with more consistency.

The toolkit @actions/core package provides an interface to the workflow commands, input and output variables, exit statuses, and debug messages.

The toolkit also offers a @actions/github package that returns an authenticated Octokit REST client and access to GitHub Actions contexts.

The toolkit offers more than the core and github packages. For more information, see the actions/toolkit repository.

At your terminal, install the actions toolkit core and github packages.

npm install @actions/core
npm install @actions/github

npm install @actions/core
npm install @actions/github

Now you should see a node_modules directory with the modules you just installed and a package-lock.json file with the installed module dependencies and the versions of each installed module.

Writing the action code

This action uses the toolkit to get the who-to-greet input variable required in the action's metadata file and prints "Hello [who-to-greet]" in a debug message in the log. Next, the script gets the current time and sets it as an output variable that actions running later in a job can use.

GitHub Actions provide context information about the webhook event, Git refs, workflow, action, and the person who triggered the workflow. To access the context information, you can use the github package. The action you'll write will print the webhook event payload to the log.

Add a new file called index.js, with the following code.

const core = require('@actions/core');
const github = require('@actions/github');

try {
  // `who-to-greet` input defined in action metadata file
  const nameToGreet = core.getInput('who-to-greet');
  console.log(`Hello ${nameToGreet}!`);
  const time = (new Date()).toTimeString();
  core.setOutput("time", time);
  // Get the JSON webhook payload for the event that triggered the workflow
  const payload = JSON.stringify(github.context.payload, undefined, 2)
  console.log(`The event payload: ${payload}`);
} catch (error) {
  core.setFailed(error.message);
}

const core = require('@actions/core');
const github = require('@actions/github');

try {
  // `who-to-greet` input defined in action metadata file
  const nameToGreet = core.getInput('who-to-greet');
  console.log(`Hello ${nameToGreet}!`);
  const time = (new Date()).toTimeString();
  core.setOutput("time", time);
  // Get the JSON webhook payload for the event that triggered the workflow
  const payload = JSON.stringify(github.context.payload, undefined, 2)
  console.log(`The event payload: ${payload}`);
} catch (error) {
  core.setFailed(error.message);
}

If an error is thrown in the above index.js example, core.setFailed(error.message); uses the actions toolkit @actions/core package to log a message and set a failing exit code. For more information, see "Setting exit codes for actions."

Creating a README

To let people know how to use your action, you can create a README file. A README is most helpful when you plan to share your action publicly, but is also a great way to remind you or your team how to use the action.

In your hello-world-javascript-action directory, create a README.md file that specifies the following information:

• A detailed description of what the action does.
• Required input and output arguments.
• Optional input and output arguments.
• Secrets the action uses.
• Environment variables the action uses.
• An example of how to use your action in a workflow.

# Hello world javascript action

This action prints "Hello World" or "Hello" + the name of a person to greet to the log.

## Inputs

### `who-to-greet`

**Required** The name of the person to greet. Default `"World"`.

## Outputs

### `time`

The time we greeted you.

## Example usage

```yaml
uses: actions/hello-world-javascript-action@e76147da8e5c81eaf017dede5645551d4b94427b
with:
  who-to-greet: 'Mona the Octocat'
```

# Hello world javascript action

This action prints "Hello World" or "Hello" + the name of a person to greet to the log.