diff --git a/jfrog-applications/SUMMARY.md b/jfrog-applications/SUMMARY.md index 29e19f6..8c6148d 100644 --- a/jfrog-applications/SUMMARY.md +++ b/jfrog-applications/SUMMARY.md @@ -14,6 +14,7 @@ * [Proxy Support](jfrog-cli/get-started/configurations/proxy-support.md) * [CLI for JFrog Artifactory](jfrog-cli/cli-for-jfrog-artifactory/README.md) * [Using File Specs](jfrog-cli/cli-for-jfrog-artifactory/using-file-specs.md) + * [Build Integration](jfrog-cli/cli-for-jfrog-artifactory/build-integration.md) * [Package Managers Integration](jfrog-cli/cli-for-jfrog-artifactory/package-managers-integration.md) * [Managing Configuration Entities](jfrog-cli/cli-for-jfrog-artifactory/managing-configuration-entities.md) * [Transferring Files Between Artifactory Servers](jfrog-cli/cli-for-jfrog-artifactory/transferring-files-between-artifactory-servers.md) diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory/README.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory/README.md index 006788e..29f1a71 100644 --- a/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory/README.md +++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory/README.md @@ -228,8 +228,8 @@ This command is used to upload files to Artifactory. | --server-id |

[Optional]

Server ID configured using the jf c add command. If not specified, the default configured Artifactory server is used.

| | --spec |

[Optional]

Path to a file spec. For more details, please refer to Using File Specs.

| | --spec-vars |

[Optional]

List of 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 follows: ${key1}.

| -| --build-name |

[Optional]

Build name. For more details, please refer to Build Integration.

| -| --build-number |

[Optional]

Build number. For more details, please refer to Build Integration.

| +| --build-name |

[Optional]

Build name. For more details, please refer to Build Integration.

| +| --build-number |

[Optional]

Build number. For more details, please refer to Build Integration.

| | --project |

[Optional]

JFrog project key.

| | --module |

[Optional]

Optional module name for the build-info.

| | --target-props |

[Optional]

A list of Artifactory properties specified as "key=value" pairs separated by a semi-colon ( ; ) to be attached to the uploaded files. If any key can take several values, then each value is separated by a comma ( , ). For example, "key1=value1;key2=value21,value22;key3=value3".

| @@ -327,8 +327,8 @@ This command is used to download files from Artifactory. | Abbreviation | rt dl | | Command options |

Warning

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

| | --server-id |

[Optional]

Server ID configured using the config command. If not specified, the default configured Artifactory server is used.

| -| --build-name |

[Optional]

Build name. For more details, please refer to Build Integration.

| -| --build-number |

[Optional]

Build number. For more details, please refer to Build Integration.

| +| --build-name |

[Optional]

Build name. For more details, please refer to Build Integration.

| +| --build-number |

[Optional]

Build number. For more details, please refer to Build Integration.

| | --project |

[Optional]

JFrog project key.

| | --module |

[Optional]

Optional module name for the build-info.

| | --spec |

[Optional]

Path to a file spec. For more details, please refer to Using File Specs.

| @@ -813,407 +813,6 @@ Execute the cUrl client, to send a GET request to the /api/build endpoint to the jf rt curl -XGET /api/build --server-id my-rt-server ``` -## 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 artifacts deployed, dependencies used and extensive information on the build environment to allow fully traceable builds. Read more about build-info and build integration with Artifactory [here](https://jfrog.com/help/r/jfrog-integrations-documentation/Build-Integration). - -Many of JFrog CLI's commands accept two optional command options: **--build-name** and **--build-number**. When these options are added, JFrog CLI collects and records the build info locally for these commands.\ -When running multiple commands using the same build and build number, JFrog CLI aggregates the collected build info into one build.\ -The recorded build-info can be later published to Artifactory using the [build-publish](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory#publishing-build-info) command. - -### 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 several times and 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. - -For example, the following command downloads the `cool-froggy.zip` file found in repository `my-local-repo`, but it 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. - -For example, the following command specifies that file `froggy.tgz` uploaded to repository `my-local-repo` 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 - -This command is used to collect environment variables and attach them to a build. - -Environment variables are collected using the `build-collect-env` (`bce`) command. - -##### Commands Params - -The following table lists the command arguments and flags: - -| | | -| ----------------- | ------------------------------------------- | -| Command name | rt build-collect-env | -| Abbreviation | rt bce | -| Command options | | -| --project |

[Optional]

JFrog project key.

| -| Command arguments | The command accepts two arguments. | -| Build name | Build name. | -| Build number | Build number. | - - -##### Example 1 - -The following command collects all currently known environment variables, and attaches 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 -``` - -#### Collecting Information from Git - -The `build-add-git` (bag) command collects the Git revision and URL from the local .git directory and adds it to the build-info. It can also collect the list of tracked project issues (for example, issues stored in JIRA or other bug tracking systems) and add 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. - -##### Commands Params - -The following table lists the command arguments and flags: - -| | | -|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Command name | rt build-add-git | -| Abbreviation | rt bag | -| 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.

