Git Integration

Overview

Dokploy integrates with major Git providers to enable automated deployments from your repositories. Connect once, deploy unlimited applications, and set up webhooks for continuous deployment.

Supported Git Providers

Dokploy supports deployments from:

GitHub

GitHub Cloud and GitHub Apps with fine-grained permissions

GitLab

GitLab Cloud and self-hosted GitLab instances

Bitbucket

Bitbucket Cloud with App Passwords

Gitea

Self-hosted Gitea instances

For detailed Git provider configuration, see Git Providers.

Application Configuration

GitHub

Deploy from GitHub repositories using an authenticated Git provider.

Connect Git Provider

First, set up your GitHub provider:

Navigate to Settings > Git Providers
Click Add Provider > GitHub
Complete OAuth authentication

Configure Application

{
  "name": "My Application",
  "sourceType": "github",
  "githubId": "github-provider-123",
  "repository": "myapp",
  "owner": "myorganization",
  "branch": "main",
  "buildPath": "/",
  "triggerType": "push",
  "autoDeploy": true,
  "watchPaths": ["app/**", "package.json"],
  "enableSubmodules": false
}

Set Trigger Type

Choose when to deploy:

Push - Deploy on every push to the branch
Tag - Deploy only when tags are created

{
  "triggerType": "push"  // or "tag"
}

Watch Paths

Deploy only when specific files or directories change:

{
  "watchPaths": [
    "src/**",           // Any file in src/
    "package.json",      // Package file changes
    "Dockerfile",        // Docker config changes
    "!**/*.md"          // Exclude markdown files
  ]
}

Watch paths use glob patterns. Prefix with ! to exclude paths.

Git Submodules

Enable submodule cloning for repositories with submodules:

{
  "enableSubmodules": true
}

This runs git submodule update --init --recursive during deployment.

GitLab

Deploy from GitLab repositories with OAuth integration.

{
  "name": "My Application",
  "sourceType": "gitlab",
  "gitlabId": "gitlab-provider-123",
  "gitlabRepository": "myapp",
  "gitlabOwner": "mygroup",
  "gitlabBranch": "main",
  "gitlabBuildPath": "/",
  "gitlabProjectId": 12345678,
  "gitlabPathNamespace": "mygroup/subgroup",
  "watchPaths": ["app/**"],
  "enableSubmodules": false
}

number

required

GitLab project ID (found in project settings)

string

required

Full namespace path including groups

# Single group
mygroup

# Nested groups
mygroup/subgroup

Bitbucket

Deploy from Bitbucket Cloud repositories.

{
  "name": "My Application",
  "sourceType": "bitbucket",
  "bitbucketId": "bitbucket-provider-123",
  "bitbucketRepository": "My App",
  "bitbucketRepositorySlug": "my-app",
  "bitbucketOwner": "myworkspace",
  "bitbucketBranch": "main",
  "bitbucketBuildPath": "/",
  "watchPaths": null,
  "enableSubmodules": false
}

string

required

URL-safe repository identifier

# Repository: "My App"
# Slug: "my-app"

Gitea

Deploy from self-hosted Gitea instances.

{
  "name": "My Application",
  "sourceType": "gitea",
  "giteaId": "gitea-provider-123",
  "giteaRepository": "myapp",
  "giteaOwner": "myuser",
  "giteaBranch": "main",
  "giteaBuildPath": "/",
  "watchPaths": null,
  "enableSubmodules": false
}

Custom Git

Deploy from any Git-compatible repository using SSH.

{
  "name": "My Application",
  "sourceType": "git",
  "customGitUrl": "git@gitlab.example.com:group/repo.git",
  "customGitBranch": "production",
  "customGitBuildPath": "/",
  "customGitSSHKeyId": "ssh-key-123",
  "watchPaths": null,
  "enableSubmodules": false
}

Generate SSH Key

ssh-keygen -t ed25519 -C "dokploy@server" -f ~/.ssh/dokploy_deploy

Add Public Key to Git Provider

Copy the public key to your Git provider:

cat ~/.ssh/dokploy_deploy.pub

GitHub: Settings > SSH and GPG keys > New SSH keyGitLab: Settings > SSH Keys > Add new keyGitea: Settings > SSH Keys > Add Key

Add Private Key to Dokploy

Navigate to Settings > SSH Keys
Click Add SSH Key
Paste the private key:
cat ~/.ssh/dokploy_deploy
Save the SSH key ID

Configure Application

Use the SSH key ID in your application configuration:

{
  "customGitSSHKeyId": "ssh-key-123"
}

Webhook Configuration

Set up webhooks for automatic deployments when code is pushed.

GitHub Webhooks

Get Webhook URL

In your Dokploy application:

Go to Settings > Git

Copy the webhook URL:

https://dokploy.example.com/api/deploy/github/app-123?refreshToken=abc123

Add Webhook to GitHub

