Deploy from a Container Registry

Last updated November 6, 2026

App Platform lets you deploy an app from a prebuilt Docker image stored in a public or private GitHub Container Registry, GitLab Container Registry, or any other registry that you can connect by its URL.

For private images, you need a username and password or an access token, depending on your provider's requirements.

This method works well if you build images yourself or use prebuilt images from container registries.

Requirements and Limitations
Copy link

  • Platform: Build your image for linux/amd64. If the image is built for a different platform, the deployment fails with a manifest error.

  • Port: App Platform detects the app port from the image metadata (for example, the EXPOSE instruction) or from environment variables, if they explicitly set a port. If no port is specified, the default port is used.

  • Proxying: App Platform automatically configures access to your app through a reverse proxy and routes traffic from external ports 80 and 443 to the container port. You don't need to configure proxying manually.

  • Direct port access: In addition to HTTPS access via a domain, you may be able to connect directly to service ports at domain:port. This is useful for services that don't use HTTP.

  • Data persistence: Data inside the container is not preserved between deployments. Use external storage for files and databases. For details, see How App Platform Works.

  • Downtime: Your app may be temporarily unavailable during redeployment.

Step 1. Select a Registry and Image
Copy link

  1. Go to App Platform and click Create app.
  2. Open the Container image tab.
  3. Select the image source: GitHub Container Registry, GitLab Container Registry, or Other registry.
  4. Click Add registry and follow the instructions for your registry:

GitHub Container Registry
Copy link

  1. Enter the user or organization (namespace).
  2. Enter a token with the read:packages scope. App Platform uses the token to find images and tags in the selected namespace and to pull the image during deployment.
  3. Click Connect.
  4. Select the connected user, organization, or registry from the list. 
  5. Select the image and enter a tag or digest. You don't need to enter your credentials again.

GitLab Container Registry
Copy link

  1. Enter the user or organization (namespace).
  2. Enter a token with the read_api and read_registry scopes. Alternatively, you can grant the api scope instead.
  3. Click Connect.
  4. Select the connected user, organization, or registry from the list. 
  5. Select the image and enter a tag or digest. You don't need to enter your credentials again.

App Platform uses the token to find images and tags in the selected namespace and to pull the image during deployment. To access private groups and projects, issue the token from an account that has access to them.

Other Registry
Copy link

  1. Enter the registry address, for example registry.example.com or registry.example.com:5000.
  2. If the registry is private, enter a username and password or a token with permission to pull images.
  3. Click Connect.
  4. Enter the image path and tag manually. Searching for images and tags is not available for registries connected through Other registry. App Platform checks that the image exists when you create the app.

After you connect a registry, you can select it from the list next time. You don't need to enter the address or credentials again.

Step 2. Choose Region and Server Configuration
Copy link

Applications run on dedicated cloud servers. Select a deployment region and an appropriate server configuration. You can choose from predefined plans or define a custom configuration under the Custom tab.

You can upgrade to a more powerful plan later if needed.

Step 3. Configure Environment Variables
Copy link

Use variables to store and pass configuration values such as passwords, file paths, and tokens. 

See more here.

Step 4. Configure a Private Network
Copy link

Click Show advanced settings to configure a private network. 

Create or select a private network for the application and assign the IP address it will use.

Note that the private network cannot be changed after deployment.

Apps with a private IP address may experience a short downtime during redeployment, as existing ports need to be freed up before the new version starts.

Step 5. Enter Application Details
Copy link

Optionally, specify an application name and add a description. This information will be displayed in the dashboard.

You can also select the project the application should belong to.

These settings can be updated at any time.

Step 6. Deploy
Copy link

Click Create. Once the process begins, you can monitor progress in the Deploy tab.

Deployment logs typically include all the information you need to troubleshoot issues. If something goes wrong—such as errors in your code—the logs will provide detailed messages explaining the cause.

During the initial deployment, server provisioning may take some time. Once the process is complete, the application status will update, and a confirmation message will appear in the logs.

You can find the application’s IP address and its default technical domain on the Dashboard tab. You can also configure a custom domain.