| -| 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 specific, the .git directory is assumed to be in the current directory or in one of the parent directories. | - -##### 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. In the example above, the regular expression matches the commit messages as displayed in the following example:

HAP-1007 - This is a sample issue

| -| keyGroupIndex |

The capturing group index in the regular expression used for retrieving the issue key. In the example above, setting the index to "1" retrieves HAP-1007 from this commit message:

HAP-1007 - This is a sample issue

| -| summaryGroupIndex |

The capturing group index in the regular expression for retrieving the issue summary. In the example above, setting the index to "2" retrieves the sample issue from this commit message:

HAP-1007 - This is a sample issue

| -| trackerUrl | The issue tracking URL. This value is used for constructing a direct link to the issues in the Artifactory build UI. | -| aggregate | Set to true, if you wish all builds to include issues from previous builds. | -| aggregationStatus | If aggregate is set to true, this property indicates how far in time should the issues be aggregated. In the above example, issues will be aggregated from previous builds, until a build with a RELEASE status is found. Build statuses are set when a build is promoted using the **jf rt build-promote** command. | - -##### Example - -``` -jf rt bag frogger-build 17 checkout-dir -``` - -This is the configuration file structure. - -```yaml -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 -``` - -#### Adding Files as Build Dependencies - -The download command, as well as other commands which download dependencies from Artifactory accept the **--build-name** and **--build-number** command options. Adding these options records the downloaded files as build dependencies. In some cases however, it is necessary to add a file, which has been downloaded by another tool, to a build. Use the **build-add-dependencies** command to this. - -By default, the command collects the files from the local file system. If you'd like the files to be collected from Artifactory however, add the **--from-rt** option to the command. - -##### Commands Params - -| | | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Command name | rt build-add-dependencies | -| Abbreviation | rt bad | -| Command options |

Warning

