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:

1. Download and install actrun

Download and install the CLI actrun runner for your platform.

Download actrun

For detailed installation instructions, see the Installation Guide.

2. 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:

macOS / Linux

export ACT_INPUT_TOKEN="ghp_your_token_here"

Windows

PowerShell

$env:ACT_INPUT_TOKEN = "ghp_your_token_here"

Command Prompt

set ACT_INPUT_TOKEN=ghp_your_token_here

Keep your token secure

Never commit your token to version control. Consider using a .actconfig file (added to .gitignore) or the --env-file flag with a .env file.

3. Set required environment variables

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

macOS / Linux

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

Windows

PowerShell

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

Command Prompt

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

Variable	Description
GITHUB_WORKSPACE	Path to your git repository root. actrun uses this to detect the repository name, branch, and commit.
GITHUB_EVENT_NAME	The event that triggered the workflow (e.g., push, pull_request, workflow_dispatch).

4. 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:

Variable	Value	Purpose
CI	true	Signals CI environment
GITHUB_ACTIONS	true	Signals GitHub Actions environment
GITHUB_REPOSITORY	owner/repo	Derived from git remote origin
GITHUB_REF	refs/heads/branch	Current git branch reference
GITHUB_REF_NAME	branch	Current branch name
GITHUB_SHA	Commit hash	Current HEAD commit
RUNNER_OS	macOS / Linux / Windows	Detected operating system
RUNNER_ARCH	X64 / ARM64	Detected CPU architecture
RUNNER_TEMP	Temp directory	Scratch space for actions
RUNNER_TOOL_CACHE	~/.actrun/tool-cache	Where actions cache tools

The following files for action communication are also created automatically:

Variable	Purpose
GITHUB_OUTPUT	Actions write outputs here
GITHUB_ENV	Actions set env vars here
GITHUB_PATH	Actions add PATH entries here
GITHUB_STATE	Actions save state here
GITHUB_STEP_SUMMARY	Actions write summaries here

---

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:

macOS / Linux

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

Windows

PowerShell

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

Command Prompt

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

Action fails with ‘GITHUB_WORKSPACE environment variable is required’

Make sure GITHUB_WORKSPACE is set to the path of your git repository before running actrun.

Action fails with ‘GITHUB_EVENT_NAME environment variable is required’

Set GITHUB_EVENT_NAME to the event type (e.g., push, pull_request, workflow_dispatch).

Action cannot find tools or cache

Ensure RUNNER_TOOL_CACHE points to a writable directory:

mkdir -p ~/.actrun/tool-cache

Action behaves differently than on GitHub

Some actions check for specific environment values. Try adding:

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