nuc/docs/gitea-coolify-auto-deploy.md

Gitea-Coolify Auto-Deploy Guide

Automatic deployment on git push using Coolify's manual webhook integration with self-hosted Gitea.

Architecture

Developer → git push → Gitea → Webhook → Coolify → Build & Deploy

Prerequisites

1. Deploy Key for Git Access

Apps use SSH deploy keys to pull code from Gitea:

Resource	Value
Deploy Key UUID	akssgwowsccgwgoggs4ks8ck
Gitea Container	gitea-ho0cwgcwos88cwc48g84c0g8
SSH Port	22222 (external) → 22 (internal)

2. Network Connectivity

Gitea container must be on the coolify network:

docker network connect coolify gitea-ho0cwgcwos88cwc48g84c0g8

3. ⚠️ CRITICAL: Gitea Webhook Allowed Hosts

Gitea blocks webhooks to internal hosts by default. You MUST configure ALLOWED_HOST_LIST in Gitea's app.ini.

# Add [webhook] section to Gitea's app.ini
ssh nuc "docker exec gitea-ho0cwgcwos88cwc48g84c0g8 sh -c 'echo \"\" >> /data/gitea/conf/app.ini && echo \"[webhook]\" >> /data/gitea/conf/app.ini && echo \"ALLOWED_HOST_LIST = coolify,10.0.1.5,192.168.1.3,localhost,host.docker.internal,external\" >> /data/gitea/conf/app.ini'"

# Restart Gitea
ssh nuc "docker restart gitea-ho0cwgcwos88cwc48g84c0g8"

# Verify
ssh nuc "docker exec gitea-ho0cwgcwos88cwc48g84c0g8 cat /data/gitea/conf/app.ini | grep -A2 '\[webhook\]'"

Without this, webhooks will fail with:

dial tcp 10.0.1.5:8080: webhook can only call allowed HTTP servers
(check your webhook.ALLOWED_HOST_LIST setting), deny 'coolify(10.0.1.5:8080)'

4. ⚠️ CRITICAL: Use Internal Port 8080

Coolify listens on port 8080 internally, not 8000. Port 8000 is only the external Docker port mapping.

Context	Port	URL Example
From Docker network (Gitea webhook)	8080	http://coolify:8080/webhooks/...
From external/browser	8000	http://192.168.1.3:8000

Creating an App with Auto-Deploy

Step 1: Create Application with Deploy Key

mcp__coolify__application(
    action="create_key",
    name="my-app",
    project_uuid="a8484ggc88c40w4g4k004ow0",
    environment_name="production",
    server_uuid="qk84w0goo4w48g4ggsoo0oss",
    git_repository="git@gitea-ho0cwgcwos88cwc48g84c0g8:nuc/<repo>.git",
    git_branch="main",
    build_pack="nixpacks",
    ports_exposes="3000",
    private_key_uuid="akssgwowsccgwgoggs4ks8ck"
)

Step 2: Configure FQDN

ssh nuc "docker exec coolify php artisan tinker --execute=\"
use App\Models\Application;
\\\$app = Application::where('uuid', '<app-uuid>')->first();
\\\$app->fqdn = 'http://<name>.nuc.lan';
\\\$app->custom_labels = null;
\\\$app->base_directory = '/';
\\\$app->save();
\""

Step 3: Generate and Set Webhook Secret

# Generate a secret
SECRET=$(openssl rand -hex 32)
echo "Webhook Secret: $SECRET"

# Set in Coolify
ssh nuc "docker exec coolify php artisan tinker --execute=\"
use App\Models\Application;
\\\$app = Application::where('uuid', '<app-uuid>')->first();
\\\$app->manual_webhook_secret_gitea = '$SECRET';
\\\$app->save();
echo 'Set webhook secret for ' . \\\$app->name;
\""

Step 4: Create Webhook in Gitea

1. Go to http://192.168.1.3:3030/nuc/<repo>/settings/hooks
2. Click Add Webhook → Gitea
3. Configure:
   • Target URL: http://coolify:8080/webhooks/source/gitea/events/manual?uuid=<app-uuid>
   • Secret: The secret generated in Step 3
   • Trigger On: Push Events
   • Active: ✓
4. Click Add Webhook

⚠️ IMPORTANT: The webhook URL MUST include ?uuid=<app-uuid> - without it, Coolify won't know which app to deploy!

