Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Hacktoberfest [JENKINS-69731] Update shared-libraries.adoc #5537

Draft
wants to merge 5 commits into
base: master
Choose a base branch
from
Draft
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
48 changes: 48 additions & 0 deletions content/doc/book/pipeline/shared-libraries.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,54 @@ A link to the example repository used is also provided in the link:https://youtu

video::eV7roTXrEqg[youtube,width=800,height=420]

=== Statically loading evaluated versions of libraries

As of currently unreleased version of the _Pipeline: Shared Groovy Libraries_ plugin,
with features proposed in
link:https://github.com/jenkinsci/pipeline-groovy-lib-plugin/pull/19[PR #19]
(link:https://issues.jenkins.io/browse/JENKINS-69731[issue JENKINS-69731])
Comment on lines +199 to +202
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for phrasing it that way to make it clear to reviewers like me that the feature is not yet released. Very nice technique!

Suggested change
As of currently unreleased version of the _Pipeline: Shared Groovy Libraries_ plugin,
with features proposed in
link:https://github.com/jenkinsci/pipeline-groovy-lib-plugin/pull/19[PR #19]
(link:https://issues.jenkins.io/browse/JENKINS-69731[issue JENKINS-69731])

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose you did not mean removing these lines, just yet? :)

(If this PR is indeed only merged after the feature release, this should get rephrased similar to library step description)

there are new options for the `@Library` annotation with limited run-time evaluation
of the version specified for the library. In order to use these features, you should
explicitly allow them in library configuration (e.g. Global Jenkins configuration of
your instance).

While the markup for these features is intentionally similar to what you would write
for Groovy code to simplify maintenance, keep in mind that the version tokens are
handled by the plugin before it would load libraries and compile the pipeline script.

One addressed use-case regards loading of "same version of library as the version of
Pipeline script from SCM" by specifying literally +`${BRANCH_NAME}`+ as the library
version in the pipeline script, e.g.:

[source,groovy]
----
@Library('my-shared-library@${BRANCH_NAME}') _
----

The plugin would try several methods to determine the branch name to use, check if
such "version" is accepted by SCM source of the library, and fall back to default
version if not.
jimklimov marked this conversation as resolved.
Show resolved Hide resolved

This was verified to work for:
* MultiBranch Project pipelines both with "Modern SCM" and with "Single repository & branch"
(in case of the latter, the "name" you specify for the source is what matters for MBP more
than the actual SCM branch);
* Pipelines backed by a single SCM source with a "Branch Specifier" like `*/main`;
* "In-line" Pipelines not backed by an SCM (just fall back to default version).

Another addressed use-case regards loading of some version of library specified by
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Possibly simpler phrasing?

Suggested change
Another addressed use-case regards loading of some version of library specified by
The plugin can also load a library version specified by

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure about this change (alone) since an earlier paragraph stressed that "one use-case is..." so here "another"...

an environment variable value defined when the job starts (e.g. coming from Global
Jenkins configuration, from build agent configuration, or injected by some plugins):
jimklimov marked this conversation as resolved.
Show resolved Hide resolved

[source,groovy]
----
@Library('my-shared-library@${env.CUSTOM_VAR_NAME}') _
----

The plugin would try to get the `CUSTOM_VAR_NAME` from environment, and if it exists --
check if such "version" is accepted by SCM source of the library, and fall back to
default version if not.

=== Loading libraries dynamically

As of version 2.7 of the _Pipeline: Shared Groovy Libraries_ plugin,
Expand Down