attune-system/attune

Fork 0

Files

David Culbreth a74e13fa0b working out the worker/execution interface

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

14 KiB

Raw Blame History

Quick Reference: Execution Environment Variables

Last Updated: 2026-02-07
Status: Standard for all action executions

Overview

The worker automatically provides standard environment variables to all action executions. These variables provide context about the execution and enable actions to interact with the Attune API.

Standard Environment Variables

All actions receive the following environment variables:

Variable	Type	Description	Always Present
`ATTUNE_ACTION`	string	Action ref (e.g., `core.http_request`)	✅ Yes
`ATTUNE_EXEC_ID`	integer	Execution database ID	✅ Yes
`ATTUNE_API_TOKEN`	string	Execution-scoped API token	✅ Yes
`ATTUNE_RULE`	string	Rule ref that triggered execution	❌ Only if from rule
`ATTUNE_TRIGGER`	string	Trigger ref that caused enforcement	❌ Only if from trigger

ATTUNE_ACTION

Purpose: Identifies which action is being executed.

Format: {pack_ref}.{action_name}

Examples:

ATTUNE_ACTION="core.http_request"
ATTUNE_ACTION="core.echo"
ATTUNE_ACTION="slack.post_message"
ATTUNE_ACTION="aws.ec2.describe_instances"

Use Cases:

Logging and telemetry
Conditional behavior based on action
Error reporting with context

Example Usage:

#!/bin/bash
echo "Executing action: $ATTUNE_ACTION" >&2
# Perform action logic...
echo "Action $ATTUNE_ACTION completed successfully" >&2

ATTUNE_EXEC_ID

Purpose: Unique identifier for this execution instance.

Format: Integer (database ID)

Examples:

ATTUNE_EXEC_ID="12345"
ATTUNE_EXEC_ID="67890"

Use Cases:

Correlate logs with execution records
Report progress back to API
Create child executions (workflows)
Generate unique temporary file names

Example Usage:

#!/bin/bash
# Create execution-specific temp file
TEMP_FILE="/tmp/attune-exec-${ATTUNE_EXEC_ID}.tmp"

# Log with execution context
echo "[Execution $ATTUNE_EXEC_ID] Processing request..." >&2

# Report progress to API
curl -s -X PATCH \
    -H "Authorization: Bearer $ATTUNE_API_TOKEN" \
    "$ATTUNE_API_URL/api/v1/executions/$ATTUNE_EXEC_ID" \
    -d '{"status": "running"}'

ATTUNE_API_TOKEN

Purpose: Execution-scoped bearer token for authenticating with Attune API.

Format: JWT token string

Security:

✅ Scoped to this execution
✅ Limited lifetime (expires with execution)
✅ Read-only access to execution data by default
✅ Can create child executions
❌ Cannot access other executions
❌ Cannot modify system configuration

Use Cases:

Query execution status
Retrieve execution parameters
Create child executions (sub-workflows)
Report progress or intermediate results
Access secrets via API

Example Usage:

#!/bin/bash
# Query execution details
curl -s -H "Authorization: Bearer $ATTUNE_API_TOKEN" \
    "$ATTUNE_API_URL/api/v1/executions/$ATTUNE_EXEC_ID"

# Create child execution
curl -s -X POST \
    -H "Authorization: Bearer $ATTUNE_API_TOKEN" \
    -H "Content-Type: application/json" \
    "$ATTUNE_API_URL/api/v1/executions" \
    -d '{
        "action_ref": "core.echo",
        "parameters": {"message": "Child execution"},
        "parent_id": '"$ATTUNE_EXEC_ID"'
    }'

# Retrieve secret from key vault
SECRET=$(curl -s \
    -H "Authorization: Bearer $ATTUNE_API_TOKEN" \
    "$ATTUNE_API_URL/api/v1/keys/my-secret" | jq -r '.value')

ATTUNE_RULE

Purpose: Identifies the rule that triggered this execution (if applicable).

