The Jenkins plugin for DeployHub (https://plugins.jenkins.io/deployhub) allows Jenkins to notify DeployHub that a build has been performed and (optionally) trigger DeployHub to perform a deployment.
To create the link from DeployHub to Jenkins, it is first necessary to create a Build Engine in DeployHub. This Build Engine object refers to the external Jenkins Server. You can then create one or more Build Jobs which are linked to this Build Engine. Each Build Job is associated with a Project in the associated Jenkins Server. Once this is done, you can view the Jenkins Build History and open Jenkins Build Logs directly from inside DeployHub.
Once these Build Jobs have been defined you can link them to Components. This allows DeployHub to update the “Last Build Number” for each component that has been built whenever Jenkins notifies DeployHub that a build has been completed.
This last step has led to some confusion amongst the DeployHub community. Our support team have had many calls stating that a build has been done and yet the last build number for the associated component(s) have not been updated. The purpose of this post is to explain how DeployHub determines the Build Engine (and from there, the Build Job and associated Component) from the incoming Jenkins message.
How DeployHub Locates the Build Engine
Firstly, the Jenkins plugin does not ask you to provide details of the Build Engine in DeployHub. It was felt that from a Jenkins user perspective having to supply this information would be confusing. In addition, a Build Engine could always be renamed in DeployHub and this would result in the need to change the values in the plugin. All the Jenkins plugin requires is the URL of the DeployHub server and some login credentials.
Secondly, there could be multiple Jenkins instances all notifying DeployHub that a build has taken place. Two or more of those instances could even be on the same physical or virtual server. So how does DeployHub link the Jenkins Instance to the Build Engine?
The answer lies in the Jenkins URL. This is a value that is set in Jenkins itself (Manage Jenkins -> Configure System) and this is the URL that Jenkins sends out as part of its notification. On receiving the build notification, DeployHub then attempts to match this “Jenkins URL” with the “Server URL” that is defined for the Build Engine. Once a match is found, the connection can be made to the underlying Build Job and from there to all the components associated with that build job.
It is therefore essential that the “Jenkins URL” defined in the Jenkins Instance matches the “Server URL” defined for the DeployHub Build Engine. If there is a mismatch, the Build Engine cannot be determined from the incoming build notification and the build number will not be updated for the component. This is the most common cause of the Jenkins plugin not seeming to update the “Last Build Number”.
Version 8.0.1 of DeployHub also has another enhancement. Along with “Server URL” there is a new (optional) attribute for a Build Engine called “Jenkins Match URL”. If this attribute is specified, DeployHub will compare the incoming “Jenkins URL” with the “Jenkins Match URL” and not just the “Server URL”.
You can use this for circumstances when DeployHub requires a different IP address or hostname for the Jenkins Server Instance than Jenkins will use via its “Jenkins URL”. For example, if DeployHub and Jenkins are both hosted in containers then the “external” URL that Jenkins will present to the outside world will resolve to a different IP Address than DeployHub will need to use to connect to the Jenkins Container. In these circumstances, you can set the “Server URL” to the IP Address of Jenkins as seen from DeployHub and set the “Jenkins Match URL” to the value of the “Jenkins URL” in the Jenkins instance. That allows DeployHub to connect to Jenkins to display the Build Logs etc but still allows it to match the “Jenkins URL” when a build notification takes place.