Use Advanced Docker Operations with Artifactory CLI

Advanced Docker operations using JFrog CLI's Artifactory commands (jf rt). These commands are separate from the main jf docker command and provide integration with alternative container tools (Podman, Kaniko, buildx, OpenShift) and Docker image lifecycle management (build-docker-create, docker-promote).

This topic covers the following tasks:

• Pull Docker images using Podman
• Push Docker images using Podman
• Push Docker images using Kaniko
• Push Docker images using buildx
• Push Docker images using OpenShift CLI
• Add published Docker images to the build-info
• Promote Docker images

🚧

Deprecation notice

The jf rt docker-push and jf rt docker-pull commands are deprecated. Use jf docker push and jf docker pull instead. The deprecated commands are hidden from --help output but still functional for backwards compatibility.

This deprecation applies only to the native Docker commands above. The Podman-specific commands jf rt podman-pull and jf rt podman-push are not deprecated and remain the supported path for Podman-based workflows.

Prerequisites

Before running any commands on this page, ensure the following are in place.

To prepare your environment:

1. JFrog CLI configured — run jf config add and verify with jf config show.
2. Docker repositories exist — the source and target repositories must already exist in your Artifactory instance.
3. Podman installed — required for podman-pull and podman-push commands.
   • On macOS, Podman requires a running VM: podman machine init && podman machine start
   • Verify: podman --version
4. Podman authenticated to your registry — the CLI automatically attempts podman login before pull/push. Pre-authenticate to avoid failures:
   Bash

   podman login <your-registry>

   If your Artifactory server is configured with a reference token (non-JWT), Podman requires explicit username credentials. Use the --user flag on podman-pull and podman-push, or pre-login manually:
   Bash

   podman login <your-registry> --username <artifactory-username> --password <access-token>

Pulling Docker Images Using Podman

Podman is a daemon-less container engine for developing, managing, and running OCI Containers. The podman-pull command pulls docker images from Artifactory using Podman, while collecting build-info.

To pull Docker images using Podman:

1. Ensure Prerequisites are met and your image tag uses the form <registry>/<repo-path>/<image>:<tag>.
2. Run jf rt podman-pull with the image tag, source repository, and optional build-info flags (see Example below).

📘

Image tag format

The image tag must include a repository sub-path between the registry domain and the image name: <registry>/<repo-path>/<image>:<tag>. For example, my-registry.io/my-repo/my-image:latest. A two-component path such as my-registry.io/my-image:latest is not accepted.

Example

jf rt podman-pull <registry>/<repo-path>/<image>:<tag> <source-repo> --build-name <build-name> --build-number <build-number>

Where:

• <registry> is your Artifactory Docker registry (for example, my-docker-registry.io)
• <repo-path> is the repository sub-path within the registry (for example, my-repo)
• <image>:<tag> is the Docker image name and tag (for example, my-docker-image:latest)
• <source-repo> is the source repository in Artifactory (for example, docker-local)

For example:

jf rt podman-pull my-docker-registry.io/my-repo/my-docker-image:latest docker-local --build-name my-build-name --build-number 7

Expected output

On success, the command prints the pulled image layers and build-info collection status:

[Info] Pulling image: my-docker-registry.io/my-repo/my-docker-image:latest
[Info] Build info successfully collected for build my-build-name/7

Pushing Docker Images Using Podman

After building your image, the podman-push command pushes the image layers to Artifactory, while collecting build-info.

To push Docker images using Podman:

1. Ensure Prerequisites are met and your image tag uses the form <registry>/<repo-path>/<image>:<tag>.
2. Run jf rt podman-push with the image tag, target repository, and optional build-info flags (see Example below).

📘

Image tag format

The image tag must include a repository sub-path between the registry domain and the image name: <registry>/<repo-path>/<image>:<tag>. For example, my-registry.io/my-repo/my-image:latest. A two-component path such as my-registry.io/my-image:latest is not accepted.

Example

jf rt podman-push <registry>/<repo-path>/<image>:<tag> <target-repo> --build-name <build-name> --build-number <build-number>

Where:

• <registry> is your Artifactory Docker registry (for example, my-docker-registry.io)
• <repo-path> is the repository sub-path within the registry (for example, my-repo)
• <image>:<tag> is the Docker image name and tag (for example, my-docker-image:latest)
• <target-repo> is the target repository in Artifactory (for example, docker-local)

For example:

jf rt podman-push my-docker-registry.io/my-repo/my-docker-image:latest docker-local --build-name my-build-name --build-number 7

Expected output

On success, the command prints the pushed image layers and build-info collection status:

