System Variables

RunnerHub automatically injects system variables into every pipeline execution. These variables provide information about the job, repository, trigger event, and execution environment.

Available System Variables

Variable	Description	Example
CI	Always set to true (standard CI indicator)	true
RUNNERHUB	Always set to true (RunnerHub indicator)	true
RUNNERHUB_JOB_ID	Unique identifier for this job	job_abc123def456
RUNNERHUB_WORKSPACE_ID	ID of the workspace this job belongs to	ws_xyz789
RUNNERHUB_APP_ID	ID of the app being built	app_def456
RUNNERHUB_BRANCH	Branch name where the event occurred	main, feature/auth
RUNNERHUB_COMMIT	Full commit hash	a1b2c3d4e5f6g7h8i9j0
RUNNERHUB_REPO_URL	Repository clone URL	https://github.com/user/repo.git
RUNNERHUB_PLATFORM	Platform for this build	ios, macos, android, flutter, react-native
RUNNERHUB_TRIGGER	What triggered this job	push, pull_request, manual, schedule
RUNNERHUB_PR_NUMBER	Pull request number (PR triggers only)	42
RUNNERHUB_CLONE_DIR	Directory where repo is cloned	/tmp/runnerhub/job_abc123/clone
RUNNERHUB_ARTIFACTS_DIR	Directory for job artifacts	/tmp/runnerhub/job_abc123/artifacts
RH_PROVISIONING_PROFILE_NAME	Provisioning profile display name (auto-sign only)	RunnerHub com.example.myapp appstore
RH_EXPORT_OPTIONS_PLIST	Absolute path to auto-generated ExportOptions.plist (auto-sign only)	/tmp/runnerhub/job_abc123/ExportOptions.plist
HOME	Home directory (set to job directory)	/tmp/runnerhub/job_abc123
TMPDIR	Temporary directory (isolated to job)	/tmp/runnerhub/job_abc123/tmp

Using System Variables

Reference system variables in your pipeline steps like any other environment variable:

name: Job Info
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Print Job Info
    run: |
      echo "Job ID: $RUNNERHUB_JOB_ID"
      echo "Branch: $RUNNERHUB_BRANCH"
      echo "Commit: $RUNNERHUB_COMMIT"
      echo "Trigger: $RUNNERHUB_TRIGGER"

Common Use Cases

Build Versioning

Use commit hash and branch to create unique build versions:

name: Versioning
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Set Build Version
    run: |
      VERSION="1.0.0-${RUNNERHUB_BRANCH#*/}-${RUNNERHUB_COMMIT:0:8}"
      echo "Building version: $VERSION"
      xcodebuild -version

Conditional Behavior Based on Trigger

Execute different steps depending on how the pipeline was triggered:

name: Conditional Deploy
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Conditional Upload
    run: |
      if [ "$RUNNERHUB_TRIGGER" = "push" ] && [ "$RUNNERHUB_BRANCH" = "main" ]; then
        echo "Running release upload..."
        fastlane release
      else
        echo "Running dev upload..."
        fastlane dev
      fi

Pull Request-Specific Actions

Only run certain steps on PR events:

name: PR Actions
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: PR Comment
    run: |
      if [ -n "$RUNNERHUB_PR_NUMBER" ]; then
        echo "This is PR #$RUNNERHUB_PR_NUMBER"
        # Post comment, upload to review builds, etc.
      fi

Artifact Organization by Branch

Organize artifacts in different directories based on the branch:

name: Organize Artifacts
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Organize Artifacts
    run: |
      mkdir -p $RUNNERHUB_ARTIFACTS_DIR/$RUNNERHUB_BRANCH
      cp build/app.ipa $RUNNERHUB_ARTIFACTS_DIR/$RUNNERHUB_BRANCH/

Job Logging and Tracking

Include job info in build logs for tracking and debugging:

name: Log Build Info
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Log Build Info
    run: |
      echo "=== Build Information ==="
      echo "Job ID: $RUNNERHUB_JOB_ID"
      echo "Workspace: $RUNNERHUB_WORKSPACE_ID"
      echo "App: $RUNNERHUB_APP_ID"
      echo "Branch: $RUNNERHUB_BRANCH"
      echo "Commit: $RUNNERHUB_COMMIT"
      echo "Repository: $RUNNERHUB_REPO_URL"
      echo "Trigger: $RUNNERHUB_TRIGGER"
      echo "========================"

Sending Build Notifications

Include job context in notifications to external services:

name: Slack Notification
platform: ios

environment:
  xcode: "16.4"
  variables:
    SLACK_WEBHOOK: $SLACK_WEBHOOK

steps:
  - name: Notify on Success
    run: |
      curl -X POST $SLACK_WEBHOOK \
        -H 'Content-Type: application/json' \
        -d "{
          \"text\": \"Build $RUNNERHUB_JOB_ID succeeded\",
          \"blocks\": [{
            \"type\": \"section\",
            \"text\": {
              \"type\": \"mrkdwn\",
              \"text\": \"Branch: *$RUNNERHUB_BRANCH*\nCommit: \`$RUNNERHUB_COMMIT\`\"
            }
          }]
        }"

Job Directory Structure

RunnerHub provides isolated directories for each job:

Variable	Purpose
RUNNERHUB_CLONE_DIR	Directory where your repository is cloned
RUNNERHUB_ARTIFACTS_DIR	Directory for storing job outputs (build artifacts, logs, etc.)
TMPDIR	Temporary directory isolated to this job
HOME	Home directory for the job environment

Steps execute from RUNNERHUB_CLONE_DIR by default. Use working_directory in your YAML to change this.

Auto-Signing Variables

When automatic code signing is enabled for your app, RunnerHub additionally injects variables related to signing:

Variable	Description	When Available
RH_PROVISIONING_PROFILE_NAME	The display name of the provisioning profile (e.g., RunnerHub com.example.myapp appstore)	When auto-sign creates or fetches a provisioning profile
RH_EXPORT_OPTIONS_PLIST	Absolute path to auto-generated ExportOptions.plist file	When auto-sign has both profile name and bundle identifier, and no existing ExportOptions.plist in the repository root

These variables are useful when building IPA archives for export:

name: Archive and Export
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Archive
    run: |
      xcodebuild archive \
        -workspace MyApp.xcworkspace \
        -scheme MyApp \
        -configuration Release \
        -archivePath $PWD/build/MyApp.xcarchive \
        -destination 'generic/platform=iOS'

  - name: Export IPA
    run: |
      xcodebuild -exportArchive \
        -archivePath $PWD/build/MyApp.xcarchive \
        -exportPath $PWD/build \
        -exportOptionsPlist $RH_EXPORT_OPTIONS_PLIST

See Code Signing Overview for more information about auto-signing.

Trigger Variable Details

RUNNERHUB_TRIGGER Values

Value	When Set
push	A commit was pushed to a branch (no open PR)
pull_request	A PR was opened, reopened, or updated
manual	Job was triggered manually via the dashboard or API
schedule	Job was triggered by a scheduled timer

RUNNERHUB_PR_NUMBER Details

The RUNNERHUB_PR_NUMBER variable is:

• Set when RUNNERHUB_TRIGGER is pull_request
• Not set for push, manual, or schedule triggers
• The numeric PR identifier (e.g., 42)

Check for its presence before using it:

name: PR Check
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: PR-Only Step
    run: |
      if [ -z "$RUNNERHUB_PR_NUMBER" ]; then
        echo "Not a PR, skipping PR-specific actions"
        exit 0
      fi
      echo "This is PR #$RUNNERHUB_PR_NUMBER"

Repository Access

Your repository is cloned to RUNNERHUB_CLONE_DIR automatically before your steps run. Use this variable to reference the cloned directory. The git workspace is already authenticated, so you can run git commands directly:

name: Clone Submodules
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Clone Submodules
    run: |
      cd $RUNNERHUB_CLONE_DIR
      git submodule update --init --recursive

The RUNNERHUB_REPO_URL contains the repository URL but does not include embedded authentication tokens. Authentication is handled internally by the agent during cloning.

Security Notes

• System variables are injected automatically and cannot be overridden at the YAML or app level
• Secrets referenced in your steps are masked in logs regardless of whether they’re stored in system variables
• Repository authentication is handled internally by the agent; do not attempt to embed credentials in git commands

Next Steps

• Learn how to configure Environment Variables for your build
• Set up Triggers to control pipeline execution
• Configure Artifacts to collect build outputs