Forem: Selma Guedidi

Publishing Your Java Library to Maven Central

Selma Guedidi — Sun, 05 Oct 2025 18:37:55 +0000

Why Maven Central Matters

You've built an amazing Java library. It solves real problems, the code is clean, and you're ready to share it with the world. But there's one crucial step between your local repository and global adoption: publishing to Maven Central.

Maven Central isn't just another package repository: it's the canonical repository for Java and JVM libraries. With over 10 million artifacts and billions of downloads monthly, it's where the entire Java ecosystem comes to find dependencies. When your library is on Maven Central, developers can add it to their projects with a single dependency declaration. No custom repositories, no manual downloads, no friction.

In this guide, I'll walk you through the entire process of publishing to Maven Central, from initial setup to your first release. Whether you're publishing your first library or your tenth, this guide will help you navigate the journey.

Step 1: Create Your Sonatype Account
Maven Central is operated by Sonatype, and they've recently modernized the onboarding process. You'll need to create an account on their new platform.

Go to https://central.sonatype.com
Click "Sign up" (you can use GitHub, Google, or email)
Verify your email address if using email registration

Step 2: Claim Your Namespace

Namespace ownership is fundamental to publishing on Maven Central. Your namespace (groupId) serves as the unique identifier for all your published artifacts, and you must demonstrate legitimate ownership before you can publish. The Central Portal offers two primary verification methods, each suited to different use cases.

Method 1: DNS-Based Verification (For Domain Owners)

If you own or maintain a registered domain name, you can leverage the Domain Name System in reversed format for your namespace. This approach mirrors Java's package naming convention and provides the most flexibility for organizational publishing.

How It Works:

The namespace uses your domain name in reverse order, allowing you to create as many subsections as needed for organizational purposes.

Examples:

Domain: example.com → Namespace: com.example
Domain: subdomain.example.com → Namespace: com.example
Domain: my-domain.com → Namespace: com.my-domain

Once verified, you can utilize any groupId starting with your reversed domain and extend it with additional subsections:

com.example.domain
com.example.test
com.example.utilities.logging

Important Considerations:

Exact Reversal: The groupId must reverse the domain name exactly as it appears, preserving hyphens and special characters even if they would produce invalid Java package names. This is acceptable and expected, your Java package names need not match your groupId.
Ownership Requirement: You must have control over the domain to add DNS verification records.

Verification Process:

Navigate to "Namespaces" in the left sidebar
Click "Add Namespace"
Enter your reversed domain namespace (e.g., com.example)
Select "DNS Verification" as your verification method
Copy the provided TXT record from the portal
Add this TXT record to your domain's DNS configuration
Return to the portal and click "Verify Namespace"
Verification typically completes within minutes once DNS propagates

Method 2: Code Hosting Service Verification (Personal Namespace)

For individual developers and open-source projects hosted on popular code hosting platforms, Maven Central provides a streamlined verification process using your platform identity. This method is ideal for personal libraries and projects without a custom domain.

Supported Platforms:

Code Hosting Service	Username Pattern	Example Namespace
GitHub	`myusername`	`io.github.myusername`
GitLab	`myusername`	`io.gitlab.myusername`
Gitee	`myusername`	`io.gitee.myusername`
Bitbucket	`myusername`	`io.bitbucket.myusername`

How It Works:

The namespace format follows the pattern io.{platform}.{username}, where the username matches your account on the respective platform. This creates a globally unique namespace tied to your platform identity.

Verification Process:

Navigate to "Namespaces"
Click "Add Namespace"
Enter your platform-based namespace (e.g., io.github.myusername)
Select your code hosting service as the verification method
The portal will prompt you to create a temporary public repository with a specific verification name
Create the repository on your platform with the exact name provided
Return to the portal and click "Verify Namespace"
Verification is typically instant once the repository is detected

Step 3: Generate GPG Keys

Maven Central enforces a strict security requirement: all published artifacts must be cryptographically signed using GPG (GNU Privacy Guard). This digital signature ensures artifact integrity and authenticity, protecting the entire Java ecosystem from tampering and unauthorized modifications.

3.1 Installing GPG

Before generating keys, you need to ensure GPG is installed on your system.

For macOS

Using Homebrew (recommended):

brew install gnupg

Using MacPorts:

sudo port install gnupg2

Verify installation:

gpg --version

For Linux

Debian/Ubuntu:

sudo apt-get update
sudo apt-get install gnupg