Format: {pack_ref}.{rule_name}

Present: Only when execution was triggered by a rule enforcement.

Examples:

ATTUNE_RULE="core.timer_to_echo"
ATTUNE_RULE="monitoring.disk_space_alert"
ATTUNE_RULE="ci.deploy_on_push"

Use Cases:

Conditional logic based on triggering rule
Logging rule context
Different behavior for manual vs automated executions

Example Usage:

#!/bin/bash
if [ -n "$ATTUNE_RULE" ]; then
    echo "Triggered by rule: $ATTUNE_RULE" >&2
    # Rule-specific logic
else
    echo "Manual execution (no rule)" >&2
    # Manual execution logic
fi

Custom Environment Variables

Purpose: Optional user-provided environment variables for manual executions.

Set Via: Web UI or API when creating manual executions.

Format: Key-value pairs (string → string mapping)

Use Cases:

Debug flags (e.g., DEBUG=true)
Log levels (e.g., LOG_LEVEL=debug)
Runtime configuration (e.g., MAX_RETRIES=5)
Feature flags (e.g., ENABLE_EXPERIMENTAL=true)

Important Distinctions:

❌ NOT for sensitive data - Use action parameters marked as secret: true instead
❌ NOT for action parameters - Use stdin JSON for actual action inputs
✅ FOR runtime configuration - Debug settings, feature flags, etc.
✅ FOR execution context - Additional metadata about how to run

Example via API:

curl -X POST http://localhost:8080/api/v1/executions/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action_ref": "core.http_request",
    "parameters": {
      "url": "https://api.example.com",
      "method": "GET"
    },
    "env_vars": {
      "DEBUG": "true",
      "LOG_LEVEL": "debug",
      "TIMEOUT_SECONDS": "30"
    }
  }'

Example via Web UI: In the Execute Action modal, the "Environment Variables" section allows adding multiple key-value pairs for custom environment variables.

Action Script Usage:

#!/bin/bash
# Custom env vars are available as standard environment variables
if [ "$DEBUG" = "true" ]; then
    set -x  # Enable bash debug mode
    echo "Debug mode enabled" >&2
fi

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

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

# ... action logic with custom configuration ...

Security Note: Custom environment variables are stored in the database and logged. Never use them for:

Passwords or API keys (use secrets API + secret: true parameters)
Personally identifiable information (PII)
Any sensitive data

For sensitive data, use action parameters marked with secret: true in the action YAML.

ATTUNE_TRIGGER

Purpose: Identifies the trigger type that caused the rule enforcement (if applicable).

Format: {pack_ref}.{trigger_name}

Present: Only when execution was triggered by an event/trigger.

Examples:

ATTUNE_TRIGGER="core.intervaltimer"
ATTUNE_TRIGGER="core.webhook"
ATTUNE_TRIGGER="github.push"
ATTUNE_TRIGGER="aws.ec2.instance_state_change"

Use Cases:

Different behavior based on trigger type
Event-specific processing
Logging event context

Example Usage:

#!/bin/bash
case "$ATTUNE_TRIGGER" in
    core.intervaltimer)
        echo "Scheduled execution" >&2
        ;;
    core.webhook)
        echo "Webhook-triggered execution" >&2
        ;;
    *)
        echo "Unknown or manual trigger" >&2
        ;;
esac

Environment Variable Precedence

Environment variables are set in the following order (later overrides earlier):

System defaults - PATH, HOME, USER, etc.
Standard Attune variables - ATTUNE_ACTION, ATTUNE_EXEC_ID, etc. (always present)
Custom environment variables - User-provided via API/UI (optional)

Note: Custom env vars cannot override standard Attune variables or critical system variables.

Additional Standard Variables

The worker also provides standard system environment variables:

Variable	Description
`PATH`	Standard PATH with Attune utilities
`HOME`	Home directory for execution
`USER`	Execution user (typically `attune`)
`PWD`	Working directory
`TMPDIR`	Temporary directory path

