gasket-cli 0.2.2

Run GitHub Actions locally using nektos/act from a Python CLI

Gasket

A Python CLI tool that wraps nektos/act to run GitHub Actions workflows locally via Docker.

Built with Click for composable commands.

Prerequisites

• Python 3.10+
• Docker - must be installed and running
• nektos/act - installed automatically via gasket setup install-act

Installation

# Clone the repository
git clone <repo-url>
cd gasket

# Create virtual environment
python -m venv .venv
source .venv/bin/activate    # Linux/macOS
# .venv\Scripts\activate     # Windows

# Install in development mode
pip install -e ".[dev]"

# Install act (if not already installed)
gasket setup install-act

# Verify installation
gasket --version
gasket --help

Or use the standalone installer:

python install.py

Commands

run-act

Run GitHub Actions workflows locally using nektos/act.

gasket run-act                              # Run push event workflows
gasket run-act --event pull_request         # Run pull_request workflows
gasket run-act --list                       # List available workflows
gasket run-act --dry-run                    # Dry run only
gasket run-act -j test                      # Run specific job
gasket run-act -W .github/workflows/ci.yml  # Run specific workflow
gasket run-act -s MY_SECRET=value           # Pass secrets
gasket run-act -P ubuntu-latest=node:16-buster-slim  # Platform override

Option	Type	Default	Description
--event / -e	Choice	push	Event type: push, pull_request, workflow_dispatch, schedule, release
--workflow / -W	Path	None	Specific workflow file or directory
--job / -j	String	None	Specific job name to run
--secret / -s	String	None	Secret in KEY=VALUE format (repeatable)
--secret-file	Path	None	Path to secrets file (.env format)
--var	String	None	Variable in KEY=VALUE format (repeatable)
--var-file	Path	None	Path to variables file
--input	String	None	Input in KEY=VALUE format for workflow_dispatch (repeatable)
--input-file	Path	None	Path to inputs file
--event-file	Path	None	Path to event JSON payload file
--platform / -P	String	None	Platform override RUNNER=IMAGE (repeatable)
--env	String	None	Environment variable KEY=VALUE (repeatable)
--env-file	Path	None	Path to env file
--matrix	String	None	Matrix filter KEY:VALUE (repeatable)
--container-architecture	String	None	Container architecture (e.g. linux/amd64)
--artifact-server-path	Path	None	Path to enable artifact server
--dry-run / -n	Flag	False	Dry run mode
--list / -l	Flag	False	List workflows without running
--verbose / -v	Flag	False	Verbose output
--offline	Flag	False	Use cached actions (offline mode)
--timeout	Integer	600	Timeout in seconds

setup

Manage installation and prerequisites.

gasket setup check                 # Check all prerequisites
gasket setup check --format json   # JSON output
gasket setup install-act           # Download and install act
gasket setup install-act --force   # Force reinstall
gasket setup install-all           # Install everything + verify
gasket setup uninstall-act         # Remove act binary

setup check

Check if Python, act, Docker, and Git are available.

setup install-act

Download the appropriate act binary for the current platform from GitHub releases.

Option	Type	Description
--install-dir	Path	Custom install directory
--force	Flag	Reinstall even if already installed

setup install-all

Install all dependencies and verify the environment.

setup uninstall-act

Remove the act binary.

Exit Codes

Code	Meaning
0	Success
1	Execution error
3	act not found

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=gasket --cov-report=term-missing

# Run specific test file
pytest tests/test_run_act.py -v

Project Structure

gasket/
├── pyproject.toml
├── install.py                      # Standalone bootstrap installer
├── src/
│   └── gasket/
│       ├── cli.py                  # Main CLI entry point (click.group)
│       ├── commands/
│       │   ├── run_act.py          # run-act command
│       │   └── setup.py           # setup command group
│       └── core/
│           ├── act_runner.py       # act subprocess wrapper
│           └── act_installer.py    # act binary downloader/installer
└── tests/
    ├── test_run_act.py
    └── test_setup.py

License

MIT