Fedora/RHEL/CentOS:

sudo dnf install gnupg2

Arch Linux:

sudo pacman -S gnupg

Verify installation:

gpg --version

For Windows

Option 1: Using Gpg4win (Recommended)

Download Gpg4win from https://gpg4win.org/download.html
Run the installer and follow the installation wizard
Add GPG to your PATH if not done automatically

Option 2: Using Chocolatey

choco install gnupg

Option 3: Using Windows Subsystem for Linux (WSL)

sudo apt-get install gnupg

Verify installation (in Command Prompt or PowerShell):

gpg --version

3.2 Generating Your Key Pair

Once GPG is installed, generate a new key pair for signing your artifacts:

gpg --gen-key

Follow the interactive prompts to configure your key:

Key type: Choose RSA and RSA (default)
Key size: Use 2048 bits or higher (4096 recommended)
Expiration: Set to 2-3 years (recommended) or no expiration
Real name: Your name or organization name
Email address: A professional email you control
Comment: Optional (e.g., "Maven Central Signing Key")
Passphrase: Create a strong passphrase

Critical: Your passphrase will be required for every release. Store it securely in a password manager—you cannot recover it if lost, and you'll need it throughout your publishing workflow.

Listing Your Keys

After generation, verify your keys:

gpg --list-keys

Output will look like:

pub   rsa4096 2025-10-05 [SC] [expires: 2027-10-05]
      1234567890ABCDEF1234567890ABCDEF12345678
uid           [ultimate] John Doe (Maven Central Signing Key) <john.doe@example.com>
sub   rsa4096 2025-10-05 [E] [expires: 2027-10-05]

The long hexadecimal string is your key ID. You can also use the last 8 characters as a short key ID.

3.3 Publishing Your Public Key

For Maven Central to verify your signatures, your public key must be published to a public key server:

# Using the full key ID
gpg --keyserver keys.openpgp.org --send-keys 1234567890ABCDEF1234567890ABCDEF12345678

# Or using the short key ID (last 8 characters)
gpg --keyserver keys.openpgp.org --send-keys 12345678

Note: It may take a few minutes for your key to propagate across key server networks.

Verifying Key Publication

Confirm your key is publicly accessible:

gpg --keyserver keys.openpgp.org --recv-keys YOUR_KEY_ID

If successful, you'll see:

gpg: key YOUR_KEY_ID: "John Doe (Maven Central Signing Key) <john.doe@example.com>" not changed
gpg: Total number processed: 1
gpg:              unchanged: 1

Next Steps

With your GPG keys generated, published, and backed up, you're ready to configure your build tool to automatically sign artifacts during the publishing process. Your key ID and passphrase will be required in the build configuration covered in Step 4.

Step 4: Configure Your Build Tool

Configuring Maven for publishing to Maven Central requires understanding two distinct deployment workflows: release versions and snapshot versions. Each serves a different purpose in the development lifecycle and has different requirements.

Understanding Release vs Snapshot Versions

Release Versions (e.g., 1.0.0, 2.3.1, 1.5.0-beta1):

Immutable and permanent once published
Require complete metadata, including developers, SCM, and license information
Undergo full validation before publication
Intended for production use and stable APIs
Cannot be overwritten or deleted after publication

Snapshot Versions (e.g., 1.0.0-SNAPSHOT, 2.3.1-SNAPSHOT):

Mutable and can be republished with the same version
Require minimal metadata validation
Used for development, testing, and continuous integration
Not indexed in Maven Central search
Must be explicitly enabled in your namespace configuration

Generating Authentication Tokens

Before configuring your build, you need to generate authentication tokens from the Central Portal:

Log in to https://central.sonatype.com
Click on your account name in the top right corner
Select "View User Tokens" from the dropdown
Click "Generate User Token"
The portal will display your username and password token
Save these immediately—the password token is only shown once

Important: These tokens are not your Sonatype login credentials. They are specifically generated for programmatic publishing and should be treated as API keys.

Enabling Snapshot Publishing (Optional)

If you plan to publish snapshot versions, you must enable this feature in your namespace:

Log in to https://central.sonatype.com
Navigate to "Namespaces"
Select your verified namespace
Click on its "dropdown menu"
Click on "Enable Snapshots"
Save the configuration

Without this setting enabled, snapshot deployments will fail with an authorization error.

Configuration for Release Versions

