Create Application Version CLI

Description: Creates a new application version that can include builds, Release Bundles, and other application versions. This command enables the creation of an application version using a spec file.

✅
Tip
Packages can be included inline using --source-type-packages, or in a spec file.

Command:

jf apptrust version-create <app-key> <version> [command options]

Alias command: jf at vc

Command Options

Option	Required/Optional	Type	Description
`<app-key>`	required	string	The application key of the application for which the version is being created.
`<version>`	required	string	The version number to assign to the application version in SemVer format.
`--dry-run`	optional	boolean	When `true`, AppTrust does a dry run of version creation. Validations are performed, but the version is not persisted. In other words, the application version is not actually created, and no audit or timeline events are generated. Default is `false`.
`--draft`	optional	boolean	Create the application version as a draft. Default is `false`.
`--conflict-resolution "<mode>"`	optional	string	How to resolve source conflicts when the same artifact path appears in multiple sources. Supported values: `automatic`, `manual`.
`--skip-unassigned`	optional	boolean	Automatically promote the new version to the first lifecycle stage when all of its source artifacts reside in repositories mapped to that stage. Otherwise the version is left unassigned and a message explaining why is returned. Default is `false`.
`--sync`	optional	boolean	Default is `true` (synchronous). Pass `--sync=false` to return as soon as the request is accepted, without waiting for the operation to complete.
`--tag "<tag>"`	optional	string	A free-text tag to associate with the version. The tag is limited to 255 characters, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics in between.
`--source-type-artifacts`	optional	array:string	List of semicolon-separated (;) artifacts to include in the application version, using the format: 'path=repo/path/to/artifact1[, sha256=hash1]; path=repo/path/to/artifact2[, sha256=hash2]' Note Each source type is optional, but the command must include at least one source type (artifacts, packages, builds, Release Bundles, or application versions), unless you define the sources in a spec file.
`--source-type-packages`	optional	array:string	List of semicolon-separated (;) packages to include in the application version, using the format: 'type=packageType1, name=packageName1, version=version1, repo-key=repo1; type=packageType2, name=packageName2, version=version2, repo-key=repo2'
`--source-type-builds`	optional	array:string	A list of semicolon-separated builds to include in the application version, using the format: 'name=buildName1, id=runID1[, include-deps=true] [, repo-key=repo1] [, started=2023-01-01T12:34:56.789+0100]; name=buildName2, id=runID2'.
`--source-type-release-bundles`	optional	array:string	A list of semicolon-separated Release Bundles to include in the application version, using the format: 'name=releaseBundleName1, version=version1[, project-key=project1] [, repo-key=repo1]; name=releaseBundleName2, version=version2'.
`--source-type-application-versions`	optional	array:string	A list of semicolon-separated application versions to include in the application version, using the format 'application-key=app_key1, version=version1; application-key=app_key2, version=version2'.
`--spec "<path>"`	optional	string	The path to a file spec to be used in place of inline command options. For more information, see Using File Specs.
`--spec-vars "<key-value-pairs>"`	optional	string	A list of variables in the form of `"key1=value1;key2=value2;..."` (wrapped by quotes) to be replaced in the file spec. In the file spec, use the variables as follows: `${key1}`
`--include-filter`	optional	string	List of semicolon-separated (;) inclusion filters. Must include `filter_type=package` or `filter_type=artifact`. For packages, at least one of `type`, `name`, or `version` must be specified. For artifacts, at least one of `path` or `sha256` must be specified.
`--exclude-filter`	optional	string	List of semicolon-separated (;) exclusion filters. Must include `filter_type=package` or `filter_type=artifact`. For packages, at least one of `type`, `name`, or `version` must be specified. For artifacts, at least one of `path` or `sha256` must be specified.
`<filter_type>`	optional	string	Required when using `--include-filter` or `--exclude-filter`. The filter type can be package or artifact.

Example 1: Create an application version from a build

This command creates a new version of the my-auth-service application tagged as a release candidate.

jfrog apptrust version-create my-auth-service 1.2.0 --source-type-builds "name=my-build, id=ID1" --tag="prototype"

