GitLab Integration

GitLab integration in Dokploy uses OAuth 2.0 authentication with support for both GitLab.com and self-hosted GitLab instances.

Features

OAuth 2.0 authentication with automatic token refresh
Support for GitLab.com and self-hosted instances
Group filtering for large organizations
Repository and branch browsing
Automatic token refresh with expiry management
Internal URL support for same-network deployments

Prerequisites

A GitLab account (GitLab.com or self-hosted)
Access to the repositories you want to deploy
Admin access to create OAuth applications
Your Dokploy instance must be accessible for OAuth callbacks

Creating a GitLab OAuth Application

Navigate to Applications

For GitLab.com:

Go to your GitLab profile
Click Settings → Applications
Click Add new application

For Self-hosted GitLab:

Go to Admin Area → Applications
Click New application

You can also create user-level applications in User Settings → Applications

Configure Application Details

Fill in the application information:Name: Choose a descriptive name (e.g., “Dokploy Production”)Redirect URI: Your Dokploy callback URL:

https://your-dokploy-domain.com/api/providers/gitlab/callback

The redirect URI must be exact. GitLab does not allow wildcards.

Set Scopes

Enable the following scopes:

api - Full API access
read_user - Read user information
read_repository - Read repository content
write_repository - Clone repositories

The api scope provides comprehensive access. For more restrictive access, use only read scopes.

Create Application

Click Save application to create the OAuth app.

Copy Credentials

After creation, save these values:

Application ID: Used as Client ID
Secret: Used as Client Secret

The secret is only shown once. Store it securely.

Configuring in Dokploy

Navigate to Git Providers

In Dokploy dashboard:

Go to Settings → Git Providers
Click Add Git Provider
Select GitLab

Enter Configuration

Fill in the GitLab OAuth details:Provider Name: A friendly name (e.g., “GitLab Production”)GitLab URL:

For GitLab.com: https://gitlab.com
For self-hosted: https://gitlab.yourdomain.com

GitLab Internal URL (optional):

Leave empty if not on same network
For same-network: http://gitlab.internal:8080

Internal URL is used for token operations when Dokploy and GitLab are on the same network, reducing latency.

Application ID: The Application ID from GitLabSecret: The Secret from GitLabGroup Name (optional): Filter repositories by group

mygroup,mygroup/subgroup

Comma-separated list of group paths.

Save and Authorize

Click Save
You’ll be redirected to GitLab
Click Authorize to grant access
You’ll be redirected back to Dokploy

Test Connection

After authorization:

Click Test Connection
Verify the number of accessible repositories

If using group filtering, only repositories in specified groups are counted.

Self-Hosted GitLab Configuration

Basic Setup

For self-hosted GitLab instances:

GitLab URL: https://gitlab.company.com
Application ID: abc123...
Secret: xyz789...

Internal URL Configuration

When Dokploy and GitLab are on the same network:

GitLab URL: https://gitlab.company.com  # External, for OAuth redirect
GitLab Internal URL: http://gitlab:8080  # Internal, for API calls

Benefits:

Faster token refresh operations
Reduced external network usage
Works even if external URL is behind firewall

Basic Authentication in URL

If your GitLab instance requires basic auth:

https://username:password@gitlab.company.com

Dokploy automatically:

Extracts credentials from URL
Adds Authorization: Basic header
Removes credentials from subsequent URLs

Only use basic auth over HTTPS to protect credentials.

Using GitLab in Applications

Deploying from GitLab

Create or Edit Application

When creating/editing an application:

Set Source Type to “Git”
Select your GitLab provider

Select Repository

Choose from accessible repositories:

Format: namespace/project-name
Includes personal and group repositories
Filtered by group name if configured

Configure Deployment

Branch: Select the branch to deployPath Namespace: Automatically set to namespace/projectAuto Deploy (optional):

Enable for automatic deployments
Currently supports manual triggers

Repository Structure

GitLab repositories include:

{
  id: 12345,
  name: "my-project",
  url: "namespace/my-project",  // Used as pathNamespace
  owner: {
    username: "namespace"
  }
}

Token Management

Automatic Token Refresh

Dokploy automatically refreshes expired tokens:

Before Each Operation: Checks token expiry
Safety Margin: Refreshes 60 seconds before expiry

Refresh Flow:

POST {gitlabUrl}/oauth/token
{
  grant_type: "refresh_token",
  refresh_token: "...",
  client_id: "...",
  client_secret: "..."
}

Store New Tokens: Updates access and refresh tokens in database

Token Expiration

Default Expiry: 2 hours (7200 seconds)
Stored as Unix Timestamp: expiresAt field
Automatic Refresh: Happens transparently during:
- Repository listing
- Branch fetching
- Repository cloning
- Connection testing

Group Filtering

Single Group

Filter by a single group:

mygroup

Shows repositories in:

mygroup/project1
mygroup/project2

Multiple Groups

Comma-separated groups:

frontend,backend,infrastructure

Subgroups

Include subgroups:

mygroup/frontend,mygroup/backend

Matches:

mygroup/frontend/app1
mygroup/frontend/app2
mygroup/backend/api

No Filtering

Leave empty to show:

All personal repositories
All group repositories you have access to

API Integration

Repository Listing

Fetches projects with pagination:

GET {gitlabUrl}/api/v4/projects?membership=true&page=1&per_page=100
Authorization: Bearer {accessToken}

Pagination:

100 projects per page (GitLab maximum)
Uses x-total header for total count
Fetches all pages automatically

Branch Listing

Fetches branches for a project:

GET {gitlabUrl}/api/v4/projects/{projectId}/repository/branches?page=1&per_page=100
Authorization: Bearer {accessToken}

Returns:

[
  {
    id: "main",
    name: "main",
    commit: { id: "abc123..." }
  }
]

