CodeQL: Auto Properties Breaking Java-Kotlin Maven Projects

Nov 27, 2025 by Alex Johnson 60 views

Automatically Supplemented Properties May Break Existing Java-Kotlin Maven Project CodeQL CI Discussion

Introduction

In this article, we'll dive into a specific issue encountered with CodeQL CI in a Java 8 project that utilizes both Java and Kotlin. The problem arises from automatically supplemented properties during the CodeQL analysis, leading to build failures. This issue was observed between CodeQL bundle versions 2.23.5 and 2.23.6, highlighting a potentially breaking change in the way CodeQL handles Maven projects with mixed languages. Understanding the root cause and potential solutions is crucial for developers maintaining similar projects. We aim to provide clarity on the situation, explore the implications, and offer insights into resolving this issue.

Background: Java-Kotlin Maven Projects and CodeQL

Before we delve into the specifics, let's establish some background. Java and Kotlin are popular languages for modern software development, often used together in the same project to leverage the strengths of each. Maven is a widely-used build automation tool, especially for Java projects, managing dependencies, compilation, and packaging. CodeQL, on the other hand, is a powerful static analysis engine used to identify potential security vulnerabilities and coding errors in a codebase. Integrating CodeQL into a CI (Continuous Integration) pipeline helps ensure code quality and security by automatically analyzing code changes.

In a typical Java-Kotlin Maven project, the pom.xml file specifies the project's configuration, including the Java and Kotlin versions, dependencies, and build settings. The kotlin-maven-plugin is essential for compiling Kotlin code within the Maven build process. CodeQL, when integrated, analyzes the project by building it and then performing static analysis on the resulting bytecode. This process often involves supplementing properties to the Maven build command to ensure correct compilation and analysis.

The Issue: Automatic Properties and Build Failures

The core issue arises from CodeQL's automatic supplementation of properties to the Maven build command. Specifically, CodeQL started automatically adding -Dmaven.compiler.source=8 -Dmaven.compiler.target=8 in version 2.23.6, which was not present in the earlier 2.23.5 version. While this might seem helpful in ensuring the Java version is explicitly set, it can cause problems when the kotlin-maven-plugin doesn't correctly recognize the Java version specified in this manner.

The user who reported the issue (Colosseum1316) observed that their project, which explicitly defines maven.compiler.source and maven.compiler.target as 1.8 in the pom.xml, started failing CodeQL CI runs after the upgrade to CodeQL 2.23.6. The failure occurred because the kotlin-maven-plugin didn't recognize the Java version 8 passed as a command-line property, leading to compilation errors. This highlights a potential incompatibility or unexpected interaction between CodeQL's automatic property supplementation and the kotlin-maven-plugin.

Examining the Evidence

The user provided links to two CodeQL CI runs to illustrate the issue. The successful run (using CodeQL 2.23.5) does not include the automatic -Dmaven.compiler.source=8 -Dmaven.compiler.target=8 properties. In contrast, the failed run (using CodeQL 2.23.6) shows these properties being automatically added, resulting in the build failure. This direct comparison provides concrete evidence of the change in behavior and its impact on the build process.

The project's pom.xml (https://github.com/Colosseum1316/Utility/blob/68b53dee80c27803b4de6cfafdc4411e5bb004e1/pom.xml) further confirms that the Java version is already explicitly defined within the project configuration. This raises the question of why CodeQL's automatic supplementation is necessary and why it's causing a conflict.

Why is This Happening? Understanding the Root Cause

To understand why this issue occurs, we need to consider the interaction between CodeQL's autobuild process, Maven, and the kotlin-maven-plugin. CodeQL's autobuild attempts to automatically configure the build process for analysis, which includes detecting the Java version and setting the maven.compiler.source and maven.compiler.target properties accordingly. This is generally a helpful feature, ensuring that the code is compiled with the correct Java version for analysis.

However, in projects that use Kotlin, the kotlin-maven-plugin is responsible for compiling Kotlin code. This plugin might have its own way of handling Java version compatibility, and it might not be fully aligned with how Maven processes the maven.compiler.source and maven.compiler.target properties when passed as command-line arguments. This discrepancy can lead to the kotlin-maven-plugin failing to recognize the Java version, even though it's correctly specified in the pom.xml.

