Local Action Debugger

!GitHub Super-Linter
!Continuous Integration
!Code Coverage

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!

The following table tracks the versions of the GitHub Actions Toolkit that are
currently implemented by this tool.

| Package | Version |
| ---------------------------------------------------------------------- | ------- |
| @actions/artifact | 5.0.2 |
| @actions/cache | 5.0.3 |
| @actions/core | 2.0.2 |
| @actions/github | 7.0.0 |

Changelog

See the CHANGELOG for a complete list of changes.

Node.js Version Support

This tool is currently tested against Node.js versions 22 and 24. It is not
guaranteed to work with other versions at this time.

Package Manager Support

$3

This tool is designed primarily for use with npm and npx. It is recommended
to use npm for managing actions you wish to test with this tool.

$3

This tool ships with experimental support for pnpm. If you encounter any
issues, please file an issue.

Some caveats to this support are listed below.

- This tool does not support CommonJS actions using pnpm.

$3

This tool ships with experimental support for yarn. If you encounter any
issues, please file an issue.

Some caveats to this support are listed below.

- The @github/local-action package should be run using
yarn dlx @github/local-action instead of yarn local-action.
- This tool does not support CommonJS actions using yarn.

Prerequisites

$3

- Node.js and npm

$3

For JavaScript and TypeScript actions, your code should follow the format of the
corresponding template repository.

- actions/javascript-action
- actions/typescript-action

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:

#### Entrypoint: index.ts

This is what is invoked by GitHub Actions when your action is run.

``typescript
/**
* This file is the entrypoint for the action
*/
import { run } from './main'

// It calls the actual logic of the action
run()
`

#### Logic: main.ts

This is the actual implementation of your action. It is called by the
entrypoint.

`typescript
import * as core from '@actions/core'
import { wait } from './wait'

/**
* This file is the actual logic of the action
* @returns {Promise} Resolves when the action is complete
*/
export async function run(): Promise {
// ...
}
`

$3

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,
@vercel/ncc, or
rollup

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 :tada:

For additional information about transpiled action code, see
Commit, tag, and push your action to GitHub.

Installation

$3

1. Install via npm

`bash
npm i -g @github/local-action
`

$3

1. Clone this repository locally

`bash
git clone https://github.com/github/local-action.git
`

1. Install dependencies

`bash
npm ci
`

1. Install via npm

`bash
npm i -g .
`

Alternatively, you can link the package if you want to make code changes

`bash
npm link .
`

Commands

$3

| Option | Description |
| ----------------- | --------------------------- |
| -h, --help | Display help information |
| -V, --version | Display version information |

$3

| Argument | Description |
| -------------------------- | ------------------------------------------------------------------- |
| path | Path to the local action directory |
| | Example: /path/to/action.yml |
| logic entrypoint | Action logic entrypoint (relative to action directory) |
| | Example: src/main.ts |
| dotenv file | Path to the local .env file for action inputs |
| | Example: /path/to/.env |
| | See the example .env.example |
| --pre

   | (Optional) pre command entrypoint (relative to action directory)  |
|                            | Example: pre/main.ts                                              |
| --post  | (Optional) post command entrypoint (relative to action directory) |
|                            | Example: post/main.ts                                             |
Examples:
`bash
local-action run /path/to/typescript-action src/main.ts .env --pre pre/main.ts --post post/main.ts
The run action is invoked by default as well

local-action /path/to/typescript-action src/main.ts .env --pre pre/main.ts --post post/main.ts
`
#### Output
`console
$ local-action run /path/to/typescript-action src/main.ts .env --pre pre/main.ts --post post/main.ts
     _        _   _               ____       _
    / \   ___| |_(_) ___  _ __   |  _ \  ___| |__  _   _  __ _  __ _  ___ _ __
   / _ \ / __| __| |/ _ \| '_ \  | | | |/ _ \ '_ \| | | |/ _ |/ _ |/ _ \ '__|
  / ___ \ (__| |_| | (_) | | | | | |_| |  __/ |_) | |_| | (_| | (_| |  __/ |
 /_/   \_\___|\__|_|\___/|_| |_| |____/ \___|_.__/ \__,_|\__, |\__, |\___|_|
                                                         |___/ |___/
================================================================================
                                 Configuration
================================================================================
┌─────────┬────────────────────┬───────────────────────────────────────────┐
│ (index) │       Field        │                  Value                    │
├─────────┼────────────────────┼───────────────────────────────────────────┤
│    0    │   'Action Path'    │       '/path/to/typescript-action'        │
│    1    │    'Entrypoint'    │ '/path/to/typescript-action/src/main.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
================================================================================
`
(TypeScript) TSConfig Requirements
If you are testing TypeScript actions, there are a few settings that must be
configured in your tsconfig.json file (either explicitly or via their default
values).
| Property                                                      | Required Value |
| ------------------------------------------------------------- | -------------- |
| allowJs | false        |
$3
Possible errors that can arise from not having allowJs: false:
- TypeError [ERR_INVALID_URL_SCHEME]: The URL must be of scheme file from tsx
  when trying to run npx @github/local-action.
Features
The following list links to documentation on how to use various features of the
local-action` tool.
- Supported Functionality
- Debugging in Visual Studio Code
- Create a Job Summary