Release versions require comprehensive metadata and validation. This configuration ensures your artifacts meet all Maven Central requirements.

Maven POM Configuration

Add the following to your pom.xml:

<project>
    <groupId>io.github.yourusername</groupId>
    <artifactId>your-library</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <name>Your Library Name</name>
    <description>A comprehensive description of your library's purpose and functionality</description>
    <url>https://github.com/yourusername/your-library</url>

    <licenses>
        <license>
            <name>Apache License, Version 2.0</name>
            <url>https://www.apache.org/licenses/LICENSE-2.0.txt</url>
            <distribution>repo</distribution>
        </license>
    </licenses>

    <developers>
        <developer>
            <id>yourusername</id>
            <name>Your Full Name</name>
            <email>your.email@example.com</email>
            <organization>Your Organization</organization>
            <organizationUrl>https://yoursite.com</organizationUrl>
        </developer>
    </developers>

    <scm>
        <connection>scm:git:git://github.com/yourusername/your-library.git</connection>
        <developerConnection>scm:git:ssh://github.com:yourusername/your-library.git</developerConnection>
        <url>https://github.com/yourusername/your-library/tree/main</url>
        <tag>HEAD</tag>
    </scm>

    <build>
        <plugins>
            <!-- Central Publishing Plugin -->
            <plugin>
                <groupId>org.sonatype.central</groupId>
                <artifactId>central-publishing-maven-plugin</artifactId>
                <version>0.9.0</version>
                <extensions>true</extensions>
                <configuration>
                    <publishingServerId>central</publishingServerId>
                    <autoPublish>true</autoPublish>
                    <waitUntil>published</waitUntil>
                </configuration>
            </plugin>

            <!-- GPG Signing Plugin -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-gpg-plugin</artifactId>
                <version>3.1.0</version>
                <executions>
                    <execution>
                        <id>sign-artifacts</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>sign</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <!-- Retrieves passphrase from settings.xml -->
                    <passphraseServerId>gpg.passphrase</passphraseServerId>
                    <!-- Required for gpg2 to avoid GUI prompts -->
                    <gpgArguments>
                        <arg>--pinentry-mode</arg>
                        <arg>loopback</arg>
                    </gpgArguments>
                    <!-- Ensure correct GPG binary is used -->
                    <executable>gpg</executable>
                </configuration>
            </plugin>

            <!-- Source Attachment Plugin -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-source-plugin</artifactId>
                <version>3.3.1</version>
                <executions>
                    <execution>
                        <id>attach-sources</id>
                        <goals>
                            <goal>jar-no-fork</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <!-- Javadoc Generation Plugin -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>3.6.3</version>
                <executions>
                    <execution>
                        <id>attach-javadocs</id>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <!-- Optional: Configure Javadoc strictness -->
                    <doclint>none</doclint>
                    <quiet>true</quiet>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Plugin Explanations

Central Publishing Maven Plugin

<groupId>org.sonatype.central</groupId>
<artifactId>central-publishing-maven-plugin</artifactId>
<version>0.9.0</version>

This is the modern publishing plugin that replaces the legacy Nexus staging plugin. It handles the entire deployment workflow to Maven Central.

Key Configuration Options:

publishingServerId: References the server credentials in settings.xml (must be central)
autoPublish: When true, automatically publishes after successful validation. When false, requires manual approval in the Central Portal
waitUntil: Controls deployment behavior
- uploaded: Waits until artifacts are uploaded
- validated: Waits until validation completes
- published: Waits until artifacts are fully published to Maven Central (recommended)

Maven GPG Plugin

<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>3.1.0</version>

Signs all project artifacts (JAR, sources, javadoc, POM) with your GPG key during the verify phase.

Key Configuration Options:

passphraseServerId: References the GPG passphrase stored in settings.xml, avoiding hardcoded credentials
gpgArguments: Configures GPG behavior
- --pinentry-mode loopback: Essential for non-interactive environments (CI/CD) and gpg2, prevents GUI password prompts
executable: Specifies the GPG binary path. Use gpg2 if you have both versions installed

Maven Source Plugin

<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>3.3.1</version>

Generates a JAR file containing your source code. Maven Central mandates source JARs for all releases.

Key Configuration:

jar-no-fork: Creates the source JAR without forking a new Maven lifecycle, improving build performance

Maven Javadoc Plugin

<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.6.3</version>

Generates comprehensive API documentation and packages it as a JAR. Maven Central requires Javadoc JARs for all releases.

