Hosting Plugins

Skip to end of metadata
Go to start of metadata

We encourage plugin developers to host the plugins in the Jenkins community repositories, either Github or svn.jenkins-ci.org. This makes it easier for the community to help you more easily, as well as to have the community benefit from the plugin. In this way, even when you move on to something else, the community can find someone else to pick up the work. You can take a quick look at how we work for more information.

Contents

Request hosting

Simply join the Developers List and send a message to tell us :

  • your GitHub plugin name
  • your personal GitHub ID (to use GitHub) or jenkins-ci.org account ID (to use Subversion), so that we can give you commit access (GitHub group IDs are not supported now, please use your personal ID)
  • The existing GitHub repository to fork (if you have one)

You'll get commit access to the repository under https://github.com/jenkinsci (GitHub).

If you'll be creating repositories often, consider getting access to do it yourself. See IRC Bot for more details.

While we recommend Git to facilitate collaboration, if you wish to host your plugin in Subversion, we can do that as an exception at https://svn.jenkins-ci.org/trunk/hudson/plugins/. Please note that using subversion is (kind of) deprecated, as most plugins moved to github (according to jenkinsci-dev).

Importing source code

Once you get commit access and a repository, you can import your source code:

$ cd path/to/yourplugin
$ git init
$ git add pom.xml src
$ git commit -m "initial import of my plugin"
$ git remote add origin git@github.com:jenkinsci/MYPLUGINNAME.git
$ git push origin master

We also recommend you look around some other plugin's POM file (such as this) to trim off the redundant things.

For example, usually the <groupId> is removed (groupId for the plugin, not the one in the <parent> section), to use the default which is org.jenkins-ci.plugins. <repositories> and <pluginRepositories> can be removed as well. If you need help, contact the dev list.

Declare your repository in your POM

The location of your repository needs to be declared in POM for plugins hosted in Github, by adding the following fragment:

  <scm>
    <connection>scm:git:ssh://github.com/jenkinsci/MYPLLUGINNAME.git</connection>
    <developerConnection>scm:git:ssh://git@github.com/jenkinsci/MYPLUGINNAME.git</developerConnection>
    <url>https://github.com/jenkinsci/MYPLUGINNAME</url>
  </scm>

Plugins in svn.jenkins-ci.org can omit this as long as the directory name in Subversion matches the plugin artifactId and the parent version is at least 1.398. Otherwise add a fragment like:

  <scm>
    <connection>scm:svn:https://svn.jenkins-ci.org/trunk/hudson/plugins/MYPLUGINNAME</connection>
    <developerConnection>scm:svn:https://svn.jenkins-ci.org/trunk/hudson/plugins/MYPLUGINNAME</developerConnection>
    <url>https://svn.jenkins-ci.org/trunk/hudson/plugins/MYPLUGINNAME</url>
  </scm>

Adding a Wiki page

A plugin should have its own Wiki page on this wiki, and the URL to the Wiki page should be listed in your POM like this:

<project>
  ...
  <url>http://wiki.jenkins-ci.org/display/JENKINS/My+Plugin</url>
</project>

This ensures that the update center will list your plugin correctly.

Give your wiki page a label like "plugin-scm" or "plugin-misc" (click Labels at the bottom of the wiki Edit page and start typing "plugin-" to see all the possible labels). This will ensure the page shows up as a link in the appropriate section of Plugins.

Also be sure to include {jenkins-plugin-info:pluginId=your-artifact} at the top of your wiki entry, to have the standard plugin infobox show up on your wiki page.

You should also include a description of your plugin inside {excerpt} tags, so that it appears in the update center.

If your plugin's component in JIRA is different than its artifact ID, use {jenkins-plugin-info:pluginId=your-artifact|jiraComponent=your-plugin-component} - if your plugin's GitHub repository or directory in Subversion does not match the artifact ID, add |sourceDir=your-plugin-dir as well.

Adding Maintainer Information

In your POM, make sure to include developer information, such as:

