Runtime environment

Environment variables follow one declared precedence ladder, resolved at plan time and visible in the plan, and the ORUN_ prefix is reserved for orun itself. A platform-wide value therefore cannot be silently shadowed by a step, and orun validate rejects a user variable that claims the reserved prefix.

orun resolves environment variables at plan time and injects them into every job and step at runtime. This page explains how env declarations are merged, what ORUN-prefixed variables are injected automatically, and the full precedence order.

Declaring environment variables

Environment variables can be declared at four levels, giving platform teams and component authors fine-grained control over runtime context.

Intent root-level env

Define global environment variables shared across all environments and components:

# intent.yaml
apiVersion: sourceplane.io/v1
kind: Intent

metadata:
  name: aws-admin

env:
  OWNER: sourceplane
  ORGANIZATION: sourceplane

Intent environment-level env

Define environment variables that apply to all components running in a given environment:

# intent.yaml
environments:
  dev:
    env:
      AWS_REGION: us-east-1
      TF_LOG: WARN
      NAMESPACE_PREFIX: dev-
  production:
    env:
      AWS_REGION: us-west-2
      TF_LOG: ERROR

Component root-level env

Define environment variables that apply to a component across all its subscribed environments:

# component.yaml
spec:
  type: terraform
  env:
    REPO: aws-admin
    SERVICE: github-iam

Component subscription-level env

Override or extend environment variables for a specific component within an environment:

# component.yaml
spec:
  type: terraform
  subscribe:
    environments:
      - name: dev
        env:
          STACK_NAME: api-platform
          TF_VAR_replicas: "1"
      - name: production
        env:
          STACK_NAME: api-platform
          TF_VAR_replicas: "3"

Merge precedence

Environment variables are merged once during plan compilation. When the same key appears at multiple levels, higher-precedence values win:

Priority	Source	Example
1 (lowest)	Intent root env	env.OWNER
2	Intent environment env	environments.dev.env.AWS_REGION
3	Component root env	spec.env.REPO
4	Component subscription env	subscribe.environments[name=dev].env.STACK_NAME
5	ORUN runtime variables	ORUN_ENVIRONMENT, ORUN_COMPONENT
6	Step-level env	Step definition in composition
7 (highest)	OS environment	Inherited from parent process

Example resolution

Given:

# intent.yaml
env:
  OWNER: sourceplane
  ORGANIZATION: sourceplane

environments:
  dev:
    env:
      AWS_REGION: us-east-1
      NAMESPACE_PREFIX: dev-

# component.yaml (api-platform)
env:
  REPO: aws-admin

subscribe:
  environments:
    - name: dev
      env:
        STACK_NAME: api-platform

The resolved runtime environment for the api-platform component in dev is:

OWNER=sourceplane              # from intent root
ORGANIZATION=sourceplane       # from intent root
AWS_REGION=us-east-1           # from intent environment
NAMESPACE_PREFIX=dev-          # from intent environment
REPO=aws-admin                 # from component root
STACK_NAME=api-platform        # from component subscription
ORUN_ENVIRONMENT=dev           # injected by runtime
ORUN_COMPONENT=api-platform    # injected by runtime
ORUN_PLAN_ID=abc1234           # injected by runtime
ORUN_JOB_ID=api-platform.dev.deploy

Reserved ORUN_ prefix

User-defined environment variables must not start with ORUN_. This prefix is reserved for runtime-injected system variables. If a user-declared env key uses the ORUN_ prefix, plan generation will fail with a validation error.

This applies to all four declaration levels (intent root, environment, component root, and subscription).

ORUN-prefixed runtime variables

These are injected automatically by the runner and cannot be overridden by user-declared env:

Variable	Description
ORUN_CONTEXT	Runtime context label (local, container, ci)
ORUN_RUNNER	Resolved runner name
ORUN_EXEC_ID	Execution ID for the current run
ORUN_PLAN_ID	Plan checksum short-hash
ORUN_JOB_ID	Current job ID
ORUN_JOB_UID	Stable job UID
ORUN_JOB_RUN_ID	Cross-job traceability identifier
ORUN_ENVIRONMENT	Environment name for the current job
ORUN_COMPONENT	Component name for the current job
ORUN_ENV	Path to env file for persisting variables across steps (alias for GITHUB_ENV)

Template interpolation

Env values support the same template variables as component parameters:

environments:
  staging:
    env:
      NAMESPACE: "{{ .environment }}-{{ .component }}"
      DOMAIN_PREFIX: "{{ .group }}"

Available variables: {{ .environment }}, {{ .component }}, {{ .group }}.

Relationship to parameters

env and parameters serve different purposes:

• parameters (spec.parameters in component.yaml) are configuration values used for template rendering in composition steps. They appear in PlanJob.parameters and are accessed via {{ .parameters.fieldName }} in templates.
• env is a flat map[string]string of shell environment variables injected at runtime. They appear in PlanJob.env and are accessible via {{ .env.VAR_NAME }} in templates.

Plan output

The resolved environment variables appear in the plan under each job's env field. Keys are sorted alphabetically for deterministic output:

{
  "jobs": [
    {
      "id": "api-platform.dev.deploy",
      "component": "api-platform",
      "environment": "dev",
      "env": {
        "AWS_REGION": "us-east-1",
        "NAMESPACE_PREFIX": "dev-",
        "ORGANIZATION": "sourceplane",
        "OWNER": "sourceplane",
        "REPO": "aws-admin",
        "STACK_NAME": "api-platform"
      },
      "parameters": {
        "stackName": "api-platform",
        "terraformDir": ".",
        "terraformVersion": "1.9.8"
      }
    }
  ]
}

Dynamic environment propagation with ORUN_ENV

Steps can persist environment variables for subsequent steps by appending KEY=VALUE pairs to the file at $ORUN_ENV:

echo "DEPLOY_SHA=$(git rev-parse HEAD)" >> "$ORUN_ENV"

This uses the same file-based mechanism as GitHub Actions' $GITHUB_ENV. Both variables point to the same file — writing to either one has the same effect. Using ORUN_ENV is preferred in compositions because it is portable and does not depend on GitHub-specific naming.

Multi-line values use heredoc syntax:

cat >> "$ORUN_ENV" <<'HEREDOC'
MULTI_LINE_VAR<<EOF
line one
line two
EOF
HEREDOC

Variables written to $ORUN_ENV are available to all subsequent steps in the same job but not to other jobs.

Value preservation guarantees

ORUN_ENV / GITHUB_ENV preserves environment variable values exactly as written. Characters like +, /, =, :, ;, and other special characters common in base64-encoded tokens (e.g. AWS session tokens) are never transformed, escaped, or split. This ensures that credentials written by GitHub Actions like aws-actions/configure-aws-credentials are propagated intact to subsequent steps such as terraform init.