FLEETOPS

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:

Part A — Get the webhook URL + secret from Coolify

  1. Open the application in Coolify.
  2. Confirm Configuration → Advanced → Auto Deploy is ON.
  3. Go to the app's Webhooks tab → Manual Git Webhooks → the Gitea section (Forgejo is Gitea-compatible).
  4. 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

  1. Open the repo → Settings → Webhooks → Add Webhook → Forgejo/Gitea.
  2. Fill in:
    FieldValue
    Target URLthe Coolify Webhook URL (Part A)
    HTTP MethodPOST
    POST Content Typeapplication/json
    Secretthe Coolify Webhook Secret (must match exactly)
    Trigger OnPush Events (or Custom → Push only)
    Branch filterthe app's branch (staging or main) — optional but tidy
    Activechecked
  3. Click Add Webhook.

Part C — Verify the delivery

  1. In Forgejo, go to repo → Settings → Webhooks. Each webhook shows a status dot: green = last delivery OK, red = failed.
  2. Click the webhook to open its page, then click Test Delivery (top-right).
  3. Scroll to Recent Deliveries. Click a delivery row to expand it → open the Response tab → the HTTP status is there. 2xx = good.
  4. Confirm a deployment started in the Coolify app's Deployments list.
  5. 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:

AppDomainBranch
FleetOps stagingfleetops.fivetitude.comstaging
FleetOps prodfleetops.rahamafresh.commain
FleetNow stagingfleetnow.fivetitude.comstaging
FleetNow prodfleetnow.rahamafresh.commain

Promotion: feature → staging (auto-deploys staging) → main (auto-deploys prod).

Troubleshooting

SymptomCause & fix
Delivery 2xx but no deployAuto Deploy off. Turn it on at Configuration → Advanced → Auto Deploy.
Delivery 401 / 403Secret mismatch — re-copy the Coolify secret into the Forgejo webhook's Secret field.
Delivery 404 / 502 on the webhookWrong Target URL, or Coolify unreachable.
Site returns 502Coolify "Ports Exposes" ≠ container port. Set it to 80 and redeploy.
Site returns 503 / self-signed certNo 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 codeWrong 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.