XL Runner
Run your GitHub Actions workflows locally from VS Code, powered by nektos/act.
Requirements
- act 0.2.86 or newer (older versions have known security issues).
brew install act, winget install nektos.act, or see the install guide.
- Docker, running.
Run XL Runner: Check Setup from the Command Palette to verify both.
Features
- Workflows view: every workflow in
.github/workflows, its triggers and jobs. Updates automatically when files change.
- ▶ run a workflow, ⚡ run it as a specific event, or do a dry run.
- ▶ run a single job. act also runs any jobs it
needs: first.
workflow_dispatch workflows prompt for their inputs (choices and booleans get pickers).
- Runs view: live job and step status for each run (matrix jobs included), duration, stop, re-run, and a saved log file per run.
- Secrets stored in your OS keychain via VS Code's SecretStorage, never in settings or on the command line.
GITHUB_TOKEN can be pulled from gh auth token.
- A
.secrets file in your repo root still works, as act loads it by default.
- Pre-flight secret check: before a real run (not dry runs), the workflow file is scanned for every
secrets.NAME it references. If any aren't set — not in the keychain, not in .secrets, not in xlRunner.secretFile — the run is blocked with the missing names listed, instead of letting act silently substitute a blank value mid-job.
Settings
| Setting |
What it does |
xlRunner.command |
How to call act: act, gh act, or a full path. |
xlRunner.platforms |
Runner label → Docker image (-P). Defaults to catthehacker/ubuntu:act-latest for ubuntu-latest. |
xlRunner.secretFile / varFile / envFile |
Paths to .env-style files. |
xlRunner.eventPayloadFile |
JSON event payload (--eventpath). |
xlRunner.containerArchitecture |
e.g. linux/amd64 on Apple Silicon. |
xlRunner.extraArgs |
Any other act flags, one per array item. |
xlRunner.showDebugOutput |
Show act's debug lines in the terminal. |
Development
npm install
npm test # unit tests (parser, argv builder) — no VS Code needed
Press F5 in VS Code to launch an Extension Development Host with the extension loaded.
npm run package # builds xl-runner-x.y.z.vsix
Install the .vsix with Extensions: Install from VSIX….
How it works
act is spawned directly with an argument array (no shell), with --json --verbose. Each JSON log line is parsed to build the job/step tree (src/actLog.ts). Debug lines are hidden from the terminal but kept in the log file. Secrets are passed as -s NAME with the value in the child process's environment, so they never appear in the command line or process list.
Design inspired by GitHub Local Actions (Apache-2.0).
