Get Application Version Promotions

Description: Returns the details of all promotions of the specified application version.

Since: AppTrust 1.16.4

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

Query Parameters (optional):

Parameter	Type	Description
`include`	string	When set to `message`, returns any error messages that were generated during the promotion operation.
`offset`	integer	Sets the number of records to skip before returning the query response. Used for pagination purposes.
`limit`	integer	Sets the maximum number of versions to return at one time. Used for pagination purposes.
`filter_by`	string	Defines a filter for the list of promotions based on: `application_version`: The application version. `target_stage`: The target stage. `promoted_by`: The name of the user who performed the promotion. `status`: The status of the promotion operation, for example, `success`, `pending`, `failed`.
`order_by`	string	Defines the criterion by which to order the list of promotions: `created` (supports standard ISO 8601 timestamps and milliseconds) `created_by` `version` `stage` The default is `created`.
`order_asc`	boolean	Defines whether to list the application in ascending (`true`) or descending (`false`) order. The default is `false`.

Response Body:

Property	Type	Description
`application_key`	string	The unique application key.
`application_version`	string	The application version.
`project_key`	string	The unique project key.
`status`	string	The current status of the application version.
`source_stage`	string	The stage from which the application version was promoted.
`target_stage`	string	The stage to which the application version was promoted.
`promoted_by`	string	The user ID who promoted this application version.
`promoted_at`	date	The date and time when this application version was promoted (ISO 8601 format).
`promoted_millis`	integer	The date and time when this application version was promoted in milliseconds.

Sample Request:

GET 'https://{host}.jfrog.io/apptrust/api/v1/applications/catalina-app/versions/1.0.0/promotions?limit=2'
Content-Type: application/json
Authorization: ••••••

Sample Response:

{
    "promotions": [
        {
            "status": "FAILED",
            "project_key": "catalina",
            "application_key": "my-app",
            "application_version": "1.0.0",
            "source_stage": "QA",
            "target_stage": "PROD",
            "promoted_by": "admin",
            "promoted": "2023-05-19T06:47:56.518Z",
            "created_millis": 1684478876518,
            "evaluations": {
              "exit_gate": {
          "stage": "QA",
          "eval_id": "eval-exit-b4c3d2a1",
          "decision": "pass"
       	 },
        "entry_gate": {
          "stage": "PROD",
          "eval_id": "eval-entry-h8g7f6e5",
          "decision": "fail",
          "explanation": "Promotion blocked due to critical security vulnerabilities."
        }
     	     }
        },
        {
            "status": "COMPLETED",
            "project_key": "catalina",
            "application_key": "my-app",
            "application_version": "1.0.0",
            "source_stage": "DEV",
            "target_stage": "QA",
            "created_by": "admin",
            "created": "2023-05-19T06:21:44.916Z",
            "created_millis": 1684477304916,
      "evaluations": {
        "exit_gate": {
          "stage": "DEV",
          "eval_id": "eval-exit-a1b2c3d4",
          "decision": "pass"
        },
        "entry_gate": {
          "stage": "QA",
          "eval_id": "eval-entry-e5f6g7h8",
          "decision": "pass"
        }
      }
    ],
    "total": 2,
    "limit": 1000,
    "offset": 0
}

Status Codes:

Code	Description
200	Success
401	Bad Credentials
403	Permission Denied