Webhooks & CI/CD: When Dokploy and Gitea refuse to talk to each other

Hello,

I struggled a bit to get my workflow running for automating updates to this blog when I push to the main branch of my repository on my Gitea server.

The Challenge: Automating Deployment

#

The goal was simple: use Gitea Actions so that every git push automatically triggers a container update for my site on my Dokploy instance.

On paper, it only takes a simple curl command to call the Webhook URL provided by Dokploy. In reality, it turned into a true exercise in “blind debugging.”

Symptoms: “All indicators are green, but nothing moves”

#

The initial diagnostic was puzzling:

• The Gitea Actions log showed a clear success (Green badge).
• The Dokploy interface, however, remained desperately silent: no trace of any new deployment.

This is where the golden rule of DevOps comes in: Never trust an exit code 0 without checking the response body.

The Diagnostic: Hunting down “Branch Not Match”

#

By running curl in verbose mode and capturing the server’s response, the culprit finally revealed itself: {"message":"Branch Not Match"}

Dokploy was indeed receiving the call, but it was rejecting it because it couldn’t identify which branch the webhook was referring to. The problem stemmed from several combined factors:

1. The Phantom Redirection (301): Since my instance is behind a reverse proxy, the HTTP URL was being redirected to HTTPS. Without the -L option, curl stopped at the redirection without transmitting the data.
2. Missing Identity: Gitea does not send the same headers as GitHub. Dokploy, not seeing the familiar “label,” ignored the request parameters.

The Solution: A “Bulletproof” Call

#

To resolve this communication conflict, I had to “force” the negotiation between the client and the Dokploy API by adding crucial elements to the Gitea workflow:

• Follow Redirects (-L): To follow the transition from HTTP to HTTPS.
• Content-Type Header (-H "Content-Type: application/json"): To confirm the data format.
• Event Header (-H "X-Gitea-Event: push"): So that Dokploy knows it should process the call as a Git action.
• Request Body (-d): To explicitly specify the branch (main).

The Final Gitea Workflow Code

#

Here is what the call that finally resolved the situation looks like in my .gitea/workflows/deploy.yaml:

1
2
3
4
5
6

- name: Trigger Dokploy Webhook
  run: |
    curl -L -X POST "${{ secrets.DOKPLOY_DEPLOY_WEB_HOOK }}" \
      -H "Content-Type: application/json" \
      -H "X-Gitea-Event: push" \
      -d '{"ref": "refs/heads/main"}'

This issue is documented here: https://github.com/Dokploy/dokploy/issues/2149

Best regards,

Marc JESTIN

https://marcjestin.fr