<project>
  ...
  <developers>
    <developer>
      <id>devguy</id>
      <name>Developer Guy</name>
      <email>devguy@developerguy.blah</email>
    </developer>
  </developers>
</project>

ID is your jenkins-ci.org account. The name is a human readable display name. This ensures that the update center and related tools are able to properly display the maintainer for your plugin. The email address is optional (it will be used in the plugin infobox on the wiki if provided in the POM).

Continuous integration builds on DEV@cloud

To have your plugin built on jenkins.ci.cloudbees.com, you do not need to do anything---all Jenkins plugins are automatically built as Maven jobs (clean install -e). All plugin CI broken build results will be mailed to any configured developers in the POM, plus culprits.

Prepare POM for release

Every plugin inherits from the "master plugin POM" (org.jenkins-ci.plugins:plugin or legacy org.jvnet.hudson.plugins:plugin). Since older master plugin POM doesn't reflect recent changes, the following adjustments need to be made.

Override the maven release plugin configuration (1.387 and earlier)

This is only for plugin that depend on a parent POM 1.387 and earlier. This prevents the release process from executing hpi:upload and hpi:announce goals, which fail.

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-release-plugin</artifactId>
        <configuration>
          <goals>deploy</goals>
        </configuration>
      </plugin>
    </plugins>
  </build>

Override the Maven repository location (1.395 and before)

Add the following declaration in your plugin POM so that the deployments goes to our Maven repository:

  <distributionManagement>
    <repository>
      <id>maven.jenkins-ci.org</id>
      <url>http://maven.jenkins-ci.org:8081/content/repositories/releases/</url>
    </repository>
  </distributionManagement>

Releasing to jenkins-ci.org

Please do not release any plugins using parent version 1.393 through 1.398 unless you follow extra steps listed here. There was a bug causing the parent version not to be recorded in the release, so Jenkins cannot warn people about upgrading such a plugin when using an older core version than it was meant for.

The easiest way to publish a plugin is to run the maven release plugin with your jenkins-ci.org account:

$ mvn release:prepare release:perform -Dusername=... -Dpassword=...

If you are using GitHub, make sure that the "origin" remote is pointed to your actual plugin repository.

This will perform all the usual release activity, and it will also post the plugin to the download section. If you run with the -B option, Maven will automatically use all the default values without prompting. Note that releases can be done for plugins hosted at Github.com as well as from Subversion (details).

Do not split that Maven command into two separate Maven invocations (i. e. mvn release:prepare followed by mvn release:perform): It won't work as you expect and will mess up your release. Always execute the two Maven goals together, in one command.
If you get back an 401: Unauthorized or if you encounter any other problem releasing your plugin while providing username and password as environment variable, try to pass username and password for authentication by modifying your settings.xml as described below.

However if your plugin is hosted on GitHub and you have different username and/or password for GitHub and jenkins-ci.org use of the command-line arguments for username/password will result in errors. You will have to start an ssh-agent and import your private key so the release plugin can access the GitHub repository and configure the password for jenkins-ci.org in your ~/.m2/settings.xml as described below.

Instead of listing username/password on the command line, you may also specify these in ~/.m2/settings.xml as follows:

settings.xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">

  <servers>
    <server>
      <id>maven.jenkins-ci.org</id> <!-- For parent 1.397 or newer; before this use id java.net-m2-repository -->
      <username>...</username>
      <password>...</password>
    </server>
  </servers>

</settings>

You may also follow these instructions to encrypt the password stored in settings.xml. Once you are done with this run mvn deploy to verify that your credential is correctly recognized by Maven.

Additionally, note that your settings.xml file may need extra configuration for publishing the plugin. See here.

Also consider these tips before making a plugin release.

The released plugin will show up in the update center in half a day or so.

You will likely need to add your new release info to the Changelog section of your Jenkins plugin wiki page.

Working around common issues

Using git version 1.8.5.2 or around
 After cd-ing to your plugin git repo folder, run the maven release commands this way, forcing version 2.5 of maven-release-plugin; alternatively, proceed to the next work-around topic right after this one:
mvn org.apache.maven.plugins:maven-release-plugin:2.5:prepare
mvn org.apache.maven.plugins:maven-release-plugin:2.5:perform
git push (should your git status still be "dirty")

Please keep this wiki topic at the beginning of hereby work-arounds, for top visibility purposes.

No prepare commits in git
 Should the previous (related) work-around not suit you, update maven-release-plugin to 2.5 version. See: jenkinsci-dev maillist
If a release fails with the following error, that means the version number for your plugin in pom.xml does not end with -SNAPSHOT. Add this suffix and commit the change, then try again.
    [INFO] ------------------------------------------------------------------------
    [ERROR] BUILD FAILURE
    [INFO] ------------------------------------------------------------------------
    [INFO] You don't have a SNAPSHOT project in the reactor projects list.
No prepare commits in git
 Should the previous (related) work-around not suit you, update maven-release-plugin to 2.5 version. See: jenkinsci-dev maillist
If a release fails with the following error, that means the version number for your plugin in pom.xml does not end with -SNAPSHOT. Add this suffix and commit the change, then try again.
    [INFO] ------------------------------------------------------------------------
    [ERROR] BUILD FAILURE
    [INFO] ------------------------------------------------------------------------
    [INFO] You don't have a SNAPSHOT project in the reactor projects list.
If a release only deploys snapshots consider upgrading the maven-scm-provider-gitexe to 1.9.1 or more (see more details.)
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-release-plugin</artifactId>
        <version>2.5.1</version>
        <dependencies>
          <dependency>
            <groupId>org.apache.maven.scm</groupId>
            <artifactId>maven-scm-provider-gitexe</artifactId>
            <version>1.9.2</version>
          </dependency>
        </dependencies>
      </plugin>