When using the * or ; characters in the command options or arguments, make sure to wrap the whole options or arguments string in quotes (") to make sure the * or ; characters 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 config command.

| -| --spec |

[Optional]

Path to a File Spec.

| -| --spec-vars |

[Optional]

List of 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 follows: ${key1}.

| -| --recursive |

[Default: true]

When false, artifacts inside sub-folders in Artifactory will not be affected.

| -| --regexp |

[Optional: false]

[Default: false] Set to true to use a regular expression instead of wildcards expression to collect files to be added to the build info.This option is not supported when --from-rt is set to true.

| -| --dry-run |

[Default: false]

Set to true to only get a summery of the dependencies that will be added to the build info.

| -| --module |

[Optional]

Optional module name in the build-info for adding the dependency.

| -| --exclusions | A list of Semicolon-separated exclude patterns. Allows using wildcards or a regular expression according to the value of the 'regexp' option. | -| 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. | - - -##### 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. 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 "my-local-repo/dependencies/" --from-rt -``` - -##### Example 3 - -Add all files located under the **path/to/build/dependencies/dir** directory as dependencies of a build. The build name is **my-build-name**, the build number is **7** and module is m1. 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/" --module m1 -``` - -### Publishing Build-Info - -This command is used to publish build info to Artifactory. To publish the accumulated build-info for a build to Artifactory, use the **build-publish** command. -For example, the following command publishes all the build-info collected for build **my-build-name** with build number 18: - -``` -jf rt bp my-build-name 18 -``` - -#### Commands Params - - -| | | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Command name | rt build-publish | -| Abbreviation | rt bp | -| Command options | | -| --server-id |

[Optional]

Server ID configured using the config command. If not specified, the default configured Artifactory server is used.

| -| --project |

[Optional]

JFrog project key.

| -| --build-url |

[Optional]

Can be used for setting the CI server build URL in the build-info.

| -| --env-include |

[Default: *]

List of patterns in the form of "value1;value2;..." Only environment variables that match those patterns will be included in the build info.

| -| --env-exclude |

[Default: *password*;*secret*;*key*]

List of case insensitive patterns in the form of "value1;value2;..." environment variables match those patterns will be excluded.

| -| --dry-run |

[Default: false]

Set to true to disable communication with Artifactory.

| -| --insecure-tls |

[Default: false]

Set to true to skip TLS certificates verification.

| -| Command arguments | The command accepts two arguments. | -| Build name | Build name to be published. | -| Build number | Build number to be published. | - -#### Example - -Publishes to Artifactory all the build-info collected for build **my-build-name** with build number 18 - -``` -jf rt bp my-build-name 18 -``` - -### Aggregating Published Builds - -The build-info, which is collected and published to Artifactory by the **jf rt build-publish** command, can include multiple modules. Each module in the build-info represents a package, which is the result of a single build step, or in other words, a JFrog CLI command execution. For example, the following command adds a module named **m1** to a build named **my-build** with **1** as the build number: - -``` -jf rt upload "a/*.zip" generic-local --build-name my-build --build-number 1 --module m1 -``` - -The following command, adds a second module, named **m2** to the same build: - -``` -jf rt upload "b/*.zip" generic-local --build-name my-build --build-number 1 --module m2 -``` - -You now publish the generated build-info to Artifactory using the following command: - -``` -jf rt build-publish my-build 1 -``` - -Now that you have your build-info published to Artifactory, you can perform actions on the entire build. For example, you can download, copy, move or delete all or some of the artifacts of a build. Here's how you do this. - -``` -jf rt download "*" --build my-build/1 -``` - -In some cases though, your build is composed of multiple build steps, which are running on multiple different machines or spread across different time periods. How do you aggregate those build steps, or in other words, aggregate those command executions, into one build-info? - -The way to do this, is to create a separate build-info for every section of the build, and publish it independently to Artifactory. Once all the build-info instances are published, you can create a new build-info, which references all the previously published build-info instances. The new build-info can be viewed as a "master" build-info, which references other build-info instances. - -So the next question is - how can this reference between the two build-instances be created? - -The way to do this is by using the **build-append** command. Running this command on an unpublished build-info, adds a reference to a different build-info, which has already been published to Artifactory. This reference is represented by a new module in the new build-info. The ID of this module will have the following format: \*\*\/\. - -Now, when downloading the artifacts of the "master" build, you'll actually be downloading the artifacts of all of its referenced builds. The examples below demonstrates this, - -| | | -| ---------------------- | --------------------------------------------------------- | -| Command name | rt build-append | -| Abbreviation | rt ba | -| Command options | This command has no options. | -| 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 | - -**Requirements** - -Artifactory version 7.25.4 and above. - -#### Example - -This script illustrates the process of creating two build-info instances, publishing both to Artifactory, and subsequently generating a third build-info that consolidates the published instances before publishing it to Artifactory. - -```yaml -# 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, which is the same as downloading the of a/1 and b/1 -jf rt download --build aggregating-build/10 -``` - -### Promoting a Build - -This command is used to [promote build](https://jfrog.com/knowledge-base/how-does-build-promotion-work/) in Artifactory. - -#### Commands Params - -| | | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| Command name | rt build-promote | -| Abbreviation | rt bpr | -| Command options | | -| --server-id |

[Optional]

Server ID configured using the 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]

List of properties in the form of "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]

Set to true to skip TLS certificates verification.

| -| 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. | - -#### Example - -This example involves moving the artifacts associated with the published build-info, identified by the build name 'my-build-name' and build number '18', from their existing Artifactory repository to a new Artifactory repository called 'target-repository'." - -``` -jf rt bpr my-build-name 18 target-repository -``` - -### Cleaning up the Build - -Build-info is accumulated by the CLI according to the commands you apply until you publish the build-info to Artifactory. If, for any reason, you wish to "reset" the build-info and cleanup (i.e. delete) any information accumulated so far, you can use the `build-clean` (`bc`) command. - -#### Commands Params - -The following table lists the command arguments and flags: - -| | | -| ----------------- | ---------------------------------- | -| Command name | rt build-clean | -| Abbreviation | rt bc | -| Command options | The command has no options. | -| Command arguments | The command accepts two arguments. | -| Build name | Build name. | -| Build number | Build number. | - - -#### Example - -The following command cleans up any build-info collected for build `my-build-name` with build number 18: - -``` -jf rt bc my-build-name 18 -``` - -### Discarding Old Builds from Artifactory - -This command is used to discard builds previously published to Artifactory using the [build-publish](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory#publishing-build-info) command. - -#### Commands Params - -The following table lists the command arguments and flags: - -| | | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | -| Command name | rt build-discard | -| Abbreviation | rt bdi | -| Command options | | -| --server-id |

