GitLab Integration

RunnerHub integrates with GitLab using OAuth, allowing you to connect projects, trigger builds, and report status back to merge requests.

How It Works

RunnerHub uses OAuth 2.0 to securely authenticate with GitLab:

You click "Connect GitLab" in RunnerHub
     ↓
Redirected to GitLab login
     ↓
Grant RunnerHub access to your projects
     ↓
GitLab redirects back to RunnerHub
     ↓
Webhook automatically configured
     ↓
Builds trigger on push/MR events

Installation

Step 1: Start the OAuth Flow

1. Go to your RunnerHub app
2. Click Repository → Connect
3. Select GitLab

You’ll be redirected to GitLab to authorize RunnerHub.

Step 2: Authorize RunnerHub

On GitLab:

1. Log in to your account
2. Review the permissions requested by RunnerHub
3. Click Authorize

You’ll be redirected back to RunnerHub.

Step 3: Select a Project

1. RunnerHub shows a list of projects you have access to
2. Click the project you want to connect
3. Click Connect

RunnerHub will:

• Store your GitLab access token (encrypted)
• Automatically configure a webhook on the project
• Start listening for push and merge request events

Permissions

When you authorize RunnerHub, GitLab grants these access scopes:

Permission	Purpose
api	Full API access to your projects
read_api	Read project data and repository content
read_repository	Clone the repository
write_repository	Optional: for advanced features

These permissions are scoped to the projects you authorize.

How Builds Are Triggered

Builds start automatically on:

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

Filter Branches:

In your pipeline YAML, specify which branches to build:

.runnerhub/runnerhub.yml

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

Webhook Configuration

Webhooks are automatically configured when you connect a project.

Webhook Details:

• Events: push_events, merge_request_events
• Active: Yes

To view or manage the webhook:

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

Note

RunnerHub manages the webhook automatically. You shouldn’t manually delete it — reconnect the project if you need to reconfigure it.

Status Reporting

Pipeline Status on Commits

When a build completes, RunnerHub posts the status to your commit:

1. Go to your GitLab project
2. Navigate to Repository → Commits
3. Click a commit hash
4. The build status appears in the commit details

Merge Request Checks

When you open a merge request:

1. RunnerHub automatically starts a build
2. Status appears in the MR “Checks” section
3. If you set status checks as required, MRs can’t merge until passing

Setting Required Checks:

1. Go to project → Settings → Protected Branches
2. Select a branch
3. Check “Status checks must succeed”
4. Save

Token Refresh

RunnerHub automatically handles token refresh:

• GitLab OAuth tokens expire after a set period
• RunnerHub detects expiration and automatically refreshes the token
• You won’t see any interruption — builds continue working

If a token becomes invalid:

1. Disconnect the project: App → Repository → Disconnect
2. Reconnect: Click Connect and authorize again

Troubleshooting

”Webhook Not Triggered”

If builds aren’t starting after commits:

1. Verify webhook exists:

   • Go to project → Settings → Webhooks
   • Check that “RunnerHub” is listed and active
   • Click “Recent events” to see delivery status

2. Check webhook logs:

   • Click the RunnerHub webhook
   • Scroll to “Recent events”
   • Look for error messages
   • Click an event to see full request/response

3. Reconnect the project:

   • Disconnect: App → Repository → Disconnect
   • Reconnect: App → Repository → Connect → Select Project
   • RunnerHub will reconfigure the webhook

”Project Not Found”

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

1. Make sure you’re logged in to GitLab
2. Verify you have at least Reporter access to the project
   • Go to project → Members
   • Check your role
3. Try logging out and authorizing RunnerHub again

”Permission Denied”

If you get permission errors:

1. Check your GitLab project role:
   • Reporter or above can trigger builds
   • Owner/Maintainer can manage webhooks
2. Verify the OAuth token has the correct scopes:
   • Disconnect the project
   • Re-authorize RunnerHub

”Build Logs Not Appearing”

If you can see the build in RunnerHub but logs don’t populate:

1. Check that the webhook was received:
   • Go to project → Settings → Webhooks → RunnerHub
   • Click “Recent events” and verify push event was received
2. Verify repository access:
   • In RunnerHub, go to app → Repository details
   • Confirm the clone URL is correct
3. Check for authentication issues in RunnerHub logs

Security

Token Storage

• GitLab OAuth tokens are encrypted at rest
• Only the workspace owner can disconnect or change integrations
• Tokens are never displayed or shared

Webhook Verification

RunnerHub verifies webhook authenticity using GitLab’s:

• X-GitLab-Event-UUID header for idempotency
• Webhook signature validation (if enabled in GitLab)

Uninstalling

To remove RunnerHub’s access:

Option 1: Disconnect in RunnerHub

1. Go to your app
2. Click Repository → Disconnect
3. The webhook is removed from GitLab

Option 2: Revoke in GitLab

1. Go to GitLab User Settings → Applications
2. Find “RunnerHub”
3. Click “Revoke”
4. All RunnerHub projects go offline in your workspace

Multiple Workspaces

You can connect the same GitLab project to different RunnerHub workspaces:

• Each workspace has separate OAuth tokens
• Webhooks are independent
• Both will receive events and create jobs

To do this:

1. Authorize RunnerHub in each workspace separately
2. Connect the same project to apps in different workspaces

Advanced: Custom Webhook URL

If your RunnerHub instance is self-hosted, you may need to update the webhook URL:

1. Go to project → Settings → Webhooks → RunnerHub
2. Edit the webhook URL to match your instance
3. Save

The URL should be: https://<your-runnerhub-instance>/webhooks/gitlab

Best Practices

1. Use Branch Protection

Require builds to pass before merging:

1. Go to project → Settings → Protected Branches
2. Select a branch (e.g., main)
3. Check “Require status checks to pass”
4. Save

2. Keep Tokens Fresh

• Every 90 days, GitLab recommends re-authorizing apps
• RunnerHub handles token refresh automatically
• If builds stop working, reconnect the project

3. Monitor Webhook Deliveries

Periodically check webhook health:

1. Go to project → Settings → Webhooks → RunnerHub
2. Click “Recent events”
3. Verify no failed deliveries
4. If failures appear, reconnect the project

4. Use Scheduled Builds

In addition to push triggers:

1. Go to your app → Schedules
2. Create a nightly build or performance test
3. Set time and days of week

Comparison with GitHub

Feature	GitLab	GitHub
Auth	OAuth 2.0	GitHub App
Webhook Setup	Automatic	Automatic
Status Checks	Yes	Yes (Check Runs)
Status Reports	Commit + MR	PR Checks
Token Refresh	Automatic	N/A (App-based)
Scope	Project-level	Organization level

---

More Help

• Pipeline YAML Reference
• GitLab Webhooks Documentation

Tip

GitLab OAuth tokens are automatically refreshed, so you don’t need to manually update credentials. If you encounter token-related errors, simply reconnect the project.