Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Nettalco/dokploy/llms.txt

Use this file to discover all available pages before exploring further.

Connecting a Git provider to Dokploy gives it permission to list your repositories and branches, register webhooks on your behalf, and automatically trigger a new deployment every time you push to a watched branch. Once a provider is linked, you can select it as the source for any application or Docker Compose service without leaving the Dokploy dashboard.

​
Supported Providers

GitHub

Connect via a GitHub App for fine-grained repository access and automatic webhook management.

GitLab

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

Bitbucket

Connect via a Bitbucket OAuth consumer with an app password or API token.

Gitea

Connect to any self-hosted Gitea instance using an OAuth2 application and access token.

​
GitHub

Dokploy integrates with GitHub through a GitHub App, which gives you granular control over which repositories the integration can access and automatically handles webhook delivery.
1

Open Git Providers settings

In the Dokploy dashboard, go to Settings → Git Providers and click Add Git Provider → GitHub.
2

Create a GitHub App

Follow the link Dokploy provides to create a new GitHub App in your GitHub account or organisation. During creation:
  • Set the Webhook URL to the callback URL shown in Dokploy.
  • Copy the generated Webhook Secret back into the Dokploy form.
  • Download the Private Key (.pem file) and paste its contents into the Private Key field.
  • Note the App ID shown on the GitHub App page.
3

Install the app

Install the GitHub App on the repositories you want Dokploy to access. GitHub will redirect you back to Dokploy after installation and automatically populate the Installation ID.
4

Save and verify

Click Update to call github.update, which persists the App ID, installation ID, private key, and webhook secret. Then click Test Connection to invoke github.testConnection — it will return the number of accessible repositories (e.g. Found 12 repositories). If the count looks correct, your provider is ready.
After setup, github.getGithubRepositories populates the repository picker when you create or edit an application, and github.getGithubBranches populates the branch picker for the selected repository.
The GitHub App’s private key is stored encrypted. Dokploy never exposes it through the API after the initial save.

​
GitLab

GitLab integration uses an OAuth application to obtain access and refresh tokens. Dokploy supports both GitLab.com and self-managed GitLab instances.
1

Open Git Providers settings

Go to Settings → Git Providers → Add Git Provider → GitLab.
2

Create a GitLab OAuth application

In GitLab, navigate to User Settings → Applications (or Admin Area → Applications for an instance-wide app). Create a new application with:
  • Redirect URI: the callback URL shown in Dokploy.
  • Scopes: api, read_user, read_repository.
Copy the Application ID (client ID) and Secret.
3

Enter your GitLab URL

If you are using a self-hosted GitLab instance, replace the default https://gitlab.com with your instance URL (e.g. https://git.example.com). This URL is stored and used by gitlab.getGitlabRepositories and gitlab.getGitlabBranches for all subsequent API calls.
4

Authorise and save

Paste the Application ID and Secret into the form, then click Authorise. Dokploy will redirect you through the GitLab OAuth flow and store the resulting tokens. gitlab.create (or gitlab.update) persists the provider record.
5

Test the connection

Click Test Connection to call gitlab.testConnection. A successful result returns the total number of accessible projects.
gitlab.getGitlabRepositories lists all projects visible to the authenticated user. gitlab.getGitlabBranches accepts a gitlabId and project identifier to return the branch list for a specific repository.

​
Bitbucket

Dokploy connects to Bitbucket using an OAuth consumer (workspace-level app) together with an API token.
1

Create an OAuth consumer in Bitbucket

In Bitbucket, go to Workspace Settings → OAuth consumers and add a consumer. Set the Callback URL to the value shown in Dokploy. Grant at minimum Repositories: Read and Webhooks: Read and write permissions.
2

Generate an API token

In your Bitbucket account settings, generate an App password (or API token). The app password approach is deprecated; using an API token is strongly recommended.
3

Add the provider in Dokploy

