nuc/docs/gitea-coolify-integration.md

Gitea-Coolify Integration for Git Auto-Deploy

Deploy Next.js applications from self-hosted Gitea with automatic deployments via Coolify.

Overview

This guide covers deploying applications from Gitea (self-hosted Git) to Coolify with:

• SSH key authentication
• Automatic builds via Nixpacks
• Traefik routing with custom domains
• Optional webhooks for auto-deploy on push

Architecture

Gitea (git@gitea-...:user/repo.git)
    ↓ SSH clone via deploy key
Coolify Helper Container
    ↓ Nixpacks build
Docker Image
    ↓ Deploy to coolify network
Running Container ← Traefik (*.nuc.lan routing)

Prerequisites

• Gitea running as Coolify service
• Gitea container connected to coolify network
• SSH deploy key configured in both Coolify and Gitea

Key References

Resource	UUID/Value
Server UUID	qk84w0goo4w48g4ggsoo0oss
Project UUID	a8484ggc88c40w4g4k004ow0
Environment	production
Deploy Key UUID	akssgwowsccgwgoggs4ks8ck
Gitea Container	gitea-ho0cwgcwos88cwc48g84c0g8
Gitea Service UUID	ho0cwgcwos88cwc48g84c0g8

Gitea Ports

Type	External	Internal
HTTP	3030	3000
SSH	22222	22

Network Configuration

Critical: Connect Gitea to Coolify Network

Gitea runs on its own Docker network. The Coolify helper container clones repositories from the coolify network and cannot reach Gitea unless connected:

docker network connect coolify gitea-ho0cwgcwos88cwc48g84c0g8

Verify connection:

docker network inspect coolify | grep gitea

Repository URL Format

Correct (use container name):

git@gitea-ho0cwgcwos88cwc48g84c0g8:alezmad/repo-name.git

Incorrect (will fail):

git@192.168.1.3:alezmad/repo.git        # Port 22 goes to NUC SSH, not Gitea
ssh://git@192.168.1.3:22222/user/repo.git  # Coolify mangles ssh:// URLs

Deploy Key Setup

1. Generate SSH Key (if needed)

ssh-keygen -t ed25519 -C "coolify-gitea" -f /tmp/coolify-gitea-key -N ""

2. Current Deploy Key

Public Key (add to Gitea repos):

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGHtsL3jicJTsBekYuwbKjO0EcRadYKhvLSUw/36XF7h coolify-gitea

Coolify Private Key UUID: akssgwowsccgwgoggs4ks8ck

3. Add Deploy Key to Gitea Repository

1. Navigate to: http://192.168.1.3:3030/<user>/<repo>/settings/keys
2. Click "Add Deploy Key"
3. Title: Coolify Deploy Key
4. Content: Paste the public key
5. Enable Write Access ✓ (required for pushing fixes)
6. Click "Add Deploy Key"

Or automate via Playwriter:

await page.goto('http://192.168.1.3:3030/alezmad/<repo>/settings/keys');
await page.locator('button:has-text("Add Deploy Key")').click();
await page.locator('input[name="title"]').fill('Coolify Deploy Key');
await page.locator('textarea[name="content"]').fill('<public-key>');
await page.locator('input[name="is_writable"]').check();
await page.locator('#add-deploy-key-panel button.ui.primary.button').click();

Deploying a New Application

Step 1: Create Application in Coolify

result = mcp__coolify__application(
    action="create_key",
    name="my-app-name",
    project_uuid="a8484ggc88c40w4g4k004ow0",
    environment_name="production",
    server_uuid="qk84w0goo4w48g4ggsoo0oss",
    git_repository="git@gitea-ho0cwgcwos88cwc48g84c0g8:alezmad/repo-name.git",
    git_branch="main",
    build_pack="nixpacks",
    ports_exposes="3000",
    private_key_uuid="akssgwowsccgwgoggs4ks8ck"
)
app_uuid = result['uuid']

Step 2: Configure FQDN and Base Directory

The API doesn't allow setting FQDN directly. Use Laravel tinker:

docker exec coolify php artisan tinker --execute="
use App\Models\Application;
\$app = Application::where('uuid', '<app-uuid>')->first();
\$app->fqdn = 'http://myapp.nuc.lan';
\$app->custom_labels = null;  # Forces label regeneration
\$app->base_directory = '/';   # Or '/subdir' for monorepos
\$app->save();
echo 'FQDN: ' . \$app->fqdn;
"

