Use apk with JFrog CLI

Run Alpine Package Keeper (apk) commands with Artifactory integration for credential injection, optional build-info collection, and package upload.

This topic covers the following tasks:

• Configure apk for Artifactory (jf setup apk)
• Install and upgrade packages (jf apk add and jf apk upgrade)
• Upload packages (jf apk upload)
• Passthrough native apk subcommands

When to Use

Use jf apk on Alpine Linux when you resolve or publish .apk packages through Artifactory and want JFrog CLI to inject credentials and optionally record build-info.

• Run jf setup apk once per environment to point /etc/apk/repositories at an Artifactory Alpine repository and to install the repository RSA public key under /etc/apk/keys/.
• Run jf apk add or jf apk upgrade to install or upgrade packages with optional build-info.
• Run jf apk upload to publish a local .apk file to Artifactory.
• Run other native apk subcommands through jf apk when you want credential injection without build-info.

If you do not need build-info or JFrog-managed credentials, you can configure apk manually. For repository layout and Set Me Up snippets, see Alpine Linux Repositories.

Prerequisites

• Alpine Linux environment for wrapped apk commands: jf apk add, jf apk upgrade, and other native wrappers require the apk binary on PATH. Verify with apk --version. For authenticated repository access through HTTP_AUTH, use apk-tools 2.12 or later.
• JFrog CLI installed and authenticated: Install or upgrade from the JFrog CLI quick start, then configure a server with jf config add or jf c add. The CLI uses this configuration (default server, or the server named by --server-id) for credential injection and uploads.
• Artifactory Alpine repositories: Create local, remote, and virtual Alpine repositories as needed. Prefer a virtual repository for resolution. Attach an RSA key pair to the repository you use for signed indexes. See Alpine Linux Repositories.
• Root or write access for setup: jf setup apk writes /etc/apk/repositories and files under /etc/apk/keys/. Package install and upgrade also require the privileges that native apk requires.
• Optional: Set JFROG_HOME if you use a non-default directory for JFrog CLI configuration files.

Configure: jf setup apk

jf setup apk configures the local Alpine client to use an Artifactory Alpine repository. It downloads the repository RSA public key and updates /etc/apk/repositories.

There is no jf apk config command. Use jf setup apk.

To configure apk for Artifactory:

1. Configure a JFrog CLI server with jf c add (or jf config add).
2. Run jf setup apk --server-id=<server-id> --repo=<repo-key> (or omit --repo to select interactively).
3. Confirm that the RSA public key is written under /etc/apk/keys/ and that /etc/apk/repositories points at Artifactory.

Synopsis

jf setup apk [--server-id=<server-id>] [--repo=<repo-key>]

Options

The following options configure the Alpine client.

When Alpine version detection succeeds (from /etc/alpine-release), the repository URL uses the layout https://<artifactory-host>/artifactory/<repo-key>/<alpine-version>/main/. Setup embeds the configured username and password or access token in that URL so native apk can authenticate.

Example

jf setup apk --server-id=my-server --repo=my-alpine-repo

On success, the CLI logs that the APK repository is configured and that the RSA signing key was written under /etc/apk/keys/.

Build: jf apk

jf apk runs the native apk binary with stdin, stdout, and stderr passed through. JFrog CLI removes its own options from the argument list, injects HTTP_AUTH into the apk subprocess environment when a server is configured, and can collect build-info after a successful add or upgrade.

HTTP_AUTH uses the format basic:<hostname>:<username>:<password-or-token>, where <hostname> is the Artifactory host only (no scheme or path). At debug log level, the CLI masks the secret as HTTP_AUTH=basic:<host>:<user>:***.

When --build-name and --build-number are both set (or supplied via JFROG_CLI_BUILD_NAME and JFROG_CLI_BUILD_NUMBER), the CLI records newly installed or upgraded packages in a build-info module of type apk. Dependency IDs use the name:version format. When --module is omitted, the default module ID is <repo>:<arch>:<alpine-version> when those values are available.

Passing --repo does not permanently change /etc/apk/repositories. For a single command, the CLI can isolate repository selection when --repo or --server-id requires it. For lasting client configuration, run jf setup apk.

To run native apk commands with credentials and optional build-info:

1. Run jf apk add or jf apk upgrade with the package arguments you need.
2. (Optional) Add --build-name and --build-number to collect build-info.
3. Publish collected build-info with jf rt build-publish <build-name> <build-number>.

Synopsis

jf apk add <packages...> [command options]
jf apk upgrade [packages...] [command options]
jf apk <native-subcommand> [args...] [command options]

Aliases: none for the apk command group. The upload subcommand also accepts u as a short alias for upload.

Arguments

The following arguments are accepted by jf apk.

Build Options

The following options control build-info collection and Artifactory access.

All other flags pass through to apk unchanged.

Build Examples

Install packages

jf apk add curl bash

Install with build-info

jf apk add curl bash --build-name=<build-name> --build-number=<build-number>

