Gitea Integration

Gitea integration in Dokploy uses OAuth 2.0 authentication with support for self-hosted Gitea instances.

Features

OAuth 2.0 authentication with automatic token refresh
Support for self-hosted Gitea instances
Repository and branch browsing
Automatic token refresh with expiry management
Internal URL support for same-network deployments
Lightweight and fast API integration

Prerequisites

A Gitea instance (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 Gitea OAuth Application

Navigate to Applications

In your Gitea instance:

Sign in to your Gitea account
Go to Settings → Applications
Scroll to “Manage OAuth2 Applications”
Click Create a new OAuth2 Application

Configure Application Details

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

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

The redirect URI must match exactly. Gitea does not allow URI patterns.

Create Application

Click Create Application to generate the OAuth credentials.

Copy Credentials

After creation, save these values:

Client ID: Used for OAuth authentication
Client Secret: Used for token exchange

The client 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 Gitea

Enter Configuration

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

https://gitea.yourdomain.com

Gitea Internal URL (optional): For same-network deployments

http://gitea:3000

Internal URL improves performance when Dokploy and Gitea are on the same network.

Client ID: The Client ID from GiteaClient Secret: The Client Secret from Gitea

Save and Authorize

Click Save
You’ll be redirected to your Gitea instance
Review the requested permissions
Click Authorize Application
You’ll be redirected back to Dokploy

Test Connection

After authorization:

Click Test Connection
Verify the number of accessible repositories

The test confirms:

OAuth tokens are valid
API access is working
Repositories are accessible

OAuth Scopes

Gitea OAuth applications request these scopes:

repo - Full repository access
repo:status - Repository commit status
read:user - Read user profile
read:org - Read organization membership

These scopes allow Dokploy to:

List accessible repositories
Clone repositories
Read repository branches
Access user and organization information

Using Gitea in Applications

Deploying from Gitea

Create or Edit Application

When creating/editing an application:

Set Source Type to “Git”
Select your Gitea provider

Select Repository

Choose from accessible repositories:

Format: owner/repository-name
Includes personal and organization repositories
Only repositories you have access to are shown

Configure Branch

Select the branch to deploy from:

main
master
develop
Any custom branch

Enable Auto Deploy (Optional)

Configure automatic deployment triggers:Auto Deploy: Toggle to enableTrigger Type: Push (for commit-based deployments)

Webhook support for Gitea is planned for future releases.

Repository Structure

Gitea repositories are returned in this format:

{
  id: 123,
  name: "my-app",
  url: "username/my-app",  // Full path used for cloning
  owner: {
    username: "username"
  }
}

Token Management

Automatic Token Refresh

Dokploy automatically manages token lifecycle:

Expiry Check: Before each operation, checks if token expires within 5 minutes

Refresh Flow:

POST {giteaUrl}/login/oauth/access_token
{
  grant_type: "refresh_token",
  refresh_token: "...",
  client_id: "...",
  client_secret: "..."
}

Update Storage: Stores new access and refresh tokens
Continue Operation: Uses refreshed token automatically

Token Expiration

Default Expiry: 1 hour (3600 seconds)
Refresh Buffer: 5 minutes before expiry
Stored as Unix Timestamp: expiresAt field
Automatic Retry: Falls back to existing token if refresh fails

Manual Reauthorization

If automatic refresh fails:

Go to Settings → Git Providers
Click on your Gitea provider
Click Reconnect or Reauthorize
Complete OAuth flow again

API Integration

Repository Listing

Fetches user’s repositories with pagination:

GET {giteaUrl}/api/v1/user/repos?page=1&limit=50
Authorization: token {accessToken}

Pagination:

50 repositories per page (Gitea maximum)
Automatically fetches all pages
Includes personal and organization repos

Response:

[
  {
    "id": 123,
    "name": "my-app",
    "full_name": "username/my-app",
    "owner": {
      "login": "username"
    }
  }
]

Branch Listing

Fetches branches for a repository:

GET {giteaUrl}/api/v1/repos/{owner}/{repo}/branches?page=1&limit=50
Authorization: token {accessToken}

Response:

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

Repository Cloning

Clone command using OAuth token:

git clone --branch {branch} --depth 1 \
  https://oauth2:{accessToken}@{giteaUrl}/{owner}/{repository}.git \
  {outputPath}

Features:

OAuth2 token authentication format
Shallow clone for faster deployments
Optional submodule support with --recurse-submodules

Internal URL Configuration

When to Use Internal URLs

Use internal URLs when:

Dokploy and Gitea are on the same network
Gitea is accessible via internal hostname/IP
You want to reduce latency and bandwidth

Configuration Example

Gitea URL: https://gitea.company.com       # External, for OAuth redirect
Gitea Internal URL: http://gitea:3000       # Internal, for API and git operations

What Uses Which URL

External URL (giteaUrl):

OAuth authorization redirect
OAuth callback validation
User-facing links

Internal URL (giteaInternalUrl) when set:

Token exchange
Token refresh
API calls (repository, branch listing)
Git clone operations

HTTP vs HTTPS

External: Should always use HTTPS for OAuth security
Internal: Can use HTTP if on trusted network

Troubleshooting

OAuth Authorization Fails

Symptoms: “Invalid redirect URI” or “Application not found”Solutions:

Check Redirect URI: Must exactly match:

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

Verify Gitea URL: Ensure Gitea URL is accessible from browser
Check Application Status: Ensure OAuth app is not deleted
Review State Parameter: Clear browser cache and retry

No Repositories Listed

Symptoms: Test connection succeeds but no repositories availableSolutions:

Check Permissions: Verify you have access to repositories
Create Test Repository: Create a repo to verify API access

Test API Manually:

curl -H "Authorization: token YOUR_TOKEN" \
  https://gitea.yourdomain.com/api/v1/user/repos

Review Scopes: Ensure OAuth app has repo scope

Token Refresh Errors

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

Check Internal URL: If set, must be accessible from Dokploy server
Verify Client Secret: Ensure secret is correct

Test Token Endpoint:

curl -X POST https://gitea.yourdomain.com/login/oauth/access_token \
  -d "grant_type=refresh_token&refresh_token=...&client_id=...&client_secret=..."

Reauthorize: Remove and re-add provider

Clone Failures

Symptoms: “Error: Gitea Provider not found” or “Repository configuration failed”Solutions:

Verify Configuration:
- Repository name
- Owner/username
- Branch name
Check Token: Use Test Connection to verify

Test Git Access:

git ls-remote https://oauth2:TOKEN@gitea.yourdomain.com/owner/repo.git

Review Logs: Check deployment logs for specific errors

Connection Timeout

Symptoms: Requests to Gitea timeout or hangSolutions:

Check Network: Ensure Dokploy can reach Gitea
Verify Firewall: Check firewall rules allow connection
Test Connectivity:
```
curl -I https://gitea.yourdomain.com
```
Use Internal URL: If on same network, configure internal URL

Security Best Practices

1. OAuth Application Security

Follow these practices to secure your Gitea integration:

Store Client Secret Securely: Never commit to version control
Rotate Credentials: Periodically regenerate client secret
Limit Scope: Request only necessary OAuth scopes
Monitor Access: Review authorized applications regularly

2. Network Security

Use HTTPS: Always use HTTPS for external Gitea URL
Internal Network: Isolate internal URL to trusted network
Firewall Rules: Restrict access to Gitea instance
Regular Updates: Keep Gitea updated to latest version

3. Token Protection

Encrypted Storage: Tokens encrypted in Dokploy database
No Logging: Tokens never logged or displayed
Automatic Expiry: Tokens automatically refreshed
Revocation: Removing provider invalidates tokens

4. Access Control

Repository Permissions: Only accessible repos are shown
User-Level OAuth: Each Dokploy user has separate OAuth tokens
Organization Access: Review organization membership

Advanced Configuration

Multiple Gitea Providers

Configure multiple providers for: Different Instances:

Provider 1:
  Name: Gitea Production
  URL: https://gitea.company.com

Provider 2:
  Name: Gitea Staging
  URL: https://gitea-staging.company.com

Different Users:

Provider 1:
  Name: Personal Gitea
  OAuth User: john@example.com

Provider 2:
  Name: Team Gitea
  OAuth User: team@example.com

Each provider maintains:

Separate OAuth tokens
Independent repository access
Isolated configuration

Submodule Support

Enable submodules in your application:

Toggle Enable Submodules in application settings
Ensure submodule repositories are accessible with same token
Submodules use the same OAuth token for authentication

Clone command with submodules:

git clone --branch main --depth 1 --recurse-submodules \
  https://oauth2:TOKEN@gitea.yourdomain.com/owner/repo.git

Watch Paths for Monorepos

For selective deployments in monorepos:

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

Watch paths currently work with manual deployments. Webhook support coming soon.

API Reference

Authentication Header

All API requests use token authentication:

Authorization: token {accessToken}

Endpoints Used

User Repositories:

GET /api/v1/user/repos

Repository Branches:

GET /api/v1/repos/{owner}/{repo}/branches

OAuth Token Exchange:

POST /login/oauth/access_token

Rate Limiting

Gitea has configurable rate limits. Default:

Authenticated requests: 5000 per hour
Unauthenticated: 60 per hour

Dokploy uses authenticated requests, well within limits.

Comparison with Other Providers

Feature	Gitea	GitHub	GitLab
Self-Hosted	✅ Yes	❌ No	✅ Yes
OAuth 2.0	✅ Yes	✅ App	✅ Yes
Auto Refresh	✅ Yes	✅ Yes	✅ Yes
Webhooks	🔜 Soon	✅ Yes	🔜 Soon
Internal URL	✅ Yes	❌ N/A	✅ Yes
Lightweight	✅ Yes	❌ N/A	❌ No

Performance Optimization

1. Use Internal URLs

When on same network:

Reduces latency by 50-200ms
Avoids external network routing
Faster token operations

2. Connection Pooling

Dokploy reuses connections for:

Multiple API calls
Token refresh operations
Repository browsing

3. Pagination Efficiency

Fetches 50 repos per page (maximum)
Parallel page fetching
Stops when all pages retrieved

Future Enhancements

Planned features for Gitea integration:

Webhooks: Automatic deployment on push events
Organization Filtering: Filter repositories by organization
Deploy Keys: Support for deploy key authentication
Tag Deployments: Deploy on tag creation
Pull Request Previews: Preview deployments for pull requests

Next Steps

Deploy an Application

Create your first deployment from Gitea

GitHub Integration

Compare with GitHub integration

GitLab Integration

Compare with GitLab integration

Git Providers Overview

Compare all Git provider options

Git Providers

Notifications

Authentication

​Features

​Prerequisites

​Creating a Gitea OAuth Application

​Configuring in Dokploy

​OAuth Scopes

​Using Gitea in Applications

​Deploying from Gitea

​Repository Structure

​Token Management

​Automatic Token Refresh

​Token Expiration

​Manual Reauthorization

​API Integration

​Repository Listing

​Branch Listing

​Repository Cloning

​Internal URL Configuration

​When to Use Internal URLs

​Configuration Example

​What Uses Which URL

​HTTP vs HTTPS

​Troubleshooting

​Security Best Practices

​1. OAuth Application Security

​2. Network Security

​3. Token Protection

​4. Access Control

​Advanced Configuration

​Multiple Gitea Providers

​Submodule Support

​Watch Paths for Monorepos

​API Reference

​Authentication Header

​Endpoints Used

​Rate Limiting

​Comparison with Other Providers

​Performance Optimization

​1. Use Internal URLs

​2. Connection Pooling

​3. Pagination Efficiency

​Future Enhancements

​Next Steps

Deploy an Application

GitHub Integration

GitLab Integration

Git Providers Overview

Features

Prerequisites

Creating a Gitea OAuth Application

Configuring in Dokploy

OAuth Scopes

Using Gitea in Applications

Deploying from Gitea

Repository Structure

Token Management

Automatic Token Refresh

Token Expiration

Manual Reauthorization

API Integration

Repository Listing

Branch Listing

Repository Cloning

Internal URL Configuration

When to Use Internal URLs

Configuration Example

What Uses Which URL

HTTP vs HTTPS

Troubleshooting

Security Best Practices

1. OAuth Application Security

2. Network Security

3. Token Protection

4. Access Control

Advanced Configuration

Multiple Gitea Providers

Submodule Support

Watch Paths for Monorepos

API Reference

Authentication Header

Endpoints Used

Rate Limiting

Comparison with Other Providers

Performance Optimization

1. Use Internal URLs

2. Connection Pooling

3. Pagination Efficiency

Future Enhancements

Next Steps