@ncalteen/local-action v0.1.3

Local Action Debugger

Run custom GitHub Actions locally and test them in VS Code!

This command-line tool emulates 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!

Prerequisites

Installed Tools

• Node.js and npm
• ts-node

Action Structure

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:

index.ts

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

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

main.ts

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> {
  // ...
}

Transpiled Actions

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

Currently, this tool supports non-transpiled action code only. This is because it uses proxyquire to override the GitHub Actions Toolkit dependencies (e.g @actions/core). In transpiled code, this simply doesn't work.

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

Installation

Option 1: Clone the Repository

1. Clone this repository locally

2. Install via npm

   npm i -g .

Option 2: Install from GitHub Packages

1. Authenticate to GitHub Packages

   $ npm login --registry=https://npm.pkg.github.com
   Username: <your username>
   Password: <your personal access token>

2. Install via npm

   npm i -g @ncalteen/local-action

Commands

local-action

local-action run <path> <entrypoint> <env file>

Output

$ local-action run /path/to/typescript-action src/main.ts .env
     _        _   _               ____       _
    / \   ___| |_(_) ___  _ __   |  _ \  ___| |__  _   _  __ _  __ _  ___ _ __
   / _ \ / __| __| |/ _ \| '_ \  | | | |/ _ \ '_ \| | | |/ _` |/ _` |/ _ \ '__|
  / ___ \ (__| |_| | (_) | | | | | |_| |  __/ |_) | |_| | (_| | (_| |  __/ |
 /_/   \_\___|\__|_|\___/|_| |_| |____/ \___|_.__/ \__,_|\__, |\__, |\___|_|
                                                         |___/ |___/
================================================================================
                                 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
================================================================================

Debugging in VS Code

This package can also be used with VS Code's built-in debugging tools. You just need to add a launch.json to your local action's directory. The following can be used as an example.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Local Action",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "local-action",
      "cwd": "${workspaceRoot}",
      "args": [".", "src/index.ts", ".env"],
      "console": "integratedTerminal",
      "skipFiles": ["<node_internals>/**", "node_modules/**"]
    }
  ]
}

In the args section, make sure to specify the appropriate path, entrypoint, and dotenv file path. After that, you can add breakpoints to your action code and start debugging!

Support