Optional Configuration:

doclint: Set to none to disable strict Javadoc validation (useful if you have legacy code with incomplete docs)
quiet: Reduces console output during generation

Maven Settings Configuration

Add the following to your ~/.m2/settings.xml:

<settings>
    <servers>
        <!-- Central Portal Authentication -->
        <server>
            <id>central</id>
            <username>YOUR_GENERATED_TOKEN_USERNAME</username>
            <password>YOUR_GENERATED_TOKEN_PASSWORD</password>
        </server>

        <!-- GPG Passphrase -->
        <server>
            <id>gpg.passphrase</id>
            <passphrase>YOUR_GPG_PASSPHRASE</passphrase>
        </server>
    </servers>
</settings>

Deploying a Release

Execute the deployment with a single command:

mvn clean deploy

This command will:

Clean previous build artifacts
Compile your code
Run tests
Generate source and Javadoc JARs
Sign all artifacts with GPG
Upload to Maven Central
Validate the deployment
Automatically publish (if autoPublish is true)

Verification: Monitor the deployment at https://central.sonatype.com/publishing/deployments

Configuration for Snapshot Versions

Snapshot versions are designed for rapid iteration during development. They have relaxed validation requirements and can be republished multiple times.

Maven POM Configuration for Snapshots

Snapshots require minimal metadata compared to releases:

<project>
    <groupId>io.github.yourusername</groupId>
    <artifactId>your-library</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <!-- Minimal required metadata for snapshots -->
    <name>Your Library Name</name>
    <description>Development snapshot of Your Library</description>
    <url>https://github.com/yourusername/your-library</url>

    <build>
        <plugins>
            <!-- Central Publishing Plugin (same as releases) -->
            <plugin>
                <groupId>org.sonatype.central</groupId>
                <artifactId>central-publishing-maven-plugin</artifactId>
                <version>0.9.0</version>
                <extensions>true</extensions>
                <configuration>
                    <publishingServerId>central</publishingServerId>
                    <autoPublish>true</autoPublish>
                </configuration>
            </plugin>

            <!-- GPG Signing (same as releases) -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-gpg-plugin</artifactId>
                <version>3.1.0</version>
                <executions>
                    <execution>
                        <id>sign-artifacts</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>sign</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <passphraseServerId>gpg.passphrase</passphraseServerId>
                    <gpgArguments>
                        <arg>--pinentry-mode</arg>
                        <arg>loopback</arg>
                    </gpgArguments>
                    <executable>gpg</executable>
                </configuration>
            </plugin>

            <!-- Source and Javadoc plugins are optional for snapshots -->
            <!-- Include them if you want consistent artifact structure -->
        </plugins>
    </build>
</project>

Key Differences for Snapshots

Relaxed Requirements:

No <developers> section required
No <scm> section required
No <licenses> section required (though recommended)
Source and Javadoc JARs are optional

Version Format:

Must end with -SNAPSHOT (e.g., 1.0.0-SNAPSHOT, 2.1.0-SNAPSHOT)
Can be republished multiple times without changing the version number

Publication Behavior:

Not indexed in Maven Central search
Available immediately after upload
Stored in a separate snapshot repository
Automatically cleaned up after a retention period

Deploying a Snapshot

Deploy snapshots using the same command:

mvn clean deploy

Maven automatically detects the -SNAPSHOT suffix and routes the deployment to the snapshot repository.

Consuming Published Snapshots

To use snapshots published by others (or your own), configure your project's pom.xml or settings.xml:

In Your Project's POM

<repositories>
    <repository>
        <id>central-portal-snapshots</id>
        <name>Central Portal Snapshots</name>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
        <releases>
            <enabled>false</enabled>
        </releases>
    </repository>
</repositories>

In Your Settings.xml (Global Configuration)

<settings>
    <profiles>
        <profile>
            <id>central-snapshots</id>
            <repositories>
                <repository>
                    <id>central-portal-snapshots</id>
                    <name>Central Portal Snapshots</name>
                    <url>https://central.sonatype.com/repository/maven-snapshots/</url>
                    <snapshots>
                        <enabled>true</enabled>
                        <updatePolicy>always</updatePolicy>
                    </snapshots>
                </repository>
            </repositories>
        </profile>
    </profiles>

    <activeProfiles>
        <activeProfile>central-snapshots</activeProfile>
    </activeProfiles>
</settings>

Configuration Options:

updatePolicy: Controls how often Maven checks for snapshot updates
- always: Check on every build (recommended for active development)
- daily: Check once per day (default)
- interval:X: Check every X minutes
- never: Never check for updates

Additional Resources

For more detailed information and the latest updates, refer to the official Sonatype documentation:

Central Portal Documentation: https://central.sonatype.org/register/central-portal/
Publishing Guide: https://central.sonatype.org/publish/publish-guide/
Maven Configuration: https://central.sonatype.org/publish/publish-maven/

The official documentation provides comprehensive coverage of edge cases, advanced configurations, and troubleshooting scenarios that may not be covered in this guide.

Note: Sonatype recently migrated from the old JIRA-based system to the new Central Portal at central.sonatype.com. If you find older tutorials mentioning JIRA tickets and issues.sonatype.org, that process is now deprecated. This guide reflects the current, streamlined process.

Questions or issues? Drop a comment below, and I'll do my best to help!

Understanding GitHub Webhooks: Leveraging Reverse Proxy with Ngrok for Local Development

Selma Guedidi — Thu, 25 Jul 2024 00:10:33 +0000

Webhooks are a powerful and flexible way for applications to communicate with each other in real-time. They are a crucial feature for developers who want to automate workflows and integrate with other services. In this blog post, we will explore what GitHub webhooks are, why we use them, and how to leverage a reverse proxy like Ngrok to trigger events on a local development environment.

What are GitHub Webhooks?

Webhooks allow you to subscribe to specific events occurring within a software system and automatically receive detailed data delivered to your server in real-time whenever those events take place.

When you create a webhook, you specify a URL and subscribe to specific events that occur within your GitHub repository. These events can range from code pushes and pull requests to issues and comments. Whenever an event that your webhook is subscribed to occurs, GitHub sends an HTTP POST request with detailed data about the event to the URL you specified.

The webhook's payload URL is the endpoint that will receive these HTTP requests. Your server must be set up to listen for webhook deliveries at this URL. When it receives a request, it can parse the event data and take appropriate actions. This allows for a wide variety of automated workflows, such as triggering CI/CD pipelines, sending notifications, or updating external systems with the latest repository information.

Detailed Workflow of GitHub Webhooks

Event Subscription: When configuring a webhook, you choose which events your webhook should listen for. These could include events like push, pull_request, issues, release, and more.
Event Trigger: When one of the subscribed events occurs in the repository, GitHub prepares an HTTP POST request with a payload containing details about the event. For example, a push event payload includes information about the commits, the branch involved, and the repository.
HTTP Request to Payload URL: GitHub sends the HTTP POST request to the specified payload URL. This request includes the payload data as JSON, providing all the necessary details about the event.
Server Processing: Your server, which is set up to handle requests at the payload URL, receives the webhook request. It then processes the payload data to determine what action to take. For instance, it might trigger a Jenkins build, post a message to a Slack channel, or update a database.
Response to GitHub: After processing the event, your server responds to GitHub with an HTTP status code. A 2xx status code indicates that the request was successfully received and processed.

Using Ngrok as a Reverse Proxy

In a local development environment, your server might not be accessible from the internet, making it difficult to test webhooks that require a publicly accessible endpoint. This is where Ngrok comes in handy. Ngrok is a tool that creates a secure tunnel to your local server, providing a public URL that GitHub can send webhooks to.

How does Ngrok Works?

Ngrok establishes a secure connection between your local machine and a publicly accessible URL, effectively exposing your local server to the internet. Here’s a detailed breakdown of the process:

Create an account in ngrok.com:

Follow given instructions to install ngrok and add authtoken:

Example: Setting Up Ngrok to Trigger a Simple CI/CD Pipeline in Jenkins

Let's walk through an example of setting up Ngrok to expose a local Jenkins server and configure a GitHub webhook to trigger a simple CI/CD pipeline when code is pushed to a repository.

Step 1: Ensure Jenkins is Running

For this example, let's assume that your Jenkins server is already installed and running on port 8080. If Jenkins is running correctly, you should be able to access it in your browser at http://localhost:8080.

Step 2: Install Github plugin

To allow Jenkins to be triggered by GitHub webhooks, you need to install the GitHub plugin:

Go to "Manage Jenkins” -> “Plugins”
Install the GitHub Plugin and restart Jenkins if required.

Step 3: Create a Jenkins Job

