attune/docs/web-ui/execute-action-env-vars.md at perms-mgmt

Files

David Culbreth a74e13fa0b working out the worker/execution interface

2026-02-08 12:55:33 -06:00

9.1 KiB

Raw Permalink Blame History

Feature: Custom Environment Variables for Manual Executions
Added: 2026-02-07
Location: Actions Page → Execute Action Modal

Overview

The Execute Action modal now includes an "Environment Variables" section that allows users to specify optional runtime configuration for manual action executions. This is useful for debug flags, log levels, and other runtime settings.

UI Components

┌──────────────────────────────────────────────────────────┐
│ Execute Action                                        X  │
├──────────────────────────────────────────────────────────┤
│                                                          │
│ Action: core.http_request                                │
│ Make an HTTP request to a specified URL                  │
│                                                          │
├──────────────────────────────────────────────────────────┤
│ Parameters                                               │
│ ┌────────────────────────────────────────────────────┐   │
│ │ URL *                                              │   │
│ │ https://api.example.com                            │   │
│ │                                                    │   │
│ │ Method                                             │   │
│ │ GET                                                │   │
│ └────────────────────────────────────────────────────┘   │
│                                                          │
├──────────────────────────────────────────────────────────┤
│ Environment Variables                                    │
│ Optional environment variables for this execution        │
│ (e.g., DEBUG, LOG_LEVEL)                                 │
│                                                          │
│ ┌──────────────────────┬──────────────────────┬────┐    │
│ │ Key                  │ Value                │    │    │
│ ├──────────────────────┼──────────────────────┼────┤    │
│ │ DEBUG                │ true                 │ X  │    │
│ ├──────────────────────┼──────────────────────┼────┤    │
│ │ LOG_LEVEL            │ debug                │ X  │    │
│ ├──────────────────────┼──────────────────────┼────┤    │
│ │ TIMEOUT_SECONDS      │ 30                   │ X  │    │
│ └──────────────────────┴──────────────────────┴────┘    │
│                                                          │
│ + Add Environment Variable                               │
│                                                          │
├──────────────────────────────────────────────────────────┤
│                                    [Cancel]  [Execute]   │
└──────────────────────────────────────────────────────────┘

Features

Dynamic Key-Value Rows

Each environment variable is entered as a key-value pair on a separate row:

Key Input: Text field for the environment variable name (e.g., DEBUG, LOG_LEVEL)
Value Input: Text field for the environment variable value (e.g., true, debug)
Remove Button: X icon to remove the row (disabled when only one row remains)

Add/Remove Functionality

Add: Click "+ Add Environment Variable" to add a new empty row
Remove: Click the X button on any row to remove it
Minimum: At least one row is always present (remove button disabled on last row)
Empty Rows: Rows with blank keys are filtered out when submitting

Validation

No built-in validation (flexible for debugging)
Empty key rows are ignored
Key-value pairs are sent as-is to the API

Use Cases

1. Debug Mode

Key: DEBUG
Value: true

Action script can check if [ "$DEBUG" = "true" ]; then set -x; fi

2. Custom Log Level

Key: LOG_LEVEL
Value: debug

Action script can use LOG_LEVEL="${LOG_LEVEL:-info}"

3. Timeout Override

Key: TIMEOUT_SECONDS
Value: 30

Action script can use TIMEOUT="${TIMEOUT_SECONDS:-60}"

4. Feature Flags

Key: ENABLE_EXPERIMENTAL
Value: true

Action script can conditionally enable features

5. Retry Configuration

Key: MAX_RETRIES
Value: 5

Action script can adjust retry behavior

Important Distinctions

❌ NOT for Sensitive Data

Environment variables are stored in the database
They appear in execution logs
Use action parameters with secret: true for passwords/API keys

❌ NOT for Action Parameters

Action parameters go via stdin as JSON
Environment variables are for runtime configuration only
Don't duplicate action parameters here

✅ FOR Runtime Configuration

Debug flags and feature toggles
Log levels and verbosity settings
Timeout and retry overrides
Non-sensitive execution metadata

Example Workflow

Navigate to Actions page
Find desired action
Click "Execute" button

Step 2: Fill Parameters

Fill in required and optional action parameters as usual.

Step 3: Add Environment Variables

Scroll to "Environment Variables" section
Enter first env var (e.g., DEBUG = true)
Click "+ Add Environment Variable" to add more rows
Enter additional env vars (e.g., LOG_LEVEL = debug)
Click X to remove any unwanted rows

Step 4: Execute

Click "Execute" button. The execution will have:

Action parameters delivered via stdin (JSON)
Environment variables set in the process environment
Standard Attune env vars (ATTUNE_ACTION, ATTUNE_EXEC_ID, etc.)

API Request Example

When you click Execute with environment variables, the UI sends:

POST /api/v1/executions/execute
{
  "action_ref": "core.http_request",
  "parameters": {
    "url": "https://api.example.com",
    "method": "GET"
  },
  "env_vars": {
    "DEBUG": "true",
    "LOG_LEVEL": "debug",
    "TIMEOUT_SECONDS": "30"
  }
}

Action Script Usage

In your action script, environment variables are available as standard environment variables:

#!/bin/bash

# Check custom env vars
if [ "$DEBUG" = "true" ]; then
    set -x  # Enable debug mode
    echo "Debug mode enabled" >&2
fi

# Use custom log level
LOG_LEVEL="${LOG_LEVEL:-info}"
echo "Log level: $LOG_LEVEL" >&2

# Apply custom timeout
TIMEOUT="${TIMEOUT_SECONDS:-60}"
echo "Using timeout: ${TIMEOUT}s" >&2

# Read action parameters from stdin
INPUT=$(cat)
URL=$(echo "$INPUT" | jq -r '.url')

# Execute action logic
curl --max-time "$TIMEOUT" "$URL"

Tips & Best Practices

1. Use Uppercase for Keys

Follow Unix convention: DEBUG, LOG_LEVEL, not debug, log_level

2. Provide Defaults in Scripts

DEBUG="${DEBUG:-false}"
LOG_LEVEL="${LOG_LEVEL:-info}"

3. Document Common Env Vars

Add comments in your action YAML:

# Supports environment variables:
# - DEBUG: Enable debug mode (true/false)
# - LOG_LEVEL: Logging verbosity (debug/info/warn/error)
# - TIMEOUT_SECONDS: Request timeout in seconds

4. Don't Duplicate Parameters

If an action has a timeout parameter, use that instead of TIMEOUT_SECONDS env var.

5. Test Locally First

Test with env vars set locally before using in production:

DEBUG=true LOG_LEVEL=debug ./my_action.sh < params.json

QUICKREF: Execution Environment - All environment variables
QUICKREF: Action Parameters - Parameter delivery via stdin
Action Development Guide - Writing actions

9.1 KiB Raw Permalink Blame History

Execute Action Modal: Environment Variables