Skip to main content

Copy images across registries

The Image Migration plugin copies an image from one registry and replicates it in another. It does this by pulling the target image from the source registry and pushing it to the destination registry.

For general information about using plugins in CI pipelines, go to Explore plugins and Use Drone plugins.

Supported registries​

Currently, this plugin's functionality is limited by its supported authentication methods.

This plugin can pull images from:

  • Public Docker registries
  • Docker registries that don't require authentication
  • Private registries that support basic authentication (username and password)
  • Private AWS ECR registries accessed by AWS access key and secret
  • GAR registries that support GAR access token authentication

This plugin can push images to:

If your authentication requirements vary from those supported by this plugin, consider running multiple Build and Push steps in parallel, running the necessary pull and push commands in a Run step, or using the Image Migration plugin as a basis to write your own plugin.

Configure the Image Migration plugin​

To use the Image Migration plugin, add a Plugin step to your CI pipeline. How you configure the Plugin step settings depends on the authentication methods involved.

To use the Image Migration plugin to pull from or push to registries that use basic authentication (username and password) or no authentication, you must provide the username and password/token for the authenticated registry.

In this example, only the destination registry requires authentication. The source registry could be public or unauthenticated.

              - step:
                  type: Plugin
                  name: migrate_image
                  identifier: migrate_image
                  spec:
                    connectorRef: account.harnessImage
                    image: plugins/image-migration
                    settings:
                      source: some-registry/image:latest
                      destination: my-target-registry/image:latest
                      username: YOUR_USERNAME
                      password: <+secrets.getValue("registry_token")>

In this example, both the source and destination registries require authentication.

              - step:
                  type: Plugin
                  name: migrate_image
                  identifier: migrate_image
                  spec:
                    connectorRef: account.harnessImage
                    image: plugins/image-migration
                    settings:
                      source: registry-1.example.com/image:latest
                      destination: registry-2.example.com/image:latest
                      source_username: USERNAME_FOR_SOURCE_REGISTRY
                      source_password: <+secrets.getValue("source_registry_token")>
                      username: YOUR_USERNAME
                      password: <+secrets.getValue("registry_token")>
                      overwrite: true

With basic authentication, the Image Migration plugin settings are as follows:

KeysTypeDescriptionValue example
connectorRefStringSelect a Docker connector. Harness uses this connector to pull the plugin image.account.harnessImage
imageStringEnter plugins/image-migration. You can specify an optional architecture tag. For a list of available tags, go to the Image Migration plugin README.plugins/image-migration:linux-amd64
sourceStringThe registry, image name, and tag of the image to copy. The format depends on the registry provider.registry-1.example.com/my-cool-image:latest
some-registry/some-image:1.2.3
destinationStringThe destination where the image will be copied along with the image name and tag. The format depends on the registry provider.registry-2.example.com/my-cool-image:latest
some-registry/some-image:1.2.3
usernameStringYour username for the destination registry.someuser
passwordStringIf required, provide a reference to a Harness text secret containing a password or access token to authenticate with the destination registry.<+secrets.getValue("destination_pat")>
source_usernameStringIf required, provide your username for the source registry.someuser2
source_passwordStringIf required, provide a reference to a Harness text secret containing a password or access token to authenticate with the source registry.<+secrets.getValue("source_pat")>
overwriteBooleanSet to true to overwrite the existing copy of the image in the destination registry, if present. The default is false (overwrite disabled).true
insecureBooleanSet to true to disable TLS. The default is false (TLS enabled).false
tip

You can use variable expressions for plugin settings. For example, registry_username: <+stage.variables.docker_user_name> references a stage variable called DOCKER_USER_NAME.