ARTIFACTORY: How to Retrieve Non-Promoted Build Numbers Using AQL and JQ

In JFrog Artifactory, it is often necessary to differentiate between promoted and non-promoted builds, especially when implementing automation in CI/CD pipelines. This article provides a method to retrieve non-promoted build numbers from a specific build name using Artifactory Query Language (AQL) in combination with the JQ.

This solution is particularly useful for identifying builds that have not yet been promoted, enabling better tracking and automation workflows.

Let’s consider a build named project in Artifactory, which contains multiple build numbers, some of which have been promoted and others not.

Below is the sample screenshot of Build and associated build number with promotion status from Artifactory GUI.

 

Step 1: Retrieve All Builds Using AQL

The below command will be helpful to retrieve all builds (including promotion information) associated with a specific build name (e.g., project

AQL command

$ curl -u<user-name> \ 
  -H "Content-Type: text/plain" \
  -d 'builds.find({
    "name": {"$match": "project"}
  }).include("name", "number", "created", "promotion")' \
  "https://<artifactory.com>/artifactory/api/search/aql"

Sample Output of above AQL query

{
"results" : [ {
  "build.created" : "2025-06-24T05:39:39.825Z",
  "build.name" : "project",
  "build.number" : "222"
},{
  "build.created" : "2025-06-24T05:40:59.797Z",
  "build.name" : "project",
  "build.number" : "111",
  "build.promotions" : [ {
    "build.promotion.comment" : "Build passed the IT tests and is being promoted",
    "build.promotion.created" : "2025-06-24T05:40:59.356Z",
    "build.promotion.created_by" : "admin",
    "build.promotion.repo" : "test-2",
    "build.promotion.status" : "it-passed"
  } ]
} ],
"range" : {
  "start_pos" : 0,
  "end_pos" : 2,
  "total" : 2,
  "limit" : 500000
}
}

From the above output, it lists both build numbers (i.e. 111 & 222) for the build name project.

Step 2: Filter Only Non-Promoted Builds Using jq

To isolate only the non-promoted builds (i.e., those that do not contain the build.promotions field), use the JQ.

AQL query using JQ

$ curl -u<user-name> \
  -H "Content-Type: text/plain" \
  -d 'builds.find({
    "name": {"$match": "project"}
  }).include("name", "number", "created", "promotion")' \
  "https://<artifactory.com>/artifactory/api/search/aql" | \
jq '[.results[] | select(.["build.promotions"] | not)]'

Sample Output of above AQL query

[
  {
    "build.created": "2025-06-24T05:39:39.825Z",
    "build.name": "project",
    "build.number": "222"
  }
]

This result shows that build number 222 under the build name project has not been promoted as shown in the above screenshot.

By combining AQL and jq, you can easily retrieve a list of non-promoted builds for a given build name in JFrog Artifactory. This method is useful for identifying builds pending promotion and is especially helpful in automating promotion logic in CI/CD workflows.

For more details on the AQL syntax, entities, and execution, refer to the following official documentation’s:

https://jfrog.com/help/r/jfrog-artifactory-documentation/artifactory-query-language
https://jfrog.com/help/r/jfrog-artifactory-documentation/aql-architecture
https://jfrog.com/help/r/jfrog-artifactory-documentation/aql-syntax
https://jfrog.com/help/r/jfrog-artifactory-documentation/aql-entities-and-fields
https://jfrog.com/help/r/jfrog-artifactory-documentation/aql-execution