Push an image

Push images to Harbor for enhanced security with role-based access control, automated vulnerability scanning, and simplified image management for your containerized applications. To push a local image to a Harbor instance, tag it with the repository name and then push the image.

Before you begin

To push an image, you must configure your environment with the necessary resources and permissions, including an existing Harbor project. For more information, see Create Harbor projects.

Required IAM roles

To push images to Harbor registry instances, contact your Project IAM Admin to request the following role:

  • Harbor Instance Viewer (harbor-instance-viewer): get, list, and watch Harbor instances in the project namespace. This role includes the required permissions to view the details of existing Harbor instances so you can retrieve the registry URLs required for pushing images.

Required Harbor RBAC roles

Unlike GDC IAM roles, pushing images requires specific permissions within Harbor's internal role-based access control (RBAC) system. Request the necessary permissions from your administrator. Enforce least privilege access by requesting only the roles required for your specific tasks.

Tag the local image

Follow these steps to tag a local image with the repository name:

  1. You must be authenticated to the Harbor instance. For more information, see Configure Docker authentication to Harbor registry instances.

  2. Set the name of the image. The format of a full image name is:

    INSTANCE_URL/HARBOR_PROJECT_NAME/IMAGE

    Replace the following:

    • INSTANCE_URL: the URL of the Harbor instance. For example, harbor-1.org-1.zone1.google.gdc.test. Get the URL of the Harbor instance using GDC console or gdcloud CLI.
    • HARBOR_PROJECT_NAME: the name of the Harbor project. For example, my-project.
    • IMAGE_NAME: the image's name. For example, nginx.

    An example of the full image name might look like the following:

    harbor-1.org-1.zone1.google.gdc.test/my-project/nginx

  3. Tag the local image with the repository name:

    docker tag SOURCE-IMAGE
INSTANCE_URL/HARBOR_PROJECT_NAME/IMAGE:TAG

Replace the following:

  • SOURCE-IMAGE: the local image name or image ID. For example, nginx.
  • TAG: the tag name. For example, staging. If you don't specify a tag, Docker applies the latest tag by default.

Push the tagged image to a Harbor registry instance

After the image is tagged, push it to the Harbor registry instance:

  1. Make sure that you are authenticated to the Harbor instance.
  2. Push the tagged image with the command:
docker push
INSTANCE_URL/HARBOR_PROJECT_NAME/IMAGE:TAG

When you push an image, it is stored in the specified instance and Harbor project.

After pushing your image, go to the Harbor instance UI to view the image.

What's next

After pushing your image to your Harbor registry, you can pull them to your local environment to verify them. You can also configure tag retention rules to automatically maintain your repositories and review security scan results to detect vulnerabilities: