mkobit / Jenkins Pipeline Shared Libraries Gradle Plugin

= Jenkins Pipeline Shared Library Gradle Plugin :toc: :supports-gradle: 5.0+ :github-repo-id: jenkins-pipeline-shared-libraries-gradle-plugin :uri-github-releases: https://github.com/mkobit/{github-repo-id}/releases :uri-jenkins-test-harness: https://github.com/jenkinsci/jenkins-test-harness.git :uri-jenkins-shared-library-docs: https://jenkins.io/doc/book/pipeline/shared-libraries/ :uri-jenkins-pipeline-unit: https://github.com/lesfurets/JenkinsPipelineUnit :uri-consumer-example: https://github.com/mkobit/jenkins-pipeline-shared-library-example :uri-build-status-image: https://circleci.com/gh/mkobit/{github-repo-id}/tree/master.svg?style=svg :circle-ci-status-badge: image:{uri-build-status-image}["CircleCI", link="https://circleci.com/gh/mkobit/{github-repo-id}/tree/master"] :uri-version-badge-image: https://img.shields.io/maven-metadata/v/https/plugins.gradle.org/m2/com/mkobit/jenkins/pipelines/jenkins-pipeline-shared-libraries-gradle-plugin/maven-metadata.xml.svg?label=Gradle Plugin Portal :uri-gradle-support-badge-image: https://img.shields.io/badge/Supports%20Gradle-{supports-gradle}-blue.svg :supports-gradle-badge: image:{uri-gradle-support-badge-image}["Gradle Version"] :uri-gradle-plugin-portal: https://plugins.gradle.org/plugin/com.mkobit.jenkins.pipelines.shared-library :uri-zenhub-badge: https://raw.githubusercontent.com/ZenHubIO/support/master/zenhub-badge.png :version-badge: image:{uri-version-badge-image}["Plugin Version", link="{uri-gradle-plugin-portal}"] :zenhub-badge: image:{uri-zenhub-badge}["ZenHub Badge", link="https://www.zenhub.com/"]

{circle-ci-status-badge} {version-badge} {supports-gradle-badge} {zenhub-badge}

NOTE: This documentation is for the HEAD of the repository. To see documentation at a specific version see the link:{uri-github-releases}[GitHub Releases page]

== Purpose

This plugin intends to help with development of link:{uri-jenkins-shared-library-docs}[Shared Libraries].

.Features

• Basic Groovy compilation to validate source code
• Unit test using link:{uri-jenkins-pipeline-unit}[Jenkins Pipeline Unit]
• Usage of plugin and Jenkins core classes in library
• @Grab support for libraries (testing limited to @JenkinsRule style integration tests due to link:https://stackoverflow.com/questions/4611230/no-suitable-classloader-found-for-grab[an issue])
• @NonCPS annotation can be used in main source code
• Source code generation to assist with development (for example, com.mkobit.jenkins.pipelines.codegen.LocalLibraryRetriever)
• Integration test using the link:{uri-jenkins-test-harness}[Jenkins Test Harness]
• Code completion in IDE

== Example Consumer

See the link:{uri-consumer-example}[example repository] for a demonstration of using this plugin.

== 5 minute onboarding

. Consume plugin from Gradle plugin portal + [source, kotlin]

plugins { id("com.mkobit.jenkins.pipelines.shared-library") version "x.x.x" }

. Set up preferred test dependencies (for example, JUnit or Spock) + [source, groovy]

repositories { jcenter() }

dependencies { testImplementation(group: 'junit', name: 'junit', version: '4.12') }

. Write some shared library code + .Library class - src/com/mkobit/LibHelper.groovy [source, groovy]

package com.mkobit

class LibHelper { private script LibHelper(script) { this.script = script }

void sayHelloTo(String name) { script.echo("LibHelper says hello to $name!") } }

.Global variable - vars/myGlobal.groovy [source, groovy]

def call() { echo 'Hello from myGlobal' }

. Write integration tests by utilizing a local JenkinsRule and setting up the shared library + .Integration tests - test/integration/groovy/com/mkobit/JenkinsGlobalLibraryUsageTest.groovy [source, groovy]

package com.mkobit

import com.mkobit.jenkins.pipelines.codegen.LocalLibraryRetriever import org.jenkinsci.plugins.workflow.libs.GlobalLibraries import org.jenkinsci.plugins.workflow.libs.LibraryConfiguration import org.jenkinsci.plugins.workflow.libs.LibraryRetriever import org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition import org.jenkinsci.plugins.workflow.job.WorkflowJob import org.jenkinsci.plugins.workflow.job.WorkflowRun import org.junit.Before import org.junit.Rule import org.junit.Test import org.jvnet.hudson.test.JenkinsRule

class JenkinsGlobalLibraryUsageTest {

@Rule public JenkinsRule rule = new JenkinsRule()

@Before void configureGlobalLibraries() { rule.timeout = 30 final LibraryRetriever retriever = new LocalLibraryRetriever() final LibraryConfiguration localLibrary = new LibraryConfiguration('testLibrary', retriever) localLibrary.implicit = true localLibrary.defaultVersion = 'unused' localLibrary.allowVersionOverride = false GlobalLibraries.get().setLibraries(Collections.singletonList(localLibrary)) }

@Test void testingMyLibrary() { CpsFlowDefinition flow = new CpsFlowDefinition(''' import com.mkobit.LibHelper

    final libHelper = new LibHelper(this)
    libHelper.sayHelloTo('mkobit')
'''.stripIndent(), true)
WorkflowJob workflowJob = rule.createProject(WorkflowJob, 'project')
workflowJob.definition = flow
WorkflowRun result = rule.buildAndAssertSuccess(workflowJob)
rule.assertLogContains('LibHelper says hello to mkobit!', result)

}

@Test void testingMyGlobalVar() { CpsFlowDefinition flow = new CpsFlowDefinition(''' import myGlobal

    myGlobal()
'''.stripIndent(), true)
WorkflowJob workflowJob = rule.createProject(WorkflowJob, 'project')
workflowJob.definition = flow
WorkflowRun result = rule.buildAndAssertSuccess(workflowJob)
rule.assertLogContains('Hello from myGlobal', result)

} }

== Configuring Versions

The sharedLibrary extension can be used to add additional plugin dependencies, Groovy version dependency, Jenkins Core dependency, etc. As of right now, most of the workflow-type plugins are automatically added based on default or configured versions. See the code for full details, but here is an example of what you can configure:

.Groovy build script - build.gradle [source, kotlin]

sharedLibrary { coreVersion = "2.86" testHarnessVersion = "2.24" pluginDependencies { workflowCpsGlobalLibraryPluginVersion = "2.8" dependency("io.jenkins.blueocean", "blueocean-web", "1.2.4") } }

NOTE: Due to link:https://github.com/gradle/kotlin-dsl/issues/380[kotlin-dsl/380], you will nee to use the .set methods instead of assignment. For example, coreVersion.set("2.86") is required.

== Limitations/Restrictions

=== Consuming the Gradle Configurations

There are several configurations that are created to group the different types of Jenkins dependencies used in this plugin. It is not recommended that you consume/extendsFrom these configurations as they may be changed underneath. It is instead recommended to use the configurations for each source set and make alterations to them (like link:https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/SourceSet.html#getImplementationConfigurationName--[`sourceSets.integrationTest.implementationConfigurationName`] and link:https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/SourceSet.html#getRuntimeOnlyConfigurationName--[`sourceSets.integrationTest.runtimeOnlyConfigurationName`]). If you have a specific use case please file an issue.