Go to Settings → Git Providers → Add Git Provider → Bitbucket. Enter your Bitbucket username, the OAuth consumer key, the OAuth consumer secret, and your API token, then click Save. Dokploy calls bitbucket.create to persist the record.
4

Test the connection

Click Test Connection. Dokploy calls bitbucket.testConnection and returns the number of repositories found in your workspace.
Once configured, bitbucket.getBitbucketRepositories lists repositories for the linked workspace, and bitbucket.getBitbucketBranches returns the branches for a selected repository.

​
Gitea

Dokploy supports any self-hosted Gitea instance through its OAuth2 application flow.
1

Create an OAuth2 application in Gitea

In your Gitea instance, navigate to User Settings → Applications → Manage OAuth2 Applications and create a new application. Set the Redirect URI to the callback URL shown in Dokploy.
2

Add the provider in Dokploy

Go to Settings → Git Providers → Add Git Provider → Gitea. Enter:
  • Gitea URL: the base URL of your instance (e.g. https://gitea.example.com). This is persisted and retrievable via gitea.getGiteaUrl.
  • Client ID and Client Secret from the OAuth2 application you just created.
Click Save. Dokploy calls gitea.create to store the provider.
3

Authorise Dokploy

Click Authorise to complete the OAuth2 flow. Gitea will redirect back to Dokploy and store the resulting access and refresh tokens.
4

Test the connection

Click Test Connection to invoke gitea.testConnection. A successful response returns the number of accessible repositories.
gitea.getGiteaRepositories lists all repositories visible to the authenticated user, and gitea.getGiteaBranches accepts a giteaId, owner, and repositoryName to return branches for a specific repository.

​
Using a Git Provider in an Application

After connecting a provider, you can select it as the deployment source for any application or Docker Compose service.
1

Create or edit a service

Open a project, click New Service → Application (or edit an existing one), and set the Source to Git.
2

Select the provider and repository

Choose the Git provider from the dropdown. Dokploy calls the appropriate getRepositories endpoint to populate the list. Select your repository.
3

Select a branch

Select the target branch. Dokploy calls the appropriate getBranches endpoint. The selected branch is watched for push events.
4

Save

Save the service. Dokploy automatically registers a webhook on the repository so that every push to the selected branch triggers a new deployment.
Webhook delivery requires your Dokploy server to be reachable from the internet on a public IP or hostname. If your server is behind a firewall or a private network, incoming webhook events from GitHub, GitLab, Bitbucket, or Gitea will not arrive, and automatic deployments will not trigger. You can still deploy manually at any time from the dashboard.

​
Sharing a Provider Across Your Organisation

By default, a Git provider is private to the user who created it. Owners and admins can share a provider with all members of the organisation by toggling the Share with organisation option on the provider settings page. Internally this calls gitProvider.toggleShare, which sets sharedWithOrganization: true on the provider record.
Only the owner of a provider can toggle sharing. The gitProvider.toggleShare mutation enforces this and returns an UNAUTHORIZED error if a non-owner attempts the action.

​
Disconnecting a Provider from a Service

To stop a service from being linked to a Git provider (for example, to switch to a Docker image source), use the Disconnect Git Provider action on the service’s settings page.
  • For applications, this calls application.disconnectGitProvider, which clears all Git-related fields (repository, branch, owner, githubId, gitlabId, bitbucketId, giteaId, etc.) and resets the source type.
  • For Docker Compose services, this calls compose.disconnectGitProvider, which clears the equivalent fields and sets composeStatus back to idle.
After disconnecting, the associated webhook is no longer active and pushes to the repository will not trigger deployments for that service.

​
Removing a Provider

To fully remove a Git provider from Dokploy, go to Settings → Git Providers, open the provider, and click Delete. This calls gitProvider.remove, which enforces that:
  • You belong to the same organisation as the provider.
  • You are either an owner or admin, or you are the user who originally created the provider.
Once removed, any services that were still linked to this provider will lose their webhook configuration and must be reconfigured with a different source.

Build docs developers (and LLMs) love

Get started for freeTalk to us