Triggers

Triggers define which repository events should execute your pipeline. The triggers field is required in every pipeline configuration.

Available Triggers

The YAML triggers: array accepts two values:

Trigger	Event	When It Fires
push	Code pushed to a branch	Any commit pushed, unless the branch has an open PR
pull_request	Pull request opened, updated, or reopened	PR created or commits added to an open PR

In addition, builds can be started from the dashboard without any YAML entry:

Source	How It’s Started
Manual trigger	User clicks Trigger Build in the dashboard (or hits the API) — works on any app regardless of triggers: content
Scheduled trigger	Cron schedule configured in App → Settings → Scheduled Triggers — works regardless of triggers: content

At runtime, the RUNNERHUB_TRIGGER environment variable distinguishes all four sources (push, pull_request, manual, schedule) so your pipeline can branch on the originator. See System Variables.

Basic Configuration

Define triggers as a simple array:

triggers:
  - push
  - pull_request

This pipeline will run on every push and every pull request event.

You can also use the object format to add branch filtering:

triggers:
  - event: push
    branches:
      - main
      - develop
  - event: pull_request
    branches:
      - main

This pipeline runs on push events only to main and develop branches, and on pull_request events targeting main.

Minimal Valid Pipeline

The triggers field is required. A pipeline without triggers is invalid:

name: My Pipeline
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Build
    run: fastlane build

Push Trigger

The push trigger fires whenever code is pushed to any branch:

triggers:
  - push

steps:
  - name: Build
    run: fastlane build

Push Deduplication: If a branch has an open Pull Request, push events to that branch are ignored. RunnerHub prioritizes the pull_request flow to avoid duplicate jobs for the same commit.

Pull Request Trigger

The pull_request trigger fires when:

• A PR is opened
• Commits are added to an open PR (synchronize event)
• A previously closed PR is reopened

triggers:
  - pull_request

steps:
  - name: Run Tests
    run: fastlane test

This is useful for validating code quality on every PR, without also running on every push.

Branch Filtering

You can restrict push and pull_request triggers to specific branches using the object format with the branches field:

triggers:
  - event: push
    branches:
      - main
      - develop
  - event: pull_request
    branches:
      - main

Branch Pattern Syntax

RunnerHub supports three types of branch patterns:

Exact match — Matches the exact branch name:

branches:
  - main
  - release/v1.0

This matches only main and release/v1.0 exactly.

Single wildcard * — Matches any characters EXCEPT / (single path segment):

