How to Deploy from GitHub to a FlowEngine Instance

You push code to GitHub. Your staging site should update. That loop is so fundamental that anything slower than "push and wait 30 seconds" feels broken. FlowEngine supports auto-deploy from GitHub for any Docker-based instance: connect your repo, add a webhook, and every push to your default branch triggers a redeploy.

This guide covers the full setup, from linking a repo to verifying the first auto-deploy fires.

What auto-deploy does

When you push a commit to your GitHub repository, GitHub sends a webhook to FlowEngine. FlowEngine receives the event, pulls the latest code, builds the image on the server, and restarts your instance with the new version. The whole cycle runs in the background. You see a new entry in Deployment History when it finishes.

This works for any instance running as a Docker service on FlowEngine. That includes custom apps, static sites, APIs, internal tools, or anything else you package in a Dockerfile.

Before you start

• A FlowEngine account on any paid plan.
• A running Docker instance. If you do not have one yet, deploy from Hosting in the sidebar, pick a size, and choose the Docker service type.
• A GitHub repository with a Dockerfile at the root (or a published GHCR package).
• Your CRON_SECRET value from FlowEngine. This is used as the webhook secret so GitHub can authenticate the deploy request.

Step 1: Create a Docker instance and link your repo

Click Hosting in the sidebar, then + Deploy. Pick a size, complete checkout, and choose Docker from the service type picker. Before you hit Deploy, switch to the GitHub tab.

Two ways to connect a repo:

Private repos. Click Login with GitHub. FlowEngine installs a GitHub App on your account. Once connected, pick your organization and repository from the dropdowns. FlowEngine clones the repo on deploy, builds from your Dockerfile, and runs the result. No need to publish to GHCR yourself.

Public repos. Paste your repo URL in the Public GitHub repo URL field. FlowEngine resolves the GHCR image path automatically. Your repo must publish a Docker image to GitHub Container Registry via GitHub Actions. Make the package public in GitHub under Packages, then Change visibility.

Either way, click Deploy at the bottom to save the config and trigger the first build.

Step 2: Your running instance

After the first deploy completes, the instance detail page shows Quick Actions (Start, Restart, Redeploy), resource gauges, and the Advanced section.

Two things to notice in the Advanced section: Docker Config lets you change the image and port after deploy, and Auto-Deploy from GitHub is where the webhook lives.

Step 3: Set up the webhook for auto-deploy

Expand the Auto-Deploy from GitHub section on the instance detail page.

You see four pieces of information:

• Payload URL. A URL like https://flowengine.cloud/api/webhooks/github/deploy?instanceId=your-id. Copy it with the button next to the field.
• Secret. Your CRON_SECRET value. This authenticates the webhook so random POST requests cannot trigger a deploy.
• Content type. application/json.
• Events. Just the push event.

Now go to your GitHub repository. Open Settings, then Webhooks, then Add webhook. Paste the Payload URL, set the secret to your CRON_SECRET, pick application/json as content type, select "Just the push event", and save.

That is the entire setup. Every push to the repository now fires a POST to FlowEngine, which pulls the latest code and redeploys.

Step 4: Verify the first auto-deploy

Push a commit to your repo. Then check two places:

1. GitHub webhook deliveries. In your repo under Settings, Webhooks, click the webhook you created, then Recent Deliveries. A green checkmark means FlowEngine received the event. A red X means the secret is wrong or the URL is unreachable.
2. FlowEngine Deployment History. Back on the instance detail page, expand Deployment History. Each deploy shows the source (github_build or docker_image), status, and timestamp. A successful auto-deploy appears here within a minute or two of the push.

If the deploy does not appear, check the webhook delivery response body in GitHub. Common issues: wrong secret (403), instance not found (404), or the Dockerfile failed to build (visible in View Logs).

Manual redeploy vs auto-deploy

Auto-deploy runs on every push. If you need to redeploy without pushing code (same image, same code, just restart), click the Redeploy button in Quick Actions. That pulls the current image and restarts the service without touching GitHub.

If you need to change the Docker image or port, edit them in Docker Config and click Deploy. That is a config change, not a code push.

Common mistakes

• Wrong webhook secret. The secret must match your CRON_SECRET exactly. If you rotated it, update the GitHub webhook too.
• Dockerfile not at the root. For private repo builds, FlowEngine expects a Dockerfile in the repository root. Monorepos with nested Dockerfiles need a wrapper Dockerfile or a build context change.
• GHCR package not public. For public repos using the GHCR path, the package must be set to public visibility in GitHub. Private GHCR packages require the GitHub App login flow instead.
• Branch mismatch. The webhook fires on pushes to any branch. FlowEngine rebuilds on every push event it receives. If you only want deploys from main, configure the webhook to fire on pushes to the default branch only (GitHub lets you filter this).

Try it

If you have a Docker instance on FlowEngine and a GitHub repo with a Dockerfile, the setup is a five-minute one-time job. Link the repo, copy the webhook URL, paste it in GitHub, push a commit. Your next deploy happens automatically.

If you are not on FlowEngine yet, sign in at flowengine.cloud and deploy your first instance in about 30 seconds. The Docker service type supports GitHub auto-deploy from day one. The backup guide covers how to protect your data before you start shipping fast.