The automatic supplementation of these properties by CodeQL, while intended to be helpful, inadvertently overrides the existing configuration in the pom.xml and introduces a conflict with the kotlin-maven-plugin. This highlights the importance of considering the specific needs and configurations of projects that use multiple languages and build tools.

Potential Solutions and Workarounds

Several solutions and workarounds can address this issue. Let's explore some of the most effective approaches:

1. Explicitly Configure CodeQL with `codeql.yml`

The most direct solution is to explicitly configure CodeQL using a codeql.yml file in the repository. This file allows you to customize the CodeQL analysis process, including specifying the build command and any necessary properties. By providing an explicit build command that excludes the problematic -Dmaven.compiler.source and -Dmaven.compiler.target properties, you can prevent CodeQL from automatically supplementing them.

Here's an example of a codeql.yml configuration that specifies the build command:

name: "CodeQL Analysis"

queries:
  - uses: security-extended

autobuild: false

build:
  - mvn clean install -DskipTests

In this configuration, autobuild: false disables CodeQL's automatic build process, and the build section specifies the explicit Maven command to use. This gives you full control over the build process and prevents CodeQL from interfering with the Java version configuration.

2. Modify the `pom.xml`

Another approach is to modify the pom.xml file to ensure that the kotlin-maven-plugin correctly recognizes the Java version. This might involve explicitly configuring the plugin to use the specified Java version or adjusting the plugin's settings to be more compatible with Maven's property handling.

For example, you might add the following configuration to the kotlin-maven-plugin section in your pom.xml:

<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-maven-plugin</artifactId>
    <version>${kotlin.version}</version>
    <executions>
        <execution>
            <id>compile</id>
            <phase>compile</phase>
            <goals>
                <goal>compile</goal>
            </goals>
        </execution>
        <execution>
            <id>test-compile</id>
            <phase>test-compile</phase>
            <goals>
                <goal>test-compile</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <jvmTarget>1.8</jvmTarget>
        <compilerPlugins>
            <plugin>kotlinx-serialization</plugin>
        </compilerPlugins>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-embeddable</artifactId>
            <version>${kotlin.version}</version>
        </dependency>
        <dependency>
            <groupId>org.jetbrains.kotlinx</groupId>
            <artifactId>kotlinx-serialization-compiler-plugin</artifactId>
            <version>${kotlin.serialization.version}</version>
        </dependency>
    </dependencies>
</plugin>

This configuration explicitly sets the jvmTarget to 1.8 for the kotlin-maven-plugin, ensuring that the plugin uses the correct Java version during compilation. However, this approach might require careful adjustment and testing to ensure compatibility with other parts of the build process.

3. Revert to CodeQL 2.23.5 (Temporary Workaround)

As a temporary workaround, you could revert to using CodeQL version 2.23.5, which does not automatically supplement the problematic properties. This would allow your CodeQL CI to pass without the need for immediate configuration changes. However, this is not a long-term solution, as you would miss out on any bug fixes or improvements in later CodeQL versions.

4. Report the Issue and Seek Community Support

Finally, it's essential to report the issue to the CodeQL team and seek support from the community. This helps ensure that the issue is properly addressed in future CodeQL releases and that other developers facing the same problem can benefit from the discussion and solutions.

You can report the issue on the GitHub repository for CodeQL or through other relevant channels, providing detailed information about your project configuration, the observed behavior, and any steps to reproduce the issue.

Conclusion

The issue of automatically supplemented properties breaking Java-Kotlin Maven projects in CodeQL CI highlights the complexities of integrating static analysis tools into multi-language build environments. While CodeQL's autobuild feature is generally helpful, it can sometimes lead to unexpected conflicts with specific project configurations.

By understanding the root cause of the issue and exploring potential solutions such as explicit CodeQL configuration, pom.xml modification, or temporary workarounds, developers can effectively address this problem and ensure the smooth integration of CodeQL into their CI pipelines. It's also crucial to engage with the CodeQL community and report any issues encountered, contributing to the continuous improvement of the tool.

For further information on CodeQL and its integration with CI/CD pipelines, refer to the official GitHub CodeQL documentation.