Output:

Successfully created application version '1.2.0' of application 'my-auth-service'.

Example 2: Create an application version using a spec file

This command creates an application version whose sources are defined in a spec file.

jf at version-create green-pizza 1.2.3 --spec /path/to/spec.json

Spec types:

"artifacts": [
   {
     "path": "repo/path/to/app.jar",
     "sha256": "abc123def456789"
   },
   {
     "path": "repo/path/to/lib.war"
   }
 ],
 "packages": [
   {
     "type": "npm",
     "name": "my-package",
     "version": "1.2.3",
     "repository_key": "npm-local"
   },
   {
     "type": "docker",
     "name": "my-docker-image",
     "version": "2.0.0",
     "repository_key": "docker-local"
   }
 ],
 "builds": [
   {
     "name": "build",
     "number": "1",
     "repository_key": "myproject-build-info",
     "include_dependencies": false
   }
 ],
 "release_bundles": [
   {
     "name": "my-release-bundle",
     "version": "1.0.0",
     "project_key": "my-project",
     "repository_key": "rb-repo"
   },
   {
     "name": "another-release-bundle",
     "version": "2.0.0"
   }
 ],
 "versions": [
   {
     "application_key": "app-version-1",
     "version": "3.0.0"
   },
   {
     "application_key": "app-version-1",
     "version": "4.5.6"
   }
 ]

Example 4: Include Filters

--include-filter "filter_type=package, type=docker, name=frontend-*"

--include-filter "filter_type=artifact, path=libs/*.jar"

--include-filter "filter_type=artifact, sha256=a1b2c3d4e5f6..."

--include-filter "filter_type=artifact, path=libs/*-4.2.1.jar; filter_type=artifact, path=libs/*-4.2.2.jar; filter_type=artifact, path=libs/*-4.2.6.jar"

--include-filter "filter_type=package, type=npm, name=_request_; filter_type=package, type=npm, name=_colors_"

Example 5: Exclude Filters

--exclude-filter "filter_type=package, name=*-dev"

--exclude-filter "filter_type=artifact, sha256=f6e5d4c3b2a1..."

Example 6: Perform a Dry Run

jf apptrust version-create --source-type-builds "name=Commons-Build, id=1.0.0" --dry-run=true app1 2.0.0

Response to a Successful Dry Run

22:13:51 [🔵Info] Dry run successful for application version: app1:2.0.0
{"application_key":"app1","version":"2.0.0","created_by":"admin","status":"COMPLETED","tag":"","dry_run":true}

Frequently Asked Questions

Common questions about creating an application version.

plusFAQs

Q: How do I create an application version from a build using the JFrog CLI?

A: Run jf apptrust version-create <app-key> <version> --source-type-builds "name=<build>, id=<runID>". You can also source artifacts, packages, Release Bundles, or other application versions instead of a build. See Example 1.

Q: What happens if I don't specify any source type?

A: The command fails unless you define your sources in a spec file. You must include at least one source type, such as artifacts, packages, builds, Release Bundles, or application versions, or use --spec.

Q: What is the difference between --dry-run and --draft?

A: --dry-run validates the request without creating anything or generating audit events. --draft creates the version as a draft (default is false).

Q: Can I create an application version using a spec file instead of inline options?

A: Yes. Pass --spec with the path to a JSON file, and optionally --spec-vars to substitute variables in that file. See Example 2.

Q: Can a new application version be automatically promoted to its first lifecycle stage on creation?

A: Yes. If you set --skip-unassigned=true and all source artifacts reside in repositories mapped to a stage, the version is automatically promoted to that stage. Otherwise it's left unassigned.

Command Options

Example 1: Create an application version from a build

Example 2: Create an application version using a spec file

Frequently Asked Questions

Q: How do I create an application version from a build using the JFrog CLI?

Q: What happens if I don't specify any source type?

Q: What is the difference between --dry-run and --draft?

Q: Can I create an application version using a spec file instead of inline options?

Q: Can a new application version be automatically promoted to its first lifecycle stage on creation?

Related Topics