actions-toolkit

Local GitHub Actions workflow runner with ephemeral repositories and actionable failure summaries.

Prerequisites

Install the toolkit itself:

pip install actions-toolkit
# or from source
uv tool install .

PR Review Workflow

GitHub

# 1. Checkout the PR branch
gh pr checkout <PR_NUMBER>
# 2. Run workflows locally and review the summary
actions-toolkit ephemeral . 2>&1 | actions-toolkit summary

Breakdown:

# Fetch a specific PR and switch to its branch
gh pr checkout 42
# Run all workflows from an ephemeral copy, pipe into the summary parser
actions-toolkit ephemeral . 2>&1 | actions-toolkit summary
# Run a single job with detailed error context
actions-toolkit ephemeral -j test . 2>&1 | actions-toolkit summary -d
# Target a specific workflow file
actions-toolkit ephemeral -w .github/workflows/ci.yml . 2>&1 \
 | actions-toolkit summary
# Simulate a pull_request event
actions-toolkit ephemeral -e pull_request . 2>&1 \
 | actions-toolkit summary

Codeberg (Forgejo)

Codeberg uses Forgejo Actions, which are compatible with the GitHub Actions syntax that act runs. The workflow is the same, but you use tea to interact with PRs and may need --action-offline-mode if your workflows reference actions from the GitHub Marketplace that aren't mirrored.

# 1. Checkout the PR branch
tea pr checkout <PR_NUMBER>
# 2. Run workflows locally with offline mode, pipe into summary
actions-toolkit ephemeral . -- --action-offline-mode 2>&1 \
 | actions-toolkit summary

Breakdown:

# Fetch a specific PR
tea pr checkout 42
# Run all workflows (offline mode avoids fetching from GitHub Marketplace)
actions-toolkit ephemeral . -- --action-offline-mode 2>&1 \
 | actions-toolkit summary
# Run a specific job with a custom platform matrix
actions-toolkit ephemeral -j build . -- \
 --action-offline-mode \
 -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest \
 2>&1 | actions-toolkit summary -d
# Simulate a pull_request_target event with secrets
actions-toolkit ephemeral \
 -e pull_request_target \
 -s MY_SECRET=value \
 . -- --action-offline-mode 2>&1 \
 | actions-toolkit summary

Note: Without --action-offline-mode, act tries to download actions from github.com, which may fail for actions that aren't mirrored on Codeberg. Set --action-offline-mode to use only locally resolved actions (from .local/actions or the act cache).

Shell Script Variants

If you don't have the Python package installed, the repo includes standalone shell scripts with identical functionality:

# Activate them (add to PATH or run from repo root)
chmod +x act-ephemeral.sh act_summary.sh
# Same workflow, same flags
act-ephemeral.sh -w .github/workflows/ci.yml . | act_summary.sh

All Options

actions-toolkit ephemeral

actions-toolkit ephemeral [OPTIONS] <source_repo> [-- ACT_ARGS...]
 -w, --workflow WORKFLOW Workflow file to run
 -j, --job JOB Specific job ID to run
 -e, --event EVENT Event name (push, pull_request, etc.)
 -i, --input KEY=VALUE Workflow input (repeatable)
 -s, --secret KEY=VALUE Secret (repeatable)
 -c, --container ENGINE podman|docker (default: podman)
 --no-cleanup Preserve temp directory after run
 -h, --help Show help
 Any arguments after -- are forwarded to act.

actions-toolkit summary

actions-toolkit summary [OPTIONS] [logfile]
 -d, --detailed Show detailed error context for failed steps
 -o, --output FILE Write plain-text summary to file
 -h, --help Show help
 If no logfile is given, reads from stdin.

Environment Variables