Jar traceability with git commit metadata

Introduction

JAR files have been a fundamental part of Java development for decades, long before modern version control systems like Git became widely adopted. Initially, tracking the exact source code corresponding to a JAR file was not a primary concern. However, as software development has evolved, the need to reliably trace a JAR file back to its source code has become important. A common practice to achieve this is by including the release version in the JAR filename, linking it directly to a corresponding Git repository tag. However, if JAR files are named generically (e.g., application.jar instead of application-1.0.0.jar), identifying the exact source code version becomes challenging.

To overcome this challenge, a more effective approach is embedding Git commit metadata directly into the JAR’s manifest file. This ensures that regardless of the JAR filename, developers can always track the exact code version from which it was built.

Why embed git metadata in the JAR manifest?

By embedding git metadata into the JAR manifest, we ensure:

• Precise Code Traceability: Developers can identify the exact commit and branch associated with the build.

• Easy Debugging: When an issue arises in production, tracing back to the specific source code is straightforward.

• Better Release Management: Ensures proper tracking of deployed versions across different environments.

What information to add in the manifest file

The JAR manifest (META-INF/MANIFEST.MF) can store git metadata such as:

• Git Commit ID: The exact commit hash from which the JAR was built.

• Git Branch Name: Name of the branch used for the build.

• Repository URL: The link to the Git repository to locate the source code.

How to embed git metadata?

Gradle Projects

For Gradle projects modify jar task in build.gradle file to include Git metadata dynamically:

import java.text.SimpleDateFormat

def gitCommit = 'git rev-parse --short HEAD'.execute().text.trim()

def gitBranch = 'git rev-parse --abbrev-ref HEAD'.execute().text.trim()

def gitRepo = 'git config --get remote.origin.url'.execute().text.trim()

def buildTime = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date())

jar {

    manifest {

        attributes(

            'Implementation-Title': project.name,

            'Implementation-Version': version,

            'Git-Commit': gitCommit,

            'Git-Branch': gitBranch,

            'Git-Repo': gitRepo,

            'Build-Time': buildTime

        )

    }

}

This script fetches the current git commit, branch name and repository URL and injects them into the manifest. It also adds the date and time when the jar was built.

Maven Projects

For Maven-based projects modify the pom.xml file to use the git-commit-id-plugin to capture Git metadata and inject it into the JAR manifest:

<properties>

       <build.time>${maven.build.timestamp}</build.time>

       <exec.maven.plugin.version>1.6.0</exec.maven.plugin.version>

</properties>

<build>

    <plugins>

        <plugin>

               <groupId>pl.project13.maven</groupId>

               <artifactId>git-commit-id-plugin</artifactId>

               <version>4.0.0</version>

               <executions>

                   <execution>

                       <goals>

                           <goal>revision</goal>

                       </goals>

                   </execution>

               </executions>

           </plugin>

           <plugin>

               <groupId>org.apache.maven.plugins</groupId>

               <artifactId>maven-jar-plugin</artifactId>

               <version>3.2.0</version>

               <configuration>

                   <archive>

                       <manifestEntries>

                           <Implementation-Title>${project.name}</Implementation-Title>

                           <Implementation-Version>${project.version}</Implementation-Version>

                           <Git-Commit>${git.commit.id.abbrev}</Git-Commit>

                           <Git-Branch>${git.branch}</Git-Branch>

                           <Git-Repo>${git.remote.origin.url}</Git-Repo>

                           <Build-Time>${build.time}</Build-Time>

                       </manifestEntries>

                   </archive>

               </configuration>

           </plugin>

    </plugins>

</build>

This ensures the JAR includes Git commit and branch information automatically.

Verifying the Embedded Metadata

After building the JAR, you can check the metadata using the following command:

jar xf application.jar META-INF/MANIFEST.MF

cat META-INF/MANIFEST.MF

You should see output similar to below, apart from existing contents of the manifest file:

Git-Commit: a1b2c3d

Git-Branch: main

Git-Repo: https://github.com/your-repo.git

Build-Time: 2024-03-08 10:30:00

Summary

Embedding Git metadata inside a JAR’s manifest ensures robust traceability, making it easier to track code changes, debug issues, and manage releases efficiently. Whether using Gradle or Maven, integrating this approach into your build process enhances software maintainability and operational transparency.

Adopting this simple yet effective practice can save hours of debugging time and improve version control in Java projects. Start implementing it today and streamline your software deployment workflows!