lms/specs/001-add-dokploy-deploy/contracts/push-to-deploy.md

Push-to-Deploy: Gitea → Dokploy flow

Flow summary:

1. Developer pushes commit to main.
2. Gitea sends a push webhook to Dokploy (https://system.cloudarix.de/api/deploy/compose/JXSdfeHdc6wBKUEiJrX_9).
3. Dokploy validates the webhook (signature if configured) and enqueues a compose deployment job.
4. Dokploy clones the repository (using REPO_DEPLOY_KEY secret) and reads docker-compose.yml at repo root.
5. Dokploy runs the compose deployment, streams logs, and performs configured healthchecks.
6. Dokploy marks the run success or failed and retains logs for troubleshooting.

Payload expectations:

• ref should indicate branch (e.g., refs/heads/main).
• commits array includes latest commit with id (SHA) and message.
• Dokploy should record commit_sha for traceability.

Acceptance criteria for push-to-deploy (US1):

• A push to main starts a Dokploy run within 30s (SC-001).
• The run uses docker-compose.yml at repo root and deploys the commit referenced in the webhook.
• Duplicate webhook deliveries for the same commit do not start duplicate active deployments.