Metadata-Version: 2.4
Name: gasket-cli
Version: 0.2.2
Summary: Run GitHub Actions locally using nektos/act from a Python CLI
Author-email: hieu_trincao <kaiinredtie@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/hieupham259/gasket
Project-URL: Repository, https://github.com/hieupham259/gasket
Project-URL: Issues, https://github.com/hieupham259/gasket/issues
Keywords: github-actions,act,ci,local,docker,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# Gasket

A Python CLI tool that wraps [nektos/act](https://github.com/nektos/act) to run
GitHub Actions workflows locally via Docker.

Built with [Click](https://click.palletsprojects.com/) for composable commands.

## Prerequisites

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

## Installation

```bash
# 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:

```bash
python install.py
```

## Commands

### run-act

Run GitHub Actions workflows locally using nektos/act.

```bash
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.

```bash
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

```bash
# 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
