Guide to Plugin Hosting

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

This guide will cover the entire plugin hosting process.

Once you’ve completed all steps described on this page you will have accomplished the following:

  • Your plugin source code will be hosted in a repository in the jenkinsci GitHub organization. You will have admin access to this repository.

  • You will be allowed to release the plugin to the Jenkins project Maven repository, which serves as a source for the Jenkins project operated update sites.

Preparation

Complete the following steps before requesting plugin hosting with the Jenkins project:

  1. Review the preparation steps and make sure they’re satisfied.

  2. Make sure your plugin follows the plugin naming convention outlined in the style guides.

  3. Have a public repository containing the plugin source code on GitHub.

Open Hosting request

Our automated process makes it much easier to fork + delete (see below), rather than transfer repository ownership. If your repository already has a significant number of forks, issues, pull requests, or other auxiliary data, we can manually transfer it — just request so in the hosting request, and provide an explanation.

Log in to GitHub and create a new issue in the repository-permissions-updater repository. Make sure to fill out all fields as described.

A member of the Hosting team will review your request within a few days. If any changes are requested, please implement them.

Once all requirements have been satisfied, your repository will be forked into the jenkinsci organization and you will be invited to join it.

At this point, you’re asked to delete your repository we forked from. You can recreate it afterwards by forking from jenkinsci again. This will ensure that the jenkinsci repository is the root of the network graph on GitHub. This means:

  • There will be no confusion which repository is the canonical one.

  • Source code search will succeed even without a significant number of watchers on GitHub.

  • Others are more likely to file pull requests in the jenkinsci repository (which is ideal for collaboration).

Enable CI Builds

The Jenkins project hosts a Jenkins instance to perform continuous integration builds for plugins. We recommend you set up CI builds for your plugin in the jenkinsci GitHub organization by creating a Jenkinsfile in your plugin’s GitHub repository. See the documentation for CI builds for details how to do this.

Request Upload Permissions

After your plugin source code has been forked into the jenkinsci organization, a pull request will be created for you that adds release permissions, if this doesn’t happen you may need to create the request yourself. Follow the instructions in the README of this repository to do that.

Once you’ve completed this step and your request has been merged, you will be able to release your plugin. See that guide for release instructions.

Alternately, you can configure your plugin to be released automatically whenever interesting changes are pushed, or on demand. In this case you only need write permission to GitHub; you never need local credentials. Follow this guide for details.

Categorize the Plugin

Jenkins shows plugins in categories in the plugin manager and on the plugins site. The plugin documentation guide includes instructions for documenting, categorizing, and labeling plugins.

Integrate with Jira

If your chosen issue tracker is Jira, you can setup autolink references, to link from commits directly to the Jenkins Jira issue. All you need to do is heading to the Settings tab of your GitHub repository and add the following configuration to the Autolink references section:

Numeric
Reference prefix: JENKINS-
Target URL: https://issues.jenkins.io/browse/JENKINS-<num>

Commits prefixed with JENKINS-<num> will now be linked to the corresponding Jira issue: jira auto reference

Join the community

As a new plugin author, its highly recommended that you join the mailing list to interact with the community and to stay up to date with the latest Jenkins news.

Kindly refrain from asking questions or communicating in private channels. We want the communications to take place in an open environment, so that we can have healthier discussions within our community.