Click on “New Item,” enter a name for your job, select “Freestyle project,” and click “OK.”
Add git repository and specify branch(s)
Select the “GitHub hook trigger for GITScm polling” option.
Configure your job. For simplicity, you might just echo a message in the Build section.

Step 4: Start Ngrok

Open a terminal and start Ngrok to create a secure tunnel to your local Jenkins server:

ngrok http 8080

Ngrok will provide a public URL, such as:

Step 5: Configure GitHub Webhook

In your GitHub repository, configure a webhook to send events to your Jenkins server through the Ngrok URL:

Navigate to your GitHub repository and go to “Settings” -> “Webhooks”
Click “Add webhook”
In the “Payload URL” field, enter the Ngrok URL followed by /github-webhook/.
Click “Add webhook” to save.

Note: If your Jenkins server denies anonymous user access, you need to include authentication credentials in the webhook URL to avoid a 401 Unauthorized error. The URL format should be https://user:password@PUBLIC_URL/github-webhook/.

Step 6: Test the Setup
To test the webhook setup, push a change to your GitHub repository. This should trigger the webhook and send a request to your Jenkins server via the Ngrok tunnel. Jenkins will then trigger the configured job.

You can verify this by checking the Jenkins job console output. You should see the echo message "Build triggered by GitHub webhook," indicating that the webhook successfully triggered the CI/CD pipeline.

Conclusion

GitHub webhooks enable real-time automation by notifying external services about repository events. Testing these integrations locally can be challenging due to accessibility constraints. Ngrok simplifies this by creating a secure tunnel to your local server, allowing you to test webhook configurations as if they were exposed on the internet.

In our example, we demonstrated how to use Ngrok to trigger a Jenkins CI/CD pipeline from GitHub events. This setup allows for seamless testing of webhooks in a local environment, ensuring your integrations work as expected before deployment. Overall, leveraging GitHub webhooks with Ngrok enhances development efficiency and reliability.

A dive into Jenkins Configuration as Code (JCasC)

Selma Guedidi — Mon, 22 Jul 2024 19:05:06 +0000

In today's fast-paced DevOps world, automation is key to maintaining efficiency and consistency across development, testing, and deployment processes. Jenkins, a popular open-source automation server, offers a powerful feature called Jenkins Configuration as Code (JCasC). This allows you to manage your Jenkins configurations in a human-readable and declarative manner using YAML files, ensuring your setup is consistent, reproducible, and version-controlled.

In this blog post, we'll explore the benefits of JCasC and walk through a sample use case to get you started.

What is Jenkins Configuration as Code (JCasC)?

Jenkins Configuration as Code (JCasC) allows you to define and configure Jenkins instances using YAML files. This means you can describe all aspects of your Jenkins setup —from global configurations to job definitions— in a version-controlled repository.

Creating the Dockerfile

The Dockerfile provided below sets up Jenkins with the necessary plugins and configurations using JCasC:

FROM jenkins/jenkins:lts-jdk17

# Install Jenkins plugins
COPY plugins.txt /usr/share/jenkins/ref/plugins.txt
RUN jenkins-plugin-cli --plugin-file /usr/share/jenkins/ref/plugins.txt

# Disable the setup wizard as we will set up Jenkins as code
ENV JAVA_OPTS="-Djenkins.install.runSetupWizard=false"

# Copy the Configuration as Code (CasC) YAML file into the image
COPY jenkins-casc.yaml /var/jenkins_home/casc_configs/jenkins.yaml

# Tell the Jenkins Configuration as Code plugin where to find the YAML file
ENV CASC_JENKINS_CONFIG="/var/jenkins_home/casc_configs/jenkins.yaml"

In this Dockerfile, we start with the jenkins/jenkins:lts-jdk17 image, ensuring we have a stable Jenkins version with JDK 17.

The jenkins-plugin-cli is a command-line tool that installs Jenkins plugins specified in plugins.txt, streamlining the setup of necessary plugins.

The JAVA_OPTS environment variable disables the Jenkins setup wizard since we are configuring Jenkins using JCasC.

The COPY commands include the required plugins.txt and jenkins-casc.yaml files into the Docker image.

Finally, the CASC_JENKINS_CONFIG environment variable points Jenkins to the location of the JCasC YAML file, allowing it to automatically apply the specified configurations at startup.

Specifying Plugins

To ensure Jenkins has the necessary plugins for its operations, create a plugins.txt file. This file lists the required plugins and their versions:

git:5.0.0
workflow-aggregator:600.vb_57cdd26fdd7
configuration-as-code:1810.v9b_c30a_249a_4c
matrix-auth:3.2.2
job-dsl:1.87

Each line in plugins.txt specifies a plugin. You can include the version after a colon (e.g., git:5.0.0) to ensure a specific version is installed. If you omit the version (e.g., git), the latest version of the plugin will be installed when the image is built. Specifying versions can help maintain consistency across different environments by ensuring the same plugin versions are used.

The matrix-auth plugin is useful for managing access control in Jenkins environments where multiple users or teams interact with Jenkins. We'll need it later when we set up users and assign them different roles based on their responsibilities.

On the other hand, job-dsl Plugin adds support for defining Jenkins jobs using Groovy DSL scripts.

Note: The configuration-as-code plugin is essential for JCasC to function. It enables Jenkins to read the YAML configuration file and apply the specified settings automatically.

Configuring Jenkins with JCasC

Create a jenkins-casc.yaml file to configure Jenkins. In this blog, we will define user authentication, tool installations, and a sample job. Here’s a comprehensive example:

jenkins:
  systemMessage: "Jenkins configured automatically by Jenkins Configuration as Code plugin"

  # Security Realm for user authentication
  securityRealm:
    local:
      allowsSignup: false
      users:
        - id: "admin"
          password: "admin"

        - id: "developer"
          password: "developer"

        - id: "viewer"
          password: "viewer"


  # Authorization Strategy
  authorizationStrategy:
    projectMatrix:
      entries:
        - user:
            name: admin
            permissions:
              - Overall/Administer
        - user:
            name: developer
            permissions:
              - Overall/Read
              - Job/Build
        - user:
            name: viewer
            permissions:
              - Overall/Read



# Tool Configuration
tool:
  git:
    installations:
      - name: "Default"
        home: "/usr/bin/git"
  maven:
    installations:
      - name: maven3
        properties:
          - installSource:
              installers:
                - maven:
                    id: "3.8.4"

# Sample Job Configuration
jobs:
  - script: >
      pipelineJob('example-pipeline-job') {
      definition {
        cps {
            script('''
                pipeline {
                    agent any
                    stages {
                        stage('Build') {
                            steps {
                                echo 'Building...'
                            }
                        }
                        stage('Test') {
                            steps {
                                echo 'Testing...'
                            }
                        }
                        stage('Deploy') {
                            steps {
                                echo 'Deploying...'
                            }
                        }
                    }
                }
            ''')
            }
          }
        }

User authentication is defined in the securityRealm section, where local user authentication is configured, and self-signup is disabled for security. Three users are predefined: admin, with full administrative access; developer, with read and build permissions; and viewer, with read-only access. This setup ensures appropriate access levels based on user roles.

Authorization is handled by the Project-based Matrix Authorization Strategy in the authorizationStrategy section. This strategy provides granular control over user permissions, giving the admin full control with (Overall/Administer), while both the developer and viewer have read access to the overall Jenkins instance (Overall/Read), with the developer also having the ability to build jobs (Job/Build).

The tool section Specifies the configuration for tools that Jenkins will use, in our case: git and Maven. The git tool is set up with a default installation path, and Maven is installed ensuring that these tools are readily available for use in jobs.

The jobs section defines a sample pipeline job using a script block.

Build and Run the Docker Container

Now, we'll build and run our Docker container.

# Build the Docker image
docker build -t jenkins-jcasc .

# Run the Docker container
docker run --name jenkins -p 8080:8080  jenkins-jcasc

Once the container is running, you can access Jenkins at http://localhost:8080 and log in using one of the user credentials created earlier.

We can notice the system message we defined earlier and the sample pipeline.

You can find the code used for this blog in the following repository: https://github.com/SelmaGuedidi/JCasC

Reference

For further information on Jenkins Configuration as Code (JCasC), you can consult these sources:

Configuration-as-code plugin documentation: https://plugins.jenkins.io/configuration-as-code/

demos: https://github.com/jenkinsci/configuration-as-code-plugin/tree/master/demos

Conclusion

Jenkins Configuration as Code simplifies the management of Jenkins configurations, making your CI/CD pipeline more robust and easier to maintain. By leveraging Docker and JCasC, you can quickly set up consistent Jenkins environments that are easy to reproduce and update.

Try out JCasC in your projects and experience the benefits of a streamlined, automated Jenkins setup. Happy automating!