Release Lifecycle Management

Overview

This page describes how to use JFrog CLI with Release Lifecycle Management.

---

Note

Release Lifecycle Management is only available since Artifactory 7.63.2.

---

Syntax

When used with JFrog Release Lifecycle Management, JFrog CLI uses the following syntax:

$ jf command-name global-options command-options arguments

Creating a release bundle

The create command allows creating a release bundle using file specs. The file spec may be of one of the following creation sources:

1. Published build infos.

   {
     "files": [
       {
         "build": "<build-name>/<build-number>",
         "includeDeps": "[true/false]",
         "project": "<project-key>"
       },
       ...
     ]
   }

   <build-number> is optional, latest build will be used if empty. includeDeps is optional, false by default. project is optional, default project will be used if empty.

2. Existing release bundles.

   {
     "files": [
       {
         "bundle": "<bundle-name>/<bundle-version>",
         "project": "<project-key>"
       },
       ...
     ]
   }

   project is optional, default project will be used if empty.

3. A pattern of artifacts in Artifactory.

   {
     "files": [
       {
         "pattern": "repo/path/*",
         "exclusions": ["excluded",...],
         "props": "key1=value1;key2=value2;key3=value3",
         "excludeArtifacts": "key1=value1;key2=value2;key3=value3",
         "recursive": "[true/false]"
       },
       ...
     ]
   }

   Only pattern is mandatory. recursive is true by default.

4. AQL query.

   {
     "files": [
       {
         "aql": {
           "items.find": {
             "repo": "<repo>",
             "path": "<path>",
             "name": "<file>"
           }
         }
       }
     ]
   }

   Only a single AQL query may be provided.

Commands Params

Command-name	release-bundle-create
Abbreviation	rbc
Command arguments:
release bundle name	Name of the newly created Release Bundle.
release bundle version	Version of the newly created Release Bundle.
Command options:
--project	[Optional] Project key associated with the created Release Bundle version.
--server-id	[Optional] Platform Server ID configured using the 'jf config' command.
--signing-key	[Mandatory] The GPG/RSA key-pair name given in Artifactory.
--spec	[Optional] Path to a File Spec.
--spec-vars	[Optional] List of semicolon-separated(;) variables in the form of "key1=value1;key2=value2;..." (wrapped by quotes) to be replaced in the File Spec. In the File Spec, the variables should be used as follows: ${key1}.
--sync	[Default: false] Set to true to run synchronously.

Examples

Example 1

Create a release bundle with name "myApp" and version "1.0.0", using signing key pair "myKeyPair". The release bundle will include artifacts corresponding to the creation source in the provided file spec.

jf rbc --spec=/path/to/spec.json --signing-key=myKeyPair myApp 1.0.0

Example 2

Create a release bundle synchronously, in project "project0".

jf rbc --spec=/path/to/spec.json --signing-key=myKeyPair --sync=true --project=project0 myApp 1.0.0

Example 3

Create a release bundle using file spec variables.

jf rbc --spec=/path/to/spec.json --spec-vars="key1=value1" --signing-key=myKeyPair myApp 1.0.0

Promoting a release bundle

This command allows promoting a release bundle to a target environment.

Commands Params

Command-name	release-bundle-promote
Abbreviation	rbp
Command arguments:
release bundle name	Name of the Release Bundle to promote.
release bundle version	Version of the Release Bundle to promote.
environment	Name of the target environment for the promotion.
Command options:
--input-repos	[Optional] A list of semicolon-separated(;) repositories to include in the promotion. If this property is left undefined, all repositories (except those specifically excluded) are included in the promotion. If one or more repositories are specifically included, all other repositories are excluded.
--exclude-repos	[Optional] A list of semicolon-separated(;) repositories to exclude from the promotion.
--project	[Optional] Project key associated with the Release Bundle version.
--server-id	[Optional] Platform Server ID configured using the 'jf config' command.
--signing-key	[Mandatory] The GPG/RSA key-pair name given in Artifactory.
--sync	[Default: false] Set to true to run synchronously.

Examples

Example 1

Promote a release bundle named "myApp" version "1.0.0" to environment "PROD". Use signing key pair "myKeyPair".

jf rbp --signing-key=myKeyPair myApp 1.0.0 PROD

