# jf docker

Run Docker commands with Artifactory integration, including login, build, push, pull, and Xray scanning.

This topic covers the following tasks:

* [Run Docker commands (`jf docker`)](#build-jf-docker)
* [Log in to an Artifactory Docker registry (`jf docker login`)](#docker-login)

## When to Use

Use `jf docker` to build, push, pull, and scan Docker images with Artifactory integration. The CLI handles Docker login automatically and collects build-info for traceability. For Helm chart operations, use [`jf helm`](jf-helm.md).

## Prerequisites

* Docker must be installed and running on the machine.
* Configure a server with `jf config add` or `jf c add`.
* Authentication to Artifactory is required.
* For scanning (`jf docker scan`), JFrog Xray must be configured on your JFrog Platform instance.

***

## Build: `jf docker`

Run Docker commands with Artifactory integration, including login, build, push, pull, and Xray scanning.

**To run Docker commands with Artifactory integration:**

### Synopsis

```
jf docker <docker-arguments> [options]
```

**Aliases:** none

### Arguments

| Argument           | Required | Description                     |
| ------------------ | -------- | ------------------------------- |
| `docker-arguments` | Yes      | Docker subcommand and arguments |

### Subcommands

| Subcommand | Description                                                               |
| ---------- | ------------------------------------------------------------------------- |
| `login`    | Log in to an Artifactory Docker registry                                  |
| `build`    | Run Docker build (also supports `buildx build` for multi-platform images) |
| `push`     | Push image to Artifactory                                                 |
| `pull`     | Pull image from Artifactory                                               |
| `scan`     | Scan a local Docker image for vulnerabilities with JFrog Xray             |

### Push / Pull Options

| Flag                 | Default | Description                                                  |
| -------------------- | ------- | ------------------------------------------------------------ |
| `--build-name`       | —       | Build name for build information (requires `--build-number`) |
| `--build-number`     | —       | Build number for build information (requires `--build-name`) |
| `--project`          | —       | JFrog Artifactory project key                                |
| `--module`           | —       | Optional module name for build information                   |
| `--skip-login`       | `false` | Skip performing Docker login                                 |
| `--threads`          | `3`     | Number of working threads                                    |
| `--detailed-summary` | `false` | Include affected files in the command summary                |
| `--server-id`        | —       | Server ID configured with `jf config add`                    |
| `--validate-sha`     | `false` | Enable SHA validation during Docker push                     |

### Scan Options (`jf docker scan`)

| Flag                      | Default | Description                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------- |
| `--server-id`             | —       | Server ID configured with `jf config add`                                              |
| `--project`               | —       | JFrog Artifactory project key                                                          |
| `--watches`               | —       | Comma-separated list of Xray watches for violation evaluation                          |
| `--repo-path`             | —       | Target repo path to enable Xray to determine watches accordingly                       |
| `--licenses`              | `false` | Set to true to receive license information from Xray scanning                          |
| `--format`                | `table` | Output format. Accepts `table`, `json`, `simple-json`, or `sarif`                      |
| `--fail`                  | `true`  | Set to false to prevent exit code 3 even if the Fail Build rule is matched by Xray     |
| `--min-severity`          | —       | Minimum severity of issues to display. Accepts: `Low`, `Medium`, `High`, or `Critical` |
| `--fixable-only`          | `false` | Set to true to display only issues that have a fixed version                           |
| `--vuln`                  | `false` | Set to true to receive all vulnerabilities regardless of Xray policy configuration     |
| `--extended-table`        | `false` | Include extended fields such as CVSS and Xray Issue ID in table output                 |
| `--bypass-archive-limits` | `false` | Set to true to bypass the indexer-app archive limits                                   |

### Build Examples

#### Login to Artifactory

```bash
jf docker login <registry-url>
```

Where:

* `<registry-url>` is your Artifactory Docker registry URL (e.g., `acme.jfrog.io`)

For example:

```bash
jf docker login acme.jfrog.io
```

#### Build and Push

```bash
jf docker build -t <registry-url>/<image>:<tag> .
jf docker push <registry-url>/<image>:<tag> --build-name=<build-name> --build-number=<build-number>
```

Where:

* `<registry-url>` is your Artifactory Docker registry (e.g., `acme.jfrog.io`)
* `<image>` is the Docker image name (e.g., `my-app`)
* `<tag>` is the image tag (e.g., `1.0.0`)

For example:

```bash
jf docker build -t acme.jfrog.io/docker-local/my-app:1.0.0 .
jf docker push acme.jfrog.io/docker-local/my-app:1.0.0 --build-name=my-app --build-number=1
```

#### Multi-Platform Build with Docker Buildx

`jf docker buildx build` supports multi-platform image builds with build-info collection. Standard Docker Buildx arguments are supported.

```bash
jf docker buildx build --platform linux/amd64,linux/arm64 \
    -t <registry-url>/<image>:<tag> . \
    --build-name=<build-name> --build-number=<build-number>
```

#### Scan Image

```bash
jf docker scan <image-name>:<tag>
```

For example:

```bash
jf docker scan acme.jfrog.io/docker-local/my-app:1.0.0
```

#### Push with Build Information

```bash
jf docker push <image-tag> --build-name=my-app --build-number=1 --threads=5
```

***

## Docker Login

**To log in to an Artifactory Docker registry:**

**Synopsis**

```
jf docker login [registry] [--server-id <id>] [--username <name>] [--password <pwd>]
```

Logs your local Docker client into an Artifactory Docker registry using credentials managed by JFrog CLI. After a successful login, you can run native Docker commands (for example, `docker pull`, `docker push`, `docker build`) that interact with Artifactory without re-authenticating each time.

**Arguments**

* `registry` (optional) — The Docker registry to log into (e.g., `my-docker.jfrog.io`). If omitted, JFrog CLI uses the platform URL from the configured server.

**Options**

* `--server-id` (optional) — Use a specific configured server.
* `--username` (optional) — Docker registry username.
* `--password` (optional) — Docker registry password.

When using `--username`/`--password`, the `registry` argument is mandatory.

**Examples**

```bash
jf docker login

jf docker login --server-id my-jfrog

jf docker login my-docker-registry.jfrog.io --server-id my-jfrog

jf docker login my-docker-registry.jfrog.io --username <USERNAME> --password <PASSWORD>
```

***

## Important Notes

* **Docker login**: The CLI performs `docker login` automatically before push/pull unless `--skip-login` is set. If you've already logged in separately, use `--skip-login` to avoid overwriting existing credentials.
* **Xray scanning**: `jf docker scan` scans a locally-built image against Xray policies. The image does not need to be pushed to Artifactory first. Requires Xray to be configured on your JFrog Platform.
* **Build info**: When using `--build-name` and `--build-number`, the CLI records Docker layers as build dependencies. Publish the build info with `jf rt build-publish` after pushing.
* **Multi-architecture images**: Build and push each architecture separately, then create a manifest list. The CLI's build info captures each push independently.
* **Registry URL**: The Docker registry URL format is typically `<your-server>.jfrog.io/<repo-key>` (for example, `acme.jfrog.io/docker-local`).

> **Coming from the UI?** In the Artifactory UI, you can view Docker images under **Artifacts > `<docker-repo>`**. The CLI's `jf docker push` and `jf docker pull` interact with the same Docker repositories you see in the UI.

## Native Mode

Docker supports **Native Mode**, which runs the native Docker build directly instead of the legacy JFrog build flow. Build-info is still collected when `--build-name` and `--build-number` are provided.

Enable with: `export JFROG_RUN_NATIVE=true`

For full setup instructions, per-tool comparison, and when to use each mode, see [Native Mode](native-mode.md).

## CI/CD Example (GitHub Actions)

```yaml
# .github/workflows/build.yml
steps:
  - uses: actions/checkout@v4
  - name: Setup JFrog CLI
    uses: jfrog/setup-jfrog-cli@v4
    env:
      JF_URL: ${{ vars.JF_URL }}
      JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}
  - name: Login to Docker registry
    run: jf docker login acme.jfrog.io --server-id=setup-jfrog-cli-server
  - name: Build Docker image
    run: jf docker build -t acme.jfrog.io/docker-local/my-app:${{ github.run_number }} .
  - name: Push Docker image
    run: jf docker push acme.jfrog.io/docker-local/my-app:${{ github.run_number }} --build-name=my-app --build-number=${{ github.run_number }}
  - name: Scan Docker image
    run: jf docker scan acme.jfrog.io/docker-local/my-app:${{ github.run_number }}
  - name: Publish build info
    run: jf rt build-publish my-app ${{ github.run_number }}
```

***

## Advanced Operations

For container operations using alternative tools (Podman, Kaniko, buildx, OpenShift) and Docker image lifecycle commands (build-docker-create, docker-promote), see [Docker Advanced Operations](docker-advanced.md).

***

## Troubleshooting

| Symptom                                         | Cause                                           | Fix                                                                                                             |
| ----------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `docker login` fails                            | Incorrect registry URL or credentials           | Verify the registry URL format: `<your-server>.jfrog.io` (not `<your-server>.jfrog.io/<repo>`)                  |
| 401 / 403 on push or pull                       | Invalid credentials or insufficient permissions | Re-run `jf config add` or `jf docker login` with valid credentials                                              |
| `jf docker push` succeeds but image not visible | Pushed to wrong repository                      | Confirm the image tag includes the correct registry and repo path: `<server>.jfrog.io/<repo-key>/<image>:<tag>` |
| `jf docker scan` returns no results             | Xray is not configured on the JFrog Platform    | Verify Xray is enabled and the image is indexed                                                                 |
| `--skip-login` causes auth failures             | No prior Docker login for this registry         | Remove `--skip-login` or run `jf docker login` first                                                            |
| Multi-arch image build-info incomplete          | Each architecture pushed separately             | Push each architecture with the same `--build-name` and `--build-number`                                        |

**Enable debug logging:** `export JFROG_CLI_LOG_LEVEL=DEBUG`

<br />

## Related Topics

* [Build Tools Overview](/artifactory/docs/build-tool-commands) — Capabilities matrix and tool reference
* [Native Mode](/artifactory/docs/native-mode) — Supported packages with Native Mode