API Base URL

The API URL is typically available via configuration or a standard environment variable:

Variable	Description	Example
`ATTUNE_API_URL`	Base URL for Attune API	`http://localhost:8080`

Usage Patterns

Pattern 1: Logging with Context

#!/bin/bash
log() {
    local level="$1"
    shift
    echo "[${level}] [Action: $ATTUNE_ACTION] [Exec: $ATTUNE_EXEC_ID] $*" >&2
}

log INFO "Starting execution"
log DEBUG "Parameters: $INPUT"
# ... action logic ...
log INFO "Execution completed"

Pattern 2: API Interaction

#!/bin/bash
# Function to call Attune API
attune_api() {
    local method="$1"
    local endpoint="$2"
    shift 2
    
    curl -s -X "$method" \
        -H "Authorization: Bearer $ATTUNE_API_TOKEN" \
        -H "Content-Type: application/json" \
        "$ATTUNE_API_URL/api/v1/$endpoint" \
        "$@"
}

# Query execution
EXEC_INFO=$(attune_api GET "executions/$ATTUNE_EXEC_ID")

# Create child execution
CHILD_EXEC=$(attune_api POST "executions" -d '{
    "action_ref": "core.echo",
    "parameters": {"message": "Child"},
    "parent_id": '"$ATTUNE_EXEC_ID"'
}')

Pattern 3: Conditional Behavior

#!/bin/bash
# Behave differently for manual vs automated executions
if [ -n "$ATTUNE_RULE" ]; then
    # Automated execution (from rule)
    echo "Automated execution via rule: $ATTUNE_RULE" >&2
    NOTIFICATION_CHANNEL="automated"
else
    # Manual execution
    echo "Manual execution" >&2
    NOTIFICATION_CHANNEL="manual"
fi

# Different behavior based on trigger
if [ "$ATTUNE_TRIGGER" = "core.webhook" ]; then
    echo "Processing webhook payload..." >&2
elif [ "$ATTUNE_TRIGGER" = "core.intervaltimer" ]; then
    echo "Processing scheduled task..." >&2
fi

Pattern 4: Temporary Files

#!/bin/bash
# Create execution-specific temp files
WORK_DIR="/tmp/attune-exec-${ATTUNE_EXEC_ID}"
mkdir -p "$WORK_DIR"

# Use temp directory
echo "Working in: $WORK_DIR" >&2
cp input.json "$WORK_DIR/input.json"

# Process files
process_data "$WORK_DIR/input.json" > "$WORK_DIR/output.json"

# Output result
cat "$WORK_DIR/output.json"

# Cleanup
rm -rf "$WORK_DIR"

Pattern 5: Progress Reporting

#!/bin/bash
report_progress() {
    local message="$1"
    local percent="$2"
    
    echo "$message" >&2
    
    # Optional: Report to API (if endpoint exists)
    curl -s -X PATCH \
        -H "Authorization: Bearer $ATTUNE_API_TOKEN" \
        -H "Content-Type: application/json" \
        "$ATTUNE_API_URL/api/v1/executions/$ATTUNE_EXEC_ID" \
        -d "{\"progress\": $percent, \"message\": \"$message\"}" \
        > /dev/null 2>&1 || true
}

report_progress "Starting download" 0
# ... download ...
report_progress "Processing data" 50
# ... process ...
report_progress "Uploading results" 90
# ... upload ...
report_progress "Completed" 100

Security Considerations

Token Scope

The ATTUNE_API_TOKEN is scoped to the execution:

✅ Can read own execution data
✅ Can create child executions
✅ Can access secrets owned by execution identity
❌ Cannot read other executions
❌ Cannot modify system configuration
❌ Cannot delete resources

Token Lifetime

Token is valid for the duration of the execution
Token expires when execution completes
Token is invalidated if execution is cancelled
Do not cache or persist the token

Best Practices

Never log the API token:

# ❌ BAD
echo "Token: $ATTUNE_API_TOKEN" >&2

