1. Overview
Jenkins provides a set of remote access APIs and endpoints that enable users to get information, trigger builds, and configure new jobs. One of the common usages of these APIs is to retrieve the status of specific builds.
In this tutorial, we’ll cover how to get the last successful build information using the Jenkins APIs.
2. Get Last Successful Build Using curl
The simplest way to retrieve Jenkins build information is by using curl. curl is a command line utility that we can use to send data through common protocols such as HTTP, and it comes by default with most Linux distributions. So, we can query the Jenkins REST API by using curl directly from a Linux machine.
To send a request to the Jenkins API, the request needs to be authenticated. The first step we need to do before using the curl command is to generate an API token for our user. To do this, we simply go to the user dashboard from the Jenkins UI and then generate the token:
Once we have our token, the next step is to use it in our curl command. To retrieve the last successful build of a job, we send our request to the Jenkins instance IP/hostname followed by the endpoint /job/jobname/lastSuccessfulBuild/buildNumber:
$ curl --user {user}:{token} http://localhost:8080/job/test-job/lastSuccessfulBuild/buildNumber
1
In the above example, we used the –user option to provide the credentials to the curl command. We issued the command from the same machine where Jenkins is installed so we used localhost as the hostname, and the default Jenkins port 8080. Finally, we provided the endpoint for the last successful build with the job name test-job.
We can verify the result by checking the job from the Jenkins UI:
As we can see, the last successful build number of the job is #1, which is matching the output of the curl command.
We can also get the last build and last failed build by changing the endpoint:
$ curl --user {user}:{token} http://localhost:8080/job/test-job/lastBuild/buildNumber
3
$ curl --user {user}:{token} http://localhost:8080/job/test-job/lastFailedBuild/buildNumber
2
In this example, we replaced the lastSuccessfulBuild in the URL with lastBuild and lastFailedBuild. The output returned is matching the build numbers we saw in the Jenkins UI.
3. Get Last Successful Build Using a Jenkins Pipeline
If we don’t prefer using the raw REST API, we have other options to retrieve information from Jenkins. There are language wrappers that consume the Jenkins API and we can use them directly. A common example would be to use the Java or Groovy Jenkins.model.jenkins class inside a pipeline script. So, we can create a pipeline that retrieves the build status of other jobs inside Jenkins.
Let’s check this with an example:
pipeline {
agent any
stages {
stage("get build status"){
steps {
script {
def jobName = Jenkins.instance.getItem("test-job")
echo "${jobName.getLastSuccessfulBuild()}"
echo "${jobName.getLastFailedBuild()}"
echo "${jobName.getLastBuild()}"
}
}
}
}
}
In the above example, we created a pipeline script that retrieves different build statuses of our test-job. The Jenkins.instance.getItem() is a method of the Jenkins.model.jenkins class that returns an item object, which is the test-job in our example.
After that, we use the getLastSuccessfulBuild(), getLastFailedBuild(), and getLastBuild() methods of the test-job item to get the corresponding build for each status.
Now let’s see the output of this pipeline:
As we can see here, the pipeline output printed the build numbers corresponding to each build status of the test-job. If we compare this to the output of the curl command or the test-job from the Jenkins UI, they’ll match.
4. Conclusion
In this article, we’ve covered how to retrieve a Jenkins job build status. Jenkins allows remote access to get this information through a set of REST APIs which can be consumed directly or by using a language wrapper. We can retrieve a build status information using a tool like curl by sending HTTP requests to the appropriate endpoint*.* We can also use a Groovy script directly inside a Jenkins pipeline to retrieve the same information.