GitHub Actions Runner の設定

Actionforge を使用すると、GitHub Actions workflow graph をローカルマシンでデバッグでき、workflow のバグを排除し、GitHub runner のコストを削減できます。actrun が GitHub Actions workflow graph（つまり GitHub Actions workflow テンプレートから作成されたもの）を検出すると、シミュレートされた GitHub Actions 環境を自動的にセットアップするため、GitHub にプッシュする前にローカルで workflow をテストできます。

デバッグセッションのセットアップ

GitHub Actions workflow graph のデバッグセッションを開始すると、セットアップダイアログに GitHub Actions 固有の追加フィールドが表示されます:

1. Runner をダウンロード — お使いのプラットフォーム用の Actionforge runner をダウンロードします。
2. ローカルリポジトリのパスを設定 — クローンした GitHub リポジトリのローカルパスを入力します。これは GITHUB_WORKSPACE として使用されます。
3. GitHub Token を設定 — 最小限の権限で fine-grained personal access token を作成します。トークンはエンドツーエンドで暗号化され、ローカルの runner のみが復号できます。
4. Session Token をコピー — session token をコピーして、ローカルの runner に貼り付けて接続します。

このダイアログが環境を設定してくれるため、デバッグセッション使用時に手動で環境変数を設定する必要はありません。

---

CLI セットアップ（デバッグセッションなし）

コマンドラインから GitHub Actions workflow graph を直接実行したい場合は、以下の手順に従ってください:

1. actrun のダウンロードとインストール

お使いのプラットフォーム用の CLI actrun runner をダウンロードしてインストールします。

Download actrun

詳細なインストール手順については、インストールガイド を参照してください。

2. GitHub Access Token の作成

多くの GitHub Actions は GitHub の API で認証するために GITHUB_TOKEN を必要とします。これらの action をローカルで実行するには、fine-grained personal access token を作成します:

1. Generate new token をクリックします
2. わかりやすい名前を付けます（例: “actrun local development”）
3. 有効期限を設定します
4. アクセスするリポジトリを選択します
5. Repository permissions で、action に必要な権限を付与します。特定の GitHub API 機能が必要でない限り、パブリックリソースへの read アクセスを付与するデフォルトの権限のままにしてください。
6. Generate token をクリックしてトークンをコピーします

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

トークンを安全に保管してください

トークンをバージョン管理にコミットしないでください。.gitignore に追加した .actconfig ファイルや、--env-file flag で .env ファイルを使用することを検討してください。

3. 必要な環境変数の設定

リポジトリのルートに移動して、以下の環境変数を設定します:

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

変数	説明
GITHUB_WORKSPACE	git リポジトリのルートへのパスです。actrun はこれを使用してリポジトリ名、ブランチ、コミットを検出します。
GITHUB_EVENT_NAME	workflow をトリガーしたイベントです（例: push、pull_request、workflow_dispatch）。

4. actrun の実行

actrun my_workflow.act

---

環境の自動セットアップ

actrun が GitHub Actions 外で実行されている GitHub Actions workflow graph を検出すると、git リポジトリに基づいて以下の環境変数を自動的に設定します:

変数	値	用途
CI	true	CI 環境を示します
GITHUB_ACTIONS	true	GitHub Actions 環境を示します
GITHUB_REPOSITORY	owner/repo	git remote origin から導出されます
GITHUB_REF	refs/heads/branch	現在の git ブランチの参照です
GITHUB_REF_NAME	branch	現在のブランチ名です
GITHUB_SHA	コミットハッシュ	現在の HEAD コミットです
RUNNER_OS	macOS / Linux / Windows	検出された OS です
RUNNER_ARCH	X64 / ARM64	検出された CPU アーキテクチャです
RUNNER_TEMP	一時ディレクトリ	action 用のスクラッチスペースです
RUNNER_TOOL_CACHE	~/.actrun/tool-cache	action がツールをキャッシュする場所です

action 間の通信用に以下のファイルも自動的に作成されます:

変数	用途
GITHUB_OUTPUT	Action が output を書き込みます
GITHUB_ENV	Action が環境変数を設定します
GITHUB_PATH	Action が PATH エントリを追加します
GITHUB_STATE	Action が状態を保存します
GITHUB_STEP_SUMMARY	Action がサマリーを書き込みます

---

作業ディレクトリ

デフォルトでは、actrun は GitHub Actions workflow graph の作業ディレクトリを GITHUB_WORKSPACE に設定します。ACT_CWD 環境変数でこれを上書きできます:

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 は GITHUB_WORKSPACE より優先されます。

---

オプション変数

action が追加の変数を必要とする場合は、環境に以下を追加してください:

# Workflow メタデータ
export GITHUB_WORKFLOW="My Workflow"
export GITHUB_JOB="build"
export GITHUB_RUN_ID="1"
export GITHUB_RUN_NUMBER="1"

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

# ユーザー情報（ご自身の情報に置き換えてください）
export GITHUB_REPOSITORY_OWNER="your-username"
export GITHUB_ACTOR="your-username"

---

トラブルシューティング

Action が ‘GITHUB_WORKSPACE environment variable is required’ で失敗する

actrun を実行する前に、GITHUB_WORKSPACE が git リポジトリのパスに設定されていることを確認してください。

Action が ‘GITHUB_EVENT_NAME environment variable is required’ で失敗する

GITHUB_EVENT_NAME をイベントタイプ（例: push、pull_request、workflow_dispatch）に設定してください。

Action がツールやキャッシュを見つけられない

RUNNER_TOOL_CACHE が書き込み可能なディレクトリを指していることを確認してください:

mkdir -p ~/.actrun/tool-cache

Action が GitHub 上と異なる動作をする

一部の action は特定の環境値をチェックします。以下を追加してみてください:

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