Promote Application Version

Description: Promotes the specified application version to the desired stage. It includes options for including/excluding repositories, specifying running conditions, and providing comments.

Note

To move an application version to the official release stage, use the Release Application Version API.

Since: AppTrust 1.16.4

Usage: POST https://{{artifactory-host}}/apptrust/api/v1/applications/{{application_key}}/versions/{{version}}/promote

Query Parameters (optional):

Parameter	Type	Description
`async`	boolean	Determines whether the operation should be asynchronous (`true`) or synchronous (`false`). The default value is `false`, which means that Artifactory waits for application version promotion to complete before allowing you to move on to the next task.

Parameter

Type

Description

async

boolean

Determines whether the operation should be asynchronous (true) or synchronous (false).

The default value is false, which means that Artifactory waits for application version promotion to complete before allowing you to move on to the next task.

Request Body:

Parameter	Required/Optional	Type	Description
`target_stage`	required	string	The target stage to which the application version should be promoted.
`promotion_type`	optional	string	The type of promotion to perform: `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. `dry_run`: Simulates the promotion without actually performing it.
`included_repository_keys`		array:string	Defines specific repositories to include in the promotion. If this property is left undefined, all repositories (except those specifically excluded) are included in the promotion. Important If one or more repositories are specifically included, all other repositories are excluded (regardless of what is defined in `excluded_repository_keys`).
`excluded_repository_keys`		array:string	Defines specific repositories to exclude from the promotion.
`artifact_additional_properties`		array:string	Key-value pairs that define properties to add to each promoted artifact on top of any existing properties. Note If a property with the same key already exists on the artifact, the value defined in `artifact_additional_properties` will override the previous value.

Consumes: application/json

Response Body:

Parameter	Type	Description
`application_key`	string	The unique application key.
`version`	string	The application version identifier.
`source_stage`	string	The source stage from which the application version was promoted.
`target_stage`	string	The target stage to which the application version was promoted.
`promotion_type`	string	The promotion type that was performed: `copy` `move` `dry_run`
`status`	string	The outcome of the request (for example, success).
`message`	string	A human-readable summary of the outcome.
`included_repository_keys`	array:string	Repository keys that were specifically included in the promotion.
`excluded_repository_keys`	array:string	Repository keys that were specifically excluded from the promotion.
`artifact_additional_properties`	array:string	Key-value pairs that were added as properties to the application version.
`created`	string	Timestamp of when the version was promoted (ISO 8601 standard).
`evaluations`	object	Contains the results of policy evaluations performed at the source and target stage gates, if any.
`evaluations.exit_gate`	object	The evaluation result at the exit gate of the source stage.
`evaluations.exit_gate_eval_id`	string	The unique ID of the evaluation.
`evaluations.exit_gate.stage`	string	The name of the source stage.
`evaluations.exit_gate.decision`	string	The overall decision at the source stage's exit gate (`pass`, `warn`, `fail`).
`evaluations.exit_gate.explanation`	string	The summary of the exit gate evaluation outcome (omitted if the overall decision is `pass`).
`evaluations.exit_gate.violated_policies`	object	The list of policies that resulted in a `warn` or `fail` decision. This field is omitted if the overall decision is `pass`.
`evaluations.exit_gate.violated_policies.name`	string	The name of the violated policy.
`evaluations.exit_gate.violated_policies.policy_id`	string	The unique ID of the violated policy.
`evaluations.exit_gate.violated_policies.rule_name`	string	The name of the policy rule that was violated.
`evaluations.exit_gate.violated_policies.rule_category`	string	The category of the policy rule that was violated.
`evaluations.exit_gate.violated_policies.decision`	string	The decision for this specific policy (`warn`, `fail`).
`evaluations.exit_gate.violated_policies.resources_evaluated`	array:string	A list of resource IDs that were evaluated by the policy.
`evaluations.exit_gate.violated_policies.resources_evaluated.pass`	integer	The number of resources that passed the evaluation.
`evaluations.exit_gate.violated_policies.resources_evaluated.warn`	integer	The number of resources that passed with warnings.
`evaluations.exit_gate.violated_policies.resources_evaluated.fail`	integer	The number of resources that failed the evaluation.
`evaluations.entry_gate`	object	The evaluation result at the entry gate of the target stage.
`evaluations.entry_gate.eval_id`	string	The unique ID of the evaluation.
`evaluations.entry_gate.stage`	string	The name of the target stage.
`evaluations.entry_gate.decision`	string	The overall decision at the target stage's entry gate (`pass`, `warn`, `fail`).
`evaluations.entry_gate.explanation`	string	The summary of the entry gate evaluation outcome (omitted if the overall decision is `pass`).
`evaluations.entry_gate.violated_policies`	object	The list of policies that resulted in a `warn` or `fail` decision. This field is omitted if the overall decision is `pass`.
`evaluations.entry_gate.violated_policies.name`	string	The name of the violated policy.
`evaluations.entry_gate.violated_policies.policy_id`	string	The unique ID of the violated policy.
`evaluations.entry_gate.violated_policies.rule_name`	string	The name of the policy rule that was violated.
`evaluations.entry_gate.violated_policies.rule_category`	string	The category of the policy rule that was violated.
`evaluations.entry_gate.violated_policies.decision`	string	The decision for this specific policy (`warn`, `fail`).
`evaluations.entry_gate.violated_policies.resources_evaluated`	array:string	A list of resource IDs that were evaluated by the policy.
`evaluations.entry_gate.violated_policies.resources_evaluated.pass`	integer	The number of resources that passed the evaluation.
`evaluations.entry_gate.violated_policies.resources_evaluated.warn`	integer	The number of resources that passed with warnings.
`evaluations.entry_gate.violated_policies.resources_evaluated.fail`	integer	The number of resources that failed the evaluation.

Sample Request:

POST 'https://{host}.jfrog.io/apptrust/api/v1/applications/my-web-app/versions/1.2.0/promote'
Content-Type: application/json
Authorization: ••••••

{
  "target_stage": "QA",
  "promotion_type": "copy",
  "included_repository_keys": [
    "docker-prod-local"
  ],
  "artifact_additional_properties": [
    {
        "key": "release.status",
        "value": ["approved"]
    },
    {
        "key": "promoted.by",
        "value": ["jane.doe"]
    }
  ]
}

Sample Response (pass):

{
  "application_key": "my-web-app",
  "version": "1.2.0",
  "source_stage": "staging",
  "target_stage": "QA",
  "promotion_type": "copy",
  "status": "success",
  "message": "Copy promotion from 'staging' to 'QA' was successful.",
  "included_repository_keys": [
    "docker-prod-local"
  ],
  "excluded_repository_keys": [],
  "artifact_additional_properties": {
    "release.status": "approved",
    "promoted.by": "jane.doe"
  },
  "created": "2023-10-27T10:00:00Z",
  "evaluations": {
    "exit_gate": {
      "stage": "dev",
      "eval_id": "eval-exit-a1b2c3d4",
      "decision": "pass"
    },
    "entry_gate": {
      "stage": "staging",
      "eval_id": "eval-entry-e5f6g7h8",
      "decision": "pass"
    }
  }
}

Sample Response (warn):

{
  "application_key": "my-web-app",
  "version": "1.2.0",
  "source_stage": "staging",
  "target_stage": "QA",
  "promotion_type": "copy",
  "status": "success",
  "message": "Copy promotion from 'staging' to 'QA' was successful, but with warnings.",
  "created": "2025-07-28T12:17:46.787Z",
  "evaluations": {
    "exit_gate": {
      "stage": "staging",
      "eval_id": "eval-exit-dbeeff5a",
      "decision": "pass"
    },
    "entry_gate": {
      "stage": "QA",
      "eval_id": "eval-entry-8a9cf92f",
      "decision": "warn",
      "explanation": "Policy evaluation completed with warnings. The resource meets critical requirements but has some quality issues that should be addressed.",

Sample Response (fail):

{
  "application_key": "my-web-app",
  "version": "1.2.0",
  "source_stage": "staging",
  "target_stage": "prod",
  "promotion_type": "copy",
  "status": "failure",
  "message": "Copy promotion from 'staging' to 'prod' failed due to policy violations.",
  "created": "2025-07-30T13:00:00.000Z",
  "evaluations": {
    "exit_gate": {
      "stage": "staging",
      "eval_id": "eval-exit-a1b2c3d4",
      "decision": "pass"
    },
    "entry_gate": {
      "stage": "prod",
      "eval_id": "eval-entry-e5f6g7h8",
      "decision": "fail",
      "explanation": "Promotion blocked due to critical security vulnerabilities.",

Status Codes:

Code	Description
200	Promoted (asynchronous)
201	Promoted (synchronous)
400	Bad Request
401	Bad Credentials
403	Permission Denied
404	Not Found

Note

Note

Important

Note