Debug Sessions

Debug Sessions は、Webベースのビジュアルエディタとローカル環境をつなぐ開発専用の機能です。ローカルの runner を Debug Session に接続することで、ブラウザでリアルタイムに graph を設計しながら、自分のマシン上で実行できます。

インターフェースの操作

コントロールバーで Debug Session のライフサイクルを管理します。デフォルトでは、debug session はオフになっています。

オンに切り替えると、Debug Session Setup ダイアログが表示されます。セットアップ手順は、デバッグする graph の種類によって異なります。

Standalone

セットアップダイアログでは、3つのステップを案内します:

1. runner のダウンロード — お使いのプラットフォーム向けの Actionforge runner をダウンロードしてください。
2. 作業ディレクトリの設定（任意）— runner の作業ディレクトリを設定します。設定しない場合、ランダムな一時フォルダが使用されます。
3. Session Token のコピー — session token をコピーして、ローカルの runner に貼り付けて接続します。

ローカルの runner を起動する際に、このトークンを入力してマシンを Debug Session に認証する必要があります。

ブラウザからセッションをセットアップする代わりに、--create-debug-session flag を使って runner 側からセットアップすることもできます。この場合、セットアップダイアログはスキップされ、graph を手動で実行するとコンソールにリンクが表示されます。そのリンクをブラウザで開くと、すでに実行中の debug session にすぐ接続できます。

actrun --create-debug-session ./my_graph.act

GitHub Actions

Actionforge では、GitHub Actions workflow graph を自分のマシンでデバッグできるため、workflow のバグを解消し、GitHub runner のコストを削減できます。actrun が GitHub Actions workflow graph を検出すると、シミュレーションされた GitHub Actions 環境を自動的にセットアップするので、GitHub にプッシュする前にローカルで workflow をテストできます。

セットアップダイアログには、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 に貼り付けて接続します。

ダイアログが環境を自動設定するため、Debug Sessions を使用する場合は環境変数を手動で設定する必要はありません。

---

CLI セットアップ（Debug Session なし）

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

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

お使いのプラットフォーム向けの CLI actrun runner をダウンロードしてインストールしてください。

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

トークンを安全に管理しましょう

トークンをバージョン管理にコミットしないでください。.actconfig ファイル（.gitignore に追加）や --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

---

自動環境セットアップ

GitHub Actions 外で GitHub Actions workflow graph を実行していることを actrun が検出すると、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	検出されたオペレーティングシステムです
RUNNER_ARCH	X64 / ARM64	検出された CPU アーキテクチャです
RUNNER_TEMP	一時ディレクトリ	action 用の一時領域です
RUNNER_TOOL_CACHE	~/.actrun/tool-cache	action がツールをキャッシュする場所です

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

変数	説明
GITHUB_OUTPUT	action がここに出力を書き込みます
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 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"

---

トラブルシューティング

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

GitLab CI (Coming soon)

GitLab CI のサポートは近日公開予定です。

接続が完了すると、デバッグコントロールがアクティブになります。

runner の切断

runner が切断された場合、再接続を促すモーダルダイアログが表示されます。ダイアログには session token が再度表示され、runner の再接続を待ちます。

暗号化

ブラウザと actrun プログラム間のすべての通信は、AES-256-GCM によるエンドツーエンド暗号化で保護されています。Actionforge サーバーはリレーとしてのみ機能し、Debug Session 中にやり取りされるメッセージを読み取ったり復号したりすることはできません。これには、graph ファイル、シークレットや環境変数などの設定データ、ログが含まれますが、これらに限定されません。

Debug Session が作成されると、ブラウザが一意の暗号化キーを生成し、session token に埋め込みます。このトークンはテキストクリップボードを使って、ブラウザから actrun プログラムに手動でコピー＆ペーストする必要があるため、サーバーがトークンを見ることはありません。

actrun の暗号化メカニズムのソースコードはこちらで公開されています。