Git Providers - Dokploy

Overview

Dokploy supports multiple Git providers to deploy applications directly from your source code repositories. Connect your Git provider once and deploy unlimited applications.

Supported Providers

Dokploy integrates with:

GitHub - GitHub Cloud and GitHub Apps
GitLab - GitLab Cloud and self-hosted GitLab instances
Bitbucket - Bitbucket Cloud
Gitea - Self-hosted Gitea instances

GitHub

Connect GitHub using GitHub Apps for secure, fine-grained access control.

Configuration

string

required

Display name for this Git provider connection

My GitHub App

string

Name of your GitHub App

number

GitHub App ID from your app settings

# Found in Settings > Developer settings > GitHub Apps
123456

string

OAuth Client ID for the GitHub App

string

OAuth Client Secret for the GitHub App

Keep your client secret secure. Never commit it to version control.

string

Installation ID after installing the app to your account/organization

string

Private key for authenticating as the GitHub App

-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----

string

Webhook secret for securing webhook payloads

Creating a GitHub App

Go to GitHub Settings > Developer settings > GitHub Apps
Click “New GitHub App”
Configure the app:
- Homepage URL: https://your-dokploy-domain.com
- Webhook URL: https://your-dokploy-domain.com/api/github/webhook
- Webhook secret: Generate a secure random string
Set permissions:
- Repository contents: Read
- Repository metadata: Read
- Deployments: Read & write
- Pull requests: Read & write (for preview deployments)
Generate a private key and download it
Install the app to your account/organization

Example Configuration

const github = await fetch('https://your-domain.com/api/trpc/github.create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.API_KEY
  },
  body: JSON.stringify({
    name: 'Production GitHub',
    githubAppName: 'dokploy-prod',
    githubAppId: 123456,
    githubClientId: 'Iv1.abc123def456',
    githubClientSecret: 'ghp_abc123def456...',
    githubInstallationId: '789012',
    githubPrivateKey: '-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----',
    githubWebhookSecret: 'webhook_secret_123'
  })
});

Fetching Branches

curl https://your-domain.com/api/trpc/github.branches \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "octocat",
    "repo": "Hello-World",
    "githubId": "github-123"
  }'

GitLab

Connect GitLab Cloud or self-hosted GitLab instances using OAuth.

Configuration

string

required

Display name for this Git provider connection

string

default:"https://gitlab.com"

required

GitLab instance URL

# GitLab Cloud
https://gitlab.com

# Self-hosted
https://gitlab.example.com

string

Internal URL for GitLab if different from external URL (useful for Docker networking)

http://gitlab.internal:8080

string

OAuth Application ID from GitLab

string

OAuth Application Secret from GitLab

string

OAuth redirect URI

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

string

GitLab group name to restrict repository access

string

OAuth access token (obtained after authentication)

string

OAuth refresh token for renewing access

number

Access token expiration timestamp (Unix epoch)

Creating a GitLab OAuth Application

Go to GitLab Settings > Applications
Create a new application:
- Name: Dokploy
- Redirect URI: https://your-dokploy-domain.com/api/gitlab/callback
- Scopes: api, read_user, read_repository
Save the Application ID and Secret

Example Configuration

const gitlab = await fetch('https://your-domain.com/api/trpc/gitlab.create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.API_KEY
  },
  body: JSON.stringify({
    name: 'GitLab Production',
    gitlabUrl: 'https://gitlab.com',
    gitlabInternalUrl: null,
    applicationId: 'abc123...',
    secret: 'secret_xyz...',
    redirectUri: 'https://dokploy.example.com/api/gitlab/callback',
    groupName: 'my-organization',
    authId: 'auth-123'
  })
});

Testing Connection

curl -X POST https://your-domain.com/api/trpc/gitlab.testConnection \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "gitlabId": "gitlab-123",
    "groupName": "my-organization"
  }'

Bitbucket

Connect Bitbucket Cloud using App Passwords or API tokens.

Configuration

string

required

Display name for this Git provider connection

string

Bitbucket username

string

Bitbucket account email

user@example.com

string

Bitbucket App PasswordCreate at: Bitbucket Settings > App passwords

string

Bitbucket API token (alternative to App Password)

string

Bitbucket workspace name

my-workspace

Creating a Bitbucket App Password

Go to Bitbucket Settings > App passwords
Create new app password with permissions:
- Repositories: Read, Write
- Webhooks: Read and write
- Pull requests: Read
Copy the generated password (shown only once)

Example Configuration

const bitbucket = await fetch('https://your-domain.com/api/trpc/bitbucket.create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.API_KEY
  },
  body: JSON.stringify({
    name: 'Bitbucket Main',
    bitbucketUsername: 'johndoe',
    bitbucketEmail: 'john@example.com',
    appPassword: 'ATBBxxxxxxxx',
    bitbucketWorkspaceName: 'my-workspace',
    authId: 'auth-123'
  })
});

Testing Connection

curl -X POST https://your-domain.com/api/trpc/bitbucket.testConnection \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "bitbucketId": "bitbucket-123",
    "bitbucketUsername": "johndoe",
    "bitbucketEmail": "john@example.com",
    "workspaceName": "my-workspace",
    "appPassword": "ATBBxxxxxxxx"
  }'

Gitea

Connect self-hosted Gitea instances using OAuth.

Configuration

string

required

Display name for this Git provider connection

string

required

Gitea instance URL

https://gitea.example.com

string

