Apereo CAS - Upgrade Recipes w/ OpenRewrite

Posted by Misagh Moayyed on March 07, 2024 · 6 mins read ·
Content Unavailable
Your browser is blocking content on this website. Please check your browser settings and try again.

OpenRewrite is a tool and platform used by the CAS allows the project to upgrade installations in place from one version to the next. It works by making changes to the project structure representing your CAS Overlay build and printing the modified files back. Modification instructions are packaged together in form of upgrade scripts called Recipes that are produced by the CAS project, and then referenced and discovered in the CAS overlay.

In this post, we are going to take a brief look at what it takes to upgrade a CAS deployment using OpenRewrite. This tutorial specifically focuses on:

  • CAS 7.1.x
  • Java 21

Upgrade Recipes

OpenRewrite recipes are produced by CAS itself and are essentially YAML files that make minimally invasive changes to your CAS build allowing you to upgrade from one version to the next with minimal effort. The recipe contains almost everything that is required for a CAS build system to navigate from one version to other and automated tedious aspects of the upgrade such as finding the correct versions of CAS, relevant libraries and plugins as well as any possible structural changes to one’s CAS build.

While upgrades recipes will continue to get smarter and better over time, you should know that their technical prowess and ability can only go so far. There may be certain aspects of the upgrade that are simply not possible to automate, specially if you have made significant modifications to your CAS build.


Let’s suppose that your current CAS deployment is based on 7.0.0 and you intend to upgrade to 7.0.2. We begin by first verifying the base CAS version to confirm:

./gradlew casVersion --no-configuration-cache -q


Next, we can ask the build to discover and list all upgrade recipes that might be applicable for the task at hand:

./gradlew --init-script openrewrite.gradle rewriteDiscover \
    -PtargetVersion=7.0.2 --no-configuration-cache | grep "org.apereo.cas"


The output above shows the list of upgrade recipes that are available, if we were to switch to a target version of 7.0.2.

Next, we can dry-run our selected recipe, org.apereo.cas.cas702, and see which files would be changed in the build log. This does not alter your source files on disk at all. This goal can be used to preview the changes that would be made by the active recipes.

./gradlew --init-script openrewrite.gradle rewriteDryRun \
    -PtargetVersion=7.0.2 -DactiveRecipe="org.apereo.cas.cas702" \

The output will show how the build would be affected by the upgrade:

These recipes would make changes to gradle.properties:
        {key=cas.version, value=7.0.2, overwrite=true, filePattern=gradle.properties}
        {key=version, value=7.0.2, overwrite=true, filePattern=gradle.properties}
        {key=tomcatVersion, value=10.1.19, overwrite=false, filePattern=gradle.properties}
Report available:

You can in fact examine the generated .patch file:

diff --git a/gradle.properties b/gradle.properties
index ad0a33e..62fcb93 100644
--- a/gradle.properties
+++ b/gradle.properties
@@ -1,7 +1,7 @@ org.openrewrite.config.CompositeRecipe

 # CAS server version


@@ -70,3 +70,4 @@

When you are ready, you can run the actual recipe:

./gradlew --init-script openrewrite.gradle rewriteRun \
    -PtargetVersion=7.0.2 -DactiveRecipe="org.apereo.cas.cas702" \

This will run the selected recipes and apply the changes. This will write changes locally to your source files on disk. Afterward, review the changes, and when you are comfortable with the changes, commit them. You can examine the changes via:

git diff


I hope this review was of some help to you and I am sure that both this post as well as the functionality it attempts to explain can be improved in any number of ways. Please feel free to engage and contribute as best as you can.

Happy Coding,

Misagh Moayyed