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_REPOSITORY | Repository full name (owner/repo) | myorg/myapp | | 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_TARGET_PLATFORM | Native target declared by the pipeline's target_platform field (Flutter only). Empty string when the field is not declared — the variable is always present, so you never need an "is it defined" check. | macos, ios, android, web, or "" when not declared | | 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 | /Users/admin/work/job_abc123/workspace | | RUNNERHUB_ARTIFACTS_DIR | Directory for job artifacts | /Users/admin/work/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). Automatically passed to flutter build ipa via --export-options-plist flag when present. | /Users/admin/work/job_abc123/ExportOptions.plist | | HOME | Home directory | /Users/admin | | TMPDIR | Temporary directory (isolated to job) | /Users/admin/work/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. Automatically passed to flutter build ipa via --export-options-plist flag — you don't need to add the flag yourself. | Whenever signing certificates are installed for the job — including Developer ID, which has no provisioning profile (the provisioningProfiles entry is simply omitted). Not set when your repository already contains an ExportOptions.plist at the workspace root: RunnerHub never overwrites your file, so reference it by its own path instead. |

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 and checked out to RUNNERHUB_CLONE_DIR automatically before your steps run. Use this variable to reference the cloned directory:

name: Inspect Checkout
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Show current commit
    run: |
      cd $RUNNERHUB_CLONE_DIR
      git log -1 --oneline
      git status

Local git commands work normally — the full history and working tree are on disk.

Git commands that contact the remote are not authenticated

The clone credential is removed from .git/config before your first step runs, so the workspace is not authenticated against the remote during your build. On a private repository these now fail:

• git submodule update --init with relative submodule URLs
• git lfs pull / git lfs fetch
• git fetch / git pull for extra branches or tags

Local operations (git log, git status, git diff, git rev-parse) are unaffected, and public repositories are unaffected.

RunnerHub has no built-in submodule or LFS authentication. To reach a private remote you must supply your own token as a secret environment variable — see Git authentication failure in a step.

The RUNNERHUB_REPO_URL contains the repository URL but does not include embedded authentication tokens. Authentication is handled internally by the agent during cloning, and the credential is discarded before your steps execute.

Security Notes

• Agent-re-injected system variables (HOME, CI, RUNNERHUB, RUNNERHUB_JOB_ID, RUNNERHUB_REPOSITORY, RUNNERHUB_BRANCH, RUNNERHUB_COMMIT, DEVELOPER_DIR) are locked and cannot be overridden. Backend-set variables (RUNNERHUB_PLATFORM, RUNNERHUB_TARGET_PLATFORM, RUNNERHUB_TRIGGER, RUNNERHUB_PR_NUMBER, RUNNERHUB_WORKSPACE_ID, RUNNERHUB_APP_ID, RUNNERHUB_REPO_URL, RUNNERHUB_CLONE_DIR, RUNNERHUB_ARTIFACTS_DIR) act as defaults and can be overridden by step-level env.
• 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, and the credential is removed from .git/config before your steps run — so a broad artifacts: glob cannot zip it into the artifact store, and git remote -v cannot print it into the build log
• If you need your own git credential for submodules or LFS, store it as a secret environment variable and write it to $HOME/.netrc — never back into .git/config inside the workspace

Next Steps

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