Locally running and testing your custom GitHub Action

When developing a custom GitHub Action, you should test and run it locally before pushing it to your repository. Initially, I created a script that allowed me to run it locally, but over the weekend, I found a better way by using the @github/local-action command-line tool.

Show image

In this post, I will show you how to use the @github/local-action command-line tool to test your custom GitHub Action locally.

Prerequisites

To start with the @github/local-action command-line tool, it is best to already have a custom GitHub Action you want to test.

If you don’t have one yet, you can use the JavaScript Action Template or the TypeScript Action Template.

Installing the @github/local-action command-line tool

To use the @github/local-action command-line tool, you need to install it first or use the npx command to run it without installing it.

1
npm install -g @github/local-action
2

3
# or
4
npx @github/local-action

Preparing the environment file

To use the command-line tool, you need to create an environment file to define the input variables and the GitHub variables. Create a new file called .env in your project and add your configuration.

Adding your variables

Your GitHub Action might require some input variables to run. You can define these variables in the environment file by adding the INPUT_ prefix to the variable name.

1
INPUT_<action-variable-name>=<VALUE>
2

3
# Example for the Playwright Issue Creator action
4
INPUT_github-token=<token>
5
INPUT_report-path="results.success.json"
6
INPUT_add-comment=true
7
INPUT_close-on-success=true
8
INPUT_job-summary=false
9
INPUT_issue-assignees=estruyf

Defining your GitHub variables

You can also define the GitHub variables in the environment file. These variables define the GitHub context.

In my case, I need to set the GITHUB_REPOSITORY variable to get the repo from the @actions/github its context object.

1
GITHUB_REPOSITORY=estruyf/github-actions-testing

Enabling debugging

You can enable debugging by setting the ACTIONS_STEP_DEBUG variable to true.

1
ACTIONS_STEP_DEBUG=true

Writing the job summary

When your action writes a job summary, you must do the following configuration to enable it locally.

• Create a new file to write the job summary. For example: summary.md.
• Add the GITHUB_STEP_SUMMARY with the path to your summary file.

1
GITHUB_STEP_SUMMARY=summary.md

Using the @github/local-action command-line tool

Once you have installed the command-line tool and created the .env file, you can run the following command to test your custom GitHub Action locally.

1
# If you have the command-line tool installed
2
local-action <path-to-your-action> <path-to-your-entrypoint> <path-to-environment-file>
3

4
# If you want to use npx
5
npx @github/local-action <path-to-your-action> <path-to-your-entrypoint> <path-to-environment-file>

The local-action command takes three arguments:

1. <path-to-your-action>: The path to your custom GitHub Action (the folder where your action.yml file is located).
2. <path-to-your-entrypoint>: The path to the entry point of your custom GitHub Action.
3. <path-to-environment-file>: The path to the environment file you want to use.

All three arguments are required to run the local-action command.

Here is an example of how I run it for my Playwright Issue Creator GitHub Action:

1
npx @github/local-action run ./ src/index.ts .env

Show image

This command-line tool is great during the development process of your custom GitHub Action.