Deploy an Existing Image

Convoy Cloud can deploy a container image you've already built and pushed to Docker Hub or GitHub Container Registry (GHCR). No build step runs — Convoy Cloud pulls your image directly and deploys it.

When to use this

• You build and push images in your own CI pipeline (GitHub Actions, CircleCI, etc.)
• You want to deploy a public image without connecting a repository
• You are using a private registry with your own credentials

Supported registries

Other registries are not supported in the alpha.

Step 1: Set up a registry connection (private images only)

If your image is public, skip to Step 2.

For private images, you need to store a Personal Access Token (PAT) so Convoy Cloud can pull from your registry.

1. Go to Workspace > Connections > Container Registries in the sidebar.
2. Click Add Registry Connection.
3. Select your registry provider (Docker Hub or GHCR).
4. Enter your PAT and a name for the connection.
5. Click Save. Convoy Cloud verifies the token can read from the registry.

Required token scopes

Registry connections are workspace-scoped. Any member of the workspace can use a saved connection when deploying an app.

Step 2: Create the deployment

1. Go to Apps in the sidebar and click New Application.
2. On the source picker, select Existing image.
3. Fill in the form:

Image provider — Docker Hub or GHCR.

Registry connection — select a saved connection for private images, or leave blank for public images.

Image reference — the full image path and tag. Examples:

# Docker Hub public image
nginx:latest

# Docker Hub private image
myorg/my-api:1.4.2

# GitHub Container Registry
ghcr.io/myorg/my-app:sha-abc1234

Tag mode — choose how Convoy Cloud reacts when a new image is pushed:

• Pin to digest (default) — Convoy Cloud resolves the image tag to a specific digest at deploy time and locks to it. New pushes to the same tag do not trigger a redeploy. Use this for stable production deployments.
• Track the tag — Convoy Cloud redeploys automatically when a new image is pushed to the tag. Requires setting up a registry webhook (see below).

4. Configure the port, environment variables, resources, and replicas — same as any other deployment.

5. Click Deploy. Convoy Cloud verifies the image is pullable, then deploys it immediately (no build phase).

Tag tracking (Track mode)

When Track the tag is selected, Convoy Cloud redeploys your app every time a new image is pushed to the tracked tag.

To enable this, you must configure a push webhook from your registry pointing to Convoy Cloud:

Docker Hub

1. Go to your repository on Docker Hub > Webhooks.
2. Add a new webhook with the URL shown on the Connections page for your registry connection.
3. Push an image to the tracked tag to verify it fires.

GitHub Container Registry (GHCR)

GHCR does not natively support push webhooks. Instead, add a step to your GitHub Actions workflow that calls the Convoy Cloud webhook URL after a successful push:

- name: Notify Convoy Cloud
  run: |
    curl -s -X POST "${{ secrets.CONVOY_WEBHOOK_URL }}" \
      -H "Content-Type: application/json"

Store the webhook URL as a repository secret.

Deduplication

If the new push resolves to the same image digest as the currently deployed image, Convoy Cloud skips the redeploy and records a registry.image_unchanged event in the Audit log.

Updating a pinned image

To deploy a newer image version on a pinned deployment:

1. Open the app detail page and click Edit.
2. Update the Image reference to the new tag or digest.
3. Save — this creates a new deployment using the updated image.

Persistent volume and environment variables

Image-mode apps have the same /data persistent volume and environment variable configuration as source-code apps. The PORT environment variable is injected automatically.

Limitations in the alpha

• Only Docker Hub and GHCR are supported. Other registries (ECR, ACR, GCR) are not available yet.
• One registry connection per provider per workspace.