Go to your GitHub repository
Navigate to Settings > Webhooks
Click Add webhook

Configure:

Payload URL: https://dokploy.example.com/api/deploy/github/app-123?refreshToken=abc123
Content type: application/json
Which events: Just the push event
Active: ✓

Click Add webhook

Verify Webhook

Make a test push to your repository
Check Recent Deliveries in GitHub webhook settings
Verify deployment started in Dokploy

GitLab Webhooks

Get Webhook URL

https://dokploy.example.com/api/deploy/gitlab/app-123?refreshToken=abc123

Add Webhook to GitLab

Go to your GitLab project
Navigate to Settings > Webhooks

Configure:

URL: https://dokploy.example.com/api/deploy/gitlab/app-123?refreshToken=abc123
Trigger: Push events
Branch filter: main (or your deployment branch)
Enable SSL verification: ✓

Click Add webhook

Test Webhook

Click Test > Push events
Verify successful response
Check deployment in Dokploy

Bitbucket Webhooks

Get Webhook URL

https://dokploy.example.com/api/deploy/bitbucket/app-123?refreshToken=abc123

Add Webhook to Bitbucket

Go to your Bitbucket repository
Navigate to Repository settings > Webhooks
Click Add webhook

Configure:

Title: Dokploy Deploy
URL: https://dokploy.example.com/api/deploy/bitbucket/app-123?refreshToken=abc123
Status: Active
Triggers: Repository push

Click Save

Gitea Webhooks

Get Webhook URL

https://dokploy.example.com/api/deploy/gitea/app-123?refreshToken=abc123

Add Webhook to Gitea

Go to your Gitea repository
Navigate to Settings > Webhooks
Click Add Webhook > Gitea

Configure:

Target URL: https://dokploy.example.com/api/deploy/gitea/app-123?refreshToken=abc123
HTTP Method: POST
POST Content Type: application/json
Trigger On: Push events
Branch filter: main
Active: ✓

Click Add Webhook

Build Path Configuration

Specify the directory containing your application code.

{
  "buildPath": "/",           // Root directory
  "buildPath": "/backend",    // Backend subdirectory
  "buildPath": "/services/api" // Nested directory
}

Use cases:

Monorepo with multiple applications
Separate frontend/backend directories
Microservices architecture

Preview Deployments

Create temporary deployments for pull requests and branches.

Enable Preview Deployments

{
  "isPreviewDeploymentsActive": true,
  "previewLimit": 3,                    // Max concurrent previews
  "previewWildcard": "pr-*.example.com", // Domain pattern
  "previewPort": 3000,
  "previewHttps": true,
  "previewPath": "/",
  "previewEnv": "PREVIEW=true\nENV=staging",
  "previewBuildArgs": "BUILD_ENV=preview",
  "previewLabels": ["preview", "ephemeral"],
  "previewRequireCollaboratorPermissions": true
}

How It Works

Open Pull Request

When a PR is opened, Dokploy creates a preview deployment:

# PR #42 creates deployment at:
pr-42.example.com

Automatic Updates

Preview updates automatically on new commits to the PR.

Comment Link

Dokploy comments on the PR with the preview URL:

🚀 Preview deployment ready!

**URL:** https://pr-42.example.com
**Commit:** abc123
**Status:** ✅ Deployed

Automatic Cleanup

Preview deployments are deleted when:

PR is merged
PR is closed
Preview limit is reached (oldest deleted first)

Preview deployments consume server resources. Set previewLimit based on available capacity.

Advanced Configuration

Patching Source Code

Apply patches to source code before building:

// Create patch
{
  "name": "Security fix",
  "content": "diff --git a/package.json b/package.json\nindex 1234567..89abcdef 100644\n--- a/package.json\n+++ b/package.json\n@@ -10,7 +10,7 @@\n-    \"express\": \"^4.17.1\"\n+    \"express\": \"^4.18.2\""
}

Patches are applied automatically during deployment after cloning the repository.

Disconnecting Git Provider

Remove Git integration from an application:

curl -X POST https://your-domain.com/api/trpc/application.disconnectGitProvider \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app-123"}'

This resets all Git-related fields to their defaults.

Deployment Source Priority

When multiple source types are configured, Dokploy uses this priority:

Drop - Direct ZIP upload (highest priority)
Docker - Pre-built Docker image
GitHub - GitHub repository
GitLab - GitLab repository
Gitea - Gitea repository
Bitbucket - Bitbucket repository
Git - Custom Git repository (lowest priority)

Best Practices

Repository Structure

Use Consistent Branch Names

# Production
main or master

# Staging
staging or develop

# Feature branches
feature/feature-name

Consistent naming simplifies webhook and deployment configuration.

Monorepo Structure

repo/
├── apps/
│   ├── frontend/     # buildPath: /apps/frontend
│   ├── backend/      # buildPath: /apps/backend
│   └── admin/        # buildPath: /apps/admin
├── packages/
│   └── shared/
└── package.json

