Build 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.JFrog Platform Integrations

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.

New: You can now 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.

Collecting Dependencies

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

Example

The following command downloads the cool-froggy.zip file from the my-local-repo repository and also specifies this file as a dependency in build my-build-name with build number 18:

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.

Example

The following command specifies that the file froggy.tgz uploaded to the my-local-repo repository is a build artifact of build my-build-name with build number 18:

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 (new)

Use jf rt bp with:

Example

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

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

Use this command to collect environment variables and attach them to a build. Environment variables are collected using the build-collect-env (bce) command.

Usage

jf rt bce <build name> <build number>

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

Collecting Environment Variable Example 2

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

jf rt bce frogger-build 17

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

Collecting Information from Git

Option A (recommended): Collect at publish time (new)

Use jf rt bp with:

Example

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

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.

Usage

jf rt bag [command options] <build name> <build number> [Path To .git]

Commands Params

Command arguments: The command accepts three arguments.

Command options:

Configuration file properties

Example

jf rt bag frogger-build 17 checkout-dir

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.

Usage

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

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/"

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 (updated)

Use the build-publish (bp) command to publish the accumulated build-info to Artifactory.

Usage

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

Commands Params

Command arguments: (The command accepts two arguments.)

Command options (updated list):

Publishing Build-Info Examples

Publish Only Example

jf rt bp my-build-name 18

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 ./.git

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

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.

jf rt upload "a/*.zip" generic-local --build-name my-build --build-number 1 --module m1
jf rt upload "b/*.zip" generic-local --build-name my-build --build-number 1 --module m2
jf rt build-publish my-build 1
jf rt download "*" --build my-build/1

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>.

Usage

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

Commands Params

Command arguments:(The command accepts four arguments.)

Command options:

This command has no 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

This command is used to promote build in Artifactory. Use the build-promote (bpr) command to promote a build in Artifactory, which typically involves moving or copying build artifacts to a target repository.

Usage

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

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

To reset the locally accumulated build-info and delete any information collected so far, use the build-clean (bc) command.

Usage

jf rt bc <build name> <build number>

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

Discarding Old Builds from Artifactory

Use the build-discard (bdi) command to remove old builds previously published to Artifactory.

Usage

jf rt bdi [command options] <build name>

Commands Params

Command arguments:(The command accepts one argument.)

Command options:

Discarding Old Builds from Artifactory Examples

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