Step 5: Initial Deploy

mcp__coolify__deploy(tag_or_uuid="<app-uuid>")

Step 6: Test Webhook

In Gitea webhook settings, click Test Delivery. Check:

• Response should be 200 OK
• Coolify should show a new deployment queued

Webhook URL Format

Correct format (use port 8080 for internal Docker network):

http://coolify:8080/webhooks/source/gitea/events/manual?uuid=<app-uuid>

App	UUID	Webhook URL
nuc-portal	t80w0cw0oooc4g0soswos4so	http://coolify:8080/webhooks/source/gitea/events/manual?uuid=t80w0cw0oooc4g0soswos4so
whyrating-hub	vw4ggc40socwkgwg4osc8wg8	http://coolify:8080/webhooks/source/gitea/events/manual?uuid=vw4ggc40socwkgwg4osc8wg8
whyrating-brand	r80gk0ccgg0okos8cw848kkk	http://coolify:8080/webhooks/source/gitea/events/manual?uuid=r80gk0ccgg0okos8cw848kkk
whyrating-templates	qw80g4sog0kk8cc4wkcs8sgc	http://coolify:8080/webhooks/source/gitea/events/manual?uuid=qw80g4sog0kk8cc4wkcs8sgc

Troubleshooting

Webhook Returns "dial tcp ... webhook can only call allowed HTTP servers"

Cause: Gitea's webhook security blocks internal hosts by default.

Fix: Add Coolify to Gitea's allowed host list:

# Check current app.ini
ssh nuc "docker exec gitea-ho0cwgcwos88cwc48g84c0g8 cat /data/gitea/conf/app.ini | grep -A5 '\[webhook\]'"

# Edit app.ini to add:
[webhook]
ALLOWED_HOST_LIST = coolify,10.0.1.5,192.168.1.3,localhost,host.docker.internal,external

# Or allow all private IPs (less secure):
ALLOWED_HOST_LIST = private

# Restart Gitea
ssh nuc "docker restart gitea-ho0cwgcwos88cwc48g84c0g8"

Webhook Returns 404 or No Deployment

Cause: Missing ?uuid= parameter in webhook URL.

Fix: Ensure URL includes the app UUID:

http://coolify:8080/webhooks/source/gitea/events/manual?uuid=<app-uuid>

Webhook Returns "Connection Refused" (dial tcp ... connection refused)

Cause: Using external port 8000 instead of internal port 8080.

Fix: Coolify's nginx listens on port 8080 inside the container, not 8000. Change:

# Wrong (external port)
http://coolify:8000/webhooks/...

# Correct (internal port)
http://coolify:8080/webhooks/...

Webhook Returns 401 Unauthorized

Cause: Webhook secret mismatch.

Fix: Verify the secret matches in both Gitea and Coolify:

# Check Coolify
ssh nuc "docker exec coolify php artisan tinker --execute=\"
use App\Models\Application;
\\\$app = Application::where('uuid', '<app-uuid>')->first();
echo 'Secret: ' . \\\$app->manual_webhook_secret_gitea;
\""

Webhook Delivers but Deployment Fails

Check Coolify logs:

ssh nuc "docker logs coolify 2>&1 | grep -i 'deploy\|webhook' | tail -30"

Common issues:

• Git pull fails: Check deploy key is added to repo
• Build fails: Check application logs in Coolify UI

Current Configuration

Shared Webhook Secret

All apps use the same webhook secret for simplicity:

9eb07a77964563378c5d66d99006e06ba3da39d232905d4b12554ff91ca39718

Deploy Key (add to each new repo)

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGHtsL3jicJTsBekYuwbKjO0EcRadYKhvLSUw/36XF7h coolify-gitea

Add via Gitea: Repository → Settings → Deploy Keys → Enable Write Access ✓

Why Not "Gitea Source"?

Coolify has a "Gitea Source" feature that attempts to use GitHub App-style OAuth. This does not work well with self-hosted Gitea because:

1. Gitea's OAuth2 is simpler than GitHub Apps (no JWT signing with private keys)
2. The credentials stored in Coolify are invalid/fake
3. Deployments fail with JWT parsing errors

Use deploy keys + manual webhooks instead - it's simpler and more reliable.

References

• Coolify CI/CD Gitea Integration
• Gitea Webhooks Documentation
• Gitea app.ini Cheat Sheet