FileSysRepo plugin

4 minute readExtensibilityDeveloper productivity

The FileSysRepo plugin supports retrieval of versioned file artifacts stored on a file system. Starting with version 1.0.0, the plugin supports a flexible artifact file structure based on each customer’s unique storage schemes. Use the FileSysRepo plugin to:

  • Add procedures to retrieve artifacts for storage in CloudBees CD/RO file systems.

  • Store artifacts in directories other than the workspace directory in one or more CloudBees CD/RO agents.

Use this procedure to retrieve an artifact from the file system by specifying its:

  • Root directory

  • Relative artifact path

  • Artifact name and version

  • Destination directory

  • Overwrite actions if it already exists


This plugin uses an updated version of Perl, cb-perl shell (Perl v5.32), and requires CloudBees CD/RO agents version 10.3+ to work.

Plugin Version Revised on November 27, 2023

Plugin procedures

For all parameter descriptions in this section, the required parameters are in bold italics.

Retrieve file artifact

Use this procedure to retrieve an artifact from the file system.

Parameter Description

Root directory

Source directory of the artifact. (Required)

Relative artifact path

Path to artifact files relative to the root directory. Placeholders $[artifact] and $[version] can be used in the relative path to represent the artifact name and it’s version. Wildcard * can be used to represent any amount of symbols in the artifact path (like timestamp). Defaults to $[artifact]/$[version] if not specified.


Name of the artifact to retrieve. (Required)


Version of the artifact to retrieve. (Required)

  • Select Latest to find the latest version automatically.

    • Select Based on system default (default) to apply default version finder strategy.

First, the plugin will look for the version definition file in the repository folder. To retrieve the latest version of an artifact, put a file named ec_version_definition.xml in the directory belonging to the artifact with the following structure:


If there is no such file, and artifact relative path contains $[version] placeholder, then latest version will be determined based on artifact version.

Say, if we found two artifacts, source/artifact/ and source/artifact/, the second artifact will be choosen, and the resulting version will be If there is no version placeholder in the artifact relative path, the last changed artifact would be the latest version. * Select *Based on artifact path to apply based on artifact path version lookup strategy.

Version should be written in format <major>.<minor>.<revision>[-<qualifier>][-<build>] or <major>.<minor>.<revision>.<build>[-<qualifier>] The plugin will automatically choose the latest version. * Select *Based on creation date to apply based on creation date version lookup strategy. The last created artifact would be considered as the latest version. * Select Exact and enter a specific version, such as 1.4.3.

Retrieve to Directory

Destination directory. If you do not enter a directory, the default is the workspace directory.

Artifact path refers to a file?

Select the checkbox if the artifact path refers to a file. If unchecked (default), the artifact path is assumed to refer to a directory.


Select the checkbox if the artifact files should overwrite any existing files in the target location. Any files in the target location that do not exist in the source location will remain as-is. If unchecked (default), artifact files will be copied to the target location only if the target location is empty, otherwise the procedure will fail with an error.

Figure 1. Retrieve File Artifact procedure parameters


Here are a couple of examples of artifact version storage schemas that are supported by EC-FileSysRepo.

Figure 2. Artifact storage scheme where the artifact name is Jupiter and the artifact version is part of a sub-directory name.

The relevant parameter values in this case may be set as follows:

Parameter Value

Root Directory


Relative Artifact Path



Latest (as selected option)

Figure 3. Fixed file artifact storage scheme supported prior to version 1.0.0

The relevant parameter values in this case may be set as follows:

Parameter Value

Root Directory


Relative Artifact Path

Leave empty (will default to $[artifact]/$[version])


Latest (as selected option)

Release notes

EC-FileSysRepo 2.0.0

  • Upgraded from Perl 5.8 to Perl 5.32. The plugin is not backward compatible with CloudBees CD/RO versions prior to 10.3. Starting from this release, a new agent is required to run plugin procedures.

EC-FileSysRepo 1.0.4

  • The documentation has been migrated to the main documentation site.

EC-FileSysRepo 1.0.3

  • Renaming to "CloudBees CD".

EC-FileSysRepo 1.0.2

  • Renaming to "CloudBees"

EC-FileSysRepo 1.0.1

  • Added metadata that is required for 9.0 release.

EC-FileSysRepo 1.0.0

  • Added support for a flexible artifacts file structure.

  • Added strategies for retrieving the latest artifact version that can be configured by the user based on their artifact versioning scheme on the file system

  • Added the Overwrite option to control whether any existing files should be overwritten in the target location. By default, the Retrieve File Artifact procedure will not overwrite any existing files and will fail with an error unless the Overwrite option is checked. The old behavior was to overwrite any overlapping files without asking.

So, users who were using the older versions of the EC-FileSysRepo plugin would need to update their scripts and procedures to set the override parameter to 'true' or '1' if they want to allow the Retrieve File Artifact procedure to overwrite an existing files in the target location.

EC-FileSysRepo 0.0.5

  • Added diagrams and screenshots to the Help documentation.

EC-FileSysRepo 0.0.1

  • Initial release of the plugin.