Internal URL for Gitea if different from external URL

http://gitea.internal:3000

string

OAuth Client ID from Gitea

string

OAuth Client Secret from Gitea

string

OAuth redirect URI

https://your-dokploy-domain.com/api/gitea/callback

string

OAuth access token (obtained after authentication)

string

OAuth refresh token for renewing access

number

Access token expiration timestamp (Unix epoch)

string

default:"repo,repo:status,read:user,read:org"

OAuth scopes

Creating a Gitea OAuth Application

Go to Gitea Settings > Applications > OAuth2 Applications
Create new OAuth2 application:
- Application Name: Dokploy
- Redirect URI: https://your-dokploy-domain.com/api/gitea/callback
Save the Client ID and Client Secret

Example Configuration

const gitea = await fetch('https://your-domain.com/api/trpc/gitea.create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.API_KEY
  },
  body: JSON.stringify({
    name: 'Gitea Production',
    giteaUrl: 'https://gitea.example.com',
    giteaInternalUrl: 'http://gitea.internal:3000',
    clientId: 'client-id-123',
    clientSecret: 'client-secret-xyz',
    redirectUri: 'https://dokploy.example.com/api/gitea/callback',
    scopes: 'repo,repo:status,read:user,read:org'
  })
});

Managing Git Providers

List All Providers

curl https://your-domain.com/api/trpc/gitProvider.getAll \
  -H "x-api-key: your-api-key"

Response:

[
  {
    "gitProviderId": "provider-123",
    "name": "GitHub Production",
    "providerType": "github",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "github": { /* GitHub-specific config */ },
    "gitlab": null,
    "bitbucket": null,
    "gitea": null
  }
]

Remove Provider

curl -X POST https://your-domain.com/api/trpc/gitProvider.remove \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"gitProviderId": "provider-123"}'

Removing a Git provider will affect all applications using it for deployment.

Provider Types

The providerType field indicates which Git service is configured:

type GitProviderType = 'github' | 'gitlab' | 'bitbucket' | 'gitea';

Database Schema

// Main git_provider table
{
  gitProviderId: string;        // Unique identifier
  name: string;                 // Display name
  providerType: GitProviderType; // Provider type
  createdAt: string;            // Creation timestamp
  organizationId: string;       // Owner organization
  userId: string;               // Creator user
}

// Provider-specific tables
github: { /* GitHub configuration */ }
gitlab: { /* GitLab configuration */ }
bitbucket: { /* Bitbucket configuration */ }
gitea: { /* Gitea configuration */ }

Authorization

Git providers are scoped to organizations
Users can only access providers in their active organization
Deleting an organization cascades to its Git providers

Best Practices

Security

Rotate Tokens: Regularly rotate OAuth tokens and App Passwords
Minimal Permissions: Grant only necessary permissions
Separate Apps: Use different apps for development and production
Audit Access: Review provider access regularly

Performance

Internal URLs: Use internal URLs for faster Docker network communication
Token Refresh: Implement automatic token refresh for OAuth providers
Cache: Cache repository and branch lists when possible

Organization

Naming: Use descriptive names (e.g., “GitHub Production”, “GitLab Dev”)
Documentation: Document which apps use which providers
Backup: Keep credentials backed up securely

Troubleshooting

Common Issues

Authentication Failed

Verify OAuth credentials are correct
Check token hasn’t expired
Ensure redirect URI matches exactly
Confirm required scopes are granted

Cannot Access Repositories

Verify Git provider has access to repositories
Check group/workspace name is correct
Ensure proper permissions are granted
Confirm organization/workspace exists

Webhooks Not Working

Verify webhook URL is accessible from Git provider
Check webhook secret matches configuration
Ensure webhook events are configured
Review webhook delivery logs on Git provider

Example: Complete Setup

// 1. Create GitHub provider
const github = await createGitHubProvider({
  name: 'GitHub Production',
  githubAppId: 123456,
  // ... other config
});

// 2. Create application using the provider
const app = await createApplication({
  name: 'My App',
  gitProviderId: github.gitProviderId,
  repository: 'owner/repo',
  branch: 'main'
});

// 3. Deploy
await deployApplication(app.applicationId);

​Overview

​Supported Providers

​GitHub

​Configuration

​Creating a GitHub App

​Example Configuration

​Fetching Branches

​GitLab

​Configuration

​Creating a GitLab OAuth Application

​Example Configuration

​Testing Connection

​Bitbucket

​Configuration

​Creating a Bitbucket App Password

​Example Configuration

​Testing Connection

​Gitea

​Configuration

​Creating a Gitea OAuth Application

​Example Configuration

​Managing Git Providers

​List All Providers

​Remove Provider

​Provider Types

​Database Schema

​Authorization

​Best Practices

​Security

​Performance

​Organization

​Troubleshooting

​Common Issues

​Example: Complete Setup

Overview

Supported Providers

GitHub

Configuration

Creating a GitHub App

Example Configuration

Fetching Branches

GitLab

Configuration

Creating a GitLab OAuth Application

Example Configuration

Testing Connection

Bitbucket

Configuration

Creating a Bitbucket App Password

Example Configuration

Testing Connection

Gitea

Configuration

Creating a Gitea OAuth Application

Example Configuration

Managing Git Providers

List All Providers

Remove Provider

Provider Types

Database Schema

Authorization

Best Practices

Security

Performance

Organization

Troubleshooting

Common Issues

Example: Complete Setup