Act Runner

Proxy for the act GitHub Actions local runner.

Handles detection, installation guidance, and workflow verification by delegating to the act CLI with sensible defaults.

exception pypreset.act_runner.ActError[source]

Bases: Exception

Raised when an act operation fails.

class pypreset.act_runner.ActCheckResult[source]

Bases: object

Result of checking whether act is available.

Parameters:
installed: bool
version: str | None = None
error: str | None = None
__init__(installed, version=None, error=None)
Parameters:
Return type:

None

class pypreset.act_runner.ActRunResult[source]

Bases: object

Result of running act on a workflow.

Parameters:
success: bool
command: list[str]
stdout: str = ''
stderr: str = ''
return_code: int = -1
__init__(success, command, stdout='', stderr='', return_code=-1)
Parameters:
Return type:

None

class pypreset.act_runner.ActInstallResult[source]

Bases: object

Result of attempting to install act.

Parameters:
success: bool
method: str = ''
message: str = ''
__init__(success, method='', message='')
Parameters:
Return type:

None

class pypreset.act_runner.WorkflowVerifyResult[source]

Bases: object

Complete result of a workflow verification.

Parameters:
act_available: bool
act_version: str | None = None
workflow_path: str = ''
runs: list[ActRunResult]
errors: list[str]
warnings: list[str]
__init__(act_available, act_version=None, workflow_path='', runs=<factory>, errors=<factory>, warnings=<factory>)
Parameters:
Return type:

None

pypreset.act_runner.check_act()[source]

Check if act is installed and return version info.

Performs a meta-check: if act –version fails, verifies whether the binary truly isn’t on PATH vs some other issue.

Return type:

ActCheckResult

pypreset.act_runner.get_install_suggestion()[source]

Return a human-readable install suggestion and optional command.

Return type:

tuple[str, list[str] | None]

Returns:

Tuple of (message, command_or_None).

pypreset.act_runner.install_act()[source]

Attempt to install act automatically on supported systems.

Return type:

ActInstallResult

pypreset.act_runner.run_act(*, project_dir, workflow_file=None, job=None, event='push', dry_run=False, list_jobs=False, platform_map=None, extra_flags=None, timeout=600)[source]

Run act with the given options.

Parameters:

  • project_dir (Path) – The project root (cwd for act).

  • workflow_file (Path | None) – Specific workflow file to run (relative to project_dir).

  • job (str | None) – Specific job to run.

  • event (str) – GitHub event to simulate (default: push).

  • dry_run (bool) – Run in dry-run mode (validate without executing).

  • list_jobs (bool) – Just list available jobs.

  • platform_map (str | None) – Platform mapping (e.g. ‘ubuntu-latest=catthehacker/ubuntu:act-latest’).

  • extra_flags (list[str] | None) – Additional flags to pass to act.

  • timeout (int) – Command timeout in seconds.

Return type:

ActRunResult

Returns:

ActRunResult with command output.

pypreset.act_runner.verify_workflow(*, project_dir, workflow_file=None, job=None, event='push', dry_run=True, platform_map=None, extra_flags=None, timeout=600, auto_install=False)[source]

Verify a GitHub Actions workflow using act.

This is the main entry point. It: 1. Checks if act is installed (with meta-check on failure) 2. Optionally attempts auto-install 3. Lists workflow jobs for info 4. Runs the workflow in dry-run or full mode 5. Surfaces all act output back to the caller

Parameters:

  • project_dir (Path) – Path to the project root.

  • workflow_file (Path | None) – Specific workflow file (relative to project). If None, act will discover workflows in .github/workflows/.

  • job (str | None) – Specific job name to run. If None, runs all jobs.

  • event (str) – GitHub event to simulate.

  • dry_run (bool) – If True, validate without executing containers.

  • platform_map (str | None) – Platform mapping for act.

  • extra_flags (list[str] | None) – Additional flags forwarded to act.

  • timeout (int) – Timeout in seconds for act commands.

  • auto_install (bool) – Attempt automatic installation if act is missing.

Return type:

WorkflowVerifyResult

Returns:

WorkflowVerifyResult with all details.