Build Integration
Overview
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.
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 separatebce
/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:
--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)
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 name
Abbreviation
rt build-collect-env
rt bce
Command arguments: (The command accepts two arguments.)
Build name
Build name.
Build number
Build number.
Command options:
--project
(Optional) JFrog project key.
Examples
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
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:
--collect-git-info
– read Git revision and remote URL.--dot-git-path
– path to.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 ./.git
Option B (legacy): build-add-git (bag)
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 name
Abbreviation
rt build-add-git
rt bag
Command arguments: (The command accepts three arguments.)
Build name
Build name.
Build number
Build number.
.git
path
(Optional) Path to a directory containing the .git
directory. If not specified, the .git
directory is assumed to be in the current directory or in one of the parent directories.
Command options:
--config
(Optional) Path to a yaml configuration file, used for collecting tracked project issues and adding them to the build-info.
--server-id
(Optional) Server ID configured using the jf config
command. This is the server to which the build-info will be later published, using the jf rt build-publish
command. This option, if provided, overrides the serverID
value in this command's yaml configuration. If both values are not provided, the default server, configured by the jf config
command, is used.
--project
(Optional) JFrog project key.
Configuration file properties
Property name
Description
Version
The schema version is intended for internal use. Do not change!
serverID
Artifactory server ID configured by the jf config
command. The command uses this server for fetching details about previous published builds. 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 jf config
command is used.
trackerName
The name (type) of the issue tracking system. For example, JIRA. This property can take any value.
regexp
A regular expression used for matching the git commit messages. The expression should include two capturing groups - for the issue key (ID) and the issue summary. Example message: HAP-1007 - This is a sample issue
keyGroupIndex
The capturing group index in the regular expression used for retrieving the issue key.
summaryGroupIndex
The capturing group index in the regular expression for retrieving the issue summary.
trackerUrl
The issue tracking URL. Used for constructing links to issues in the Artifactory build UI.
aggregate
Set to true
to include issues from previous builds.
aggregationStatus
If aggregate
is true
, indicates how far in time to aggregate (e.g., until a build with a RELEASE
status is found).
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. Usebag
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 name
Abbreviation
rt build-add-dependencies
rt bad
Command arguments: (The command takes three arguments.)
Build name
The build name to add the dependencies to
Build number
The build number to add the dependencies to
Pattern
Specifies the local file system path to dependencies which should be added to the build info. You can specify multiple dependencies by using wildcards or a regular expression as designated by the --regexp
command option. If you have specified that you are using regular expressions, then the first one used in the argument must be enclosed in parenthesis.
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.
--from-rt
(Default: false) Set to true to search the files in Artifactory, rather than on the local file system. The --regexp
option is not supported when --from-rt
is set to true.
--server-id
(Optional) Server ID configured using the jf config
command.
--spec
(Optional) Path to a File Spec.
--spec-vars
(Optional) Semicolon-separated variables in the form of "key1=value1;key2=value2;..."
to be replaced in the File Spec. In the File Spec, the variables should be used as ${key1}
.
--recursive
(Default: true) When false, artifacts inside sub-folders in Artifactory will not be affected.
--regexp
(Optional: false; Default: false) Use a regular expression instead of wildcards to collect files (not supported with --from-rt
).
--dry-run
(Default: false) Only show a summary of dependencies that will be added.
--module
(Optional) Optional module name in the build-info for adding the dependency.
--exclusions
A list of semicolon-separated exclude patterns. Allows wildcards or a regular expression according to the value of the --regexp
option.
Examples
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/"
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
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 name
Abbreviation
rt build-publish
rt bp
Command arguments: (The command accepts two arguments.)
Build name
Build name to be published.
Build number
Build number to be published.
Command options (updated list):
--server-id
(Optional) Server ID configured using the jf config
command. If not specified, the default configured Artifactory server is used.
--project
(Optional) JFrog project key.
--build-url
(Optional) CI server build URL to include in the build-info.
--collect-env
(Default: false) New. Collect environment variables at publish time.
--env-include
(Default: *
) Semicolon-separated patterns in the form "value1;value2;..."
. Only environment variables that match those patterns are included.
--env-exclude
(Default: *passwd*;*password*;*secret*;*key*;*token*;*auth*
) Case-insensitive semicolon-separated patterns to exclude sensitive variables. (Updated default set for security.)
--collect-git-info
(Default: false) New. Collect Git revision and remote URL at publish time.
--dot-git-path
(Optional) New. Path to a .git
directory (if not at project root); CLI otherwise searches upward from the current directory.
--git-config-file-path
(Optional) New. Path to a Git config file (for advanced repository layouts).
--dry-run
(Default: false) Set to true to disable communication with Artifactory.
--insecure-tls
(Default: false) Skip TLS certificates verification.
--overwrite
(Default: false) Overwrite all existing occurrences of build infos with the provided name and number. Build artifacts will not be deleted.
Examples
Publish only
jf rt bp my-build-name 18
Publish + collect env + git (one step)
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 name
Abbreviation
rt build-append
rt ba
Command arguments: (The command accepts four arguments.)
Build name
The current (not yet published) build name.
Build number
The current (not yet published) build number.
build name to append
The published build name to append to the current build.
build number to append
The published build number to append to the current build.
Command options: This command has no options.
Requirements Artifactory version 7.25.4 and above.
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 name
Abbreviation
rt build-promote
rt bpr
Command arguments: (The command accepts three arguments.)
Build name
Build name to be promoted.
Build number
Build number to be promoted.
Target repository
Build promotion target repository.
Command options:
--server-id
(Optional) Server ID configured using the jf config
command. If not specified, the default configured Artifactory server is used.
--project
(Optional) JFrog project key.
--status
(Optional) Build promotion status.
--comment
(Optional) Build promotion comment.
--source-repo
(Optional) Build promotion source repository.
--include-dependencies
(Default: false) If set to true, the build dependencies are also promoted.
--copy
(Default: false) If set true, the build artifacts and dependencies are copied to the target repository, otherwise they are moved.
--props
(Optional) Semicolon-separated properties in the form "key1=value1;key2=value2,..."
to attach to the build artifacts.
--dry-run
(Default: false) If true, promotion is only simulated. The build is not promoted.
--insecure-tls
(Default: false) Skip TLS certificates verification.
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 name
Abbreviation
rt build-clean
rt bc
Command arguments: (The command accepts two arguments.)
Build name
Build name.
Build number
Build number.
Command options: This command has no options.
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 name
Abbreviation
rt build-discard
rt bdi
Command arguments: (The command accepts one argument.)
Build name
Build name.
Command options:
--server-id
(Optional) Server ID configured using the jf config
command. If not specified, the default configured Artifactory server is used.
--max-days
(Optional) The maximum number of days to keep builds in Artifactory.
--max-builds
(Optional) The maximum number of builds to store in Artifactory.
--exclude-builds
(Optional) Comma-separated build numbers in the form "build1,build2,..."
that should not be removed.
--delete-artifacts
(Default: false) If set to true, automatically removes build artifacts stored in Artifactory.
--async
(Default: false) If set to true, build discard will run asynchronously and will not wait for response.
Examples
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
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
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 duringinstall
.npm/yarn:
install
only resolves; publish withjf npm publish
(orjf rt u
), thenjf 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.
Last updated