Repository Cloning

Clone command format:

git clone --branch {branch} --depth 1 \
  https://oauth2:{accessToken}@{gitlabUrl}/{pathNamespace}.git \
  {outputPath}

Features:

Uses OAuth2 token authentication
Shallow clone (—depth 1) for speed
Optional submodule support

Troubleshooting

Authorization Fails

Symptoms: Redirect loop or “Invalid redirect URI” errorSolutions:

Check Redirect URI: Must exactly match:

https://your-dokploy-domain.com/api/providers/gitlab/callback

Verify HTTPS: GitLab requires HTTPS for OAuth (except localhost)
Check Application Status: Ensure application is not revoked
Review Scopes: Ensure all required scopes are enabled

No Repositories Shown

Symptoms: Test connection succeeds but no repositories availableSolutions:

Check Group Filter: Verify group names are correct
Review Permissions: User must have at least Reporter role

Test API Access:

curl -H "Authorization: Bearer TOKEN" \
  https://gitlab.com/api/v4/projects?membership=true

Clear and Reconnect: Remove and re-add the provider

Token Refresh Errors

Symptoms: “Failed to refresh token” errors in logsSolutions:

Check Secret: Ensure client secret is correct
Verify Application: Application might be deleted or revoked
Review Internal URL: If set, must be accessible from Dokploy
Reauthorize: Remove provider and go through OAuth flow again

Clone Failures

Symptoms: “Repository configuration failed” during deploymentSolutions:

Verify Required Fields:
- Repository name
- Owner/namespace
- Branch name
- Path namespace
Check Token: Use Test Connection to verify
Review Permissions: Ensure read_repository scope

Test Manually:

git ls-remote https://oauth2:TOKEN@gitlab.com/namespace/project.git

Self-Hosted Certificate Issues

Symptoms: SSL/TLS errors when connectingSolutions:

Valid Certificate: Ensure GitLab has valid SSL certificate
Internal URL: Use HTTP for internal URL if on same network
Certificate Trust: Dokploy must trust the CA
Disable SSL Verification (not recommended): Configure in GitLab settings if absolutely necessary

Security Best Practices

1. OAuth Secret Management

Store client secret securely
Never commit to version control
Rotate periodically
Use different applications for different environments

2. Scope Limitation

Request only necessary scopes:

Minimum: read_user, read_repository
Standard: Add write_repository for full functionality
Avoid: sudo or admin scopes unless absolutely required

3. Group Filtering

For large organizations:

Use group filtering to limit repository access
Separate providers for different teams
Regular access audits

4. Token Storage

Tokens are encrypted in database
Never logged or exposed in UI
Automatically refreshed before expiry
Invalidated when provider is removed

5. Self-Hosted Security

Use HTTPS for external URLs
Keep GitLab instance updated
Configure internal URLs only on trusted networks
Regular security audits

Advanced Configuration

Multiple GitLab Providers

Configure separate providers for:

Different Instances: GitLab.com + self-hosted
Different Groups: Frontend team, Backend team
Different Environments: Production, Staging

Each provider maintains:

Separate OAuth tokens
Independent group filters
Isolated repository access

Webhook Integration (Future)

While not currently implemented, prepare for webhook support:

Note your Dokploy webhook endpoint
Plan webhook events needed (Push, Tag, Merge Request)
Prepare secret token generation

API Response Examples

Project List Response

[
  {
    "id": 12345,
    "name": "my-project",
    "path_with_namespace": "mygroup/my-project",
    "namespace": {
      "path": "mygroup",
      "full_path": "mygroup",
      "kind": "group"
    }
  }
]

Branch List Response

[
  {
    "name": "main",
    "commit": {
      "id": "abc123...",
      "short_id": "abc123",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  }
]

Next Steps

Deploy an Application

Create your first deployment from GitLab

GitHub Integration

Compare with GitHub integration

Gitea Integration

Self-hosted Git alternative

Git Providers Overview

Compare all Git provider options

Git Providers

Notifications

Authentication

​Features

​Prerequisites

​Creating a GitLab OAuth Application

​Configuring in Dokploy

​Self-Hosted GitLab Configuration

​Basic Setup

​Internal URL Configuration

​Basic Authentication in URL

​Using GitLab in Applications

​Deploying from GitLab

​Repository Structure

​Token Management

​Automatic Token Refresh

​Token Expiration

​Group Filtering

​Single Group

​Multiple Groups

​Subgroups

​No Filtering

​API Integration

​Repository Listing

​Branch Listing

​Repository Cloning

​Troubleshooting

​Security Best Practices

​1. OAuth Secret Management

​2. Scope Limitation

​3. Group Filtering

​4. Token Storage

​5. Self-Hosted Security

​Advanced Configuration

​Multiple GitLab Providers

​Webhook Integration (Future)

​API Response Examples

​Project List Response

​Branch List Response

​Next Steps

Deploy an Application

GitHub Integration

Gitea Integration

Git Providers Overview

Features

Prerequisites

Creating a GitLab OAuth Application

Configuring in Dokploy

Self-Hosted GitLab Configuration

Basic Setup

Internal URL Configuration

Basic Authentication in URL

Using GitLab in Applications

Deploying from GitLab

Repository Structure

Token Management

Automatic Token Refresh

Token Expiration

Group Filtering

Single Group

Multiple Groups

Subgroups

No Filtering

API Integration

Repository Listing

Branch Listing

Repository Cloning

Troubleshooting

Security Best Practices

1. OAuth Secret Management

2. Scope Limitation

3. Group Filtering

4. Token Storage

5. Self-Hosted Security

Advanced Configuration

Multiple GitLab Providers

Webhook Integration (Future)

API Response Examples

Project List Response

Branch List Response

Next Steps