{jenkins-plugin-info:plasticscm-plugin}

This plugin integrates Plastic SCM with Jenkins.

Configuration

System configuration

In order to configure the plugin, you need the cm executable installed in the Jenkins server machine. Then, please follow these steps:

  1. Open the system configuration page "Manage Jenkins" and navigate to "Configure System"
  2. Scroll down to the "Plastic SCM" section and enter the path where the cm executable (CLI client) is located
  3. Click "Check" to verify that the path you set is correct
  4. You can leave the field empty: "cm" will be used by default (i.e. the executable will be loaded from $PATH)

 


Job configuration

Freestyle projects

Scroll down to the Source Code Management section and select "Plastic SCM" (see screenshot below). You'll need to enter a valid selector, which will be used to check out the repository contents in every build. The "Poll SCM" trigger also uses that selector.

Every build will ensure that the Jenkins workspace contains a Plastic SCM before starting the cm update operation. If you'd like to create the PlasticSCM workspace in a particular subdirectory under the Jenkins job workspace, you can specify one in the Subdirectory field. This field is mandatory if you want to use multiple workspaces.

If you want to keep the workspace between builds, check the Use update box. Otherwise, the Plastic SCM workspace and its contents will be deleted before each build.


Selector format

The selector accepts branches, changesets or labels. You can setup not only branches (which is the normal case), but labels as well as changesets in the selector.

repository "myRepo@my.plasticscm.server.com:8087"
  path "/"
    smartbranch "/main/scm1773"
repository "myRepo@my.plasticscm.server.com:8087"
  path "/"
    smartbranch "/main/scm1773" changeset "7030383"
repository "myRepo@my.plasticscm.server.com:8087"
  path "/"
    label "1.0.32-preview_997"

You can also use build parameters in the selector.
Example: Let's say that you defined two build parameters in your project:

Then you can use those parameters in the Plastic SCM selector using the macro pattern $parameter_name:

repository '$repositoryname'
    path "/"
        smartbranch '$branchname'

Multiple workspaces

The Plastic SCM plugin allows you to checkout multiple workspaces in a single Jenkins workspace. This can be useful if you need to fetch sources from two or more repositories in order to build your application.

To enable this feature, check the Use multiple workspaces box in the SCM configuration. You'll see a new button "Add workspace..." to append a new workspace to the list of additional workspaces. The configuration settings are identical to the root ones.

(warning) Be careful! (warning) This setup requires you to specify a subdirectory value for all workspaces, and they must be different from one another. If you don't, you might risk having the plugin download the contents from two or more repositories into the same directory.

Pipelines

If you use scripted pipelines or you want to specify the pipeline script directly in the job configuration, you can take advantage of the cm command inside the groovy script:

cm branch: '<full-branch-name>', repository: '<rep-name>', server: '<server-address>:<server-port>, useUpdate: (true|false), directory: '<subdirectory-name>'

As you see, there's a one-to-one parameter mapping. To use multiple workspaces you simply need to add multiple cm statements, paying attention to the value of the directory parameter.

cm branch: '/hotfix', repository: 'assets-repo', server: 'my.plasticscm.server.com:8087', useUpdate: true, directory: 'assets'


If you'd rather use declarative pipelines (selecting the Pipeline script from SCM option), you'll have to specify the Plastic SCM configuration just as you'd do for a freestyle project. Then, two new parameters will appear: Script path and Lightweight checkout.

The script path tells Jenkins where to find the pipeline script file. This path is relative to the Jenkins workspace! So, if you defined subdirectories (regardless of how many additional repositories you described) you'll need to include the subdirectory in the Script path. See an example below:

Enabling lightweight checkout lets Jenkins retrieve the pipeline script file directly, without a full Plastic SCM update.

Build information

Summary

The build summary includes a reference to the Plastic SCM changeset spec that was built.

Changes list

The changes page in each build will have details about each of the changesets that were included in the build, linked from the summary list.

Plastic SCM Build Data

You'll find a link in the build page sidebar to display the Plastic SCM data for that build.

Environment variables

If the checkout operation succeeds, these environment variables will be populated with the appropriate values for the build:


Additional workspaces will include their position in the list, like this:

Requirements

Upgrading from 2.x to 3.x

The upgrade process is mostly seamless. You'll only need to review the configuration parameters of your jobs if you configured them to use multiple workspaces. Since the subdirectory name was inferred from the workspace name before and that parameter is now gone, the Subdirectory parameter (used now to specify the subdirectory name explicitly) will be empty. Builds might download all workspaces in the same directory!

