Pushing Images to Artifact Registry

Introduction and Goal

Welcome to the third lesson in our course on working with container registries . In the previous lesson, you created a secure Artifact Registry repository with vulnerability scanning enabled. Now you have an empty repository waiting for container images, but how do you actually get your applications into Artifact Registry? This lesson bridges that gap by teaching you the complete workflow for getting locally built Docker images into your Artifact Registry repository. We'll start with a simple containerized web application, build it into a Docker image on your local machine, authenticate Docker to work with Artifact Registry, tag the image with the proper Google Cloud naming convention, and finally push it to your repository. By the end of this lesson, you'll execute the full sequence: docker build to create your image locally, gcloud auth configure-docker to authenticate, docker tag to prepare the image for Artifact Registry, and docker push to upload it. This workflow forms the foundation for all Artifact Registry operations, whether you're working manually or setting up automated CI/CD pipelines. The sample application we'll use is a minimal Flask-based web application that responds with "Hello from Artifact Registry!" when accessed. While simple, this demonstrates the complete process we'll use for any containerized application, from microservices to complex web applications.

Prerequisites and Repo Check

Before pushing your first image to Artifact Registry, you need to confirm that your repository from the previous lesson exists and gather the specific details required for the push process. The repository URI you created earlier contains your Google Cloud project ID and location, both of which are essential for the tagging and authentication steps. Run this command to verify your repository exists and note its details: Shell gcloud artifacts repositories describe my-web-app --location=us-central1 The output should show your repository details, including the repository format (DOCKER) and location. From this information, you can construct your repository URI, which looks like us-central1-docker.pkg.dev/PROJECT_ID/my-web-app . This URI contains three critical pieces of information: your location (us-central1), your Google Cloud project ID (PROJECT_ID), and your repository name (my-web-app). We'll need these components for the authentication and tagging steps. Your gcloud CLI must be configured with credentials that have Artifact Registry permissions. The key IAM roles you need are roles/artifactregistry.writer for pushing images and roles/artifactregistry.reader for pulling images. Note that while you needed roles/artifactregistry.repoAdmin to create your repository in the previous lesson, pushing images only requires roles/artifactregistry.writer . This separation allows teams to grant developers push access without giving them repository management permissions. You can verify your current project with: Shell gcloud config get-value project In the CodeSignal environment, Docker, the gcloud CLI, and all necessary permissions are pre-configured for you. However, understanding these requirements is important when you work on your own development machine or set up CI/CD pipelines in production environments.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Tag the Image for Artifact Registry

Docker images must be tagged with the complete Artifact Registry repository URI before they can be pushed to Artifact Registry. The tag tells Docker exactly where to push the image and what to call it in the registry. Artifact Registry requires a specific naming format that includes your location, project ID, repository name, image name, and tag.

Tag your local image with the Artifact Registry repository URI:

Shell

docker tag my-web-app:latest us-central1-docker.pkg.dev/PROJECT_ID/my-web-app/my-web-app:latest

docker tag my-web-app:latest us-central1-docker.pkg.dev/PROJECT_ID/my-web-app/my-web-app:latest

Replace PROJECT_ID with your actual Google Cloud project ID and adjust the location if needed. Remember, you can find your project ID by running gcloud config get-value project. This command creates a new tag for your existing image without duplicating the image data. The format <location>-docker.pkg.dev/<project-id>/<repository-name>/<image-name>:<tag> is required for all Artifact Registry images.

Note that the repository name (my-web-app) appears in the path, followed by the image name (also my-web-app in this case). While we're using the same name for both, they can be different. The repository is the container you created in the previous lesson, while the image name identifies this specific application within that repository.

The tag portion (:latest in this example) is optional but recommended. If you omit it, Docker assumes :latest. While :latest is convenient for development, production environments typically use specific version tags like :v1.2.3 or :build-456 to ensure predictable deployments.

After tagging, you can verify that both tags exist for the same image:

Shell

docker images | grep my-web-app

docker images | grep my-web-app

You should see two entries: your original my-web-app:latest tag and the new Artifact Registry-formatted tag. Both point to the same image ID, confirming that tagging doesn't create duplicate images locally.

Push the Image and Verify

With your image properly tagged and Docker authenticated to Artifact Registry, you can now push the image to your repository. The push process uploads all the image layers to Artifact Registry, where they're stored securely and made available for deployment.

Push your tagged image to Artifact Registry:

Shell

docker push us-central1-docker.pkg.dev/PROJECT_ID/my-web-app/my-web-app:latest

docker push us-central1-docker.pkg.dev/PROJECT_ID/my-web-app/my-web-app:latest

The push command uploads your image layers to Artifact Registry. You'll see progress indicators showing each layer being pushed. Docker optimizes this process by only uploading layers that don't already exist in the registry, which speeds up subsequent pushes of related images.

Once the push completes, verify that your image is now stored in Artifact Registry:

Shell

gcloud artifacts docker images list us-central1-docker.pkg.dev/PROJECT_ID/my-web-app

gcloud artifacts docker images list us-central1-docker.pkg.dev/PROJECT_ID/my-web-app

This command shows all images in your repository. You should see your image with the :latest tag along with details like the image digest and upload timestamp. The image digest is a unique identifier based on the image content, ensuring integrity and enabling precise image references.

For more detailed information about a specific image, including its layers and metadata, use:

Shell

gcloud artifacts docker images describe us-central1-docker.pkg.dev/PROJECT_ID/my-web-app/my-web-app:latest

gcloud artifacts docker images describe us-central1-docker.pkg.dev/PROJECT_ID/my-web-app/my-web-app:latest

Since the Container Analysis API is enabled for your Google Cloud project, vulnerability scanning automatically begins when you push images to Artifact Registry. You can check the scan results by viewing the image details in the Google Cloud Console or by querying the Container Analysis API. Initial scans typically complete within a few minutes and provide valuable security insights about your container images.

Introduction and Goal

Prerequisites and Repo Check

Join the 1M+ learners on CodeSignal

Build a Simple Image Locally

Authenticate Docker to Artifact Registry

Tag the Image for Artifact Registry

Push the Image and Verify

Common Pitfalls and Quick Fixes

Summary and Practice