GitHub Integration

Connect GitHub repositories using GitHub Apps for secure automated deployments

GitHub integration in Dokploy uses GitHub Apps for authentication, providing enterprise-grade security and fine-grained repository access control.

Features

• GitHub App authentication with installation-based access
• Automatic webhook configuration
• Support for push, tag, and pull request events
• Preview deployments for pull requests
• Collaborator permission validation
• Submodule support

Prerequisites

• A GitHub account (personal or organization)
• Admin access to the repositories you want to deploy
• Your Dokploy instance must be accessible from the internet for webhooks

Creating a GitHub App

1. Navigate to GitHub Settings

   Go to your GitHub account or organization settings:

   • Personal Account: Settings → Developer settings → GitHub Apps → New GitHub App
   • Organization: Settings → Developer settings → GitHub Apps → New GitHub App
2. Configure Basic Information

   Fill in the GitHub App details:

   GitHub App name: Choose a unique name (e.g., Dokploy-Production)

   Homepage URL: Your Dokploy instance URL (e.g., https://dokploy.yourdomain.com)

   Webhook URL: https://your-dokploy-domain.com/api/deploy/github

   The webhook URL must be publicly accessible for GitHub to send events.

3. Set Webhook Secret

   Generate a secure webhook secret:

   openssl rand -hex 32
   

   Save this secret - you’ll need it when configuring the provider in Dokploy.

4. Configure Permissions

   Set the following repository permissions:

   Permission	Access	Purpose
   Contents	Read	Clone repositories
   Metadata	Read	Access repository information
   Pull requests	Read & Write	Preview deployments and comments
   Issues	Read & Write	Post deployment status comments
   Administration	Read	Check collaborator permissions

   Administration permission is only needed if using preview deployment security features.

5. Subscribe to Events

   Enable webhook events:

   • Push
   • Pull request
   • Create (for tag deployments)
6. Set Installation Location

   Choose where the app can be installed:

   • Only on this account: Restricts to your account/organization
   • Any account: Allows installation on any GitHub account

   For most use cases, select “Only on this account”.

7. Create the App

   Click Create GitHub App to finalize creation.

8. Generate Private Key

   After creation:

   1. Scroll to “Private keys” section
   2. Click Generate a private key
   3. Save the downloaded .pem file securely

   Store the private key safely. You cannot download it again.

9. Note Important Values

   Copy these values for Dokploy configuration:

   • App ID: Found at the top of the app settings page
   • Client ID: In the “About” section
   • Client Secret: Generate if needed in “Client secrets” section

Installing the GitHub App

1. Install the App

   1. Go to your GitHub App settings page
   2. Click Install App in the left sidebar
   3. Select the account to install on
   4. Choose repository access:
      • All repositories: Grant access to all current and future repos
      • Only select repositories: Choose specific repositories
2. Get Installation ID

   After installation, note the installation ID from the URL:

   https://github.com/settings/installations/12345678
                                             ^^^^^^^^
                                             Installation ID
   

Configuring in Dokploy

1. Navigate to Git Providers

   In Dokploy dashboard:

   1. Go to Settings → Git Providers
   2. Click Add Git Provider
   3. Select GitHub
2. Enter Configuration

   Fill in the GitHub App details:

   Provider Name: A friendly name (e.g., “GitHub Production”)

   GitHub App Name: Your GitHub App name

   App ID: The App ID from GitHub

   Client ID: The Client ID from GitHub

   Client Secret: The Client Secret from GitHub

   Installation ID: The installation ID from the installation URL

   Private Key: Paste the entire contents of the .pem file

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

   Webhook Secret: The webhook secret you generated

3. Test Connection

   Click Test Connection to verify:

   • Private key is valid
   • Installation ID is correct
   • App has access to repositories

   The test displays the number of accessible repositories.

4. Save Provider

   Click Save to store the GitHub provider configuration.

Using GitHub in Applications

Deploying from GitHub

1. Create or Edit Application

   When creating a new application or editing an existing one:

   1. Set Source Type to “Git”
   2. Select your GitHub provider from the dropdown
2. Select Repository

   Choose from your accessible repositories:

   • Repositories appear as owner/repository-name
   • Only repositories the App has access to are shown
3. Configure Branch

   Select the branch to deploy from (e.g., main, production)

4. Enable Auto Deploy (Optional)

   Toggle Auto Deploy to enable webhook-based deployments:

   Trigger Type:

   • Push: Deploy on commits to the selected branch
   • Tag: Deploy when tags are created

   Watch Paths (optional):

   ["src/**", "package.json", "Dockerfile"]
   

   Only deploy when these paths are modified.

Preview Deployments

Enable preview deployments for pull requests:

1. Enable Preview Deployments

   In your application settings:

   1. Toggle Preview Deployments
   2. Set Preview Limit: Maximum concurrent preview deployments (e.g., 5)
2. Configure Security (Recommended)

   Require Collaborator Permissions: When enabled, only users with write/maintain/admin access can trigger preview deployments.

   Disabling this security feature allows any GitHub user to trigger deployments through pull requests, potentially exposing your infrastructure.

   When a non-collaborator opens a PR, Dokploy:

   1. Blocks the deployment
   2. Posts a security notification comment
   3. Provides instructions for resolution
3. Label Filtering (Optional)

   Restrict previews to PRs with specific labels:

   ["preview", "deploy"]
   

   Only PRs with these labels trigger preview deployments.

4. Preview Deployment Flow

   When a PR is opened/updated:

   1. Dokploy validates permissions (if enabled)
   2. Creates a preview deployment
   3. Posts a comment with deployment status
   4. Updates the comment when deployment completes
   5. Includes a link to the preview URL

   When the PR is closed, preview deployments are automatically cleaned up.

Webhook Events

Push Events

Triggered when commits are pushed to a branch:

{
  "ref": "refs/heads/main",
  "repository": {
    "name": "my-app",
    "owner": { "name": "username" }
  },
  "commits": [
    {
      "message": "Update feature",
      "modified": ["src/index.ts"]
    }
  ]
}

Dokploy matches:

• Repository name and owner
• Branch name
• Watch paths (if configured)

Tag Events

Triggered when tags are created:

{
  "ref": "refs/tags/v1.0.0",
  "repository": {
    "name": "my-app",
    "owner": { "name": "username" }
  }
}

Applications configured with triggerType: tag deploy automatically.

Pull Request Events

Triggered on PR actions (opened, synchronize, reopened, closed):

{
  "action": "opened",
  "pull_request": {
    "id": 123456,
    "number": 42,
    "title": "Add new feature",
    "head": { "ref": "feature-branch", "sha": "abc123" },
    "base": { "ref": "main" },
    "user": { "login": "contributor" }
  }
}

Creates or updates preview deployments.

Troubleshooting

Webhooks Not Triggering

1. Check Webhook URL: Ensure it’s publicly accessible
2. Verify Webhook Secret: Must match in GitHub and Dokploy
3. Check Recent Deliveries: In GitHub App settings → Advanced → Recent Deliveries
4. Review Response Codes:
   • 200: Success
   • 401: Invalid webhook secret
   • 400: Missing installation or configuration error

Testing Webhooks:

GitHub provides a “Redeliver” button in Recent Deliveries to resend webhook payloads.

Cannot Access Repositories

1. Verify Installation: Check the app is installed on the correct account
2. Check Repository Access: Ensure specific repos are selected if not using “All repositories”
3. Reinstall App: Sometimes reinstallation resolves access issues
4. Test Connection: Use the “Test Connection” button in Dokploy

Private Key Errors

1. Check Format: Ensure the entire key including headers is pasted:
   -----BEGIN RSA PRIVATE KEY-----
   ...
   -----END RSA PRIVATE KEY-----
   
2. No Extra Whitespace: Remove trailing spaces or newlines
3. Regenerate if Needed: Generate a new private key if corrupted

Preview Deployments Not Created

1. Check Base Branch: Preview deployments match the base branch, not the PR branch
2. Verify Labels: If using label filtering, ensure PR has required labels
3. Check Limit: Preview limit might be reached
4. Review Permissions: If security is enabled, verify contributor has write access

Submodules Not Cloning

1. Enable Submodules: Toggle “Enable Submodules” in application settings
2. Check Submodule Access: Ensure GitHub App has access to submodule repositories
3. Use HTTPS URLs: Submodules should use HTTPS, not SSH URLs

Security Best Practices

Follow these security practices to protect your infrastructure:

1. Webhook Secret

• Use a strong, randomly generated secret (minimum 32 characters)
• Never commit the secret to version control
• Rotate periodically (update in both GitHub and Dokploy)

2. Repository Access

• Grant access only to necessary repositories
• Use “Only select repositories” when possible
• Review and audit access regularly

3. Preview Deployment Security

• Always enable Require Collaborator Permissions for preview deployments
• Review the security notification system is working
• Monitor who has write access to repositories

4. Private Key Protection

• Store the .pem file securely offline
• Never share or commit private keys
• Use separate GitHub Apps for production and development

5. Principle of Least Privilege

• Only enable required webhook events
• Grant minimum necessary permissions
• Create separate apps for different environments

Advanced Configuration

Multiple GitHub Apps

You can configure multiple GitHub providers:

• Production App: For production repositories
• Development App: For staging/dev repositories
• Organization Apps: Separate apps per organization

Each app maintains separate:

• Access permissions
• Webhook configurations
• Rate limits

Watch Paths for Monorepos

For monorepo deployments:

{
  "watchPaths": ["apps/api/**", "packages/shared/**"]
}

Deploys only when specific app directories change.

Custom Deployment Comments

Preview deployment comments include:

• Application name
• Deployment status (Building, Done, Failed)
• Preview URL with clickable link
• Timestamp (UTC)

Format:

### Dokploy Preview Deployment

| Name    | Status  | Preview                              | Updated (UTC)           |
|---------|---------|--------------------------------------|-------------------------|
| my-app  | ✅ Done | [Preview URL](https://preview.url)  | 2024-01-15T10:30:00.000Z |

API Reference

The GitHub integration uses these API endpoints:

Repository Listing

octokit.rest.apps.listReposAccessibleToInstallation()

Returns all repositories accessible to the installed GitHub App.

Branch Listing

octokit.rest.repos.listBranches({
  owner: "username",
  repo: "repository"
})

Fetches all branches for a repository.

Permission Check

octokit.rest.repos.getCollaboratorPermissionLevel({
  owner: "username",
  repo: "repository",
  username: "contributor"
})

Validates user permissions for preview deployment security.

Next Steps

Deploy an Application

Create your first deployment from GitHub

Preview Deployments

Enable PR preview environments

Docker Compose

Deploy multi-container applications

Git Providers Overview

Compare all Git provider options