Example 2

Promote a release bundle synchronously to environment "PROD". The release bundle is named "myApp", version "1.0.0", of project "project0". Use signing key pair "myKeyPair".

jf rbp --signing-key=myKeyPair --project=project0 --sync=true myApp 1.0.0 PROD

Example 3

Promote a release bundle while including certain repositories.

jf rbp --signing-key=myKeyPair --include-repos="generic-local;my-repo" myApp 1.0.0 PROD

Example 4

Promote a release bundle while excluding certain repositories.

jf rbp --signing-key=myKeyPair --exclude-repos="generic-local;my-repo" myApp 1.0.0 PROD

Distributing a release bundle

This command distributes a release bundle to an edge node.

Command-name	release-bundle-distribute
Abbreviation	rbd
Command arguments:
release bundle name	Name of the release bundle to distribute.
release bundle version	Version of the release bundle to distribute.
Command options:
--city	[Default: *] Wildcard filter for site city name.
--country-codes	[Default: *] semicolon-separated(;) list of wildcard filters for site country codes.
--create-repo	[Default: false] Set to true to create the repository on the edge if it does not exist.
--dist-rules	[Optional] Path to a file, which includes the Distribution Rules in a JSON format. See the "Distribution Rules Structure" bellow.
--dry-run	[Default: false] Set to true to disable communication with JFrog Distribution.
--mapping-pattern	[Optional] Specify along with 'mapping-target' to distribute artifacts to a different path on the edge node. You can use wildcards to specify multiple artifacts.
--mapping-target	[Optional] The target path for distributed artifacts on the edge node. If not specified, the artifacts will have the same path and name on the edge node, as on the source Artifactory server. For flexibility in specifying the distribution path, you can include placeholders in the form of {1}, {2} which are replaced by corresponding tokens in the pattern path that are enclosed in parenthesis.
--max-wait-minutes	[Default: 60] Max minutes to wait for sync distribution.
--project	[Optional] Project key associated with the Release Bundle version.
--server-id	[Optional] Platform Server ID configured using the 'jf config' command.
--site	[Default: *] Wildcard filter for site name.
--sync	[Default: false] Set to true to run synchronously.

Distribution Rules Structure

{
 "distribution_rules": [
    {
       "site_name": "DC-1",
       "city_name": "New-York",
       "country_codes": ["1"]
    },
    {
       "site_name": "DC-2",
       "city_name": "Tel-Aviv",
       "country_codes": ["972"]
    }
 ]
}

The Distribution Rules format also supports wildcards. For example:

{
 "distribution_rules": [
    {
       "site_name": "",
       "city_name": "",
       "country_codes": ["*"]
    }
 ]
}

Examples

Example 1

Distribute the release bundle named myApp with version 1.0.0. Use the distribution rules defined in the specified file.

jf rbd --dist-rules=/path/to/dist-rules.json myApp 1.0.0

Example 2

Distribute the release bundle named myApp with version 1.0.0 using the default distribution rules. Map files under the source directory to be placed under the target directory.

jf rbd --dist-rules=/path/to/dist-rules.json --mapping-pattern="(*)/source/(*)" --mapping-target="{1}/target/{2}" myApp 1.0.0

Example 3

Synchronously distribute a release bundle associated with project "proj"

jf rbd --dist-rules=/path/to/dist-rules.json --sync --project="proj" myApp 1.0.0

Deleting release bundle locally

This command allows deleting all release bundle promotions to an environment or deleting a release bundle locally altogether. Deleting locally means distributions of the release bundle will not be deleted.

Command-name	release-bundle-delete-local
Abbreviation	rbdell
Command arguments:
release bundle name	Name of the release bundle to distribute.
release bundle version	Version of the release bundle to distribute.
environment	If provided, all promotions to this environment are deleted. Otherwise, the release bundle is deleted locally with all its promotions.
Command options:
--project	[Optional] Project key associated with the Release Bundle version.
--quiet	[Default: $CI] Set to true to skip the delete confirmation message.
--server-id	[Optional] Platform Server ID configured using the 'jf config' command.
--sync	[Default: false] Set to true to run synchronously.

Examples

Example 1

Locally delete the release bundle named myApp with version 1.0.0 altogether.

