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:

graph TD
    Flags["1. Program Flags / Arguments"]
    Env["2. Environment Vars (.env / System)"]
    LocalActConfig["3. Local Config"]
    GlobalActConfig["4. Global Config (`~/actconfig`)"]
    Flags --> Env
    Env --> LocalActConfig
    LocalActConfig --> GlobalActConfig

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 as the first positional argument. Any flags following the filename are passed directly to your graph as inputs.

# Syntax: actrun [options] <filename> [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.

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#

actrun automatically loads variables from a .env file located in the same directory as the executable.

3. Configuration Files (.actconfig)#

You can use YAML configuration files to persist environment variables and secrets. Either you define a specific config file, or actrun will look in your home folder for a global config.

1. Local: A specified file provided via the --config_file flag or ACT_CONFIG_FILE environment variable.
2. Global: A .actconfig file in your user home directory (~/.actconfig).

Example actconfig content:

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

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=true
./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. Instead, they must be defined in a config file under the secrets key.

Secrets can be accessed using the 🔑 Secret Node. Alternatively, you can access them directly in the inputs of Run Program, Run Script or Environment Vars 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:

- name: Execute Action Graph
  uses: actionforge/action@1cb7c39...
  with:
      graph_file: my-workflow.yml
      secrets: ${{ toJson(secrets) }} # (1)

1. Add this line to allow that your secrets can be accessed within the action graph.