Promote Application Version CLI

Description: Promotes the application version to the desired stage, with options for including or excluding repositories, running conditions, and adding comments. There is also a path mapping option, so that you can change the directory structure or path names in the target environment.

Command:

jf apptrust version-promote <app-key> <version> <target-stage> [command options]

Alias command: jf at vp

Command Options

Option	Required/Optional	Type	Description
`<app-key>`	required	string	The application key of the application for which the version is being promoted.
`<version>`	required	string	The version to promote.
`<target-stage>`	required	string	The stage to which the application version should be promoted (for example, DEV, QA, STG).
`--sync <true\|false>`	optional	boolean	Determines whether to perform the promotion synchronously or asynchronously. Default is `true` (synchronous). Pass `--sync=false` to return as soon as the request is accepted, without waiting for the operation to complete.
`--promotion-type`	optional	string	The type of promotion to perform: Specifies the promotion type: `copy`: Copies the application version to the target stage, preserving the source artifacts. This is the default. Note No physical copy occurs if the source and target repositories are identical. `move`: Moves the application version to the target stage, transferring the source. `keep`: Promotes without copying or moving artifacts.
`--props "<key>=<value1>[,<value2>,...]"`	optional	object	Defines a semicolon-separated list of properties to be added to each artifact in the application version. The format is: `'key1=value1;key2=value2;...'`
`--dry-run`	optional	boolean	When set to `true`, simulates the promotion without actually performing it. The default value is `false`.
`--exclude-repos`	optional	array:string	A list of semicolon-separated (;) repositories to exclude from the promotion.
`--include-repos`	optional	array:string	A list of semicolon-separated (;) repositories to include in the promotion. If this property is not defined, all repositories (except those explicitly excluded) are included in the promotion. If one or more repositories are specifically included, all other repositories are excluded.
`--overwrite-strategy`	optional	string	Determines whether artifacts can be overwritten during promotion. This is a strategy for handling target artifacts with the same path but different checksums and is an exception to the general immutability of artifacts. If omitted, the platform determines the applicable strategy. Policy options: `latest`: Overwrite is permitted only if the artifact tag is `latest`. This option is intended primarily for artifacts that make use of the latest tag. `all`: Overwriting of artifacts of any path is permitted. `disabled`: No overwriting is permitted. This is the strongest option for preserving immutability during promotion. If you chose `keep` as the `promotion-type`, the `overwrite-strategy` parameter will be ignored.
`--path-mapping`	optional	array:string	Changes the relative path structure or path names of artifacts in the target environment. A list of semicolon-separated (;) mapping rules in the form `'input=<regex>, output=<target-path>[, package-type=<type>]'`. Fields are: `input`: A standard regex pattern executed against the source relative paths to capture components via grouping. `output`: The target path string using placeholder variables, for example, $1, $2, to reconstruct the destination layout. `package-type`: A regular expression string used to target specific artifact types, for example, docker, npm, or .* to match all types. Quote the value to prevent shell expansion of `$1`. See Example 4.

Example 1: Promote an application version

This command promotes an application version to the QA stage.

jfrog apptrust version-promote APP001 1.0.0 QA

Output (error):

{
   "message": "Failed to promote version.",
   "error": "<error-message>"
}

Example 2: Promote an application version with optional flags

This command performs a copy promotion in synchronous mode, while excluding repoA and repoB from the promotion.

jfrog apptrust version-promote APP001 1.0.0 DEV --sync=true --exclude-repos "repoA;repoB" --promotion-type copy

Example 3: Perform a dry-run promotion

This command simulates a promotion to the QA stage:

jfrog apptrust version-promote APP001 1.0.0 QA --dry-run=true

Example 4: Path mappings

This command applies a regex rule during a version promotion via the CLI, so that specific file extensions are automatically moved into designated subdirectories at the target destination. The example includes multiple mappings.

jf at version-promote my-app 1.5.0 PROD --path-mapping="input=(.*), output=stable-release/\$1, package-type=.*; input=(.*\.jar), output=jars/\$1, package-type=maven"

Frequently Asked Questions

Common questions about promoting an application version.

plusFAQs

Q: How do I promote an application version to a new stage using the JFrog CLI?

A: Run jf apptrust version-promote <app-key> <version> <target-stage>. See Example 1.

Q: What is the difference between the copy, move, and keep promotion types?

A: copy preserves the source artifacts and copies them to the target stage, move transfers the source artifacts to the target stage, and keep promotes the version without copying or moving any artifacts.

Q: What happens if I promote with an overwrite-strategy of disabled?

A: No overwriting is permitted. This is the strongest option for preserving artifact immutability, and it's ignored if you also choose keep as the promotion type.

Q: Can I change artifact paths when promoting to a target environment?

A: Yes. Use --path-mapping with regex input and output rules to restructure paths or names in the target environment. See Example 4.

Q: Can I preview a promotion before running it?

A: Yes. Pass --dry-run=true to simulate the promotion without actually performing it. See Example 3.