https://github.com/hibernate/hibernate-jenkins-pipeline-helpers
Hibernate helpers for Jenkins pipelines
https://github.com/hibernate/hibernate-jenkins-pipeline-helpers
ci hibernate jenkins jenkins-pipeline jenkins-pipeline-library
Last synced: 3 months ago
JSON representation
Hibernate helpers for Jenkins pipelines
- Host: GitHub
- URL: https://github.com/hibernate/hibernate-jenkins-pipeline-helpers
- Owner: hibernate
- License: apache-2.0
- Created: 2018-09-25T08:03:15.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2025-04-03T13:42:19.000Z (3 months ago)
- Last Synced: 2025-04-13T14:06:53.604Z (3 months ago)
- Topics: ci, hibernate, jenkins, jenkins-pipeline, jenkins-pipeline-library
- Language: Groovy
- Size: 156 KB
- Stars: 3
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Hibernate helpers for Jenkins pipelines
This is a shared library containing helpers for Jenkins pipeline.
See below for documentation of the helpers.
See near the bottom of this file for help writing Groovy in a Jenkinsfile environment,
be it a Jenkinsfile or a shared library like this one.
You will also need to [configure your Jenkins instance](#jenkins-configuration).
## Using the helper steps (declarative or programmatic pipelines)
This library provides a set of helper steps that can come in handy
in both declarative and programmatic pipelines.
### requireApprovalForPullRequest
Blocks pull request builds (and only pull request builds)
pending approval from a given user group.
The approval is skipped if:
* the pull request was submitted by a member of the given user group.
* the build was triggered explicitly by a member of the given user group.
Usage:
```groovy
requireApprovalForPullRequest 'hibernate'
```
### notifyBuildResult
Usage:
```groovy
notifyBuildResult(
/**
* Space-separated emails of maintainers to notify of build results on primary branches.
* Optional, defaults to empty.
*/
maintainers: "[email protected] [email protected]",
/**
* Whether maintainers should always be notified.
* Optional, defaults to false.
*/
notifySuccessAfterSuccess: true
)
```
## Using the helper classes (programmatic pipelines)
This library provides a set of helper classes that can come in handy
in programmatic pipelines.
See the content of the `execute()` method in `test/SmokePipeline.groovy`
for an example of how the helpers are expected to be configured and used.
## Setup
### `Jenkinsfile`
In order to use this library, you need to explicitly import it into your Jenkinsfile, by adding this near the top (~before imports):
```groovy
@Library('hibernate-jenkins-pipeline-helpers') _
```
This relies on the library being [defined in the Jenkins instance](#jenkins-configuration-definition).
### Library definition and version
In order for `@Library` to work, you will need to define it in your Jenkins instance.
See [here](https://www.jenkins.io/doc/book/pipeline/shared-libraries/#defining-shared-libraries) for details.
For https://ci.hibernate.org, we define the library [globally](https://www.jenkins.io/doc/book/pipeline/shared-libraries/#global-shared-libraries),
so that we can set the (default) version globally [here](https://ci.hibernate.org/manage/configure#global-untrusted-pipeline-libraries).
### Required plugins
- https://plugins.jenkins.io/pipeline-maven
- https://plugins.jenkins.io/email-ext
- https://plugins.jenkins.io/config-file-provider
- https://plugins.jenkins.io/pipeline-utility-steps for YAML reading
- https://plugins.jenkins.io/notification for Gitter notifications
### Script approval
If not already done, you will need to allow the following calls in /scriptApproval/:
- method java.lang.Class isInstance java.lang.Object
- method java.util.Map putIfAbsent java.lang.Object java.lang.Object
- staticMethod org.jenkinsci.plugins.pipeline.modeldefinition.Utils markStageSkippedForConditional java.lang.String
- new java.lang.IllegalArgumentException java.lang.String
- new java.lang.IllegalStateException java.lang.String
- method hudson.plugins.git.GitSCM getUserRemoteConfigs
- method hudson.plugins.git.UserRemoteConfig getUrl
- method java.lang.Throwable addSuppressed java.lang.Throwable
- new java.util.LinkedHashMap
Just run the script a few times, it will fail and logs will display a link to allow these calls.
## Conventions
### "primary" branches
Branches named "main", "master" or matching the regex `/[0-9]+.[0-9]+/` will be considered as "primary" branches,
and, depending on the Jenkinsfile, may undergo additional testing.
### "tracking" branches
Branches named "tracking-" will be considered as "tracking branches",
i.e. branches containing a patch to be applied regularly
on top of a base branch, whenever that base branch changes, or another job succeeds.
In a multibranch pipeline, the specific job for each tracking branch will be configured to run:
- when the branch is updated (as usual)
- when a snapshot dependency is updated in the same Jenkins instance (as usual)
- when the base branch is built successfully
- when the Jenkins jobs mentioned in the branch name are built successfully
Also, when such branches are built, they are automatically merged with the base branch.
### Job configuration file
The job configuration file is optional. Its purpose is to host job-specific configuration, such as notification recipients.
The file is named 'job-configuration.yaml', and it should be set up using the config file provider plugin
(https://plugins.jenkins.io/config-file-provider).
```
notification:
email:
# String containing a space-separated list of email addresses to notify in case of failing non-PR builds.
recipients: ...
gitter:
# List of "secret text" credentials for Gitter chat rooms that should be notified
# Note that only global credentials will work; the notification plugin apparently doesn't handle job-scoped credentials
urlCredentialsId:
-
-
scm:
# User info for commits created during the job. Useful for releases in particular.
user:
name: ... # Defaults to 'Hibernate-CI'
email: ... # Defaults to '[email protected]'
# Remotes to be added to git when checking out. Useful for tracking (see below) in particular.
remotes:
:
# The URL of a remote
url: ...
tracking:
# The tracking ID, used as a suffix for tracking branch names:
# if the branch is named "tracking-foo", the tracking ID will be "foo".
:
# The Git refspec to the base of this tracking branch.
# For example this can be "origin/main" or "upstream/main" (if a remote named "upstream" is defined).
base: ...
# The Jenkins jobs to track.
# Use "branchname" to reference jobs corresponding to other branches in the same multibranch job.
# Use a "/" prefix ("/somename") to reference jobs outside of the multibranch job.
tracked:
-
-
```
## Contributing & writing Jenkinsfiles
See `CONTRIBUTING.md`.