If changes to your pom.xml seem to be having no effect, try one of these to clear out any intermediate files and start over:
mvn -Dresume=false release:prepare release:perform
mvn release:rollback
mvn release:clean
Releasing failed due to errors relating to Javadoc?
If you see something like this when releasing, including lots of Javadoc errors you can't actually fix, because they're part of the Messages class...
[INFO] [ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.8:jar (attach-javadocs) on project <plugin-artifact-id>: MavenReportException: Error while creating archive:
... lots of Javadoc errors here ...

..then it's probable that you're building your plugin with Java 8, which has a tool called DocLint enabled by default.

You need to disable DocLint by adding the following to your pom.xml. Merge into the existing build.plugins section, if there is one.

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <configuration>
        <additionalparam>-Xdoclint:none</additionalparam>
      </configuration>
    </plugin>
  </plugins>
</build>
My release failed and I want to redo it from scratch
When a release fails in the middle, you unfortunately have to manually cancel out some of the side-effects Maven has caused. See this e-mail for details. The easiest way out is to forget about the botched release and simply move on to the next release number.
Subversion 1.6 authentication problem
Subversion 1.6 has a known problem with the --non-interactive switch that Maven uses, in that the presence of this switch prevents Subversion from accessing your authentication credentials. See this thread for more background discussion.
You can verify whether this is the cause of your problem by comparing the behavior between svn ls --non-interactive https://svn.jenkins-ci.org/ and svn ls https://svn.jenkins-ci.org/. Once verified that this is the root cause, tell Subversion to store the password in plain text

Additionally you need to check that you are not accessing the subversion repository with the "guest" user. So try svn ls --username YOURNAME https://svn.jenkins-ci.org/ . If it asks for your credentials then simply give it and retry.

OutOfMemoryError: Java heap space
If the release fails because Maven runs out of heap space, you may need to increase its limit by defining the MAVEN_OPTS environment variable. For example, in a bash shell, you could add the following to ~/.profile:
~/.profile
export MAVEN_OPTS=-Xmx300m

If you are running Maven inside IntelliJ 9.0.1, its setting for Maven > Runner > VM Parameters applies to only the parent Maven process, but it may be a child Maven process that is running out of memory. Furthermore, if you are running IntelliJ on MacOSX 10.6, normal environment variables, i.e., exported from ~/.profile, are not seen by apps launched from Finder. So, to increase the heap limit of child Maven processes in IntelliJ, you can configure MAVEN_OPTS in /etc/launchd.conf instead. Create or edit the file, e.g. sudo vi /etc/launchd.conf and add:

/etc/launchd.conf on MacOSX
setenv MAVEN_OPTS -Xmx300m
Error deploying artifact: Connection failed: Unable to connect to https://svn.dev.java.net/svn/maven2-repository/trunk/repository/
If the deployment fails it might be trying to write to a legacy repository. The instructions above and in the migration page should help with setting the correct target repository.
HTTP 401 when transferring a file to the Jenkins Maven repository
If, when running mvn release:perform, you get an error message similar to the following one, there are a few possibilities:
  • Your password is incorrect
  • You haven't added your jenkins-ci.org credentials to your ~/.m2/settings.xml file as described above.
  • The ID of the repository as specified in POM (which is normally inherited) doesn't match the ID in ~/.m2/settings.xml. To verify this, run mvn help:effective-pom and look for the <distributionManagement> element. For example, see this. This is because earlier versions of the plugin parent POM had this kind of problems. The easiest solution is bump up the parent POM to 1.409 or later. If you need to keep the parent version as is, then add additional <server> entry in your settings.xml with all the variations of the IDs.
[INFO] [ERROR] Failed to execute goal org.apache.maven.plugins:maven-deploy-plugin:2.5:deploy (default-deploy) on project sbt:
Failed to deploy artifacts: Could not transfer artifact org.jvnet.hudson.plugins:sbt:hpi:1.0 from/to
maven.jenkins-ci.org (http://maven.jenkins-ci.org:8081/content/repositories/releases/):
Failed to transfer file:
http://maven.jenkins-ci.org:8081/content/repositories/releases/org/jvnet/hudson/plugins/sbt/1.0/sbt-1.0.hpi.
Return code is: 401 -> [Help 1]
Make sure PW encryption is correct:
If release:prepare fails with the following error, you are most likely using "Cygwin" on Windows. There is a failure of path translation somewhere between Maven and the Cygwin Subversion client. The easiest way around this is to install a native Windows Subversion client (eg. Win32Svn) and re-run from a DOS/CMD window.
[INFO] Checking in modified POMs...
[INFO] Executing: cmd.exe /X /C "svn --non-interactive commit
       --file C:\DOCUME~1\username\LOCALS~1\Temp\maven-scm-1876439793.commit
       --targets C:\DOCUME~1\username\LOCALS~1\Temp\maven-scm-7190199490958000758-targets"
[INFO] Working directory: D:\home\ed\projects\hudson\plugins\lavalamp
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Unable to commit files
Provider message:
The svn command failed.
svn: '/cygdrive/d/home/username/projects/hudson/plugins/lavalamp/D:/home/username' does not exist
If a release fails with either of the following errors, that means you don't have hudson/plugins/pom.xml installed in your local repository. Run mvn -N install in the plugins directory and retry a release.
[INFO] Executing: mvn deploy
--no-plugin-updates -DperformRelease=true
    [INFO] Scanning for projects...
    Downloading:
http://repo1.maven.org/maven2/org/jvnet/hudson/plugins/plugin/1.NNN/plugin-1.NNN.pom
    [INFO] ------------------------------------------------------------------------
    [ERROR] FATAL ERROR
    [INFO] ------------------------------------------------------------------------
    [INFO] Error building POM (may not be this project's POM).


    Project ID: null:xxxxxx:hpi:N.N
[INFO] Scanning for projects...
       Downloading: http://repo1.maven.org/maven2/org/jvnet/hudson/plugins/plugin/1.212/plugin-1.212.pom
       [INFO] ------------------------------------------------------------------------
       [ERROR] FATAL ERROR
       [INFO] ------------------------------------------------------------------------
       [INFO] Failed to resolve artifact.

    GroupId: org.jvnet.hudson.plugins
       ArtifactId: plugin
       Version: 1.212

    Reason: Unable to download the artifact from any repository

      org.jvnet.hudson.plugins:plugin:pom:1.212

    from the specified remote repositories:
          central (http://repo1.maven.org/maven2)
Could not find maven-hpi-plugin jar
If release:prepare fails with an error like the following:
[ERROR] Unresolveable build extension: Plugin org.jenkins-ci.tools:maven-hpi-plugin:1.95 or one of its dependencies could not be resolved:
Could not find artifact org.jenkins-ci.tools:maven-hpi-plugin:jar:1.95 in central (http://repo.maven.apache.org/maven2)

You may need to update your local settings.xml. (A build might work, but not a release:prepare.) See here.

Subversion 409 Conflict
If a release:perform fails with an error like the following, retry mvn release:perform later. We don't know the root cause of this problem, but the problem does seem to disappear after a while.
[INFO] [INFO] Error deploying artifact: Connection failed: Unable to connect to
  https://svn.dev.java.net/svn/maven2-repository/trunk/repository/
[INFO]
[INFO] svn: The specified baseline is not the latest baseline, so it may not be checked out.
[INFO] svn: CHECKOUT of '/svn/maven2-repository/!svn/bln/1348162': 409 Conflict (https://svn.dev.java.net)
[INFO] [INFO] ------------------------------------------------------------------------
[INFO] [INFO] For more information, run Maven with the -e switch
[INFO] [INFO] ------------------------------------------------------------------------
git push hangs
Stackoverflow offers suggestions on how to correct this at http://stackoverflow.com/questions/3243755/maven-error-releasing-code-to-github-hangs-after-push.
For TortoiseGit users
If you use TortoiseGit as a Git client, do followings to have maven to run with TortoiseGit settings.
  1. Write the username/password of your jenkins-ci.org account in settings.xml (See above for details).
    • Passing username/password in the command line seems result that SSH client recognizes the username as the hostname, and fails to connect.
  2. Add the path of msysgit to PATH environment variable. You can see the path to msysgit in TortoiseGit>Settings>General, "Git.exe Path"
    set PATH=C:\Program Files\Git\bin
  3. Set the path of TortoisePlink.exe (in the bin directory of TortoiseGit) to GIT_SSH environment variable.
    set GIT_SSH=C:\Program Files\TortoiseGit\bin\TortoisePlink.exe
  4. Start pageant, and load putty key (ppk).
    pageant path\to\id_rsa.ppk
  5. Run release command without username/password
    mvn release:prepare release:perform

Frequently asked questions

What should be the Java package name?

If you'd like to use your own package name, feel free to do so. If you don't want to do so, or prefer to use the Jenkins name in the package name, we recommend jenkins.plugins.XYZ.

Help! My plugin is not showing up in the update center.

  1. First, check http://repo.jenkins-ci.org/releases/org/jenkins-ci/plugins/ or http://repo.jenkins-ci.org/releases/org/jvnet/hudson/plugins/ and see if your plugin is listed there. If not, your release process failed, and it never left your PC. If you can't resolve this issue, capture the output from mvn release:prepare release:perform and send it to the dev list.
  2. Check if your new version is in http://updates.jenkins-ci.org/update-center.json. This file is updated every 6 hours, so there's some delay before your new version appears here.
  3. If your plugin appears there but not in your Jenkins update center, visit Manage Plugins / Advanced and click the button to make Jenkins retrieve the latest update-center.json data.
  4. Look at https://ci.jenkins-ci.org/job/infra_update_center/ for more information on the updated update center json file. Make sure a build has occurred recently which should include your updated plugin.
  5. Check INFRA project for existing issues, ask jenkinsci-dev maillist and then open issue in INFRA
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment