GitLab

Integration

Connect via OAuth. Supports GitLab.com and self-hosted instances.

GitLab integration uses OAuth for authentication. This works with both GitLab.com and self-hosted GitLab instances.

Setup Guide

Start OAuth Connection

Go to your team's Integrations page (Settings → Integrations) and select the GitLab tab.

For GitLab.com:

Simply click "Connect with GitLab" to start the OAuth flow.

For Self-Hosted GitLab:

Enter your GitLab instance URL first (e.g., https://gitlab.yourcompany.com), then click "Connect with GitLab".

Authorize Arbtr

You'll be redirected to GitLab to authorize Arbtr. Review and approve the requested permissions.

Permissions Requested:

• Read-Only mode: read_api, read_repository
• Full Access mode: api, read_repository, write_repository

After authorization, you'll be redirected back to Arbtr with your account connected. Your GitLab username will be displayed in the integration settings.

Configure Repository

After connecting, configure which repository to sync decisions to.

Fill in the following:

Project ID:Numeric ID (e.g., 12345) or path (e.g., group/project)
Branch:Target branch, usually main
ADR Directory:Where to store ADRs (e.g., docs/adr)

Finding your Project ID: In GitLab, go to your project → Settings → General. The Project ID is displayed at the top.

Test and Save

Click "Test Connection" to verify everything is configured correctly, then save your settings.

The test will verify that Arbtr can access your repository using the OAuth token. Tokens are automatically refreshed, so you won't need to reconnect manually.

Publishing Decisions

Once configured with Full Access mode, you can publish concluded decisions to GitLab:

Manual Publishing

On any concluded decision, click Actions → Publish to Git. This creates a Merge Request with your ADR file. Review and merge the MR in GitLab.

Auto-Publishing

Enable "Auto-publish on conclusion" in Integrations settings. Decisions will be automatically published when you approve the comprehensive summary.

Self-Hosted GitLab

For self-hosted GitLab instances, you may need to configure your own OAuth application in your Arbtr deployment.

Creating a GitLab OAuth Application

In GitLab, go to User Settings → Applications (or Admin → Applications for instance-wide)
Create a new application with:
- • Name: "Arbtr"
- • Redirect URI: https://your-arbtr-instance.com/api/auth/gitlab/callback
- • Scopes: read_api read_repository (Read-Only) or api read_repository write_repository (Full Access)
Copy the Application ID and Secret

Environment Variables

GITLAB_CLIENT_ID_READ - OAuth app ID for read-only mode
GITLAB_CLIENT_SECRET_READ - OAuth secret for read-only app
GITLAB_CLIENT_ID_FULL - OAuth app ID for full access mode
GITLAB_CLIENT_SECRET_FULL - OAuth secret for full access app

Troubleshooting

401 Unauthorized

Your OAuth token may have expired and failed to refresh. Disconnect and reconnect your GitLab account to get new credentials.

403 Forbidden

You don't have access to the specified project, or the OAuth scopes are insufficient. Make sure you have at least Developer access to the repository.

404 Project Not Found

The Project ID is incorrect or the project doesn't exist. Verify the Project ID in GitLab Settings → General.

Self-hosted SSL issues

If connecting to a self-hosted GitLab with a self-signed certificate fails, your Arbtr deployment may need to trust the certificate. Contact your administrator.

GitHub Setup

Bitbucket Setup

Command Palette