Guide to Plugin Hosting

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 controller 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.

After the hosting acceptance

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.

Automate your GitHub repository

Activate GitHub actions

During the hosting process, you have included a shared workflow to generate changelogs automatically. Publishing changelogs as GitHub release notes is a good practice to keep your users informed about the changes in your plugin.

To activate the workflow, you need to go to the Actions tab of your GitHub repository and click on the I understand my workflows, go ahead and enable them button. Follow the next section to create the necessary labels for your pull requests.

Create the default labels

Use the following script to create the default labels for your GitHub repository, used to categorize issues and pull requests and generate changelogs automatically:

The script makes use of gh, you may need to install and authenticate(https://cli.github.com/manual/gh_auth_login) first, if you haven’t already.

https://gist.github.com/NotMyFault/b036718b73f1ad2a96faca315fc8ca68/raw

Enter the repository name of your plugin when prompted.

Bear in mind, that the script is intended to overwrite existing labels, to make sure you don’t have any outdated labels with different descriptions or colors.

Activate dependabot

Dependabot is a GitHub feature that automatically creates pull requests to update dependencies in your repository. It is a good practice to keep your dependencies up to date, as it helps to avoid security vulnerabilities and compatibility issues.

To activate dependabot, you need to go to the Settings tab, followed by Code security and analysis tab of your GitHub repository and click on the Enable button next to Dependabot version updates and Dependency graph.

Alternatively, you can use renovate(https://www.mend.io/renovate/) too, which is used by plugin maintainers, if you prefer.

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.