Step 3: Deploy

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

Step 4: Monitor Deployment

# Check deployment status
mcp__coolify__list_deployments(per_page=5)

# Get detailed logs
mcp__coolify__deployment(action="get", uuid="<deployment-uuid>", lines=50)

Troubleshooting

"Permission denied (publickey)"

Cause: Deploy key not authorized for the repository.

Fix:

1. Verify key is added to Gitea repository settings
2. Ensure "Enable Write Access" is checked
3. Verify Gitea is connected to coolify network

"Could not resolve hostname"

Cause: Gitea container not on coolify network.

Fix:

docker network connect coolify gitea-ho0cwgcwos88cwc48g84c0g8

"Nixpacks failed to detect application type"

Cause: Wrong base_directory setting.

Fix: Update via tinker:

docker exec coolify php artisan tinker --execute="
use App\Models\Application;
\$app = Application::where('uuid', '<uuid>')->first();
\$app->base_directory = '/';  # Adjust as needed
\$app->save();
"

TypeScript Build Errors

Common issue: Missing function arguments (e.g., Expected 6 arguments, but got 5)

Fix:

1. Clone repo locally or on NUC
2. Fix the code
3. Commit and push to Gitea
4. Redeploy

Example fix workflow:

# On NUC
cd /tmp && git clone http://192.168.1.3:3030/alezmad/repo.git repo-fix
cd repo-fix
# Make fixes...
git add -A && git commit -m "Fix: description"

# Push using deploy key
cat > /tmp/gitea_key << 'EOF'
<private-key-content>
EOF
chmod 600 /tmp/gitea_key
git remote set-url origin ssh://git@localhost:22222/alezmad/repo.git
GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no -i /tmp/gitea_key" git push origin main

Traefik Labels Not Updated

Cause: FQDN changed but container labels still have old domain.

Fix: Clear custom_labels and redeploy:

docker exec coolify php artisan tinker --execute="
use App\Models\Application;
\$app = Application::where('uuid', '<uuid>')->first();
\$app->custom_labels = null;
\$app->save();
"

Then force redeploy:

mcp__coolify__deploy(tag_or_uuid="<uuid>", force=True)

404 After Deployment

Cause: Traefik not routing to the new domain.

Verify labels:

container=$(docker ps --format '{{.Names}}' | grep <app-uuid-prefix> | head -1)
docker inspect $container --format '{{json .Config.Labels}}' | jq -r 'to_entries[] | select(.key | startswith("traefik")) | "\(.key)=\(.value)"' | grep rule

Should show: Host(\myapp.nuc.lan`)`

Webhooks (Auto-Deploy on Push)

Setup Gitea Webhook

1. Get webhook URL from Coolify application settings
2. In Gitea: Repository → Settings → Webhooks → Add Webhook
3. Payload URL: Coolify webhook URL
4. Content type: application/json
5. Secret: From Coolify
6. Events: Push events

Via MCP

# Get application details (includes webhook info)
app = mcp__coolify__get_application(uuid="<uuid>")
# Webhook URL is in manual_webhook_secret_gitea field

Current Deployed Applications

Application	UUID	FQDN	Repository
whyrating-brand	r80gk0ccgg0okos8cw848kkk	http://brand.nuc.lan	alezmad/whyrating-brand
whyrating-templates	qw80g4sog0kk8cc4wkcs8sgc	http://templates.nuc.lan	alezmad/whyrating-templates

Quick Reference Commands

Check Application Status

mcp__coolify__list_applications()

View Logs

mcp__coolify__application_logs(uuid="<uuid>", lines=50)

Restart Application

mcp__coolify__control(resource="application", action="restart", uuid="<uuid>")

Force Redeploy

mcp__coolify__deploy(tag_or_uuid="<uuid>", force=True)

Check Container Status

docker ps --format 'table {{.Names}}\t{{.Status}}' | grep <uuid-prefix>

Related Documentation

• .artifacts/2026-02-01_21-06_gitea-coolify-integration.md - Original setup notes
• CLAUDE.md - Quick reference section
• Coolify docs: https://coolify.io/docs