GitHub Integration

RunnerHub uses a GitHub App to seamlessly integrate with your GitHub repositories. The app handles authentication, webhook management, and check runs without manual configuration.

What is the GitHub App?

The RunnerHub GitHub App is a GitHub-approved integration that connects your repositories to RunnerHub. It:

• Authenticates with your GitHub repositories securely
• Automatically configures webhooks (no manual setup)
• Creates GitHub Checks to display build status in PRs
• Posts build summary comments on pull requests
• Listens for push and pull request events
• Provides repository access control through GitHub’s permissions system

App Permissions:

• contents:read — Read repository code and commits
• checks:write — Create and update check runs
• pull_requests:write — Read pull request details and post build summary comments
• webhooks — Manage webhook subscriptions

Installation

Step 1: Go to Workspace Settings

1. Log in to RunnerHub
2. Select your workspace from the sidebar
3. Click Settings → Integrations → GitHub

Step 2: Install the GitHub App

Click the Install GitHub App button. You’ll be redirected to GitHub.

Step 3: Authorize RunnerHub

On GitHub:

1. Choose the account/organization where you want to install the app
2. Select which repositories (all or specific ones)
3. Click Install

GitHub will redirect you back to RunnerHub with the installation confirmed.

Step 4: Connect a Repository to an App

1. Go to your app in RunnerHub
2. Click Repository → Connect
3. Select GitHub
4. Choose the repository from the list

That’s it! RunnerHub will automatically:

• Configure a webhook on the repository
• Start listening for push and pull request events
• Create check runs for each build

How It Works

Webhook Events

When you push code or open a pull request, GitHub sends an event to RunnerHub:

You push to GitHub
     ↓
GitHub sends webhook event
     ↓
RunnerHub receives and parses event
     ↓
Job created in PENDING state
     ↓
Available agent picks it up
     ↓
Build executes
     ↓
Result posted to GitHub Check

Note

If multiple apps share the same repository, each webhook event triggers a separate pipeline for every connected app. Each app uses its own pipeline configuration, variables, and signing settings.

Check Runs

RunnerHub creates a GitHub Check for each build. You’ll see the status in:

• Pull Request — Checks section
• Commit — Details (green check or red X)
• Branch — Protection rules can require passing checks

Check Status:

• Pending → Build queued/running
• Success → Build passed
• Failure → Build failed (with link to full logs)

Status Checks in Pull Requests

When you open a PR:

1. RunnerHub creates a check run
2. Status appears in the PR checks section
3. You can see detailed logs by clicking the check
4. PR merge requirements can enforce passing checks

Triggering Builds

Builds are triggered automatically on:

Event	Trigger
Push	New commits to any branch
Pull Request	PR opened or updated
Manual	Via RunnerHub dashboard
Scheduled	Cron-based triggers (app config)

Filtering Branches:

Add a pipeline trigger to only build on specific branches:

.runnerhub/runnerhub.yml

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

Webhook Configuration

Webhooks are configured automatically when you connect a repository. You don’t need to set them up manually.

Webhook Details:

• Events: push, pull_request, check_suite
• Active: Yes

To view or edit the webhook manually:

1. Go to your GitHub repo
2. Settings → Webhooks
3. Find “RunnerHub” in the list

Note

The webhook is managed by RunnerHub. You can disable it temporarily but shouldn’t delete it — reconnecting the repository will reconfigure it.

Permissions and Access

GitHub App Installation

The GitHub App installation controls which repositories RunnerHub can access:

1. Go to GitHub Settings → Applications → Installed GitHub Apps → RunnerHub
2. Click Configure to manage repository access
3. Add or remove repositories as needed

Workspace Access

Within RunnerHub:

• Only workspace members can connect repositories
• Once connected, all workspace members can trigger builds on that app
• Workspace owner can disconnect repositories

Troubleshooting

”Webhook Delivery Failed”

If you see webhook failures in GitHub:

1. Check that RunnerHub is accessible (no network blocks)
2. Verify your workspace subscription tier (free tier has limited features)
3. Check GitHub’s webhook delivery logs:
   • Go to repo → Settings → Webhooks
   • Click “Recent Deliveries” to see errors
4. Reconnect the repository: Disconnect and reconnect in RunnerHub

”Check Never Updates”

If build status isn’t showing up in GitHub:

1. Verify the webhook is configured:
   • Go to repo → Settings → Webhooks
   • Check that “RunnerHub” is listed and Active
2. Check build logs in RunnerHub dashboard
3. Ensure the GitHub App has been installed and authorized

”Repository Not Found”

If you can’t see your repository in the list:

1. Make sure the GitHub App is installed:
   • Go to RunnerHub workspace → Settings → GitHub
   • Check that installation shows a checkmark
2. Verify repository access:
   • Go to GitHub Settings → Applications → RunnerHub → Configure
   • Add the repository to the list
3. Refresh the RunnerHub page

”Permission Denied”

If you get a permission error:

1. Check that the GitHub App is installed in the correct organization
2. Verify your GitHub user has admin access to the repository
3. Try disconnecting and reconnecting the repository

Uninstalling the GitHub App

To remove RunnerHub from your GitHub account:

1. Go to GitHub Settings → Applications → Installed GitHub Apps
2. Find RunnerHub
3. Click Uninstall

In RunnerHub, all connected GitHub repositories will go offline. You can reinstall later to reconnect.

Advanced: Custom Webhook Handling

If you need more control with a self-hosted RunnerHub instance, you can manage webhooks manually:

1. Disconnect the repository in RunnerHub
2. Manually add a webhook in GitHub:
   • URL: https://<your-runnerhub-instance>/webhooks/github
   • Events: push, pull_request
   • Active: Yes
3. Include the required signature header validation

However, we recommend using the GitHub App for automatic management and security.

Best Practices

1. Use Branch Protection Rules

Require RunnerHub checks to pass before merging:

1. Go to repo → Settings → Branches
2. Add protection rule for main
3. Check “Require status checks to pass”
4. Select “RunnerHub” from the list

2. Shared Repositories (White-Label)

You can connect the same repository to multiple apps within your account — ideal for white-label apps that share a codebase. When a webhook event arrives, RunnerHub triggers pipelines for all connected apps simultaneously.

• Each app can use a different pipeline YAML path for independent configurations
• Each app maintains its own variables, signing settings, and build history
• Repositories are locked at the account level — other accounts cannot connect to a repo already in use. See Shared Repositories for details

3. Review Webhook Logs

GitHub stores webhook delivery logs for 30 days:

1. Go to repo → Settings → Webhooks → RunnerHub
2. Click “Recent Deliveries”
3. Check status and response for each delivery

4. Use Scheduled Builds for Nightly Tests

In addition to push triggers, set up scheduled builds:

1. Go to your app → Schedules
2. Create a nightly test schedule
3. Configure time and days of week

Comparison: GitHub App vs Personal Access Token

RunnerHub uses a GitHub App instead of personal access tokens for better security:

Aspect	GitHub App	Personal Token
Scope	Repository-level permissions	Account-wide
Revocation	One-click uninstall per repo	Manual token rotation
Sharing	No token sharing needed	Token embedded in config
Audit Trail	GitHub logs app actions	Less transparent
Security	Approved by GitHub	User responsible

---

More Help

• Pipeline YAML Reference
• GitHub Webhooks Documentation

Tip

The GitHub App approach means you never need to share tokens or credentials. GitHub handles all authentication and audit logging.