Build-Info Integration

JFrog CLI integrates with any development ecosystem, allowing you to collect build-info and then publish it to Artifactory. By publishing build-info to Artifactory, JFrog CLI empowers Artifactory to provide visibility into deployed artifacts, used dependencies, and extensive information on the build environment to allow fully traceable builds. For more information about build-info and build integration with Artifactory, see the JFrog Integrations Documentation.

When to Use Build-Info

📘

What is Build-Info?

Build-info is a JSON record that captures everything about a build: which dependencies were resolved, which artifacts were produced, environment variables, Git information, and more. It provides full traceability from source to artifact and integrates with JFrog Xray for security scanning.

📘

Coming from the REST API?

If you have been using POST /api/build to publish build-info directly, the CLI automates the entire collection process. Instead of manually constructing the build-info JSON, use --build-name and --build-number on your upload/download/build commands, then jf rt build-publish to send it all at once.

Many JFrog CLI commands accept the optional --build-name and --build-number options. When you add these options, JFrog CLI collects and records the build info locally for these commands. When running multiple commands with the same build name and build number, JFrog CLI aggregates the collected build info into one build. The recorded build-info can be published to Artifactory later using the build-publish command.

📘

You can optionally collect

You can optionally collect environment variables and Git metadata at publish time with jf rt bp using --collect-env and --collect-git-info, reducing the need for separate bce / bag steps (details below). Legacy commands remain supported.

Collecting Build-Info

Build-info is collected by adding the --build-name and --build-number options to different CLI commands. The CLI commands can be run multiple times to cumulatively collect build-info for the specified build name and number until it is published to Artifactory. For example, running the jf rt download command several times with the same build name and number will accumulate each downloaded file in the corresponding build-info.

📘

Where is local build-info stored?

Until published, collected build-info (env vars, git metadata, file dependencies) is stored in a temporary directory on the local machine: $TMPDIR/jfrog-<username>/builds/<hash>/partials/. Use jf rt bp --dry-run to preview the accumulated build-info JSON at any time without publishing to Artifactory. Use jf rt bc <build-name> <build-number> to clear locally accumulated data.

Collecting Dependencies

Dependencies are collected by adding the --build-name and --build-number options to the jf rt download command.

To record downloaded artifacts as build dependencies:

1. Run jf rt dl with a repository path, artifact path, and matching --build-name and --build-number values.

   jf rt dl <repository>/<artifact-path> --build-name=<build-name> --build-number=<build-number>

   Where:

   • <repository> — Artifactory repository key and path prefix for the artifact.
   • <artifact-path> — Path to the artifact under that repository.
   • <build-name> — Build name to associate with the download.
   • <build-number> — Build number to associate with the download.

   Example:

   jf rt dl my-local-repo/cool-froggy.zip --build-name=my-build-name --build-number=18

Collecting Build Artifacts

Build artifacts are collected by adding the --build-name and --build-number options to the jf rt upload command.

To record uploaded files as build artifacts:

1. Run jf rt u (upload) with local source path, target repository, and matching --build-name and --build-number values.

   jf rt u <local-path> <repository> --build-name=<build-name> --build-number=<build-number>

   Where:

   • <local-path> — Path to the file or pattern on your machine.
   • <repository> — Target Artifactory repository (and optional path).
   • <build-name> — Build name to associate with the upload.
   • <build-number> — Build number to associate with the upload.

   Example:

   jf rt u froggy.tgz my-local-repo --build-name=my-build-name --build-number=18

Collecting Environment Variables

Option A (recommended): Collect at publish time

Use jf rt bp with:

• --collect-env – include environment variables in the build-info.
• Combine with --env-include / --env-exclude to control what's sent.

Example

jf rt bp my-build-name 18 \
  --collect-env \
  --env-exclude "*password*;*secret*;*key*;*token*;*auth*"

Option B (legacy): build-collect-env (bce)

🚧

Deprecated

bce is retained for backward compatibility. Prefer --collect-env on jf rt bp (Option A), which collects environment variables at publish time and eliminates an extra pipeline step.

The build-collect-env (bce) command collects environment variables and attaches them to a build.

To collect environment variables with bce (legacy):

1. Run jf rt bce with the target build name and number (see Usage below).

Usage

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

Where:

