Configuration

actrun provides a flexible configuration system that allows you to define values through program flags, environment variables, and configuration files.

The configuration priority is strictly hierarchical. Values defined at the top of the list override those below it:

1. Program Flags (Recommended)

The most direct way to configure actrun is by passing arguments and flags directly to the executable. This is the highest priority method.

Running a Graph Directly

To run a specific action graph, provide the filename (or URL) as the first positional argument. Any flags following the filename are passed directly to your graph as inputs.

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

# Run a graph
./actrun my_graph.act

# Run a graph and pass flags to it
./actrun my_graph.act --my-flag=test --another-flag=123

# Run a graph with your own config file, and pass flags to it
./actrun --config-file=/path/to/config.actconfig my_graph.act --my-flag=test --another-flag=123

Note: actrun specific flags (like --config-file) must be placed before the graph filename. Everything after the filename is treated as an argument for the graph itself.

Available Flags

Flag	Description
--config-file	Path to a specific .actconfig configuration file.
--concurrency	Enable or disable concurrent execution (default: true).
--session-token	Token for connecting to a browser debug session.
--create-debug-session	Create a debug session by connecting to the web app. Cannot be used together with --session-token.
--env-file	Absolute path to an .env file to load before execution.

Note: Both hyphens (--config-file) and underscores (--config_file) are accepted for all flags.

Subcommands

Command	Description
validate [graph-file]	Validate a graph file without executing it.
version	Print the version number of actrun.

2. Environment Variables

You can configure the runtime behavior and define default values using environment variables. This is useful for CI/CD environments or setting defaults for the user.

Defining the Graph via Environment

Instead of passing the filename every time, you can set the ACT_GRAPH_FILE variable.

export ACT_GRAPH_FILE=my_workflow.act
./actrun

Passing Flags to an Implicit Graph

If you have defined your graph via the ACT_GRAPH_FILE environment variable but still need to pass runtime flags (like inputs), you must use the double-dash -- separator. This tells actrun that the following flags belong to the graph, and not the CLI tool.

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

# Use '--' to pass flags to your graph
./actrun -- --my-flag=test --another-flag=123

Supported Variables

You can load additional variables from an .env file by using the --env-file flag.

Variable	Flag Equivalent	Description
ACT_GRAPH_FILE	[filename]	The default graph file to execute if none is provided as an argument.
ACT_CONCURRENCY	--concurrency	Enable or disable concurrent execution (default: true).
ACT_CONFIG_FILE	--config-file	Path to a specific .actconfig file.
ACT_SESSION_TOKEN	--session-token	Token for connecting to a browser debug session.
ACT_CREATE_DEBUG_SESSION	--create-debug-session	Create a debug session by connecting to the web app.
ACT_LOGLEVEL	—	Set the log level (debug, verbose, or default).
ACT_NOCOLOR	—	Set to true to disable color output in the terminal.

3. Configuration Files (.actconfig)

You can use YAML configuration files to persist environment variables and secrets. Specify a config file via the --config-file flag or the ACT_CONFIG_FILE environment variable.

• Directoryyour-project/

  • .actconfig config file
  • my-workflow.act

Example actconfig content:

.actconfig

env:
  # These variables will be available to your graph
  API_ENDPOINT: https://api.example.com
  DEFAULT_REGION: us-east-1
secrets:
  # Secrets are securely made available to the Secret Node
  API_KEY: abcdef123456
  DB_PASSWORD: super_secret_password
inputs:
  # Inputs are available as graph inputs
  DEPLOYMENT_ENV: production

Debug Output

To see exactly where configuration values are being loaded from during startup, set the ACT_LOGLEVEL environment variable to debug.

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

Secrets Management

Secrets should never be passed via command-line flags. Either use environment variables, or define them in your config file under the secrets key.

Secrets can be accessed using the 🔑 Secret Node. Alternatively, you can access them directly in the inputs of a input by using the Expression Syntax.

GitHub Actions Workflows

When running actrun inside a GitHub Action workflow, you can pass repository secrets into the graph context using the JSON format:

• Directory.github/

  • Directoryworkflows/

    • my-gh-workflow.yml workflow YAML
    • my-workflow.act action graph

.github/workflows/my-gh-workflow.yml

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) }}

1. Save your graph here .github/workflows/my-workflow.act.
2. ℹ️ Add this line to allow that your repository or organization secrets can be accessed within the action graph.