# ✅ GOOD
echo "Using API token for authentication" >&2

Validate token presence:

if [ -z "$ATTUNE_API_TOKEN" ]; then
    echo "ERROR: ATTUNE_API_TOKEN not set" >&2
    exit 1
fi

Use HTTPS in production:

# Check API URL uses HTTPS
if [[ ! "$ATTUNE_API_URL" =~ ^https:// ]] && [ "$ENVIRONMENT" = "production" ]; then
    echo "WARNING: API URL should use HTTPS in production" >&2
fi

Distinction: Environment Variables vs Parameters

Standard Environment Variables

Purpose: Execution context and metadata
Source: System-provided automatically
Examples: ATTUNE_ACTION, ATTUNE_EXEC_ID, ATTUNE_API_TOKEN
Access: Standard environment variable access
Used for: Logging, API access, execution identity

Custom Environment Variables

Purpose: Runtime configuration and debug settings
Source: User-provided via API/UI (optional)
Examples: DEBUG=true, LOG_LEVEL=debug, MAX_RETRIES=5
Access: Standard environment variable access
Used for: Debug flags, feature toggles, non-sensitive runtime config

Action Parameters

Purpose: Action-specific input data
Source: User-provided via API/UI (required/optional per action)
Examples: {"url": "...", "method": "POST", "data": {...}}
Access: Read from stdin as JSON
Used for: Action-specific configuration and data

Example:

#!/bin/bash
# Standard environment variables - system context (always present)
echo "Action: $ATTUNE_ACTION" >&2
echo "Execution ID: $ATTUNE_EXEC_ID" >&2

# Custom environment variables - runtime config (optional)
DEBUG="${DEBUG:-false}"
LOG_LEVEL="${LOG_LEVEL:-info}"
if [ "$DEBUG" = "true" ]; then
    set -x
fi

# Action parameters - user data (from stdin)
INPUT=$(cat)
URL=$(echo "$INPUT" | jq -r '.url')
METHOD=$(echo "$INPUT" | jq -r '.method // "GET"')

# Use all three together
curl -s -X "$METHOD" \
    -H "X-Attune-Action: $ATTUNE_ACTION" \
    -H "X-Attune-Exec-Id: $ATTUNE_EXEC_ID" \
    -H "X-Debug-Mode: $DEBUG" \
    "$URL"

Testing Locally

When testing actions locally, you can simulate these environment variables:

#!/bin/bash
# test-action.sh - Local testing script

export ATTUNE_ACTION="core.http_request"
export ATTUNE_EXEC_ID="99999"
export ATTUNE_API_TOKEN="test-token-local"
export ATTUNE_RULE="test.rule"
export ATTUNE_TRIGGER="test.trigger"
export ATTUNE_API_URL="http://localhost:8080"

# Simulate custom env vars
export DEBUG="true"
export LOG_LEVEL="debug"

echo '{"url": "https://httpbin.org/get"}' | ./http_request.sh

References

Action Parameter Handling - Stdin-based parameter delivery
Action Output Format - Output format and schemas
Worker Service Architecture - How workers execute actions
Core Pack Actions - Reference implementations

14 KiB Raw Blame History

Quick Reference: Execution Environment Variables

Overview

Standard Environment Variables

ATTUNE_ACTION

ATTUNE_EXEC_ID

ATTUNE_API_TOKEN

ATTUNE_RULE

Custom Environment Variables

ATTUNE_TRIGGER

Environment Variable Precedence

Additional Standard Variables

API Base URL

Usage Patterns

Pattern 1: Logging with Context

Pattern 2: API Interaction

Pattern 3: Conditional Behavior

Pattern 4: Temporary Files

Pattern 5: Progress Reporting

Security Considerations

Token Scope

Token Lifetime

Best Practices

Distinction: Environment Variables vs Parameters

Standard Environment Variables

Custom Environment Variables

Action Parameters

Testing Locally

References

See Also

14 KiB

Raw Blame History