Pipeline Issues

runnerhub.yml Not Found

Error:

Missing runnerhub.yml pipeline configuration

Cause: RunnerHub cannot locate your pipeline configuration file. It looks for the file at a specific location.

Solution:

Ensure the pipeline file exists at the correct path:

.runnerhub/runnerhub.yml

Example repository structure:

repo-root/
├── .runnerhub/
│   └── runnerhub.yml
├── ios/
└── README.md

Primary location is .runnerhub/runnerhub.yml; root-level runnerhub.yml is also accepted as a fallback. Custom paths can be set in App → Settings → Pipeline Configuration Path.

Job Not Triggered

Symptom: The webhook is received, but no job is created.

Cause: The runnerhub.yml file has a triggers field that doesn't include the event you sent (e.g., push or pull_request).

Solution:

Verify that the event you want to trigger is listed in the triggers array:

triggers:
  - push
  - pull_request

The triggers field is required. Without it, your pipeline is invalid and no jobs will be created.

Supported trigger events:

push — triggered by commits pushed to a branch
pull_request — triggered by pull request open/update/reopen

Builds Stopped After Renaming a Repository (GitLab / Bitbucket)

Symptom: Builds ran fine, then silently stopped after you renamed the repository (or moved it to a new group/workspace/namespace) on GitLab or Bitbucket. Webhook deliveries still succeed on the provider side, but no jobs appear in RunnerHub.

Cause: For security, RunnerHub verifies each incoming GitLab/Bitbucket webhook payload against the repository name that was registered when you linked the repo. A valid webhook token only proves the sender knows this repo's secret — it does not prove the payload's repository name is genuine — so a mismatched name is skipped (with a warning in the backend logs) rather than trusted. Renaming the repo makes the provider send the new name, which no longer matches the stored one, so every delivery is skipped.

Solution: Re-link the repository in RunnerHub so the current name is stored again:

Open your app in the dashboard → App → Settings → Repository.
Disconnect the current repository, then reconnect and select it under its new name.
Push a commit (or open/update a PR) to confirm builds resume.

Push Ignored When PR is Open

Symptom: You push to a branch with an open pull request, but no job appears.

Cause: This is expected behavior. When a branch has an open PR, RunnerHub ignores push events to avoid duplicate jobs. Only the pull_request event triggers the job.

Solution:

No action needed. Look for the job under the Pull Requests tab or check the PR status in your Git provider.

Job Automatically Cancelled (CANCELLING)

Symptom: A job changes automatically from PENDING, ASSIGNED, or RUNNING to CANCELLING and then CANCELLED.

Cause: A new commit has been received for the same Pull Request. RunnerHub automatically cancels previous executions to prioritize the most recent code.

Solution:

No action needed. The most recent commit will generate a new job that will execute shortly.

This is expected behavior and helps keep CI efficient by not running outdated jobs.

Invalid Pipeline Configuration

Error:

Invalid runnerhub.yml: validation failed

Invalid runnerhub.yml: <validation message>

Cause: The YAML configuration doesn't match the required schema.

Common mistakes:

Missing platform field
Missing steps array
Missing triggers field
Incorrect indentation (YAML is whitespace-sensitive)
Invalid field types

Solution:

Use this minimal valid pipeline as a starting point:

name: My Pipeline
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Run script
    run: sh script.sh

Then expand with your own steps. Check that:

All required fields are present (name, platform, triggers, steps)
All indentation is consistent (use 2 spaces, not tabs)
Field values have the correct type (strings, arrays, etc.)

Invalid Platform

Error:

Invalid platform. Supported values: ios, macos, android, flutter, react-native

Cause: Unsupported or misspelled platform value.

Solution:

Fully supported platforms:

ios — iOS apps
macos — macOS apps
android — Android apps
flutter — Flutter apps (cross-platform)
react-native — React Native apps (cross-platform iOS and Android)

Example:

platform: ios

Missing or Empty Steps

Error:

Invalid runnerhub.yml: steps must contain at least one step

Cause: The pipeline has no steps defined, or the steps array is empty.

Solution:

Add at least one step to your pipeline:

name: Pipeline
platform: ios

environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Build
    run: xcodebuild build

  - name: Test
    run: xcodebuild test

Each step must have:

name — A descriptive name for the step
run — The command(s) to execute

Command Rejected by Platform Validation

Error:

Command rejected: command does not match allowed commands for platform 'ios'

Cause: The command in your step doesn't contain a recognized command for the declared platform. For iOS/macOS, RunnerHub requires at least one of these:

xcodebuild
fastlane
swift build, swift test, swift package
pod install, pod repo update
bundle install, bundle exec

Solution:

Ensure your command uses appropriate platform tools:

name: Pipeline
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Build and test
    run: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp test

If you need to run auxiliary scripts, combine them with recognized commands:

name: Pipeline
platform: ios

environment:
  xcode: "16.4"

steps:
  - name: Build with script
    run: |
      sh scripts/setup.sh
      xcodebuild -workspace MyApp.xcworkspace -scheme MyApp build

Blocked Command

Error:

Command rejected: blocked command detected

Cause: The pipeline contains a command that's explicitly blocked for security reasons:

docker
sudo
apt, yum (package managers)
curl | sh (piped shell execution)
Other dangerous patterns

Solution:

RunnerHub does not allow arbitrary system commands. Use platform-specific tools instead:

Instead of:

run: sudo brew install library

Use:

run: pod install  # or manage via Podfile

Instead of:

run: curl https://script.example.com/setup.sh | sh

Use:

run: sh scripts/setup.sh  # Keep scripts in your repo

For complex workflows, use Fastlane, which runs within the pipeline's restricted environment.

Cloud YAML Locking Issues

Error:

Cannot edit Cloud YAML in dashboard

Cause: Cloud YAML for a specific branch is locked (locked=true). This is a safety feature to prevent accidental changes to production pipelines. Each branch has its own independent lock state.

Solution:

Go to App > Cloud YAML tab
Find the branch you want to edit in the list
Click the Unlock button next to that branch's configuration
Make your changes
Save your changes (this automatically re-locks the configuration)

Use the Unlock button in the Cloud YAML tab to allow edits for a specific branch. Other branches remain unaffected.

Scheduled Build Not Triggered

Symptom: Scheduled build did not trigger at the expected time.

Cause: Possible reasons:

Schedule is disabled or misconfigured
The scheduling service may be temporarily unavailable
No agent is available at the scheduled time
Branch or day-of-week filter doesn't match

Solution:

Go to App > Schedules tab
Verify the schedule is enabled
Check that:
- Branch matches your target branch (e.g., main)
- Days of week includes today
- Time is in UTC (or your configured timezone)
Ensure at least one agent is online and available at the scheduled time
If the issue persists, try again in a few minutes or contact support

Quick Checklist

Before running a pipeline, verify:

[ ] .runnerhub/runnerhub.yml exists in repo
[ ] triggers field is present and includes your event type
[ ] platform is ios, macos, android, flutter, or react-native
[ ] At least one step exists
[ ] Commands use appropriate platform tools
[ ] All scripts referenced in steps exist and are committed
[ ] YAML indentation is correct (no mixing tabs and spaces)

See Code Signing Troubleshooting for signing-related issues.