Push Docker Image to Google Container Registry

Reading Time: 4 minutes

Dive into the essentials of containerization with our in-depth article on pushing Docker images to Google Container Registry (GCR).earn step-by-step how to create Docker images using Cloud Shell, manage permissions, tag and push images to GCR, and understand the pricing structure. Whether you’re deploying microservices on Kubernetes Engine or running containerized apps on App Engine, this article equips you with the knowledge to streamline your deployment process.

what is google container registry?

Google Container Registry is a private storage service for Docker images, used to run containerized apps. Docker Images in container registry can be used to run containers on google cloud services like GKE, Cloud Run and App Engine.

Learn more about Running container apps in GKE Deploy Microservices On Google Kubernetes Engine (GKE) In 8 Easy Steps – Google Cloud Tutorials .

Learn more about Running container apps in App Engine Run Containerize App In Google Cloud App Engine – Google Cloud Tutorials


  • Google free tier or paid account.
  • Basic knowledge of using Google cloud services.

Google cloud free tier account offers credits worth 300 $ to be spend over 90 days from data of account creation. Learn more about Google Cloud free tier program here Google Cloud Free Credits – Google Cloud Tutorials .

This would be Handson tutorial and the best way to learn is to follow along.

It is always recommended practice to create a new project In GCP and then start with new development. This would allow you to delete program and all cloud resources would be released.

Create Docker Image using Cloud Shell

The first step is to create a custom image of the application.

To learn more about app containerization refer Containerizing An Application In 3 Easy Steps – Google Cloud Tutorials .

Required permissions

How to push image to google container registry?

Role: Storage Admin (roles/storage.admin) at the Google Cloud Project Level. The predefined Owner role includes these permissions.

The first time you push an image to a registry host in your project (such as gcr.io), Container Registry creates a storage bucket for the registry. The Storage Admin role has the necessary permissions to create the storage bucket.

Pushing images to an existing registry in your project

Role: Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter) on the registry storage bucket.

This role has permissions to push and pull images for existing registry hosts in your project. For example, if your project only contains the gcr.io registry, a user with the Storage Legacy Bucket Writer role can push images to gcr.io but cannot push images to asia.gcr.io.

Before you begin

Make sure that you have:

  1. Enable Container Registry API in your project.
  2. Installed and configure Docker.
Google Container Registry API

In this article we would be using Google Cloud Shell Editor VM terminal it will have Docker installed by default.

Tag image with the registry name

Determine the name for the image in Container Registry:

  • gcr.io hosts images in data centers in the United States, but the location may change in the future
  • us.gcr.io hosts images in data centers in the United States, in a separate storage bucket from images hosted by gcr.io
  • eu.gcr.io hosts the images in the European Union
  • asia.gcr.io hosts images in data centers in Asia

These locations correspond to the multi-regions for Cloud Storage storage buckets. When you push an image to a registry with a new hostname, Container Registry creates a storage bucket in the specified multi-region. This bucket is the underlying storage for the registry. Within a project, all registries with the same hostname share one storage bucket.

Choose a target image name, which can be different from the image’s name on your local machine.


docker tag custom-image gcr.io/buildcustomimage/custom-image:0.1

Push the tagged image to Container Registry

Push the tagged Image to Container Registry:

Run the following command to push an image with a specific tag:


docker push gcr.io/containerdemo-387205/container-image:0.1

Authorize Cloud shell

Authorize Cloud Shell

Docker Push Command

Container Image Successfully pushed to Google Registry.

Image is visible in Container Registry.

Container Image

Google Container Registry will become obsolete after MAY 15, 2024, and has been replaced by Google cloud Artifactory registry.

Artifact registry also known as next generation Container Registry. It supports storage of custom docker images along with non-container artifacts.

It is recommended to use to use google artifact registry for new projects.

Learn more about Artifact Registry  |  Google Cloud

Is Google Container Registry free?

Detailed pricing for Google container registry can be found here Pricing  |  Container Registry  |  Google Cloud

Scroll to Top