Connect a Repository

Before RunnerHub can build your app, it needs access to your Git repository. This guide covers connecting repositories on GitHub, GitLab, and Bitbucket.

Supported Platforms

RunnerHub integrates with:

• GitHub — Via GitHub App (recommended for automatic webhook setup)
• GitLab — Via OAuth
• Bitbucket — Via OAuth

Connect GitHub Repository

GitHub integration uses the official RunnerHub GitHub App for secure, scope-limited access.

Install the GitHub App

1. In RunnerHub dashboard, go to your app and click Connect Repository or Settings → Repository
2. Click “GitHub” from the provider options
3. You’ll be redirected to GitHub — Review the permissions (read access to code, pull requests, and webhooks)
4. Click “Install” to authorize the RunnerHub app on your account or organization
5. Select repositories — Choose which repositories to grant RunnerHub access to (you can limit this to specific repos)
6. Confirm authorization — You’ll be redirected back to RunnerHub

Select Your Repository

1. Back in RunnerHub, you’ll see a list of repositories the app has access to
2. Click to select your repository
3. RunnerHub will automatically:
   • Create a webhook on your repository
   • Test the webhook connection
   • Link the app to this RunnerHub app

Tip

If you don’t see your repository in the list, check:

1. The GitHub App is installed on your GitHub account/organization
2. You have admin access to the repository (required to manage webhooks)
3. The repository is public or the app has been granted access to it

Connect GitLab Repository

GitLab integration uses OAuth for seamless authentication.

Authorize with OAuth

1. In RunnerHub dashboard, go to your app and click Connect Repository or Settings → Repository
2. Click “GitLab” from the provider options
3. You’ll be redirected to GitLab — Review the permissions (API access to code and webhooks)
4. Click “Authorize” to approve RunnerHub’s access to your GitLab account
5. You’ll be redirected back to RunnerHub

Select Your Project

1. You’ll see a list of your GitLab projects and groups
2. Click to select your project
3. RunnerHub will automatically:
   • Create a webhook on your project
   • Verify the webhook is working
   • Link the project to this RunnerHub app

Note

RunnerHub requires Maintainer or Owner role on the project to manage webhooks. If you’re a Developer, ask your GitLab project maintainer to authorize RunnerHub instead.

Connect Bitbucket Repository

Bitbucket integration uses OAuth for authentication.

Authorize with OAuth

1. In RunnerHub dashboard, go to your app and click Connect Repository or Settings → Repository
2. Click “Bitbucket” from the provider options
3. You’ll be redirected to Bitbucket — Review the permissions (API access and webhook management)
4. Click “Authorize” to approve RunnerHub’s access
5. You’ll be redirected back to RunnerHub

Select Your Repository

1. You’ll see a list of your Bitbucket workspaces and repositories
2. Click to select your repository
3. RunnerHub will automatically:
   • Create a webhook on your repository
   • Test the webhook connection
   • Link the repository to this RunnerHub app

Note

You need admin access to the Bitbucket repository to authorize webhook creation. If you’re a developer on the team, ask your repo admin to authorize RunnerHub.

What Happens After Connection?

Once your repository is connected:

1. Webhook created — RunnerHub creates a webhook that listens for push events and pull requests
2. Automatic triggers — When you push code or open a PR, RunnerHub automatically queues a build (if you have a .runnerhub/runnerhub.yml in your repo)
3. Status checks — Build status appears as a check on your GitHub commits, GitLab merge requests, or Bitbucket pull requests
4. Build logs accessible — Click the check/status to view build logs directly from your Git provider

Manage Repository Connection

To view or disconnect a repository:

1. Go to App Settings — Click your app name in the sidebar, then Settings
2. Click “Repository” tab
3. You’ll see:
   • Connected repository name
   • Last webhook activity
   • Option to disconnect or reconnect

Caution

Disconnecting a repository will:

• Pause webhook deliveries to RunnerHub
• Not delete your build history
• Not affect your pipeline configuration

You can reconnect anytime.

Shared Repositories

Multiple apps within the same account can connect to the same repository. This is useful for white-label apps — different branded versions of the same codebase.

When you connect a repo that’s already used by another app in your account:

• The repository list shows “Also used by: App Name” as an informational label
• You can still select and connect it — the button remains enabled
• Each app gets its own pipeline runs, variables, signing, and build history

Note

Repositories are locked at the account level. If another account has already connected a repository, it will appear as “In use by another account” and cannot be selected. Disconnecting all apps from the repo releases the lock.

Each app sharing a repository can optionally use a custom pipeline YAML path to run a different pipeline configuration. See Custom Pipeline Path for details.

Troubleshooting

Repository doesn’t appear in the list

• On GitHub: Check the GitHub App is installed and you have the repo selected in the app settings
• On GitLab: Verify you’re viewing the correct group and have appropriate access
• On Bitbucket: Make sure you’re in the correct workspace

Webhook not triggering builds

• Check repository settings to ensure the webhook exists
• Verify .runnerhub/runnerhub.yml exists in your repository root
• View webhook logs in your Git provider’s settings (GitHub → Settings → Webhooks, etc.)

Permission denied when connecting

• Ensure you have admin access to the repository
• Try disconnecting and reconnecting
• Check that your Git provider account hasn’t revoked app authorization

For more help, see Troubleshooting.

Next Steps

With your repository connected:

1. Write your first pipeline — Create .runnerhub/runnerhub.yml in your repository root (guide →)
2. Push and trigger a build — Commit and push to see your first build run
3. View build results — Check the dashboard or your Git provider’s status checks

Tip

Your repository webhook will start delivering events immediately. You don’t need to do anything else to activate it.