Migrate App Engine container images to Artifact Registry

Container Registry is deprecated and was shutdown on March 18, 2025. We recommend that you use Artifact Registry for storing and managing container images. By default, new deployments created after March 5, 2025 use Artifact Registry instead of Container Registry for storing application images. Artifact Registry provides the same container management features as Container Registry and includes additional features and benefits. As a fully managed service with support for both container images and non-container artifacts, Artifact Registry extends the capabilities of Container Registry.

For projects created before May 2024 or that haven't yet run the automated migration tooling , follow the steps in this guide to enable App Engine to automatically migrate your deployment flows.

App Engine standard environment

Most of your application components in the standard environment follow an automated migration process. However, for a smooth transition to Artifact Registry, ensure that your service account has the following required permissions:

• For existing standard deployments, the deploying service account (either the App Engine default service account ( PROJECT_ID @appspot.gserviceaccount.com ) or your custom service account ) must have a role that grants the explicit Artifact Registry write permission artifactregistry.repositories.uploadArtifacts . To find the roles associated with your deploying service account, see Manage access to service accounts .

• New deployments can use Artifact Registry if any of the following roles are present in the service account associated with deployments:

  • Editor role

  • Pre-defined Artifact Registry role with write access, such as Artifact Registry Writer ( roles/artifactregistry.writer ).

  • Custom role that grants artifactregistry.repositories.uploadArtifacts permission. You can verify custom roles access from the Google Cloud console or by running the gcloud iam roles describe command.

  If none of these roles are present, grant the Artifact Registry Writer role ( roles/artifactregistry.writer ) to your deploying service account.

Failing to provide the required permissions prevents you from deploying new versions in the standard environment.

During automated migrations, Google Cloud might create new repositories and copy images from Container Registry to Artifact Registry.

App Engine flexible environment

Most of your application components in the flexible environment follow an automated migration process. However, for a smooth transition to Artifact Registry, ensure that your service account has the following required permissions:

• For existing flexible deployments to work as expected with Artifact Registry, the deploying service account (either the App Engine default service account ( PROJECT_ID @appspot.gserviceaccount.com ) or your custom service account ) must have a role that grants the explicit Artifact Registry permissions such as artifactregistry.repositories.downloadArtifacts for read and artifactregistry.repositories.uploadArtifacts for write. To find the roles associated with your deploying service account, see Manage access to service accounts .

• New deployments can use Artifact Registry, if any of the following roles are present in the service account associated with deployments:

  • Editor role

  • Pre-defined Artifact Registry role with read and write access, such as Artifact Registry Writer ( roles/artifactregistry.writer ).

  • Custom role that grants artifactregistry.repositories.downloadArtifacts and artifactregistry.repositories.uploadArtifacts permissions. You can verify custom roles access from the Google Cloud console or by running the gcloud iam roles describe command.

  If none of these roles are present, grant the Artifact Registry Repository Administrator role ( roles/artifactregistry.repoAdmin ) to your deploying service account.

Failing to provide the required permissions prevents you from deploying applications in the flexible environment. Scaling and restarting instances also fail.

During automated migrations, Google Cloud might create new repositories and copy images from Container Registry to Artifact Registry.

Migrate to Artifact Registry for manually built container images

The automated migration process doesn't apply if you previously deployed your apps by using prebuilt or manually built container images from Container Registry . For example, the automated migration process doesn't work if you built container images with Docker, pushed these images to the Container Registry, and deployed your apps by using the gcloud app deploy --image-url command.

If you use prebuilt or manually built container images from Container Registry to deploy your apps, choose one of the following options to migrate to Artifact Registry:

• Use the automatic migration tool to migrate from Container Registry to gcr.io repositories that are hosted on Artifact Registry. You don't need to redeploy new versions of your service if you use this tool. For more information, see Automatically migrate from Container Registry to Artifact Registry .

• Manually move the container images from Container Registry to Artifact Registry and redeploy new versions of your service. For more information, see Manual migration to gcr.io repositories in Artifact Registry .

• Use the copy-only flag to copy your container images to Artifact Registry and redeploy new versions of your service.