Act-cli VS Code Extension - GitHub Actions Locally from VS Code
Run and test your GitHub Actions workflows locally using act directly from VS Code!
Features
- 🚀 Quick Workflow Execution - Run workflows with a single click
- ⚡ Quick Run - Instantly run your default workflow with no prompts
- 📋 Job Selection - Execute specific jobs from your workflows
- 👁️ Dry Run Mode - Preview what will run without executing
- 🌳 Workflow Explorer - Browse all workflows in the sidebar
- ⚙️ Easy Configuration - Manage .actrc and .secrets files
- 🎯 Status Bar Integration - Quick access from the status bar
- ✅ Workflow Validation - Lint and validate your workflow YAML files
- 🔐 Environment Variable Management - Easy UI for managing env vars and secrets
- 📡 Webhook Simulation - Test webhook events with custom payloads
- 📜 Execution History - Track and re-run past workflow executions
- 📝 Workflow Templates - Quick-start with pre-built CI/CD templates
- 🔍 CodeLens Integration - Run workflows directly from editor
- 🔔 Auto-Detection - Checks if act is installed and guides setup
- 💻 Multi-Script Support - PowerShell, Bash, Python, and Bicep templates
- 📦 Script Generator - Create sample automation scripts instantly
- 🐳 Docker Alternatives Guide - Free alternatives to Docker Desktop for enterprise
- 🔒 Security Best Practices - Comprehensive guide for secure secret management
Language & Script Support
This extension provides full support for multiple scripting languages and tools commonly used in CI/CD:
✅ PowerShell
- Cross-platform PowerShell Core (pwsh)
- Windows PowerShell compatibility
- Azure PowerShell integration
- Ready-to-use templates with parameters and error handling
✅ Bash/Shell
- POSIX-compliant shell scripts
- Multiple shell support (bash, sh, zsh)
- Automatic executable permissions
- Color-coded logging templates
✅ Python
- Python 3.x automation scripts
- Argparse CLI with full argument parsing
- Logging and error handling
- Type hints and documentation
- Virtual environment support
✅ Bicep (Azure IaC)
- Infrastructure as Code templates
- Azure resource deployment
- Validation and what-if analysis
- Multi-environment parameter files
✅ All Major CI/CD Scenarios
- Node.js, Python, Docker builds
- AWS deployments (S3, CloudFront)
- Azure deployments (Web Apps, Containers, Infrastructure)
- Release automation
- Custom shell commands
Prerequisites
You must have act installed:
# macOS
brew install act
# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
# Windows (Chocolatey)
choco install act-cli
Container Runtime Required: Act needs a container runtime to work. See Docker Desktop Alternatives section below if you can't install Docker Desktop.
Docker Desktop Alternatives
Cannot install Docker Desktop? (Enterprise licensing or restrictions)
The extension includes a built-in guide for Docker alternatives:
- Command:
Act: Docker Alternatives from the command palette
- Access: Cmd+Shift+A → Docker Alternatives
Recommended Free Alternatives:
# macOS
brew install podman
podman machine init
podman machine start
# Configure act to use Podman
echo "--container-daemon-socket unix://\$HOME/.local/share/containers/podman/machine/podman.sock" >> ~/.actrc
# Or on Linux
echo "--container-daemon-socket unix:///run/podman/podman.sock" >> ~/.actrc
- Complete Docker Desktop replacement with GUI
- Kubernetes included
- Download: https://rancherdesktop.io/
- No additional configuration needed
3. Colima (macOS/Linux)
# macOS
brew install colima
colima start
# Works with act automatically
4. WSL2 + Docker Engine (Windows)
# Inside WSL2 Ubuntu
sudo apt update
sudo apt install docker.io
sudo service docker start
# Act works automatically with WSL2 Docker
5. Remote Docker Host
# Connect to remote Docker server
echo "--container-daemon-socket tcp://remote-server:2375" >> ~/.actrc
# Or use SSH
echo "--container-daemon-socket ssh://user@remote-server" >> ~/.actrc
6. GitHub Codespaces (Cloud Alternative)
- Run workflows directly in the cloud
- No local container runtime needed
- Perfect for restricted environments
Usage
Via Status Bar
Click the "Act" button in the status bar to open the quick menu.
Via Command Palette
Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) and type "Act"
Available Commands
- Act: Show Menu - Open the main menu with all options
- Act: Run Workflow - Select and run a specific workflow
- Act: Quick Run - Instantly run default workflow (no prompts)
- Act: Run Job - Execute a specific job
- Act: List Jobs - See all available workflows and jobs
- Act: Dry Run - Preview execution without running
- Act: Validate Workflow - Check workflow syntax and structure
- Act: Manage Environment Variables - Configure env vars and secrets
- Act: Simulate Webhook - Trigger workflows with custom webhook payloads
- Act: View History - See past executions and re-run them
- Act: Create New Workflow - Generate workflow from templates
- Act: Create Sample Scripts - Generate PowerShell, Bash, Python, or Bicep files
- Act: Docker Alternatives - Guide for Docker Desktop alternatives
- Act: Security Best Practices - GitHub Secrets security & enterprise alternatives
- Act: Configure - Edit .actrc or .secrets files
Workflow Explorer
Find the Act icon in the Activity Bar (left sidebar) to:
- View all workflows in your repository
- Click on any workflow to run it
- Right-click for more options (validate, edit)
- Refresh the list when you add new workflows
Keyboard Shortcuts
- Cmd/Ctrl + Shift + A - Open Act menu
- Cmd/Ctrl + Shift + R - Quick run default workflow
You can customize these in VS Code's keyboard shortcuts settings.
In-Editor CodeLens
When you open a workflow file (.github/workflows/*.yml), you'll see action buttons at the top:
- ▶ Run with Act - Execute the workflow immediately
- 👁️ Dry Run - Preview what would execute
- ✓ Validate - Check syntax and structure
These buttons provide quick access without leaving your editor!
Configuration
Extension Settings
act.executablePath - Custom path to act executable (default: "act")act.defaultEvent - Default event type (default: "push")act.verboseOutput - Enable verbose output (default: false)act.autoSaveHistory - Automatically save execution history (default: true)
Act Configuration Files
The extension helps you manage:
.actrc - Default act options and flags.secrets - Environment secrets for workflows
Tips
Use smaller Docker images for faster execution:
-P ubuntu-latest=catthehacker/ubuntu:act-latest
Create a .actrc file in your project root for consistent settings
Use .secrets file to avoid passing secrets via command line
Validate workflows before running to catch syntax errors early
Use webhook simulation to test different event types locally
Check execution history to re-run successful configurations
Advanced Features
Workflow Validation
Validates your workflow YAML files for:
- Missing required fields (on, jobs, runs-on)
- YAML syntax errors
- Basic structure issues
Select a workflow and get immediate feedback on potential issues.
Environment Variable Management
Easily manage environment variables and secrets:
- Edit Variables - Direct file editing with syntax highlighting
- Quick Add - Add new variables through a simple prompt
- Template Creation - Start with common CI/CD variables
- View All - See all configured variables at a glance
The extension creates .env.act files that can be loaded with:
act --env-file .env.act
Webhook Simulation
Test your workflows with realistic webhook events:
- Pre-configured Events - pull_request, push, issues, releases, etc.
- Custom Payloads - Create your own JSON payloads
- Sample Generation - Auto-generate realistic webhook data
- Payload Editing - Edit payloads before execution
Sample payloads are stored in .github/act-payloads/ for reuse.
Execution History
Track all workflow executions:
- View past runs with success/failure status
- Re-run previous configurations
- Quick access to working setups
- Troubleshoot failed runs
History is stored in .github/act-history.json.
Workflow Templates
Quickly create new workflows from templates:
- Node.js CI - Complete CI pipeline for Node.js projects
- Python CI - Testing and linting for Python apps
- Docker Build - Container image building and publishing
- Deploy to AWS - S3 and CloudFront deployment
- Deploy to Azure - Azure Web Apps and Container Instances deployment
- Azure Infrastructure (Bicep) - Deploy Azure resources with Infrastructure as Code
- PowerShell Scripts - Cross-platform PowerShell automation
- Shell Scripts - Bash/shell script execution across platforms
- Release on Tag - Automated releases with artifacts
- Blank Workflow - Start from scratch
Templates include best practices and are ready to customize for your needs.
Script Generation
Create ready-to-use automation scripts with Act: Create Sample Scripts:
PowerShell Scripts (.ps1)
- Cross-platform PowerShell Core support
- Parameter handling and validation
- Logging and error handling
- Azure PowerShell integration examples
- Works on Windows, Linux, and macOS runners
Bash Scripts (.sh)
- POSIX-compliant shell scripts
- Color-coded output and logging
- Argument parsing
- Error handling with traps
- Automatically made executable
Python Scripts (.py)
- Python 3.x with modern best practices
- Argparse for CLI argument handling
- Structured logging with timestamps
- Type hints and comprehensive docstrings
- Exception handling and exit codes
- Modular function design
- Automatically made executable
Bicep Templates (.bicep)
- Complete Azure infrastructure templates
- App Service + Application Insights + Storage
- Parameter files for different environments
- Best practices for security and scalability
- Ready for
az deployment commands
All generated scripts include:
- Comprehensive comments and documentation
- Error handling and logging
- Parameterization for flexibility
- Examples of common operations
Quick Start Guide
- Install the extension from VS Code marketplace
- Ensure act is installed:
brew install act (macOS) or see act installation
- Install a container runtime:
- ✅ Docker Desktop - If you have a license
- ✅ Podman - Free for all (recommended for enterprise)
- ✅ Rancher Desktop - Free Docker Desktop alternative
- ✅ Colima - Lightweight option (macOS/Linux)
- 💡 Use the extension's built-in guide:
Act: Docker Alternatives
- Open a project with
.github/workflows/ directory
- Click the Act icon in the status bar or use
Cmd+Shift+A
- Select an action from the menu
- Watch your workflows run locally!
Common Workflows
Test Before Push
# Press Cmd+Shift+A → Dry Run
# Review what will execute
# Press Cmd+Shift+A → Run Workflow
Debug Failed CI
# Press Cmd+Shift+A → Run Workflow
# Select failing workflow
# View output in terminal
# Make fixes and re-run
Set Up New Project
# Press Cmd+Shift+A → Create New Workflow
# Choose template (Node.js CI, Python CI, etc.)
# Customize for your needs
# Test with Act before committing
Create Automation Scripts
# Press Cmd+Shift+A → Create Sample Scripts
# Choose: PowerShell, Bash, Python, Bicep, or All
# Get production-ready script templates
# Reference them in your workflows
Generated Python script example:
#!/usr/bin/env python3
# Full CLI with argparse, logging, error handling
python scripts/automation.py --env production --version 1.0.0
Script Support
The extension provides comprehensive support for multiple scripting languages and tools:
PowerShell Support
- ✅ Works with PowerShell Core (pwsh) on all platforms
- ✅ Windows PowerShell support
- ✅ Azure PowerShell module examples
- ✅ Parameter validation and help
- ✅ Cross-platform compatibility
Example workflow:
- name: Run PowerShell script
shell: pwsh
run: ./scripts/deploy.ps1 -Environment Production
Bash/Shell Support
- ✅ Bash scripts on Linux/macOS runners
- ✅ POSIX sh compatibility
- ✅ Multiple shell types (bash, sh, zsh)
- ✅ Automatic executable permissions
- ✅ Error handling with set -e
Example workflow:
- name: Run deployment script
run: ./scripts/deploy.sh --env production --version ${{ github.sha }}
Python Support
- ✅ Python 3.x automation scripts
- ✅ Argparse CLI framework
- ✅ Structured logging
- ✅ Type hints and documentation
- ✅ Cross-platform compatibility
Example workflow:
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Run Python automation
run: python scripts/automation.py --env production --version ${{ github.sha }}
Bicep Support
- ✅ Azure infrastructure as code
- ✅ Template validation with
az bicep build
- ✅ What-if analysis before deployment
- ✅ Parameter files for environments
- ✅ Output values for downstream steps
Example workflow:
- name: Deploy Bicep template
run: |
az deployment group create \
--template-file ./infra/main.bicep \
--parameters ./infra/parameters.prod.json
Known Limitations
- Act simulates GitHub Actions but isn't 100% identical
- Some GitHub-specific features may not work locally
- Requires a container runtime (Docker, Podman, Colima, or Rancher Desktop)
- Docker Desktop has enterprise licensing restrictions - see Docker Alternatives section for free options
Troubleshooting
"act: command not found"
Make sure act is installed and in your PATH. Try: which act or where act
Cannot install Docker Desktop (Enterprise restrictions)
Use one of the free alternatives:
- Podman - Run
Act: Docker Alternatives in the command palette for setup guide
- Rancher Desktop - Full Docker Desktop replacement
- Colima - Lightweight option for macOS/Linux
- Remote Docker - Connect to a remote Docker host
- GitHub Codespaces - Cloud-based alternative
The extension includes an interactive guide: Cmd+Shift+A → Docker Alternatives
Docker/Container runtime errors
# Check if container runtime is running
docker ps # or podman ps
# For Podman, make sure machine is started
podman machine start
# For Colima
colima start
# Check act can see the runtime
act --version
act -l # Should list workflows
Workflows run slowly
Use smaller Docker images in your .actrc:
-P ubuntu-latest=catthehacker/ubuntu:act-latest
Docker errors
Ensure Docker Desktop is running and you have sufficient resources allocated.
Secrets not working
Check that your .secrets file is properly formatted:
GITHUB_TOKEN=ghp_xxxxx
API_KEY=your_key
Reference it in .actrc:
--secret-file .secrets
Script execution fails
PowerShell:
- Ensure PowerShell Core (pwsh) is installed:
pwsh --version
- Use
shell: pwsh in workflow steps
- Check script execution policy on Windows
Bash:
- Ensure scripts are executable:
chmod +x scripts/*.sh
- Use proper shebang:
#!/bin/bash
- Test script locally before running in workflow
Python:
- Ensure Python 3 is available:
python3 --version or python --version
- Use proper shebang:
#!/usr/bin/env python3
- Install dependencies:
pip install -r requirements.txt
- Test script locally:
python scripts/automation.py --help
Bicep:
- Install Azure CLI:
az --version
- Install Bicep:
az bicep version
- Validate templates:
az bicep build --file main.bicep
Scripts not found
Make sure script paths in workflows are relative to repository root:
# Correct
run: ./scripts/deploy.sh
# Also correct
run: |
cd scripts
./deploy.sh
Feedback & Contributions
- 🐛 Found a bug? Open an issue on GitHub
- 💡 Feature request? Start a discussion
- 🤝 Want to contribute? PRs welcome!
- ⭐ Enjoying the extension? Leave a review!
Acknowledgments
This extension is built on top of the amazing act project by nektos.
License
MIT
Changelog
1.0.0 (Initial Release)
Features:
- ✨ Quick workflow execution with event selection
- ⚡ Instant quick-run for default workflows
- 📋 Specific job execution
- 👁️ Dry run mode for preview
- 🌳 Workflow explorer sidebar
- ✅ YAML workflow validation
- 🔐 Environment variable management UI
- 📡 Webhook simulation with custom payloads
- 📜 Execution history tracking
- 📝 Workflow templates (Node.js, Python, Docker, AWS, Azure, Bicep, PowerShell, Shell, Release)
- 💻 Script generation for PowerShell, Bash, Python, and Bicep
- ⚙️ Easy configuration management
- ⌨️ Keyboard shortcuts (Cmd+Shift+A, Cmd+Shift+R)
- 🎯 Status bar integration
- 🔍 CodeLens buttons in workflow files
- 🔄 Auto-refresh workflow list on file changes
- 🔔 Act installation detection and guidance
- 🐳 Docker alternatives guide and setup helper
- 🔒 Security best practices guide
- 🔑 OIDC workflow templates
- 🏰 Enterprise secret management integration guides
Enterprise-Friendly:
- Built-in guide for Docker Desktop alternatives
- Podman, Rancher Desktop, Colima configuration
- Remote Docker host support
- Auto-detection of container runtimes
Security-First:
- Comprehensive GitHub Secrets security analysis
- OIDC authentication guides (AWS, Azure, GCP)
- Enterprise secret manager integration (Key Vault, Secrets Manager, Vault)
- Secure workflow templates
- What NOT to store in secrets guide
- Compliance considerations (SOC 2, GDPR, PCI DSS, HIPAA)
Made with ❤️ for the GitHub Actions community