Use buildPath to deploy different applications from the same repository.

Environment-Specific Branches

# Production application
branch: main
autoDeploy: true

# Staging application
branch: staging
autoDeploy: true

# Development application
branch: develop
autoDeploy: false  # Manual deploys only

Security

Protect Sensitive Branches - Enable branch protection on production branches
Review Permissions - Grant minimal permissions to Git providers
Rotate Tokens - Refresh access tokens regularly
Secure Webhooks - Use HTTPS and verify webhook signatures
Limit Preview Access - Enable previewRequireCollaboratorPermissions

Performance

Use Shallow Clones - Dokploy clones with --depth 1 by default
Cache Dependencies - Enable build caching for faster deployments
Watch Specific Paths - Avoid unnecessary deployments with watchPaths
Optimize Repository Size - Use .gitattributes to exclude large files

Troubleshooting

Webhook Not Triggering Deployments

Check webhook status:

Go to repository webhook settings
Check recent deliveries
Look for error messages

Common issues:

Incorrect webhook URL
Firewall blocking requests
Invalid refresh token
Webhook disabled in repository

Solution:

# Test webhook manually
curl -X POST 'https://dokploy.example.com/api/deploy/github/app-123?refreshToken=abc123' \
  -H 'Content-Type: application/json' \
  -d '{"ref": "refs/heads/main"}'

Repository Clone Failed

Symptoms: fatal: could not read from remote repositorySolutions:

Verify Git provider credentials:

curl -X POST https://your-domain.com/api/trpc/github.testConnection \
  -H "x-api-key: your-api-key" \
  -d '{"githubId": "github-123"}'

Check SSH key permissions (for custom Git):
chmod 600 ~/.ssh/dokploy_deploy
Verify repository exists and is accessible
Ensure Git provider has repo access

Submodule Clone Failed

Symptoms: Submodule directories are empty after cloneSolutions:

Enable submodule support:
{"enableSubmodules": true}
Verify submodule URLs are accessible
Check Git provider has access to submodule repositories

Test manual clone:

git clone --recurse-submodules <repo-url>

Wrong Branch Deployed

Symptoms: Deployment uses different branch than configuredSolutions:

Verify branch configuration:

// GitHub
{"branch": "main"}

// GitLab
{"gitlabBranch": "main"}

// Bitbucket
{"bitbucketBranch": "main"}

Check webhook branch filter
Ensure branch exists in repository

API Reference

Deploy from Git

curl -X POST https://your-domain.com/api/trpc/application.deploy \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app-123",
    "title": "Deploy from main",
    "description": "Deploying latest changes"
  }'

Save Git Provider

# GitHub
curl -X POST https://your-domain.com/api/trpc/application.saveGithubProvider \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "app-123",
    "githubId": "github-123",
    "repository": "myapp",
    "owner": "myorg",
    "branch": "main",
    "buildPath": "/",
    "watchPaths": ["src/**"],
    "triggerType": "push",
    "enableSubmodules": false
  }'

Get Repository Branches

# GitHub
curl https://your-domain.com/api/trpc/github.getGithubBranches \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "githubId": "github-123",
    "owner": "myorg",
    "repo": "myapp"
  }'

Next Steps

Build Configuration

Configure build methods and optimize builds

Environment Variables

Manage configuration and secrets

Git Providers

Detailed Git provider configuration

Docker Registry

Configure container registries

​Overview

​Supported Git Providers

GitHub

GitLab

Bitbucket

Gitea

​Application Configuration

​GitHub

​Watch Paths

​Git Submodules

​GitLab

​Bitbucket

​Gitea

​Custom Git

​Webhook Configuration

​GitHub Webhooks

​GitLab Webhooks

​Bitbucket Webhooks

​Gitea Webhooks

​Build Path Configuration

​Preview Deployments

​Enable Preview Deployments

​How It Works

​Advanced Configuration

​Patching Source Code

​Disconnecting Git Provider

​Deployment Source Priority

​Best Practices

​Repository Structure

​Security

​Performance

​Troubleshooting

​API Reference

​Deploy from Git

​Save Git Provider

​Get Repository Branches

​Next Steps

Build Configuration

Environment Variables

Git Providers

Docker Registry

Overview

Supported Git Providers

Application Configuration

GitHub

Watch Paths

Git Submodules

GitLab

Bitbucket

Gitea

Custom Git

Webhook Configuration

GitHub Webhooks

GitLab Webhooks

Bitbucket Webhooks

Gitea Webhooks

Build Path Configuration

Preview Deployments

Enable Preview Deployments

How It Works

Advanced Configuration

Patching Source Code

Disconnecting Git Provider

Deployment Source Priority

Best Practices

Repository Structure

Security

Performance

Troubleshooting

API Reference

Deploy from Git

Save Git Provider

Get Repository Branches

Next Steps