Issue
-
I have a Shared Library that developers will use in their CloudBees CI pipelines. I would like to add some descriptions to the variables defined in it that the developers can consult when they configure their jobs.
Resolution
Jenkins Pipeline delivers built-in documentation features to make it easier to write Pipeline code. This documentation is automatically generated and updated based on the plugins installed in the Jenkins instance. Shared libraries use this feature to inject helpers for the variables and classes defined in it.
The built-in documentation can be found globally at ${YOUR_JENKINS_URL}/pipeline-syntax. The same documentation is also linked as Pipeline Syntax in the side-bar for any configured Pipeline project. As indicated in Shared Libraries: Directory structure, for each foo.groovy in your vars directory, a foo.txt file can be added to include help for foo variable.
A variable defined in a shared library will only show up in Global Variables Reference (under Pipeline Syntax) after Jenkins loads and uses that library as part of a successful Pipeline run. The same happens for the variable syntax help. Until the pipeline is run successfully at least once after the description was added, the description won’t show up.
Troubleshooting
If you have problems to get the variable descriptions displayed, please double-check that:
-
the
.groovyand.txtfiles have the same name before the extension, -
the pipeline has been run successfully at least once with the library configured, and
-
the version of the library to use matches the one where you are making changes.
Should the issue persist, open a request for support at CloudBees.