[Optional]

Server ID configured using the 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]

List of build numbers in the form of "value1,value2,...", that should not be removed from Artifactory.

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

| -| Command arguments | The command accepts one argument. | -| Build name | Build name. | - -#### Example 1 - -Discard the oldest build numbers of build **my-build-name** from Artifactory, leaving only the 10 most recent builds. - -``` -jf rt bdi my-build-name --max-builds= 10 -``` - -#### Example 2 - -Discard the oldest build numbers of build **my-build-name** from Artifactory, leaving only builds published during the last 7 days. - -``` -jf rt bdi my-build-name --max-days=7 -``` - -#### Example 3 - -Discard the oldest build numbers of build **my-build-name** from Artifactory, leaving only builds published during the last 7 days. **b20** and **b21** will not be discarded. - -``` -jf rt bdi my-build-name --max-days 7 --exclude-builds "b20,b21" -``` - ## Downloading the Maven and Gradle Extractor JARs For integrating with Maven and Gradle, JFrog CLI uses the build-info-extractor jars files. These jar files are downloaded by JFrog CLI from jcenter the first time they are needed. diff --git a/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory/build-integration.md b/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory/build-integration.md new file mode 100644 index 0000000..d358dcb --- /dev/null +++ b/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory/build-integration.md @@ -0,0 +1,400 @@ +# 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 artifacts deployed, dependencies used and extensive information on the build environment to allow fully traceable builds. Read more about build-info and build integration with Artifactory [here](https://jfrog.com/help/r/jfrog-integrations-documentation/Build-Integration). + +Many of JFrog CLI's commands accept two optional command options: **--build-name** and **--build-number**. When these options are added, JFrog CLI collects and records the build info locally for these commands.\ +When running multiple commands using the same build and build number, JFrog CLI aggregates the collected build info into one build.\ +The recorded build-info can be later published to Artifactory using the [build-publish](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory#publishing-build-info) command. + +## 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 several times and 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. + +For example, the following command downloads the `cool-froggy.zip` file found in repository `my-local-repo`, but it 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. + +For example, the following command specifies that file `froggy.tgz` uploaded to repository `my-local-repo` 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 + +This command is used to collect environment variables and attach them to a build. + +Environment variables are collected using the `build-collect-env` (`bce`) command. + +#### Commands Params + +The following table lists the command arguments and flags: + +| | | +| ----------------- | ------------------------------------------- | +| Command name | rt build-collect-env | +| Abbreviation | rt bce | +| Command options | | +| --project |

[Optional]

JFrog project key.

| +| Command arguments | The command accepts two arguments. | +| Build name | Build name. | +| Build number | Build number. | + +#### Examples +##### Example 1 + +The following command collects all currently known environment variables, and attaches 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 +``` + +### Collecting Information from Git + +The `build-add-git` (bag) command collects the Git revision and URL from the local .git directory and adds it to the build-info. It can also collect the list of tracked project issues (for example, issues stored in JIRA or other bug tracking systems) and add 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. + +#### Commands Params + +The following table lists the command arguments and flags: + +| | | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Command name | rt build-add-git | +| Abbreviation | rt bag | +| 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.

| +| 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 specific, the .git directory is assumed to be in the current directory or in one of the parent directories. | + +#### 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. In the example above, the regular expression matches the commit messages as displayed in the following example:

HAP-1007 - This is a sample issue

| +| keyGroupIndex |

The capturing group index in the regular expression used for retrieving the issue key. In the example above, setting the index to "1" retrieves HAP-1007 from this commit message:

HAP-1007 - This is a sample issue

| +| summaryGroupIndex |

The capturing group index in the regular expression for retrieving the issue summary. In the example above, setting the index to "2" retrieves the sample issue from this commit message:

HAP-1007 - This is a sample issue