Where:

• <build-name> is the logical name for the build
• <build-number> is the build ID (for example a CI run number)

For example:

jf apk add curl bash --build-name=ci-image --build-number=42

Install with an explicit server and repository

jf apk add curl --server-id=<server-id> --repo=<repo-key> --build-name=<build-name> --build-number=<build-number>

For example:

jf apk add curl --server-id=my-server --repo=my-alpine-repo --build-name=ci-image --build-number=42

Upgrade packages

jf apk upgrade --server-id=my-server --repo=my-alpine-repo

Build-info from environment variables

export JFROG_CLI_BUILD_NAME=ci-image
export JFROG_CLI_BUILD_NUMBER=7
jf apk add curl

Publish build-info to Artifactory

jf rt build-publish <build-name> <build-number>

For example:

jf rt build-publish ci-image 42

The following subcommands collect build-info when --build-name and --build-number are both set.

Checksums are collected from cached .apk archives when possible. When --repo is set, the CLI can enrich missing checksums from Artifactory with AQL. Using apk --no-cache limits local checksum collection; drop --no-cache when you need complete local checksums in build-info.

Publish: jf apk upload

jf apk upload publishes a local .apk file to an Artifactory Alpine repository. Upload is a REST operation and does not require a local apk binary.

To upload an Alpine package:

1. Run jf apk upload with the package file, repository, and Alpine version.
2. (Optional) Add build-info options to record the uploaded artifact.

Synopsis

jf apk upload <file.apk> --repo <repo-key> --alpine-version <vX.Y> [command options]

Aliases: jf apk u

Arguments

The following argument identifies the package to upload.

Upload Options

The following options control the upload destination and build-info collection.

Upload path and properties

The CLI uploads to:

<repo-key>/<alpine-version>/<branch>/<arch>/<filename>

For example: my-alpine-repo/v3.20/main/x86_64/myapp-1.0.0-r0.x86_64.apk.

On upload, the CLI sets artifact properties including os.name=alpine, os.version=<alpine-version>, os.arch=<arch>, apk.name=<name>, and apk.version=<version>.

Upload Examples

jf apk upload ./myapp-1.0.0-r0.x86_64.apk --repo=my-alpine-repo --alpine-version=v3.20

jf apk upload ./myapp-1.0.0-r0.x86_64.apk \
  --repo=my-alpine-repo \
  --alpine-version=v3.20 \
  --branch=main \
  --build-name=ci-image \
  --build-number=42

Passthrough Native apk Subcommands

Every other native apk subcommand runs as a passthrough: JFrog flags are accepted, credentials are injected when a server is configured, and remaining arguments are forwarded to apk. Build-info is not collected. If you pass build-info flags on a passthrough command, the CLI prints a warning after execution.

Passthrough examples include update, fetch, search, del, info, fix, audit, version, and stats.

To pass through a native apk subcommand:

1. Run the subcommand through jf apk.
2. Add JFrog CLI options when you need credential injection or a specific repository.

jf apk update
jf apk search curl
jf apk info musl

Important Notes

• After collecting build-info locally, publish it to Artifactory with jf rt build-publish <build-name> <build-number> (alias jf rt bp).
• If no JFrog server is configured, the CLI skips HTTP_AUTH injection and warns you to run jf c add.
• An explicit unknown --server-id is a hard error. Omit --server-id to use the default server.
• Signature verification failures can include a hint to run jf setup apk so the RSA public key is installed.
• jf apk add, jf apk upgrade, and other wrappers that invoke native apk target Alpine Linux. jf apk upload can run wherever JFrog CLI can reach Artifactory.

Environment Variables

The following environment variables configure build-info collection and credential injection.

Dockerfile Example

FROM alpine:3.20

# Install JFrog CLI (pin the release URL your organization uses)
RUN wget -qO /usr/local/bin/jf https://releases.jfrog.io/artifactory/jfrog-cli/v2-jf/jfrog-cli-linux-amd64/jf && \
    chmod +x /usr/local/bin/jf

# Configure the Artifactory server non-interactively in CI, then:
RUN jf setup apk --server-id="$JF_SERVER_ID" --repo="$JF_ALPINE_REPO"

RUN jf apk add curl bash jq \
      --server-id="$JF_SERVER_ID" \
      --repo="$JF_ALPINE_REPO" \
      --build-name="$JFROG_CLI_BUILD_NAME" \
      --build-number="$JFROG_CLI_BUILD_NUMBER"

Provide server credentials through your CI secret mechanism before jf setup apk and jf apk add.

Troubleshooting

The following table lists common issues and resolutions.

Enable debug logging: export JFROG_CLI_LOG_LEVEL=DEBUG

Frequently Asked Questions

This section provides answers to frequently asked questions about using apk with JFrog CLI.

Related Topics

• Build Tools Overview
• Alpine Linux Repositories
• Use JFrog CLI Package Alias
• Supported Package Manager Versions