branches:
  - release/*
  - feature/*

• release/* matches release/1.0, release/2.0, but NOT release/1.0/beta
• feature/* matches feature/auth, feature/payments, but NOT feature/user/auth

Double wildcard ** — Matches everything INCLUDING / (multiple path segments):

branches:
  - feature/**
  - hotfix/**

• feature/** matches feature/auth, feature/user/auth, feature/user/login/v2
• hotfix/** matches hotfix/bug, hotfix/security/critical

Mixed patterns work together:

branches:
  - main
  - develop
  - release/*
  - feature/**

Limits and Constraints

• Maximum patterns per trigger: 50 branch patterns
• Maximum pattern length: 255 characters per pattern
• Special characters: Treated literally (e.g., . is not a regex, just a dot)

Push Trigger with Branch Filter

Run on push events only to specific branches:

triggers:
  - event: push
    branches:
      - main
      - develop
      - release/*

steps:
  - name: Build
    run: fastlane build

This pipeline runs on every push to main, develop, or any release/* branch. Pushes to other branches are ignored.

Pull Request Trigger with Branch Filter

For pull_request triggers, the branch pattern matches the target branch (where the PR is being merged INTO), not the source branch:

triggers:
  - event: pull_request
    branches:
      - main
      - develop

steps:
  - name: Run Tests
    run: fastlane test

This pipeline runs when a PR targets main or develop, regardless of the source branch name. A PR from feature/auth → main will trigger, but feature/auth → staging will not.

Mixing String and Object Formats

You can mix simple string triggers with object triggers in the same list:

triggers:
  - push                          # Runs on all push events
  - event: pull_request           # Runs on all PR events
    branches:
      - main

In this example:

• push has no branch restriction (all branches trigger)
• pull_request is restricted to PRs targeting main

To also enable scheduled builds, configure them in the dashboard under App → Settings → Scheduled Triggers (no YAML entry needed).

Manual Trigger

You can manually trigger builds from the RunnerHub dashboard by going to your app and clicking Trigger Build, or by rerunning a completed pipeline. Manual runs work regardless of your triggers: array configuration — you do not need to include manual in the YAML.

Manual triggers are useful for:

• Deployments that require human approval
• One-off testing or validation runs
• Ad-hoc builds on specific branches

Schedule Trigger

Scheduled builds are configured entirely in the RunnerHub dashboard. No YAML changes are required.

Note

Scheduled builds are configured in the dashboard, not in the YAML. Do not add schedule to your triggers: array — the YAML schema only accepts push and pull_request for webhook-driven runs.

To enable scheduled builds:

1. Open your app in RunnerHub
2. Navigate to Settings → Scheduled Triggers
3. Add a new schedule (e.g., 0 2 * * * for 2 AM daily)

When a scheduled build fires, the pipeline runs just like a push — steps execute in order and the RUNNERHUB_TRIGGER environment variable is set to schedule.

Multiple Triggers

Combine multiple triggers to run on different events:

triggers:
  - push
  - pull_request

steps:
  - name: Build
    run: fastlane build

This pipeline will:

• Run on every push (unless the branch has an open PR)
• Run on every PR event
• Also runs whenever a dashboard-configured scheduled trigger or manual trigger fires — no YAML entry needed for those (see the Available Triggers section above)

Trigger Deduplication

Push with Open PR

When a branch has an open Pull Request, push events are ignored to avoid duplicate jobs:

Branch: feature/auth (has open PR)
  │
  ├─ Push event → IGNORED (PR #5 has priority)
  │
  └─ PR event for commit → JOB CREATED

This ensures that for the same commit, you only get one job running, not two.

Auto-Cancellation

When a new commit is pushed to an open PR, RunnerHub automatically cancels previously running jobs for that PR and creates a new job for the latest commit:

PR #5, Commit A → Job created, RUNNING
  │
  └─ New commit pushed to PR #5
       │
       └─ Previous job cancelled
       └─ New job created for Commit B

This ensures you’re always building and testing the latest code on a PR, without wasting resources on outdated builds.

Event Evaluation

RunnerHub evaluates the triggers field against the incoming webhook event before cloning the repository:

1. Webhook received from Git provider (GitHub, GitLab, Bitbucket)
2. RunnerHub checks the event type
3. Compares against triggers list in YAML (via provider API)
4. If no match: job is not created
5. If match: job created in PENDING state

Because the YAML is read via the Git provider’s API (without cloning), trigger evaluation is fast and happens early.

Practical Examples

Build on Every Commit

Run on both push and PR events:

triggers:
  - push
  - pull_request

steps:
  - name: Build
    run: fastlane build

Deploy Only from Main Branch

Run on push events only to the main branch (production deployments):

triggers:
  - event: push
    branches:
      - main

steps:
  - name: Build Release
    run: fastlane build_release
  - name: Deploy to Production
    run: fastlane deploy_production

Only PR Validation (Targeting Main)

Run only on PR events targeting the main branch:

triggers:
  - event: pull_request
    branches:
      - main

steps:
  - name: Run Tests
    run: fastlane test

CI on Feature Branches

Run tests on push events to any feature branch:

triggers:
  - event: push
    branches:
      - feature/**
      - bugfix/**

steps:
  - name: Run Tests
    run: fastlane test

This triggers on pushes to feature/auth, feature/user/profile, bugfix/memory-leak, etc.

Nightly Release

For automated nightly builds, configure a schedule in the dashboard (App → Settings → Scheduled Triggers) and use conditional logic:

triggers:
  - push
  - pull_request

steps:
  - name: Build and Release
    if: env.RUNNERHUB_TRIGGER == 'schedule'
    run: fastlane release

Configure the schedule (e.g., 0 2 * * * for 2 AM daily) in the dashboard. When a scheduled build runs, RUNNERHUB_TRIGGER will be set to schedule.

Common Trigger Combinations

Most projects benefit from building on push and pull requests:

triggers:
  - push
  - pull_request

steps:
  - name: Build
    run: fastlane build

Conditional Behavior Based on Trigger

Use the RUNNERHUB_TRIGGER system variable to conditionally run different commands:

steps:
  - name: Conditional Deploy
    run: |
      if [ "$RUNNERHUB_TRIGGER" = "schedule" ]; then
        echo "Nightly build, deploying to staging"
        fastlane deploy_staging
      elif [ "$RUNNERHUB_TRIGGER" = "push" ] && [ "$RUNNERHUB_BRANCH" = "main" ]; then
        echo "Production push detected"
        fastlane deploy_production
      else
        echo "Building for testing"
        fastlane build
      fi

Git Provider Integration

RunnerHub integrates with your Git provider to receive webhook events:

Provider	Supported	Status
GitHub	Yes	Fully supported
GitLab	Yes	Fully supported
Bitbucket	Yes	Fully supported

Webhooks must be configured in your Git provider settings to point to RunnerHub.

Best Practices

Start with Push and PR Most projects benefit from building on both pushes and PRs:

triggers:
  - push
  - pull_request

Use Manual for Deployments You can trigger manual runs from the dashboard for controlled releases. Use conditional logic in your steps to handle deployment scenarios:

triggers:
  - pull_request
  - push

Then use if: env.RUNNERHUB_TRIGGER == 'manual' in your steps for conditional deployment logic.

Leverage Schedule for Nightly Builds Configure nightly/weekly builds as scheduled triggers in the dashboard (App → Settings → Scheduled Triggers). Your triggers: field can remain simple:

triggers:
  - push
  - pull_request

When a scheduled build runs, the pipeline executes with RUNNERHUB_TRIGGER set to schedule.

Test Locally Before Pushing Use your local environment to test pipeline changes before committing.

Next Steps

• Configure System Variables for trigger context
• Set up Environment Variables for your build
• Define Artifacts to collect build outputs
• Learn about Timeout & Limits