| +| trackerUrl | The issue tracking URL. This value is used for constructing a direct link to the issues in the Artifactory build UI. | +| aggregate | Set to true, if you wish all builds to include issues from previous builds. | +| aggregationStatus | If aggregate is set to true, this property indicates how far in time should the issues be aggregated. In the above example, issues will be aggregated from previous builds, until a build with a RELEASE status is found. Build statuses are set when a build is promoted using the **jf rt build-promote** command. | + +#### Example + +``` +jf rt bag frogger-build 17 checkout-dir +``` + +This is the configuration file structure. + +```yaml +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 +``` + +### Adding Files as Build Dependencies + +The download command, as well as other commands which download dependencies from Artifactory accept the **--build-name** and **--build-number** command options. Adding these options records the downloaded files as build dependencies. In some cases however, it is necessary to add a file, which has been downloaded by another tool, to a build. Use the **build-add-dependencies** command to this. + +By default, the command collects the files from the local file system. If you'd like the files to be collected from Artifactory however, add the **--from-rt** option to the command. + +#### Commands Params + +| | | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Command name | rt build-add-dependencies | +| Abbreviation | rt bad | +| Command options |

Warning

When using the * or ; characters in the command options or arguments, make sure to wrap the whole options or arguments string in quotes (") to make sure the * or ; characters 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 config command.

| +| --spec |

[Optional]

Path to a File Spec.

| +| --spec-vars |

[Optional]

List of 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 follows: ${key1}.

| +| --recursive |

[Default: true]

When false, artifacts inside sub-folders in Artifactory will not be affected.

| +| --regexp |

[Optional: false]

[Default: false] Set to true to use a regular expression instead of wildcards expression to collect files to be added to the build info.This option is not supported when --from-rt is set to true.

| +| --dry-run |

[Default: false]

Set to true to only get a summery of the dependencies that will be added to the build info.

| +| --module |

[Optional]

Optional module name in the build-info for adding the dependency.

| +| --exclusions | A list of Semicolon-separated exclude patterns. Allows using wildcards or a regular expression according to the value of the 'regexp' option. | +| 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. | + +#### 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. 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 "my-local-repo/dependencies/" --from-rt +``` + +##### Example 3 + +Add all files located under the **path/to/build/dependencies/dir** directory as dependencies of a build. The build name is **my-build-name**, the build number is **7** and module is m1. 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/" --module m1 +``` + +## Publishing Build-Info + +This command is used to publish build info to Artifactory. To publish the accumulated build-info for a build to Artifactory, use the **build-publish** command. +For example, the following command publishes all the build-info collected for build **my-build-name** with build number 18: + +``` +jf rt bp my-build-name 18 +``` + +### Commands Params + +| | | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Command name | rt build-publish | +| Abbreviation | rt bp | +| Command options | | +| --server-id |

[Optional]

Server ID configured using the config command. If not specified, the default configured Artifactory server is used.

| +| --project |

[Optional]

JFrog project key.

| +| --build-url |

[Optional]

Can be used for setting the CI server build URL in the build-info.

| +| --env-include |

[Default: *]

List of patterns in the form of "value1;value2;..." Only environment variables that match those patterns will be included in the build info.

| +| --env-exclude |

[Default: *password*;*secret*;*key*]

List of case insensitive patterns in the form of "value1;value2;..." environment variables match those patterns will be excluded.

| +| --dry-run |

[Default: false]

Set to true to disable communication with Artifactory.

| +| --insecure-tls |

[Default: false]

Set to true to skip TLS certificates verification.

| +| Command arguments | The command accepts two arguments. | +| Build name | Build name to be published. | +| Build number | Build number to be published. | + +### Example + +Publishes to Artifactory all the build-info collected for build **my-build-name** with build number 18 + +``` +jf rt bp my-build-name 18 +``` + +## Aggregating Published Builds + +The build-info, which is collected and published to Artifactory by the **jf rt build-publish** command, can include multiple modules. Each module in the build-info represents a package, which is the result of a single build step, or in other words, a JFrog CLI command execution. For example, the following command adds a module named **m1** to a build named **my-build** with **1** as the build number: + +``` +jf rt upload "a/*.zip" generic-local --build-name my-build --build-number 1 --module m1 +``` + +The following command, adds a second module, named **m2** to the same build: + +``` +jf rt upload "b/*.zip" generic-local --build-name my-build --build-number 1 --module m2 +``` + +You now publish the generated build-info to Artifactory using the following command: + +``` +jf rt build-publish my-build 1 +``` + +Now that you have your build-info published to Artifactory, you can perform actions on the entire build. For example, you can download, copy, move or delete all or some of the artifacts of a build. Here's how you do this. + +``` +jf rt download "*" --build my-build/1 +``` + +In some cases though, your build is composed of multiple build steps, which are running on multiple different machines or spread across different time periods. How do you aggregate those build steps, or in other words, aggregate those command executions, into one build-info? + +The way to do this, is to create a separate build-info for every section of the build, and publish it independently to Artifactory. Once all the build-info instances are published, you can create a new build-info, which references all the previously published build-info instances. The new build-info can be viewed as a "master" build-info, which references other build-info instances. + +So the next question is - how can this reference between the two build-instances be created? + +The way to do this is by using the **build-append** command. Running this command on an unpublished build-info, adds a reference to a different build-info, which has already been published to Artifactory. This reference is represented by a new module in the new build-info. The ID of this module will have the following format: \*\*\/\. + +Now, when downloading the artifacts of the "master" build, you'll actually be downloading the artifacts of all of its referenced builds. The examples below demonstrates this, + +| | | +| ---------------------- | --------------------------------------------------------- | +| Command name | rt build-append | +| Abbreviation | rt ba | +| Command options | This command has no options. | +| 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 | + +**Requirements** + +Artifactory version 7.25.4 and above. + +### Example + +This script illustrates the process of creating two build-info instances, publishing both to Artifactory, and subsequently generating a third build-info that consolidates the published instances before publishing it to Artifactory. + +```yaml +# 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, which is the same as downloading the of a/1 and b/1 +jf rt download --build aggregating-build/10 +``` + +## Promoting a Build + +This command is used to [promote build](https://jfrog.com/knowledge-base/how-does-build-promotion-work/) in Artifactory. + +### Commands Params + +| | | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| Command name | rt build-promote | +| Abbreviation | rt bpr | +| Command options | | +| --server-id |

[Optional]

Server ID configured using the 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]

