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
Prerequisites
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 2.0.0.2023083041 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. |
Artifact |
Name of the artifact to retrieve. (Required) |
Version |
Version of the artifact to retrieve. (Required)
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: <metadata> <versioning> <latest>1.5.0</latest> </versioning> </metadata> 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/1.0.0.1/artifact.jar and source/artifact/1.0.0.2/artifact.jar, the second artifact will be choosen, and the resulting version will be 1.0.0.2. 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. |
Overwrite? |
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
Examples
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 |
/path/to/folder |
Relative Artifact Path |
$[artifact]/Europa_$[version] |
Version |
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 |
/path/to/folder |
Relative Artifact Path |
Leave empty (will default to $[artifact]/$[version]) |
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.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.