[Info] Pushing image: my-docker-registry.io/my-repo/my-docker-image:latest
[Info] Build info successfully collected for build my-build-name/7

Pushing Docker Images Using Kaniko

JFrog CLI allows pushing containers to Artifactory using Kaniko, while collecting build-info and storing it in Artifactory.

The Kaniko workflow uses the jf rt build-docker-create command (jf rt bdc) to attach the already-built and pushed image to the build-info after Kaniko completes the push.

To push Docker images using Kaniko:

1. Run Kaniko to build and push the image to Artifactory, capturing the image digest.

2. Write the image reference to a file in the format <IMAGE-TAG>@sha256:<MANIFEST-SHA256>.

3. Run jf rt bdc to add the image to the build-info:

   Bash

   jf rt bdc <target-repo> --image-file <path-to-image-file> --build-name <build-name> --build-number <build-number>

4. Publish the build-info with jf rt build-publish.

For a complete setup including the Kaniko container configuration and Dockerfile, refer to the Kaniko project example on GitHub.

Pushing Docker Images Using buildx

JFrog CLI allows pushing containers to Artifactory using buildx, while collecting build-info and storing it in Artifactory.

The buildx workflow uses docker buildx build --push to build and push a multi-platform (fat manifest) image to Artifactory, then attaches it to the build-info using jf rt bdc.

To push Docker images using buildx:

1. Run docker buildx build --push targeting your Artifactory registry, capturing the image digest.

2. Write the image reference to a file in the format <IMAGE-TAG>@sha256:<MANIFEST-SHA256>.

3. Run jf rt bdc to add the image to the build-info:

   Bash

   jf rt bdc <target-repo> --image-file <path-to-image-file> --build-name <build-name> --build-number <build-number>

4. Publish the build-info with jf rt build-publish.

For a complete setup including multi-platform build configuration, refer to the buildx project example on GitHub.

Pushing Docker Images Using the OpenShift CLI

JFrog CLI allows pushing containers to Artifactory using the OpenShift CLI, while collecting build-info and storing it in Artifactory.

The OpenShift workflow uses OpenShift's native build system (oc start-build) to push images to Artifactory, then attaches the result to the build-info using jf rt bdc.

To push Docker images using the OpenShift CLI:

1. Configure your OpenShift BuildConfig to push to your Artifactory Docker registry.

2. Trigger the build with oc start-build, capturing the resulting image digest.

3. Write the image reference to a file in the format <IMAGE-TAG>@sha256:<MANIFEST-SHA256>.

4. Run jf rt bdc to add the image to the build-info:

   Bash

   jf rt bdc <target-repo> --image-file <path-to-image-file> --build-name <build-name> --build-number <build-number>

5. Publish the build-info with jf rt build-publish.

For a complete setup including the OpenShift BuildConfig and pipeline integration, refer to the OpenShift build project example on GitHub.

Adding Published Docker Images to the Build-Info

The build-docker-create command allows adding a docker image that is already published to Artifactory into the build-info.

To add a published Docker image to the build-info:

1. Write the image reference (including digest) to a file (see Example below).
2. Run jf rt bdc with the target repository, --image-file, and optional build-info flags.

If your Docker image has multiple tags pointing to the same digest, provide them in comma-separated format in the --image-file.

Example

Create the image file first:

echo "<registry>/<repo-path>/<image>:<tag>@sha256:<manifest-sha256>" > image-file-details.txt

Then run:

jf rt bdc docker-local --image-file image-file-details.txt --build-name myBuild --build-number 1

Expected output

On success:

[Info] Build info successfully created

Promoting Docker Images

The docker-promote command moves or copies a Docker image from one repository to another in Artifactory.

To promote a Docker image between repositories:

1. Identify the source image name, source repository, and target repository in Artifactory.
2. Run jf rt docker-promote (or jf rt dpr) with those arguments and optional flags (see Example below).

Example

jf rt docker-promote hello-world docker-dev-local docker-staging-local

Expected output

On success:

[Info] Promoting image hello-world from docker-dev-local to docker-staging-local
[Info] Docker image promotion completed successfully

📘

Note

The jf rt docker-promote command currently requires the source and target repositories to be different. It does not support promoting a Docker image to the same repository while assigning a different target image name.

📘

Note

The --project flag is not supported by docker-promote. To scope build-info by project, use --project on the build-publish command instead.

Troubleshooting

Enable debug logging: export JFROG_CLI_LOG_LEVEL=DEBUG

Related Topics

• Build Tools Overview — Capabilities matrix and tool reference
• Native Mode — Supported packages with Native Mode