• <build-name> — Build name to attach environment variables to.
• <build-number> — Build number for that build.

Commands Params

Command arguments: The command accepts two arguments.

Command options:

Collecting Environment Examples

Collecting Environment Variable Example 1

Collect all currently known environment variables and attach them to the build-info for build my-build-name with build number 18:

jf rt bce my-build-name 18

Expected output:

[Info] Collecting environment variables...
[Info] Collected environment variables for my-build-name/18.

Collecting Environment Variable Example 2

Collect environment variables for build name frogger-build and build number 17:

jf rt bce frogger-build 17

Expected output:

[Info] Collecting environment variables...
[Info] Collected environment variables for frogger-build/17.

Recommendation: Prefer jf rt bp ... --collect-env to capture environment variables at publish time and reduce pipeline steps. bce remains supported for backward compatibility.

Collect Information from Git

Option A (recommended): Collect at publish time

Use jf rt bp with:

• --collect-git-info: read Git revision and remote URL.
• --dot-git-path: path to the directory containing .git, if not at project root.
• --git-config-file-path: path to a Git config file for advanced layouts.

Example

jf rt bp my-build-name 18 \
  --collect-git-info \
  --dot-git-path .

📘

Note

--dot-git-path expects the directory that contains the .git folder, not the .git directory itself. For example, if your project root is at /path/to/project and contains /path/to/project/.git, pass --dot-git-path /path/to/project. If .git is in the current working directory, pass --dot-git-path . or omit the flag entirely. If the path is incorrect, the CLI will silently skip VCS collection (exit 0) and log a [Warn] message — verify VCS fields in the published build-info when traceability is required.

Option B (legacy): build-add-git (bag)

The build-add-git (bag) command collects the Git revision and URL from the local .git directory and adds it to the build-info. The command also collects the list of tracked project issues (for example, issues stored in JIRA or other bug tracking systems) and adds them to the build-info. The issues are collected by reading the git commit messages from the local git log. Each commit message is matched against a pre-configured regular expression, which retrieves the issue ID and issue summary. The information required for collecting the issues is retrieved from a YAML configuration file provided to the command.

To add Git metadata with bag (legacy):

1. Run jf rt bag with build name and number, and optionally the path to the directory that contains .git (see Usage and Command options below).

Usage

jf rt bag [command options] <build-name> <build-number>

Where:

• <build-name> — Build name to add Git metadata to.
• <build-number> — Build number for that build.

To point at a specific project directory, append a third argument after <build-number>: <path-to-git-parent> (the directory that contains .git). If you omit it, the CLI searches upward from the current directory.

Commands Params

Command arguments: The command accepts three arguments.

Command options:

Configuration file properties

Example

jf rt bag frogger-build 17 checkout-dir

Expected output:

[Info] Reading the git branch, revision and remote URL and adding them to the build-info.

📘

Note

checkout-dir here is the directory that contains the .git folder, not the .git folder itself. The Git information (branch, revision, remote URL) is stored locally and included when you later run jf rt bp to publish the build.

Configuration file structure (example)

version: 1
issues: 
  # The serverID yaml property is optional. The --server-id command option, if provided, overrides the serverID value.
  # If both the serverID property and the --server-id command options are not provided,
  # the default server, configured by the "jfrog config add" command is used.
  serverID: my-artifactory-server

  trackerName: JIRA
  regexp: (.+-[0-9]+)\s-\s(.+)
  keyGroupIndex: 1
  summaryGroupIndex: 2
  trackerUrl: https://my-jira.com/issues
  aggregate: true
  aggregationStatus: RELEASED

Recommendation: Prefer jf rt bp ... --collect-git-info [--dot-git-path ...] to gather Git metadata at publish time. Use bag only when you need commit-message issue extraction via YAML.

Adding Files as Build Dependencies

The download command and other commands that download dependencies from Artifactory accept the --build-name and --build-number options to record the downloaded files as build dependencies. In cases where it is necessary to add a file downloaded by another tool as a dependency, use the build-add-dependencies (bad) command.

By default, the command collects files from the local file system. To collect files from Artifactory instead, add the --from-rt option.

To add files as build dependencies:

1. Run jf rt bad with build name, number, and pattern (or a File Spec); add --from-rt to resolve paths in Artifactory. See Usage, Command options, and the examples below.