jf rbdell myApp 1.0.0

Example 2

Delete a release bundle locally altogether. Run the command synchronously and skip the confirmation message.

jf rbdell --quiet --sync myApp 1.0.0

Example 3

Delete all promotions of the release bundle to environment "PROD".

jf rbdell myApp 1.0.0 PROD

Deleting release bundle remotely

This command will delete distributions of a release bundle from edge nodes.

Command-name	release-bundle-delete-remote
Abbreviation	rbdelr
Command arguments:
release bundle name	Name of the release bundle to distribute.
release bundle version	Version of the release bundle to distribute.
Command options:
--city	[Default: *] Wildcard filter for site city name.
--country-codes	[Default: *] semicolon-separated(;) list of wildcard filters for site country codes.
--dist-rules	[Optional] Path to a file, which includes the Distribution Rules in a JSON format. See the "Distribution Rules Structure" bellow.
--dry-run	[Default: false] Set to true to disable communication with JFrog Distribution.
--max-wait-minutes	[Default: 60] Max minutes to wait for sync distribution.
--project	[Optional] Project key associated with the Release Bundle version.
--quiet	[Default: $CI] Set to true to skip the delete confirmation message.
--server-id	[Optional] Platform Server ID configured using the 'jf config' command.
--site	[Default: *] Wildcard filter for site name.
--sync	[Default: false] Set to true to run synchronously.

Examples

Example 1

Delete the distributions of release bundle named myApp with version 1.0.0 from edge nodes matching the provided distribution rules defined in the specified file.

jf rbd --dist-rules=/path/to/dist-rules.json myApp 1.0.0

Example 2

Delete the distributions of the release bundle associated with project "proj" from the provided edge nodes. Run the command synchronously and skip the confirmation message.

jf rbd --dist-rules=/path/to/dist-rules.json --project="proj" --quiet --sync myApp 1.0.0

Exporting Release Bundle archive

JFrog Lifecycle Management supports distributing your Release Bundles to remote Edge nodes within an air-gapped environment. This use case is mainly intended for organizations that have two or more JFrog instances that have no network connection between them.

The following command allows exporting a Release Bundle as an archive to the filesystem that can be transferred to a different instance in an air-gapped environment.

Command-name	release-bundle-export
Abbreviation	rbe
Command arguments:
release bundle name	Name of the Release Bundle to export.
release bundle version	Version of the release bundle to export.
target pattern	The argument is optional and specifies the local file system target path.If the target path ends with a slash, the path is assumed to be a directory.For example, if you specify the target as "repo-name/a/b/", then "b" is assumed to be a directory into which files should be downloaded.If there is no terminal slash, the target path is assumed to be a file to which the downloaded file should be renamed.For example, if you specify the target as "a/b", the downloaded file is renamed to "b".
Command options:
--project	[Optional] Project key associated with the Release Bundle version.
--server-id	[Optional] Platform Server ID configured using the 'jf config' command.
mapping-pattern	[Optional] Specify a list of input regex mapping pairs that define where the queried artifact is located and where it should be placed after it is imported. Use this option if the path on the target is different than the source path.
mapping-target	[Optional] Specify a list of output regex mapping pairs that define where the queried artifact is located and where it should be placed after it is imported. Use this option if the path on the target is different than the source path.
split-count	[Optional] The maximum number of parts that can be concurrently uploaded per file during a multi-part upload. Set to 0 to disable multi-part upload.
min-split	[Optional] Minimum file size in KB to split into ranges when downloading. Set to -1 for no splits

Example

Export release bundle named "myApp" and version 1.0.0

jf rbe myApp 1.0.0

Example

Download to a specific location

jf rbe myApp 1.0.0 /user/mybundle/

Importing Release Bundle archive

Import a Release Bundle archive from a release bundle exported zip file.

Please note this functionality only works on Edge nodes within an air-gapped environment.

Command-name	release-bundle-import
Abbreviation	rbi
Command arguments:
path to archive	Path to the release bundle archive on the filesystem
Command options:
--project	[Optional] Project key associated with the Release Bundle version.
--server-id	[Optional] Platform Server ID configured using the 'jf config' command.

Example

Import a Release Bundle named "myExportedApp" and version 1.0.0

jf rbi ./myExportedApp.zip