cd:
enabled: true
View the index of available developer guides
Continuous Delivery of Jenkins Components and Plugin (JEP-229) is relatively new. Any feedback from early adopters will be appreciated. |
Maintainers of Jenkins plugin repositories on GitHub can opt into continuous delivery (CD).
In this mode, every successful build of the default branch (master
or main
) by ci.jenkins.io results in a new plugin release.
GitHub Actions are used to rebuild the code and deploy it to Artifactory,
without the need for maintainers to use personal credentials or local builds.
Release notes are generated automatically according to pull request (PR) titles and some predefined labels.
maven-release-plugin (MRP) is not used in this mode.
Rather than traditional version numbers like 1.23 or 2.3.4 which are chosen by the maintainer,
a CD release will have a version of the form 123.vabcdef456789 :
an integer component determined by the Git history depth,
and an informational component with the Git commit hash.
|
Verify that the plugin has already been incrementalified.
pom.xml
should contain <version>${revision}${changelist}</version>
before proceeding with subsequent steps.
(A new plugin created from the archetypes will already have this setup.)
Enable the continuous delivery flag in repository permission updater (RPU) for your plugin
by filing a pull request adding to permissions/plugin-xxx.yml
:
cd:
enabled: true
Once that has been merged, start checking https://github.com/jenkinsci/your-plugin/settings/secrets/actions
until you see MAVEN_TOKEN
and MAVEN_USERNAME
appear under Repository secrets.
If you already have Release Drafter configured, remove any tag-template
override in .github/release-drafter.yml
,
and delete .github/workflows/release-drafter.yml
if using GitHub Actions (or remove the app from the repo otherwise).
If you have not yet configured Release Drafter, just create .github/release-drafter.yml
containing only:
_extends: .github
Create .github/workflows/cd.yaml
as a copy of the cd.yaml template.
(Optional) If you have a .github/dependabot.yml
, add:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
If you did not yet have such a file, create it now. For example:
version: 2
updates:
- package-ecosystem: maven
directory: /
schedule:
interval: weekly
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
Edit pom.xml
and .mvn/maven.config
to activate an automatic version number format.
For a regular component whose version number is not that meaningful:
--- a/.mvn/maven.config
+++ b/.mvn/maven.config
@@ -1,2 +1,3 @@
-Pconsume-incrementals
-Pmight-produce-incrementals
+-Dchangelist.format=%d.v%s
--- a/pom.xml
+++ b/pom.xml
@@ -7,7 +7,7 @@
- <version>${revision}${changelist}</version>
+ <version>${changelist}</version>
<packaging>hpi</packaging>
@@ -26,8 +26,7 @@
<properties>
- <revision>1.23</revision>
- <changelist>-SNAPSHOT</changelist>
+ <changelist>999999-SNAPSHOT</changelist>
<jenkins.version>2.176.4</jenkins.version>
</properties>
Thus your resulting .mvn/maven.config
should look like:
-Pconsume-incrementals
-Pmight-produce-incrementals
-Dchangelist.format=%d.v%s
and your pom.xml
should contain a top-level
<version>${changelist}</version>
as well as a <properties>
section containing
<changelist>999999-SNAPSHOT</changelist>
but no <revision>
.
In this typical case, a CI/release build (-Dset.changelist
specified) will be of the form 123.vabcdef456789
.
A snapshot build will be 999999-SNAPSHOT
: arbitrary but treated as a snapshot by Maven and newer than any release.
It is worth communicating this to your users, as they will see a very different version number format than before. The best way to do this is to add a line to the release notes: example note. |
For a component whose version number ought to reflect a release version of some wrapped component:
--- a/.mvn/maven.config
+++ b/.mvn/maven.config
@@ -1,2 +1,3 @@
-Pconsume-incrementals
-Pmight-produce-incrementals
+-Dchangelist.format=%d.v%s
--- a/pom.xml
+++ b/pom.xml
@@ -10,12 +10,12 @@
<artifactId>some-library-wrapper</artifactId>
- <version>${revision}${changelist}</version>
+ <version>${revision}-${changelist}</version>
<packaging>hpi</packaging>
<properties>
- <revision>4.0.0-1.3</revision>
- <changelist>-SNAPSHOT</changelist>
+ <revision>4.0.0</revision>
+ <changelist>999999-SNAPSHOT</changelist>
<jenkins.version>2.176.4</jenkins.version>
Here the version numbers will look like 4.0.0-123.vabcdef456789
or 4.0.0-999999-SNAPSHOT
, respectively.
When you pick up a new third-party component like 4.0.1
, your version numbers will match;
to refer to the third-party component, just use:
<version>${revision}</version>
Commit all of the above source file changes in a branch and file a pull request for them.
Do not forget to git add .
to make sure any newly created files are included.
Merge this PR activating CD. Be sure to apply one of the predefined labels to this and every subsequent PR before merging so that Release Drafter can properly categorize changes.
Now whenever Jenkins reports a successful build of your default branch,
and at least one pull request had a label indicating it was of interest to users
(e.g., enhancement
rather than chore
), your component will be released to Artifactory and
release notes published in GitHub.
You do not need any special credentials or local checkout; just merge pull requests with suitable titles and labels.
You will see a lot of workflow runs in the Actions tab in GitHub, only a small proportion of which are actual releases. Due to technical limitations in GitHub Actions it is not possible to suppress the extraneous runs. Actual releases will display a green check next to the release stage.
You can also trigger a deployment explicitly, if the current commit has a passing check from Jenkins. Visit https://github.com/jenkinsci/your-plugin/actions?query=workflow%3Acd and click Run workflow.
If you prefer to only deploy explicitly, not on every push, just comment out the check_run
section in the workflow.
You can also release manually if you have configured your machine for manual release. To cut a release:
git checkout master
git pull --ff-only
mvn -Dset.changelist \
-DaltDeploymentRepository=maven.jenkins-ci.org::default::https://repo.jenkins-ci.org/releases/ \
clean deploy
Check that MAVEN_TOKEN
and MAVEN_USERNAME
appear under Repository secrets.
Unauthorized means that the credentials were invalid, or not sent by Maven.
This normally means that the secrets configured in the repository have expired, create an issue in the INFRA helpdesk on GitHub, and let the team know in #jenkins-infra on Libera Chat.
Alternatively you can temporarily update the secrets yourself with your own personal credentials.
If none of the provided solutions help, send an email to the Jenkins developers mailing list and explain what you did, and how it failed.