Usage

jf rt bad [command options] <build-name> <build-number> <pattern>
jf rt bad --spec=<file-spec-path> [command options] <build-name> <build-number>

Where:

• <build-name> — Build name to add dependencies to.
• <build-number> — Build number for that build.
• <pattern> — Local path or pattern for dependencies (when not using --spec).
• <file-spec-path> — Path to a File Spec file (second command form).

Commands Params

Command arguments: The command takes three arguments.

Command options:

When using the * or ; characters in the command options or arguments, wrap the whole string in quotes (") so they are not interpreted as literals.

Adding Files as Build Dependencies Examples

Adding Files as Build Dependencies Example 1

Add all files located under the path/to/build/dependencies/dir directory as dependencies of a build. The build name is my-build-name and the build number is 7. The build-info is only updated locally. To publish the build-info to Artifactory use the jf rt build-publish command.

jf rt bad my-build-name 7 "path/to/build/dependencies/dir/"

Expected output:

[Info] Running Build Add Dependencies command...
[Info] Adding dependency: path/to/build/dependencies/dir/dep1.jar
[Info] Adding dependency: path/to/build/dependencies/dir/dep2.jar
{
  "status": "success",
  "totals": {
    "success": 2,
    "failure": 0
  }
}

Adding Files as Build Dependencies Example 2

Add all files located in the m-local-repo Artifactory repository, under the dependencies folder, as dependencies of a build.

jf rt bad my-build-name 7 "my-local-repo/dependencies/" --from-rt

Adding Files as Build Dependencies Example 3

Add all files located under the directory to module m1.

jf rt bad my-build-name 7 "path/to/build/dependencies/dir/" --module m1

Publishing Build-Info

The build-publish (bp) command publishes accumulated build-info to Artifactory.

To publish build-info:

1. Run jf rt bp with the build name and number to publish, plus any optional flags (see Usage and Command options below).

Usage

jf rt bp [command options] <build-name> <build-number>

Where:

• <build-name> — Build name to publish.
• <build-number> — Build number to publish.

Commands Params

Command arguments: The command accepts two arguments.

Command options:

Publishing Build-Info Examples

Publish Only Example

jf rt bp my-build-name 18

Expected output (success):

[Info] Publishing build info for <my-build-name>/<18>...
[Info] Build info successfully published to Artifactory.

Publish + collect env + git (one step) Example

jf rt bp my-build-name 18 \
  --collect-env \
  --env-exclude "*password*;*secret*;*key*;*token*;*auth*" \
  --collect-git-info \
  --dot-git-path .

Security note: Always use --env-exclude to prevent leaking secrets. The default covers common names; extend it for your organization's variables.

Dry-run tip: Use --dry-run to preview the full build-info JSON (including collected env vars and VCS fields) without publishing to Artifactory:

jf rt bp my-build-name 18 --dry-run

Aggregating Published Builds

In complex builds where steps run across multiple machines, you can publish separate build-info instances and then aggregate them into a "master" build-info record. The build-append (ba) command adds a reference from a new build-info to a previously published one.

If your build is composed of multiple build steps across different machines/time periods, create a separate build-info for each section and publish it independently. Once all are published, create a new build-info that references all previously published build-info instances using build-append. The reference is represented by a new module in the new build-info, with ID format: <referenced build name>/<referenced build number>.

To aggregate published builds:

1. Satisfy the prerequisites in the note below, then run jf rt ba for each published build you want to append, and publish the aggregating build with jf rt bp.

📘

Prerequisites for build-append

1. Upload artifacts for each sub-build (using jf rt upload with --build-name and --build-number).
2. Publish each sub-build to Artifactory with jf rt build-publish.
3. Only then run jf rt ba — the appended builds must already be published. The command contacts Artifactory to verify the referenced builds exist.

Usage

jf rt ba <build-name> <build-number> <build-name-to-append> <build-number-to-append>

Where:

• <build-name> — Current (aggregating) build name.
• <build-number> — Current (aggregating) build number.
• <build-name-to-append> — Published build name to append.
• <build-number-to-append> — Published build number to append.

Commands Params

Command arguments: The command accepts four arguments.

Command options:

Requirements

Artifactory version 7.25.4 and above.

Aggregating Published Builds Example

# Create and publish build a/1
jf rt upload "a/*.zip" generic-local --build-name a --build-number 1
jf rt build-publish a 1

# Create and publish build b/1
jf rt upload "b/*.zip" generic-local --build-name b --build-number 1
jf rt build-publish b 1

# Append builds a/1 and b/1 to build aggregating-build/10
jf rt build-append aggregating-build 10 a 1
jf rt build-append aggregating-build 10 b 1

# Publish build aggregating-build/10
jf rt build-publish aggregating-build 10

# Download the artifacts of aggregating-build/10 (includes a/1 and b/1)
jf rt download --build aggregating-build/10

Promoting a Build

The build-promote (bpr) command promotes a build in Artifactory, typically by moving or copying build artifacts to a target repository.

To promote a build:

1. Run jf rt bpr with the build name, build number, and target repository (see Usage and Command options below).

Usage

jf rt bpr [command options] <build-name> <build-number> <target-repository>

Where:

• <build-name> — Build name to promote.
• <build-number> — Build number to promote.
• <target-repository> — Repository key to promote artifacts into.

Commands Params

Command arguments: The command accepts three arguments.

Command options:

Promoting a Build Example

Move the artifacts associated with the published build-info my-build-name/18 to target-repository:

jf rt bpr my-build-name 18 target-repository

Cleaning up the Build

Use the build-clean (bc) command to reset locally accumulated build-info and delete any information collected so far for a given build name and number.

To reset locally accumulated build-info:

1. Run jf rt bc with the build name and number you want to clear (see Usage below).

Usage

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

Where:

• <build-name> — Build name whose local build-info you want to clear.
• <build-number> — Build number for that build.

Commands Params

Command arguments: The command accepts two arguments.

Command options:

This command has no options.

Cleaning up the Build Example

jf rt bc my-build-name 18

Expected output:

[Info] Cleaning build info...
[Info] Cleaned build info my-build-name/18.

Discarding Old Builds from Artifactory

The build-discard (bdi) command removes old builds previously published to Artifactory according to retention options.

To discard old published builds:

1. Run jf rt bdi with the build name and at least one retention rule (such as --max-builds or --max-days); see Usage, Command options, and the examples below.

Usage

jf rt bdi [command options] <build-name>

Where:

• <build-name> — Build name whose old published builds you want to discard (subject to retention flags).

Commands Params

Command arguments: The command accepts one argument.

Command options:

Discarding Old Builds from Artifactory Examples

📘

Build discard operations require at least one retention rule (such as max-builds or max-days). If no retention criteria are specified, the request succeeds, but no builds are removed. The delete-artifacts option only controls artifact removal for discarded builds.

Example: jf rt bdi my-build-name --max-builds=10 --delete-artifacts=false

Discarding Old Builds from Artifactory Example 1

Discard the oldest build numbers of build my-build-name, leaving only the 10 most recent:

jf rt bdi my-build-name --max-builds=10

Discarding Old Builds from Artifactory Example 2

Discard the oldest build numbers, leaving only builds published during the last 7 days:

jf rt bdi my-build-name --max-days=7

Discarding Old Builds from Artifactory Example 3

Discard by age but keep specific builds:

jf rt bdi my-build-name --max-days 7 --exclude-builds "b20,b21"

Troubleshooting

• Build succeeded but nothing was deployed

  • Gradle (Artifactory plugin): specify publications (artifactory.publish.publications=release or via CLI/DSL).
  • Maven: run a deploy phase/goal (deploy) or ensure your setup deploys during install.
  • npm/yarn: install only resolves; publish with jf npm publish (or jf rt u), then jf rt bp.
  • Docker/Podman: ensure jf docker login (or remove --skip-login), and that the repo permissions are correct.

• Secrets in env: use --env-exclude with --collect-env; extend default patterns to match your org's variables.

• .git path not found: The bag command and --collect-git-info require a valid .git directory. Ensure your working directory contains a .git folder, or specify the path to the directory containing .git with --dot-git-path <parent-dir>. For example, if .git is at /repo/.git, use --dot-git-path /repo. Do not pass the .git folder itself. If the path is wrong, the CLI exits 0 with a [Warn] and silently omits VCS data from the build-info.