List of properties in the form of "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]

Set to true to skip TLS certificates verification.

| +| 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. | + +### Example + +This example involves moving the artifacts associated with the published build-info, identified by the build name 'my-build-name' and build number '18', from their existing Artifactory repository to a new Artifactory repository called 'target-repository'." + +``` +jf rt bpr my-build-name 18 target-repository +``` + +## Cleaning up the Build + +Build-info is accumulated by the CLI according to the commands you apply until you publish the build-info to Artifactory. If, for any reason, you wish to "reset" the build-info and cleanup (i.e. delete) any information accumulated so far, you can use the `build-clean` (`bc`) command. + +### Commands Params + +The following table lists the command arguments and flags: + +| | | +| ----------------- | ---------------------------------- | +| Command name | rt build-clean | +| Abbreviation | rt bc | +| Command options | The command has no options. | +| Command arguments | The command accepts two arguments. | +| Build name | Build name. | +| Build number | Build number. | + + +### Example + +The following command cleans up any build-info collected for build `my-build-name` with build number 18: + +``` +jf rt bc my-build-name 18 +``` + +## Discarding Old Builds from Artifactory + +This command is used to discard builds previously published to Artifactory using the [build-publish](https://docs.jfrog-applications.jfrog.io/jfrog-applications/jfrog-cli/cli-for-jfrog-artifactory#publishing-build-info) command. + +### Commands Params + +The following table lists the command arguments and flags: + +| | | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| Command name | rt build-discard | +| Abbreviation | rt bdi | +| Command options | | +| --server-id |

[Optional]

Server ID configured using the 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]

List of build numbers in the form of "value1,value2,...", that should not be removed from Artifactory.

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

| +| Command arguments | The command accepts one argument. | +| Build name | Build name. | + +### Examples +#### Example 1 + +Discard the oldest build numbers of build **my-build-name** from Artifactory, leaving only the 10 most recent builds. + +``` +jf rt bdi my-build-name --max-builds= 10 +``` + +#### Example 2 + +Discard the oldest build numbers of build **my-build-name** from Artifactory, leaving only builds published during the last 7 days. + +``` +jf rt bdi my-build-name --max-days=7 +``` + +#### Example 3 + +Discard the oldest build numbers of build **my-build-name** from Artifactory, leaving only builds published during the last 7 days. **b20** and **b21** will not be discarded. + +``` +jf rt bdi my-build-name --max-days 7 --exclude-builds "b20,b21" +```