--- updatedAt: 2026-07-29T14:27:30.000Z agentTools: siteIndex: https://docs.jfrog.com/llms.txt projectIndex: https://docs.jfrog.com/artifactory/llms.txt --- # Use Advanced Docker Operations with Artifactory CLI Push and pull Docker images with Podman, Kaniko, buildx, or OpenShift and Artifactory. 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](#pull-docker-images-using-podman) * [Push Docker images using Podman](#push-docker-images-using-podman) * [Push Docker images using Kaniko](#push-docker-images-using-kaniko) * [Push Docker images using buildx](#push-docker-images-using-buildx) * [Push Docker images using OpenShift CLI](#push-docker-images-using-the-openshift-cli) * [Add published Docker images to the build-info](#add-published-docker-images-to-the-build-info) * [Promote Docker images](#promote-docker-images) Deprecation notice The `jf rt docker-push` and `jf rt docker-pull` commands are deprecated. Use [`jf docker push`](/docs/jf-docker) and [`jf docker pull`](/docs/jf-docker) instead. The deprecated commands are hidden from `--help` output but still functional for backwards compatibility. This deprecation applies **only** to `jf rt docker-push` and `jf rt docker-pull`. 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. *** **Package Alias (Ghost Frog)** To run `docker` without the `jf` prefix, enable Package Alias in `setup-jfrog-cli` and set `JFROG_CLI_GHOST_FROG=true`. If you install the tool **after** the action (for example `setup-java` or `setup-node`), re-pin the alias path to `GITHUB_PATH`. See [Use JFrog CLI Package Alias](/artifactory/docs/jfrog-cli-package-alias#path-priority-and-re-pinning-aliases). ## 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 ``` 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 --username --password ``` 5. **`jf docker` integration** — If you also use [`jf docker`](/docs/jf-docker) (native Docker client flows), see [Environment variables](/docs/jf-docker#environment-variables) on that page for **`JFROG_CLI_CONTAINER_MANAGER`** and **`JFROG_CLI_SKIP_DOCKER_IMAGE_ID_VERIFICATION`**. *** ## Pull Docker Images Using Podman [Podman](https://podman.io/) 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](#prerequisites) are met and your image tag uses the form `//:`. 2. Run `jf rt podman-pull` with the image tag, source repository, and optional build-info flags (see **Example**). | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Command-name | `rt podman-pull` | | Abbreviation | `rt ppl` | | `--server-id` | \[Optional] Server ID configured using `jf config` | | `--user` | \[Optional] Artifactory username. Required when the server uses a reference token (non-JWT). | | `--build-name` | \[Optional] Build name | | `--build-number` | \[Optional] Build number | | `--project` | \[Optional] JFrog project key | | `--module` | \[Optional] Module name for build-info | | `--skip-login` | \[Default: false] Skip Docker login | | `--format` | \[Optional] Output format: `json` or `table`. When omitted, output is backward-compatible. See [jf rt output format](/docs/jf-rt-output-format#jf-rt-podman-pull). | | Image tag | The docker image tag to pull. Must be in the form `//:` | | Source repository | Source repository in Artifactory | Image tag format The image tag must include a repository sub-path between the registry domain and the image name: `//:`. 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** ```bash jf rt podman-pull //: --build-name --build-number ``` Where: * `` is your Artifactory Docker registry (for example, `my-docker-registry.io`) * `` is the repository sub-path within the registry (for example, `my-repo`) * `:` is the Docker image name and tag (for example, `my-docker-image:latest`) * `` is the source repository in Artifactory (for example, `docker-local`) For example: ```bash 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 ``` *** ## Push 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](#prerequisites) are met and your image tag uses the form `//:`. 2. Run `jf rt podman-push` with the image tag, target repository, and optional build-info flags (see **Example**). | Parameter | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Command-name | `rt podman-push` | | Abbreviation | `rt pp` | | `--server-id` | \[Optional] Server ID configured using `jf config` | | `--user` | \[Optional] Artifactory username. Required when the server uses a reference token (non-JWT). | | `--build-name` | \[Optional] Build name | | `--build-number` | \[Optional] Build number | | `--project` | \[Optional] JFrog project key | | `--module` | \[Optional] Module name for build-info | | `--skip-login` | \[Default: false] Skip Docker login | | `--threads` | \[Default: 3] Number of working threads | | `--detailed-summary` | \[Default: false] Include affected files in the command summary | | `--validate-sha` | \[Default: false] Enable SHA validation during Docker push | | `--format` | \[Optional] Output format: `json` or `table`. Setting `--format` enables detailed summary. See [jf rt output format](/docs/jf-rt-output-format#jf-rt-podman-push). | | Image tag | The docker image tag to push. Must be in the form `//:` | | Target repository | Target repository in Artifactory | Image tag format The image tag must include a repository sub-path between the registry domain and the image name: `//:`. 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** ```bash jf rt podman-push //: --build-name --build-number ``` Where: * `` is your Artifactory Docker registry (for example, `my-docker-registry.io`) * `` is the repository sub-path within the registry (for example, `my-repo`) * `:` is the Docker image name and tag (for example, `my-docker-image:latest`) * `` is the target repository in Artifactory (for example, `docker-local`) For example: ```bash 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 ``` *** ## Push Docker Images Using Kaniko JFrog CLI allows pushing containers to Artifactory using [Kaniko](https://github.com/GoogleContainerTools/kaniko#kaniko---build-images-in-kubernetes), 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 `@sha256:`. 3. Run `jf rt bdc` to add the image to the build-info: ```bash jf rt bdc --image-file --build-name --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](https://github.com/jfrog/project-examples/tree/master/docker-oci-examples/kaniko-example). ## Push Docker Images Using buildx JFrog CLI allows pushing containers to Artifactory using [buildx](https://docs.docker.com/reference/cli/docker/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 `@sha256:`. 3. Run `jf rt bdc` to add the image to the build-info: ```bash jf rt bdc --image-file --build-name --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](https://github.com/jfrog/project-examples/tree/master/docker-oci-examples/fat-manifest-example). ## Push 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 `jf rt oc start-build` command (abbreviation `jf rt osb`) wraps OpenShift's native build system. It runs `oc start-build` on your behalf and then reads the resulting image tag and digest directly from OpenShift to add them to the build-info — no separate `jf rt bdc` step is required. **To push Docker images using the OpenShift CLI:** 1. Configure your OpenShift `BuildConfig` to push to your Artifactory Docker registry. 2. Ensure the OpenShift CLI (`oc`), version 3.0.0 or higher, is installed and authenticated to the cluster. 3. Run `jf rt oc start-build` with the build config name and target repository: ```bash jf rt oc start-build --repo --build-name --build-number ``` | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------- | | Command-name | `rt oc start-build` | | Abbreviation | `rt osb` | | `--repo` | \[Mandatory] The name of the repository to which the image was pushed | | `--server-id` | \[Optional] Server ID configured using `jf config` | | `--build-name` | \[Optional] Build name | | `--build-number` | \[Optional] Build number | | `--project` | \[Optional] JFrog project key | | `--module` | \[Optional] Module name for build-info | | Build config name | The OpenShift `BuildConfig` name to trigger (or `--from-build=` to reuse an existing build) | The `-w`/`--wait`, `--template`, and `-o`/`--output` `oc` options are not supported, since `jf rt oc start-build` manages waiting for build completion and reads the result itself. Only the `start-build` subcommand of `oc` is supported. 4. 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](https://github.com/jfrog/project-examples/tree/master/docker-oci-examples/openshift-examples/openshift-build-example). *** ## Add 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**). 2. Run `jf rt bdc` with the target repository, `--image-file`, and optional build-info flags. | Parameter | Description | | ----------------- | -------------------------------------------------------------------------- | | Command-name | `rt build-docker-create` | | Abbreviation | `rt bdc` | | `--image-file` | \[Mandatory] Path to a file containing: `IMAGE-TAG@sha256:MANIFEST-SHA256` | | `--server-id` | \[Optional] Server ID | | `--build-name` | \[Optional] Build name | | `--build-number` | \[Optional] Build number | | `--project` | \[Optional] JFrog project key | | `--module` | \[Optional] Module name for build-info | | Target repository | The repository to which the image was pushed | 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: ```bash echo "//:@sha256:" > image-file-details.txt ``` Then run: ```bash 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 ``` *** ## Promote 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**). | Parameter | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Command-name | `rt docker-promote` | | Abbreviation | `rt dpr` | | `--server-id` | \[Optional] Server ID | | `--copy` | \[Default: false] Copy instead of move | | `--source-tag` | \[Optional] Tag name to promote | | `--target-docker-image` | \[Optional] Docker target image name | | `--target-tag` | \[Optional] Target tag to assign after promotion | | `--format` | \[Optional] Output format: `json` only. When omitted, produces no output (backward-compatible). See [jf rt output format](/docs/jf-rt-output-format#jf-rt-docker-promote). | | Source docker image | The docker image name to promote | | Source repository | Source repository in Artifactory | | Target repository | Target repository in Artifactory | **Example** ```bash 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 | Symptom | Cause | Fix | | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `podman login failed` / `must provide --username with --password-stdin` | Server uses a reference token (non-JWT), so Podman requires basic auth | Add `--user ` to the `podman-pull` or `podman-push` command, or pre-login: `podman login --username --password ` | | `podman image must be in the form: registry-domain/path-in-repository/image-name:version` | Image tag is missing the repository sub-path | Use the three-component format: `//:` (for example, `my-registry.io/my-repo/my-image:latest`) | | Podman push/pull 401 errors | Authentication not configured for Podman | Run `podman login ` or use `--server-id` | | `build-docker-create` fails | Image file format is incorrect | Ensure the file contains `IMAGE-TAG@sha256:MANIFEST-SHA256` | | `docker-promote` fails with same source and target repository | Same-repository promotion is not supported | Use different source and target repositories | | Kaniko/buildx integration issues | Configuration not set up correctly | Refer to the linked project examples for step-by-step instructions | **Enable debug logging:** `export JFROG_CLI_LOG_LEVEL=DEBUG`
## Frequently Asked Questions This section provides answers to frequently asked questions. ##### Q: When should I use `jf rt podman-push` instead of `jf docker push`? **A:** Use the Podman commands when your workflow already runs Podman instead of the Docker CLI. See [Push Docker Images Using Podman](#push-docker-images-using-podman) for the required image tag format. ##### Q: What happens if my Podman image tag is missing the repository sub-path? **A:** The command fails because the tag must be in the three-component form `//:`. See [Prerequisites](#prerequisites) for the required format. ##### Q: What is the difference between the Kaniko and buildx push workflows? **A:** Both build and push the image themselves, then use `jf rt bdc` to attach the already-pushed image to the build-info. Kaniko is typically used for in-cluster builds, while buildx adds multi-platform (fat manifest) images. See [Push Docker Images Using Kaniko](#push-docker-images-using-kaniko) and [Push Docker Images Using buildx](#push-docker-images-using-buildx). ##### Q: Do I need `jf rt bdc` after pushing with the OpenShift CLI? **A:** No. `jf rt oc start-build` reads the resulting image tag and digest directly from OpenShift and adds them to the build-info, so no separate `jf rt bdc` step is required. ##### Q: Can I promote a Docker image to the same repository under a new name? **A:** No. `jf rt docker-promote` requires the source and target repositories to be different. See [Promote Docker Images](#promote-docker-images). *** ## Related Topics * [Use Docker with JFrog CLI](/artifactory/docs/jf-docker) * [Build Tools Overview](/artifactory/docs/build-tool-commands) * [Native Mode](/artifactory/docs/native-mode)