Environment Variables

Environment variables allow you to securely pass secrets and configuration to your build steps. This recipe shows how to configure environment variables at both the pipeline and step levels.

Complete YAML

name: Deploy Build
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Build
    run: fastlane build
    env:
      APP_ENV: production
      API_TOKEN: $API_TOKEN

YAML-Level Environment Variables

You can define variables at the pipeline level, available to all steps:

name: Environment Variables Example
platform: ios
environment:
  xcode: "16.4"
  variables:
    DEPLOYMENT_TARGET: "13.0"
    MINIMUM_IOS_VERSION: "13.0"
    BUILD_CONFIGURATION: "Release"

triggers:
  - push

steps:
  - name: Build
    run: |
      xcodebuild \
      -workspace MyApp.xcworkspace \
      -scheme MyApp \
      -configuration $BUILD_CONFIGURATION \
      build

YAML Interpolation

In RunnerHub YAML, only ${{ matrix.KEY }} is supported for YAML-level interpolation. For all other variables (dashboard env vars, secrets, pipeline-level vars under environment.variables:), use shell $VARIABLE_NAME syntax directly in your run: commands, and they’ll be expanded by the shell at runtime. The $RH_* variables (like $RH_EXPORT_OPTIONS_PLIST) are injected by the agent at execution time.

Step-Level Environment Variables

Variables defined in a step are only available to that step:

name: Step-Level Variables
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Build with debug settings
    run: fastlane build
    env:
      DEBUG: "1"
      VERBOSE: "true"

  - name: Build with production settings
    run: fastlane build
    env:
      DEBUG: "0"
      DEPLOYMENT_TARGET: "13.0"

Using Environment Variables from Dashboard

Environment variables are configured in the RunnerHub dashboard at workspace or app scope. Reference them in your YAML using $VARIABLE_NAME:

name: Secure Deploy
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Build and deploy
    run: fastlane beta
    env:
      APP_STORE_CONNECT_API_KEY: $APP_STORE_CONNECT_API_KEY
      FASTLANE_PASSWORD: $FASTLANE_PASSWORD
      GITHUB_TOKEN: $GITHUB_TOKEN

Key Points

Tip

Environment variables configured in the RunnerHub dashboard are stored securely and never exposed in logs. Always use environment variables for API keys, passwords, and tokens instead of hardcoding them.

• Dashboard Variables: Created in dashboard (Workspace → Environment tab or App → Environment tab), available as environment variables with $VARIABLE_NAME syntax
• YAML Variables: Literal values defined in the pipeline YAML file
• Variable Scope: Pipeline-level env applies to all steps; step-level env applies only to that step; app-scoped variables override workspace-scoped
• Masking: Environment variable values are automatically masked in build logs and output

Environment Variable Examples

Fastlane with API Keys

name: Deploy to TestFlight
platform: ios
environment:
  xcode: "16.4"
  variables:
    FASTLANE_USER: $APPLE_ID_EMAIL
    FASTLANE_PASSWORD: $APPLE_ID_PASSWORD
    FASTLANE_SESSION: $FASTLANE_SESSION

triggers:
  - push

steps:
  - name: Deploy to TestFlight
    run: fastlane beta
    env:
      APP_STORE_CONNECT_API_KEY: $APP_STORE_CONNECT_API_KEY

CocoaPods with Private Specs

steps:
  - name: Install pods from private repo
    run: pod install
    env:
      GIT_AUTHORIZATION_TOKEN: $GITHUB_TOKEN
      COCOAPODS_USERNAME: $COCOAPODS_USER
      COCOAPODS_PASSWORD: $COCOAPODS_PASSWORD

Xcodebuild with Custom Settings

name: Signed Build
platform: ios
environment:
  xcode: "16.4"
  variables:
    DEVELOPMENT_TEAM: $APPLE_TEAM_ID
    PROVISIONING_PROFILE_SPECIFIER: $PROFILE_NAME
    CODE_SIGN_IDENTITY: "iPhone Developer"

triggers:
  - push

steps:
  - name: Build signed
    run: |
      xcodebuild \
      -workspace MyApp.xcworkspace \
      -scheme MyApp \
      -configuration Release \
      build

Debugging Environment Variables

To inspect what variables are available, use the env command:

steps:
  - name: Print environment
    run: env | grep -E "APP_|FASTLANE_|API_" | sort

Caution

Never commit secrets to your repository. Always use environment variables configured in the RunnerHub dashboard. If a secret is accidentally committed, rotate it immediately.

Best Practices

1. Use dashboard environment variables for all sensitive data
2. Keep secrets out of YAML — use variable references only
3. Document required secrets in your repository README
4. Rotate secrets regularly for security
5. Limit secret access — only expose needed secrets to steps that use them