Plugin information

This plugin has been developed by Codice Software S.L., owner of the Plastic SCM product.

Visit us at http://www.plasticscm.com

You can meet the team here!

We really appreciate PR and contributions in the plugin GitHub repository.

Feel the power of merging branches easier than ever with SemanticMerge!

Change log

Version 3.2  

Fixes

Version 3.1  

Fixes

Version 3.0  

Version 3 is out! This new major version enhances build information and improves SCM configuration parameters. Big shout-out to Housemarque, who contributed enormously to this new batch of changes. Enjoy!

(warning) Important (warning)  Jenkins baseline version is now 2.60.3 and Plastic SCM client minimum version is 8.0.16.3400! Please ensure you have your software up to date before upgrading the Plastic SCM plugin.

Improvements

Fixes

Version 2.23

Since version 2.22, the plugin is using paths instead of names to find out whether a workspace exists. However, that caused an issue with Windows agents that had their root paths specified with forward slashes (such as C:/jenkins/myAgent). This is fixed now.

Version 2.22

Changes in previous version broke how workspace names were set, which was fixed in this release.

The 'use multiple workspaces' checkbox was broken as well in freestyle and declarative pipeline projects because it was always set as true. Fixed.

We improved how shared library projects are detected to avoid inconsistent workspace names like 'shl-[number]'.

We added support for build parameters in Jenkinsfile pipelines that have lightweight checkout enabled.

The cm path field in the plugin global configuration section now has a validation button.

Version 2.21

There were issues with shared libraries when two or more projects were consuming a single shared library. They were related to the workspace names assigned to the shared library workspace for each project, which turned out to be always the same. We fixed that to make every shared library workspace have its own self-generated workspace name.

Version 2.20

We improved how the plugin reports errors in a Pipeline with Lightweight checkout. Before this, if the Jenkinsfile download failed only a 'NULL' message was printed. Now the complete command execution is displayed.

Fixed an incompatibility with other plugins if they require the SCM plugin to support the ChangeLogSet.Entry.getAffectedfiles() method.

Version 2.19

Added support to SCM environment variables for pipelines.

Now, you can check the available ones here: https://<your-jenkins>/env-vars.html

Version 2.18

Version 2.17  

Version 2.16  

The Plastic SCM plugin had a file path issue that prevented it from working as expected when the master and slave instances had different OS. Fixed.

Version 2.15  

The parameters of the plastic workspace name were not correctly resolved. It means, it used the exact workspace name string (e.g. 'Jenkins-${JOB_NAME}-${NODE_NAME}') without resolving the parameters JOB_NAME and NODE_NAME (e.g. 'Jenkins-project-MASTER'). Fixed.

Version 2.14  

The Plastic SCM plugin can work with multiple plastic workspaces or just a single plastic workspace. Now, the jenkins workspace and the plastic workspace paths will match in the single workspace mode.

Therefore, some jenkins features (such as pipeline shared libraries) that need both paths to match will correctly work.

Version 2.13  

Version 2.12  

In Blue Ocean, if a build included multiple changesets, only the first one was rendered in the details. Also, the info for the commit and timestamp columns were not filled. Fixed.

Version 2.11  

Reduced the number of duplicated builds that can happen using the Plastic SCM plugin. Now, the scm polling takes into account the current build, avoiding to start a new build for the same changeset.

Version 2.10  

We fixed an issue configuring existing pipeline projects: the PlasticSCM entry didn't appear in the SCM dropdown list if the pipeline was set to get the script from SCM.

Also, now the Plastic SCM configuration will automatically propose a default workspace name for the first (mandatory) workspace.

Version 2.9  

From now on, each build will publish environment variables containing the data of the built changeset for each configured workspace. These are the variables exposed by the main workspace of the project:

Additional workspaces will include their position in the list, like this:

Version 2.8  

The pipeline script syntax for Plastic SCM is:

cm branch: '<full-branch-name>', changelog: (true|false), poll: (true|false), repository: '<rep-name>', server: '<server-address>:<server-port>, useUpdate: (true|false), workspaceName: '<wk-name-using-jenkins-variables>'

For example:

cm branch: '/main', changelog: true, poll: true, repository: 'default', server: 'localhost:8087', useUpdate: true, workspaceName: 'Jenkins-${JOB_NAME}-${NODE_NAME}'

Version 2.7

Version 2.6

Version 2.5

Version 2.4  

Version 2.3

Version 2.2

Version 2.1

Version 2.0

Version 1.0