設定

actrun は、プログラム flag、環境変数、設定ファイルを通じて値を定義できる柔軟な設定システムを提供します。

設定の優先順位は厳密な階層構造になっています。リストの上位で定義された値が、下位の値を上書きします:

Configuration priority: 1. Program Flags, 2. Environment Vars, 3. Local Config, 4. Global Config

1. プログラム Flag（推奨）

actrun を設定する最も直接的な方法は、引数と flag を実行ファイルに直接渡すことです。これは最も優先度の高い方法です。

Graph の直接実行

特定の action graph を実行するには、最初の位置引数としてファイル名（または URL）を指定します。ファイル名の後に続く flag は、graph の input として直接渡されます。

# 構文: actrun [options] <filename|url> [graph-flags]

# graph を実行する
./actrun my_graph.act

# graph を実行し、flag を渡す
./actrun my_graph.act --my-flag=test --another-flag=123

# 独自の設定ファイルを指定して graph を実行し、flag を渡す
./actrun --config-file=/path/to/config.actconfig my_graph.act --my-flag=test --another-flag=123

注意: actrun 固有の flag（--config-file など）は、graph のファイル名の前に配置する必要があります。ファイル名より後ろのものはすべて、graph 自体への引数として扱われます。

利用可能な Flag

Flag	説明
`--config-file`	特定の `.actconfig` 設定ファイルへのパスです。
`--concurrency`	並行 execution を有効または無効にします（デフォルト: true）。
`--session-token`	ブラウザのデバッグセッションに接続するためのトークンです。
`--create-debug-session`	Web アプリに接続してデバッグセッションを作成します。`--session-token` と同時に使用することはできません。
`--env-file`	execution 前に読み込む `.env` ファイルの絶対パスです。

注意: すべての flag でハイフン（--config-file）とアンダースコア（--config_file）の両方を使用できます。

サブコマンド

コマンド	説明
`validate [graph-file]`	graph ファイルを実行せずに検証します。
`version`	actrun のバージョン番号を表示します。

2. 環境変数

環境変数を使用して、ランタイムの動作を設定したり、デフォルト値を定義したりできます。これは CI/CD 環境やユーザーのデフォルト設定に便利です。

環境変数による Graph の指定

毎回ファイル名を渡す代わりに、ACT_GRAPH_FILE 変数を設定できます。

export ACT_GRAPH_FILE=my_workflow.act
./actrun

暗黙的な Graph への Flag の受け渡し

ACT_GRAPH_FILE 環境変数で graph を定義していて、ランタイム flag（input など）も渡したい場合は、ダブルダッシュ -- セパレータを使う 必要があります。これにより、後続の flag が CLI ツールではなく graph に属することを actrun に伝えます。

export ACT_GRAPH_FILE=my_workflow.act
export ACT_CONFIG_FILE=my_config.actconfig

# '--' を使用して graph に flag を渡す
./actrun -- --my-flag=test --another-flag=123

サポートされる変数

--env-file flag を使用して、.env ファイルから追加の変数を読み込むことができます。

変数	対応する Flag	説明
`ACT_GRAPH_FILE`	`[filename]`	引数として指定されない場合に実行するデフォルトの graph ファイルです。
`ACT_CONCURRENCY`	`--concurrency`	並行 execution を有効または無効にします（デフォルト: true）。
`ACT_CONFIG_FILE`	`--config-file`	特定の `.actconfig` ファイルへのパスです。
`ACT_SESSION_TOKEN`	`--session-token`	ブラウザのデバッグセッションに接続するためのトークンです。
`ACT_CREATE_DEBUG_SESSION`	`--create-debug-session`	Web アプリに接続してデバッグセッションを作成します。
`ACT_LOGLEVEL`	—	ログレベルを設定します（`debug`、`verbose`、またはデフォルト）。
`ACT_NOCOLOR`	—	`true` に設定すると、ターミナルのカラー出力を無効にします。

3. 設定ファイル（`.actconfig`）

YAML 設定ファイルを使用して、環境変数と secret を永続化できます。特定の設定ファイルを定義するか、actrun がホームフォルダでグローバル設定を検索します。

ローカル: --config-file flag または ACT_CONFIG_FILE 環境変数で指定されたファイルです。
グローバル: ユーザーのホームディレクトリにある .actconfig ファイル（~/.actconfig）です。

ディレクトリ~/ ホームディレクトリ
- .actconfig グローバル設定
ディレクトリyour-project/
- .actconfig ローカル設定
- my-workflow.act

actconfig の内容例:

env:
  # これらの変数は graph で使用できます
  API_ENDPOINT: https://api.example.com
  DEFAULT_REGION: us-east-1
secrets:
  # Secret は Secret Node から安全にアクセスできます
  API_KEY: abcdef123456
  DB_PASSWORD: super_secret_password
inputs:
  # Input は graph の input として利用できます
  DEPLOYMENT_ENV: production

デバッグ出力

起動時に設定値がどこから読み込まれているかを正確に確認するには、ACT_LOGLEVEL 環境変数を debug に設定します。

export ACT_LOGLEVEL=debug
./actrun --concurrency=false
looking for value: 'concurrency'
  found value in flags
  evaluated to: 'false'

Secret の管理

Secret はコマンドライン flag で渡すべきでは ありません。環境変数を使用するか、設定ファイルの secrets キーの下に定義してください。

Secret は Secret Node を使用してアクセスできます。また、Expression 構文を使用して、 input から直接アクセスすることもできます。

GitHub Actions Workflow

GitHub Action workflow 内で actrun を実行する場合、JSON 形式を使用してリポジトリの secret を graph コンテキストに渡すことができます:

ディレクトリ.github/
- ディレクトリworkflows/
  - my-gh-workflow.yml workflow YAML
  - my-workflow.act action graph

jobs:
  build-quick:
    runs-on: ubuntu-latest
    name: Run Graph
    steps:
      - name: Run Graph
        uses: actionforge/action@866e7df1ce5e84a2b32fda7414812ae72000dae8 # v0.14.6
        with:
          graph_file: my-workflow.act # (1)

          inputs: ${{toJson(inputs) }}
          secrets: ${{toJson(secrets) }} # (2)
          matrix: ${{toJson(matrix) }}
          needs: ${{toJson(needs) }}

graph の保存先は .github/workflows/my-workflow.act です。
ℹ️ この行を追加すると、リポジトリまたは組織の secret を action graph 内でアクセスできるようになります。

設定