How to Build, Test, and Publish Your Own Jenkins Plugin from Scratch

Why create a Jenkins plugin?

Integration : Connect Jenkins to proprietary or third‑party tools that lack existing plugins.

Custom workflow : Implement organization‑specific build steps or validation logic.

Security & compliance : Enforce security gates, policy checks, or compliance requirements in your pipelines.

Automation : Automate repetitive tasks or complex orchestration scenarios.

Community contribution : Share solutions with the open‑source Jenkins ecosystem.

Prerequisites and environment setup

Jenkins plugin development requires Java 21 (the version recommended by Jenkins) and Apache Maven 3.9.6 or newer. Verify installations with:

java -version

mvn -version

Configure Maven by creating or updating ~/.m2/settings.xml (or C:\Users\...\.m2\settings.xml on Windows) with the Jenkins plugin repository:

<settings>
  <pluginGroups>
    <pluginGroup>org.jenkins-ci.tools</pluginGroup>
  </pluginGroups>
  <profiles>
    <profile>
      <id>jenkins</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <repositories>
        <repository>
          <id>repo.jenkins-ci.org</id>
          <url>https://repo.jenkins-ci.org/public/</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>repo.jenkins-ci.org</id>
          <url>https://repo.jenkins-ci.org/public/</url>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
</settings>

IDE support is optional but helpful; IntelliJ IDEA, Eclipse, and NetBeans all provide Maven integration and Jenkins‑specific plugins for syntax highlighting and navigation.

Generate your first plugin

Use Jenkins’ Maven archetypes to scaffold a project. Run the following command in the directory where you want the plugin:

mvn -U archetype:generate -Dfilter=io.jenkins.archetypes:

Select the hello-world-plugin archetype. Provide the following values when prompted:

artifactId : a unique identifier (avoid the words “jenkins” or “plugin”). Example: release-gate groupId : follow Java package naming, e.g., io.jenkins.plugins.yourcompany version : defaults to 1.0‑SNAPSHOT package : Java package structure, e.g., io.jenkins.plugins.releasegate If the archetype generation hangs, bypass repository mirrors with an empty settings file:

echo '<settings/>' > /tmp/empty.xml
mvn -s /tmp/empty.xml -U archetype:generate -Dfilter=io.jenkins.archetypes:

Project structure

your-plugin/
├── pom.xml                # Maven build configuration
├── src/
│   ├── main/
│   │   ├── java/          # Java source code
│   │   └── resources/     # Configuration files, Jelly views
│   └── test/
│       ├── java/         # Unit and integration tests
│       └── resources/
├── work/                  # Jenkins home directory (created on first run)
└── target/                # Compiled artifacts (created during build)

Build the plugin

From the plugin directory run: mvn verify This compiles the code, runs unit tests, performs static analysis, and packages the plugin as an .hpi file.

Local testing

Start a Jenkins instance with your plugin loaded: mvn hpi:run If port 8080 is in use, specify another port: mvn hpi:run -Dport=5000 Open http://localhost:8080/jenkins/ in a browser. The Jenkins home directory is the work/ folder inside your project; changes to the plugin code require restarting the Maven process.

Iterative development

Make code changes.

Stop the running mvn hpi:run process (Ctrl+C).

Run mvn hpi:run again to reload changes.

Test the new functionality in the local Jenkins instance.

Repeat until satisfied.

Publish to the Jenkins Marketplace

Before requesting hosting, ensure the following:

Plugin code follows Jenkins naming conventions (plugin name, GroupID, proper commit messages).

The source resides in a public GitHub repository under your personal account.

A LICENSE file is present (MIT is recommended).

You have a Jenkins community account (register at https://accounts.jenkins.io/) to access the Jira tracker, Maven repository credentials, and mailing lists.

Comprehensive documentation (install guide, configuration guide, usage examples, troubleshooting).

Submit a hosting request via the repository-permissions-updater repository:

Log in to GitHub.

Navigate to the repository-permissions-updater repository.

Create a new issue using the provided template.

Provide plugin name, repository URL, GitHub username, description, and license information.

The Jenkins hosting team will review the request and may ask for code or documentation changes. After approval, an automated workflow forks your repository into the jenkinsci GitHub organization, grants you admin access, and asks you to delete the original repo or make it private, keeping the fork as the canonical source.

Continuous‑integration builds

Add a Jenkinsfile to enable CI for every commit:

buildPlugin(
  // Use Java 21 for building configurations
  configurations: [
    [platform: 'linux', jdk: 21],
    [platform: 'windows', jdk: 21]
  ]
)

This runs builds on multiple platforms, validates compatibility with different Jenkins versions, and runs static analysis.

Release process

When ready to ship a new version, follow semantic versioning ( MAJOR.MINOR.PATCH) and update the pom.xml version. Record changes in a CHANGELOG or release notes. Publish with Maven: mvn release:prepare release:perform Or, if you use automated publishing, simply tag the commit:

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

Plugin development best practices

Security

Validate all user input to prevent injection attacks.

Escape output in Jelly views to avoid XSS.

Use Jenkins Permission APIs for fine‑grained access control.

Never store sensitive data as plain text; follow OWASP Top 10 guidelines.

Code quality

Write comprehensive unit tests (coverage > 80%).

Include integration tests using JenkinsRule.

Run static analysis tools such as SpotBugs and Checkstyle.

Follow Java coding conventions and provide clear Javadoc.

Backward compatibility

Select an appropriate Jenkins baseline version.

Avoid breaking changes; deprecate before removal.

Test against multiple Jenkins versions.

Documentation

Maintain a detailed README with installation instructions and usage examples.

Document all configuration options and keep a changelog.

Example use cases

Security gate plugin : Integrate a vulnerability scanner into the CI/CD pipeline to block or mark builds based on policy violations.

Custom deployment plugin : Implement organization‑specific deployment steps supporting multiple environments.

Job discovery & monitoring : Scan all Jenkins jobs and push metadata to an external monitoring platform for compliance tracking.

Proprietary tool integration : Connect Jenkins to internal ticketing or deployment systems that lack existing plugins.

Policy enforcement : Enforce code‑review requirements, test‑coverage thresholds, or approval workflows before production deployment.

Common challenges and solutions

Long build times : Use Maven HPI Plugin incremental builds and optimise the test suite.

Debugging plugin issues : Run mvn hpi:run -Dorg.slf4j.simpleLogger.defaultLogLevel=debug for detailed logs.

Dependency conflicts : Manage dependencies carefully and declare Jenkins core dependencies with provided scope.

UI not updating : Clear browser cache or use incognito mode when testing UI changes.

Plugin fails to load : Check Jenkins system logs for errors and verify that all required dependencies are satisfied.