GitHub Actions Runner Setup#

Actionforge lets you debug GitHub Actions workflow graphs on your machine, eliminating workflow bugs and reducing GitHub runner costs. When actrun detects a GitHub Actions workflow graph (i.e., one created from the GitHub Actions workflow template), it automatically sets up a simulated GitHub Actions environment so you can test your workflows locally before pushing them to GitHub.

Debug Session Setup#

When you start a Debug Session for a GitHub Actions workflow graph, the setup dialog includes additional fields specific to GitHub Actions:

1. Download Runner — Download the Actionforge runner for your platform.
2. Set Local Repository Path — Enter the local path to your cloned GitHub repository. This is used as the GITHUB_WORKSPACE.
3. Set GitHub Token — Create a fine-grained personal access token with minimal permissions. The token is end-to-end encrypted and can only be decrypted by your local runner.
4. Copy Session Token — Copy the session token and paste it into your local runner to connect.

The dialog configures the environment for you — no manual environment variable setup is needed when using Debug Sessions.

CLI Setup (Without Debug Session)#

If you prefer to run your GitHub Actions workflow graph directly from the command line, follow these steps:

Download and install actrun#

Download and install the CLI actrun runner for your platform.

Download actrun

For detailed installation instructions, see the Installation Guide.

Create a GitHub Access Token#

Many GitHub Actions require a GITHUB_TOKEN to authenticate with GitHub's API. To run these actions locally, create a fine-grained personal access token :

1. Click Generate new token
2. Give it a descriptive name (e.g., "actrun local development")
3. Set an expiration date
4. Select the repositories you want to access
5. Under Repository permissions, grant the permissions your actions need. Unless you need specific GitHub API features, leave the default permissions which give read access to public resources.
6. Click Generate token and copy the token

Set the token as an environment variable before running actrun:

export ACT_INPUT_TOKEN="ghp_your_token_here"

$env:ACT_INPUT_TOKEN = "ghp_your_token_here"

set ACT_INPUT_TOKEN=ghp_your_token_here

Set required environment variables#

Navigate to your repository root and set the following environment variables:

cd /path/to/your/repo
export GITHUB_WORKSPACE="$(pwd)"
export GITHUB_EVENT_NAME="push"

cd C:\path\to\your\repo
$env:GITHUB_WORKSPACE = (Get-Location).Path
$env:GITHUB_EVENT_NAME = "push"

cd C:\path\to\your\repo
set GITHUB_WORKSPACE=%CD%
set GITHUB_EVENT_NAME=push

Run actrun#

actrun my_workflow.act

Automatic Environment Setup#

When actrun detects a GitHub Actions workflow graph running outside of GitHub Actions, it automatically configures the following environment variables based on your git repository:

The following files for action communication are also created automatically:

Working Directory#

By default, actrun sets the working directory to GITHUB_WORKSPACE for GitHub Actions workflow graphs. You can override this with the ACT_CWD environment variable:

export ACT_CWD="/path/to/custom/workdir"

$env:ACT_CWD = "C:\path\to\custom\workdir"

set ACT_CWD=C:\path\to\custom\workdir

ACT_CWD takes precedence over GITHUB_WORKSPACE when both are set.

Optional Variables#

If an action requires additional variables, add these to your environment:

# Workflow metadata
export GITHUB_WORKFLOW="My Workflow"
export GITHUB_JOB="build"
export GITHUB_RUN_ID="1"
export GITHUB_RUN_NUMBER="1"

# GitHub URLs
export GITHUB_SERVER_URL="https://github.com"
export GITHUB_API_URL="https://api.github.com"
export GITHUB_GRAPHQL_URL="https://api.github.com/graphql"

# User info (replace with your details)
export GITHUB_REPOSITORY_OWNER="your-username"
export GITHUB_ACTOR="your-username"

Troubleshooting#

mkdir -p ~/.actrun/tool-cache

export RUNNER_ENVIRONMENT="github-hosted"
export ImageOS="ubuntu24"  # or macos15, win25