Operations runbook · Automatic deploys via Forgejo → Coolify webhooks
+
+
Automatic deploys: push → live
+
+ Every Coolify app (FleetOps + FleetNow, staging & prod) deploys automatically on a
+ git push. The chain is:
+
+
git push → Forgejo webhook → Coolify rebuilds the app whose branch matches → Traefik serves the new container
+
+ Each Coolify application tracks one branch. A push to that branch fires the webhook;
+ Coolify rebuilds only the app(s) bound to the pushed branch. So staging pushes
+ deploy the *.fivetitude.com apps, and main merges deploy the
+ *.rahamafresh.com (prod) apps.
+
+
+
+ Prerequisites on the Coolify app before the webhook will do anything:
+
+
Auto Deploy = ON — under Configuration → Advanced → Auto Deploy
+ (not General). The webhook can return 2xx but Coolify ignores it if this is off.
+
Branch set correctly (staging vs main).
+
Ports Exposes = 80 (both FleetOps/Caddy and FleetNow/nginx listen on 80).
+
Domain spelled correctly and attached.
+
+
+
+
Part A — Get the webhook URL + secret from Coolify
+
+
+
Open the application in Coolify.
+
Confirm Configuration → Advanced → Auto Deploy is ON.
+
Go to the app's Webhooks tab → Manual Git Webhooks →
+ the Gitea section (Forgejo is Gitea-compatible).
+
Copy the Webhook URL (e.g.
+ https://<coolify-domain>/webhooks/source/gitea/events/manual)
+ and the Webhook Secret.
+
+
+
+
Part B — Add the webhook in Forgejo
+
+
+
Open the repo → Settings → Webhooks → Add Webhook → Forgejo/Gitea.
+
Fill in:
+
+
Field
Value
+
Target URL
the Coolify Webhook URL (Part A)
+
HTTP Method
POST
+
POST Content Type
application/json
+
Secret
the Coolify Webhook Secret (must match exactly)
+
Trigger On
Push Events (or Custom → Push only)
+
Branch filter
the app's branch (staging or main) — optional but tidy
+
Active
checked
+
+
+
Click Add Webhook.
+
+
+
+
Part C — Verify the delivery
+
+
+
In Forgejo, go to repo → Settings → Webhooks. Each webhook shows a status dot:
+ green = last delivery OK, red = failed.
+
Click the webhook to open its page, then click Test Delivery (top-right).
+
Scroll to Recent Deliveries. Click a delivery row to expand it →
+ open the Response tab → the HTTP status is there.
+ 2xx = good.
+
Confirm a deployment started in the Coolify app's Deployments list.
+
Real test: push a trivial change to the branch and confirm only the matching app redeploys.
+
+
+
+
Multiple environments (staging + prod)
+
+ There is one Coolify app per environment, each on its own branch, and
+ each app has its own webhook secret. Add a separate Forgejo webhook per app
+ (same repo), each with its own URL/secret and branch filter:
+
+
+
App
Domain
Branch
+
FleetOps staging
fleetops.fivetitude.com
staging
+
FleetOps prod
fleetops.rahamafresh.com
main
+
FleetNow staging
fleetnow.fivetitude.com
staging
+
FleetNow prod
fleetnow.rahamafresh.com
main
+
+
Promotion: feature → staging (auto-deploys staging) → main (auto-deploys prod).
+
+
Troubleshooting
+
+
Symptom
Cause & fix
+
Delivery 2xx but no deploy
Auto Deploy off. Turn it on at Configuration → Advanced → Auto Deploy.
+
Delivery 401 / 403
Secret mismatch — re-copy the Coolify secret into the Forgejo webhook's Secret field.
+
Delivery 404 / 502 on the webhook
Wrong Target URL, or Coolify unreachable.
+
Site returns 502
Coolify "Ports Exposes" ≠ container port. Set it to 80 and redeploy.
+
Site returns 503 / self-signed cert
No healthy backend yet, or the domain doesn't match the Traefik rule (often a domain typo). Fix the domain and redeploy.
+
Deploys, but it's the wrong code
Wrong branch. Set the app's Branch (e.g. staging) in the Source config, Save, then redeploy (Force rebuild).
+
+
+
+ Never point a prod app at a non-prod branch. The prod apps
+ (*.rahamafresh.com) must stay on main. Pointing one at staging
+ would push unreviewed code to the client's live site.
+