Using Jenkins-X UpdateBot

Jenkins-X UpdateBot is a tool for automating the update of dependency versions within project source code. Say you're building two projects, A and B, such that B uses A as a dependency. The release process for A could use UpdateBot to update the source for project B to use a new version of A. With UpdateBot this would result in a pull request so that the change could be tested and reviewed or automatically merged.

Within pipelines on the Jenkins-X platform, UpdateBot is automatically present and invoked by updatebot commands in Jenkinsfiles. But UpdateBot can also be used outside of Jenkins-X and running it alone can help to understand what it can do and test out version replacements. So let's try it out with a simple tester project.

Configuring the Demo

UpdateBot can set versions for a range of different file types — we won't test them all here but we want a project that features several. So we can use a JHipster sample app as this features a Maven pom.xml, an npm package.json and a Dockerfile. We'll run UpdateBot against it to see what UpdateBot can replace in these source files.

We can download the UpdateBot jar file (v1.1.31) and set up a simple UpdateBot config file pointing at the GitHub repository for the project we want to update:

github:
  organisations:
  - name: ryandawsonuk
    repositories:
    - name: jhipster-sample-app
      useSinglePullRequest: true

The flag useSinglePullRequest would mean that one PR is created containing all of the changes we make. But we're not actually going to push any changes - we'll just run it locally so that we don't need GitHub write permissions on the repository. We can run without pushing to GitHub by setting an environment variable:

export UPDATEBOT_DRY_RUN=true

We will then still need to set git credentials with further environment variables for UPDATEBOT_GITHUB_USER and UPDATEBOT_GITHUB_PASSWORD (or token).

Then we can run some UpdateBot commands and see what is replaced in the project cloned from Git. To do this we can use a demo project on GitHub containing a pre-configured script. 

Running the Demo

First the script updates the maven pom.xml, asking for a change to a spring boot version:

java -jar updatebot-1.1.31.jar push-version --kind maven org.springframework.boot:spring-boot-starter-data-jpa 2.1.0.RELEASE

And it inspects the change and outputs a git diff, with the result that we see:

So the version is replaced. Notice that it is replaced in a property that the dependency references as in this case the pom.xml features this version in a property. UpdateBot can also work for changes that are direct in a dependency or a parent or plugin.

The change to package.json is to change ngx-cookie version to 2.0.2:

java -jar updatebot-1.1.31.jar push-version --kind npm ngx-cookie 2.0.2

And this is made much as we would expect:

The change to the Dockerfile is to change the openjdk version/tag to 8-jdk:

java -jar updatebot-1.1.31.jar push-version --kind docker openjdk 8-jdk

This one shows that we can be caught out. The Dockerfile actually uses two different openjdk images, each with a different tag and this command replaces both:

I hadn't thought about this in advance of running the command so here I'd need to decide what I really want to replace.

Running for Real

If we run without the dry-run flag then a real pull request gets created, provided we have permission to create it.

The UpdateBot has features to auto-merge pull requests such as this by polling GitHub to check the PR status and merge if all is good (the command is  updatebot update-loop ). However, GitHub does rate-limit these requests so the UpdateBot can also add its approval to a PR for it to be merged by a tool directly integrated with GitHub. This could work well when using tools such as prow or mergify for automatic merging.

UpdateBot can try to infer changes to push as part of a commit-triggered pipeline by using just updatebot push instead of updatebot push-version with explicit parameters. However, typically a pipeline job will have access to the version to be pushed and  push-version  makes changes more explicit and more easily traceable.

This example has used a single UpdateBot YAML file to push one set of dependencies/versions to a single downstream project. The YAML file also supports pushing a set of changes to multiple downstream repositories. UpdateBot pushes all the replacements that it is able to make so that each downstream repo gets all the changes applicable to it.

 UpdateBot could, for example, be used for propagating versions in a CI/CD setup when building maven projects without snapshots. But as we have seen it is not limited to maven and could push a range of changes for projects that produce a variety of different types of artifacts.