Run custom GitHub Actions locally and test them in Visual Studio Code!
This command-line tool emulates some basic functionality of the GitHub Actions Toolkit so that custom actions can be run directly on your workstation.
[!NOTE]
This tool currently only supports JavaScript and TypeScript actions!
As of version 2.0.0
, the local-action
tool has been updated to require
Node.js v20.6.0 or higher. This is necessary to support ESM loaders to
override dependencies in the GitHub Actions Toolkit.
With the release of v1.0.0
, there was a need to switch from
ts-node
to
tsx
. However, the bundled version of
tsx
is being used, so you should no longer need to install either 😀
For JavaScript and TypeScript actions, your code should follow the format of the corresponding template repository.
Specifically, there should be a separation between the entrypoint used by GitHub Actions when invoking your code, and the actual logic of your action. For example:
This is what is invoked by GitHub Actions when your action is run.
/**
* This file is the entrypoint for the action
*/
import { run } from './main'
// It calls the actual logic of the action
run()
This is the actual implementation of your action. It is called by the entrypoint.
import * as core from '@actions/core'
import { wait } from './wait'
/**
* This file is the actual logic of the action
* @returns {Promise<void>} Resolves when the action is complete
*/
export async function run(): Promise<void> {
// ...
}
Depending on how you build your JavaScript/TypeScript actions, you may do one of the following when preparing for release:
- Commit the
node_modules
directory to your repository - Transpile your code and dependencies using tools like
tsc
or@vercel/ncc
This tool supports non-transpiled action code only. This is because it uses
quibble
to override GitHub Actions
Toolkit dependencies (e.g
@actions/core
). In transpiled
code, this simply doesn't work.
For example, if you have a TypeScript action that follows the same format as the
template, you would have both
src
and dist
directories in your repository. The dist
directory contains
the transpiled code with any dependencies included. When running this utility,
you will want to target the code files in the src
directory instead (including
the dependencies this tool wants to replace). This has the added benefit of
being able to hook into debugging utilities in your IDE 🎉
For additional information about transpiled action code, see Commit, tag, and push your action to GitHub.
-
Install via
npm
npm i -g @github/local-action
-
Clone this repository locally
git clone https://github.com/github/local-action.git
-
Install dependencies
npm ci
-
Install via
npm
npm i -g .
Alternatively, you can link the package if you want to make code changes
npm link .
Option | Description |
---|---|
-h , --help
|
Display help information |
-V , --version
|
Display version information |
Argument | Description |
---|---|
path |
Path to the local action directory |
Example: /path/to/action.yml
|
|
entrypoint |
Action entrypoint (relative to the action directory) |
Example: src/index.ts
|
|
dotenv file |
Path to the local .env file for action inputs |
Example: /path/to/.env
|
|
See the example .env.example
|
Examples:
local-action run /path/to/typescript-action src/index.ts .env
# The `run` action is invoked by default as well
local-action /path/to/typescript-action src/index.ts .env
$ local-action run /path/to/typescript-action src/index.ts .env
_ _ _ ____ _
/ \ ___| |_(_) ___ _ __ | _ \ ___| |__ _ _ __ _ __ _ ___ _ __
/ _ \ / __| __| |/ _ \| '_ \ | | | |/ _ \ '_ \| | | |/ _` |/ _` |/ _ \ '__|
/ ___ \ (__| |_| | (_) | | | | | |_| | __/ |_) | |_| | (_| | (_| | __/ |
/_/ \_\___|\__|_|\___/|_| |_| |____/ \___|_.__/ \__,_|\__, |\__, |\___|_|
|___/ |___/
================================================================================
Configuration
================================================================================
┌─────────┬────────────────────┬───────────────────────────────────────────┐
│ (index) │ Field │ Value │
├─────────┼────────────────────┼───────────────────────────────────────────┤
│ 0 │ 'Action Path' │ '/path/to/typescript-action' │
│ 1 │ 'Entrypoint' │ '/path/to/typescript-action/src/index.ts' │
│ 2 │ 'Environment File' │ '/path/to/local-action-debugger/.env' │
└─────────┴────────────────────┴───────────────────────────────────────────┘
================================================================================
Action Metadata
================================================================================
┌─────────┬────────────────┬───────────────────────────────┐
│ (index) │ Input │ Description │
├─────────┼────────────────┼───────────────────────────────┤
│ 0 │ 'milliseconds' │ 'Your input description here' │
└─────────┴────────────────┴───────────────────────────────┘
┌─────────┬────────┬────────────────────────────────┐
│ (index) │ Output │ Description │
├─────────┼────────┼────────────────────────────────┤
│ 0 │ 'time' │ 'Your output description here' │
└─────────┴────────┴────────────────────────────────┘
================================================================================
Running Action
================================================================================
The following list links to documentation on how to use various features of the
local-action
tool.