Environment Variables

RunnerHub supports environment variables at multiple levels with clear precedence rules. Variables can be defined in your YAML configuration, the dashboard (at workspace or app scope), or they’re automatically injected as system variables.

Variable Precedence

Environment variables are resolved in this order (highest to lowest priority):

1. Step-level env — Variables in the step’s env: block (highest priority)
2. YAML environment — Pipeline-level variables in the environment: block
3. App-level variables — Environment variables configured in the dashboard (App → Environment tab)
4. Workspace-level variables — Environment variables configured at workspace level (Workspace → Environment tab)
5. System variables — Auto-injected by RunnerHub (see System Variables)
6. Host environment — Variables inherited from the host machine (lowest priority)

If a variable is defined at multiple levels, the highest-priority definition wins.

YAML-Level Variables

Define variables available to all steps using the environment block:

name: My Pipeline
platform: ios

environment:
  xcode: "16.4"
  variables:
    NODE_ENV: production
    API_URL: https://api.example.com
    LC_ALL: en_US.UTF-8

steps:
  - name: Build
    run: echo "API is at $API_URL"

All variables in the environment: block are available in every step.

Step-Level Variables

Define variables specific to a single step using the env block:

steps:
  - name: Build Release
    run: fastlane build
    env:
      BUILD_CONFIG: Release
      OPTIMIZATION_LEVEL: -Ofast

  - name: Build Debug
    run: fastlane build
    env:
      BUILD_CONFIG: Debug
      OPTIMIZATION_LEVEL: -O0

Step-level variables override YAML-level variables of the same name.

App-Level Variables

For sensitive data like API keys, tokens, and passwords, configure environment variables in the dashboard:

1. Open your app in the RunnerHub dashboard
2. Navigate to App → Environment
3. Add a new variable with a key and value
4. Reference it in your YAML using $KEY_NAME

Example:

Dashboard configuration:

• Key: FASTLANE_USER
• Value: your-email@example.com

YAML usage:

name: Deploy
platform: ios

environment:
  xcode: "16.4"
  variables:
    FASTLANE_USER: $FASTLANE_USER
    FASTLANE_PASSWORD: $FASTLANE_PASSWORD

steps:
  - name: Upload to TestFlight
    run: fastlane beta

App-level environment variables are encrypted at rest and masked in logs automatically. Variable names must match the pattern ^[A-Z0-9_]+$ (uppercase letters, digits, and underscores only).

Workspace-Level Variables

Set organization-wide variables in your workspace settings:

1. Navigate to Workspace → Environment
2. Add variables that apply to all apps in the workspace
3. Reference them in any app’s pipeline YAML

Workspace-level environment variables are useful for:

• Shared build configurations
• Common API endpoints
• Organization-wide credentials

Variable Masking

Environment variables configured in the dashboard are automatically masked in pipeline logs. If a variable contains my-secret-token, any occurrence in the logs will be replaced with ****:

Log output:

Uploading build with token ****

The actual variable value is never exposed in logs, even if your script prints it directly.

Multi-Line Variables

Use YAML’s multi-line syntax for complex values:

name: Build with Settings
platform: ios

environment:
  xcode: "16.4"
  variables:
    BUILD_SETTINGS: |
      CODE_SIGN_IDENTITY=iPhone Distribution
      CODE_SIGNING_REQUIRED=YES
      PROVISIONING_PROFILE_SPECIFIER=My Profile

steps:
  - name: Build
    run: xcodebuild build-for-testing $BUILD_SETTINGS

Special Characters

Variables can contain special characters. Strings with spaces or special chars should be quoted:

name: Pipeline
platform: ios

environment:
  xcode: "16.4"
  variables:
    SIMPLE_VAR: production
    VAR_WITH_SPACES: "my value with spaces"
    URL: "https://example.com/path?query=value"
    SCRIPT_CONTENT: |
      #!/bin/bash
      echo "Multi-line content"

Using Variables in Commands

Access variables in your shell commands using standard shell syntax:

steps:
  - name: Deploy
    run: |
      echo "Building for $BUILD_CONFIG"
      curl -H "Authorization: Bearer $API_TOKEN" \
        -d @build.json \
        $API_URL/upload

Variable Interpolation

YAML will interpolate variables if they’re already defined in the environment. To reference a variable that will be set at runtime, use quotes or use the $VAR syntax:

name: Pipeline
platform: ios

environment:
  xcode: "16.4"
  variables:
    VERSION: "1.0.0"
    VERSION_STRING: "Version $VERSION"  # Interpolated at runtime
    QUOTED_VERSION: '$VERSION'           # Treated as literal string

Best Practices

Use App-Level Environment Variables for Sensitive Data Never hardcode API keys, tokens, or passwords in your YAML. Always use the dashboard’s Environment tab (at app or workspace scope).

# ✓ Good
name: Pipeline
platform: ios
environment:
  xcode: "16.4"
  variables:
    API_TOKEN: $API_TOKEN

# ✗ Bad
name: Pipeline
platform: ios
environment:
  xcode: "16.4"
  variables:
    API_TOKEN: "abc123def456"

Keep YAML Variables for Configuration Use YAML-level variables for non-sensitive configuration that might change between pipelines.

name: Pipeline
platform: ios

environment:
  xcode: "16.4"
  variables:
    NODE_ENV: production
    LOG_LEVEL: info

Override at Step Level When Needed Use step-level variables for step-specific behavior.

steps:
  - name: Build Release
    run: fastlane build
    env:
      BUILD_TYPE: release

  - name: Build Debug
    run: fastlane build
    env:
      BUILD_TYPE: debug

Common Variables

Here are variables commonly used in mobile CI pipelines:

Variable	Purpose
NODE_ENV	Set to production or development
BUILD_CONFIG	Release or Debug for Xcode builds
LC_ALL	Locale setting; often set to en_US.UTF-8
FASTLANE_USER	Fastlane Apple ID (stored as secret)
FASTLANE_PASSWORD	Fastlane password (stored as secret)
MATCH_PASSWORD	Fastlane Match decryption password
GITHUB_TOKEN	GitHub API token for releases
SLACK_WEBHOOK	Slack webhook for notifications

Debugging Variables

To debug which variables are set, use a step to print them:

steps:
  - name: Debug Environment
    run: |
      echo "Build Config: $BUILD_CONFIG"
      echo "API URL: $API_URL"
      echo "Node Env: $NODE_ENV"

Note: Secrets will be masked in the output as ****.

Next Steps

• Learn about System Variables auto-injected by RunnerHub
• Configure Triggers for your pipeline
• Set up Artifacts collection