Skip to content
Reoclo Reoclo Reoclo Docs

External Deployments

What are External Deployments?

Section titled “What are External Deployments?”

Reoclo’s standard deployment pipeline integrates with GitHub and Gitea: it pulls your code, builds an image, and manages the full container lifecycle on your server. But some teams run docker compose up or docker run directly in their own CI workflows — pulling a pre-built image, running a custom script, or using a deployment tool that Reoclo didn’t orchestrate.

When that happens, Reoclo has no visibility into what changed. The managed Caddy proxy still has the last upstream it knew about. If the container name, port, or image changed, traffic gets routed to a stale upstream and your site returns 502s until you manually reconcile.

External Deployments solve this by giving your CI workflow a lightweight hook to tell Reoclo exactly what was deployed. Reoclo updates proxy_routes.upstream for every domain bound to a matching Application, triggers the managed-Caddy reconciler, and surfaces the synced FQDNs back to your workflow — all without Reoclo ever owning the build or deploy step.

When to use it

Section titled “When to use it”

Use External Deployments when:

  • Your workflow runs docker compose up, docker run, or similar commands directly on a Reoclo-managed server.
  • You build images in your own CI pipeline (GitHub Actions, GitLab CI, etc.) and push them to a registry, then pull and start them on the server.
  • You want Reoclo’s proxy to stay in sync automatically without manually updating routes after each deploy.

You do not need External Deployments if Reoclo’s GitHub App or Gitea integration already manages your build and deploy — Reoclo updates the proxy automatically in that case.

How it works

Section titled “How it works”
  1. You generate an rca_ automation API key in the dashboard with the external_deploy operation allowed.
  2. Your CI workflow stores that key as REOCLO_API_KEY and adds a single step using the reoclo/deploy-sync@v2 GitHub Action.
  3. After your docker run / docker compose up step completes, the action calls the Reoclo API, creates a short-lived deploy session, discovers which Applications match your containers, and syncs the proxy routes.
  4. Reoclo rewrites proxy_routes.upstream for every domain bound to a matched Application, triggers the Caddy reconciler, and returns the synced FQDNs.
  5. Reruns with an identical configuration are deduplicated (status: noop). A different configuration within 30 seconds is held as a conflict until you pass force: true or the window expires.

The long-lived rca_ key never touches the Reoclo API directly during syncs — the action exchanges it for a short-lived rds_ session token that is scoped to only the containers in that workflow run. If the token leaks, the blast radius is limited to those containers for at most 15 minutes.

Next steps

Section titled “Next steps”