Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction

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

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

Create FileSysRepo plugin procedures

Plugin procedures can be used in procedure steps, process steps, and pipeline tasks, allowing you to orchestrate third-party tools at the appropriate time in your component, application process, or pipeline.

Depending on your plugin configuration and how you run procedures, the Input parameters  Configuration name field may behave differently in the CloudBees CD/RO UI. For more information, refer to Differences in plugin UI behavior.

Retrieve file artifact

Retrieves an artifact from the file system.

Parameter Description

Root directory

Required. Source directory of the artifact.

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 its version. A wildcard * can be used to represent any number of symbols in the artifact path (for example, a timestamp). The default is $[artifact]/$[version].

Artifact

Required. Name of the artifact to retrieve.

Version

Required. Version of the artifact to retrieve.

  • Exact: Enter a specific version, such as 1.4.3.

  • Latest: Select the latest version automatically.

    • Based on system default: (default) Select the latest version based on the default version finder strategy.

      First, the plugin looks for the version definition file in the repository folder. To retrieve the latest version of an artifact, add 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 the relative artifact path contains a $[version] placeholder, then the latest version is determined based on the artifact version.

      For example, if there are two artifacts, source/artifact/1.0.0.1/artifact.jar and source/artifact/1.0.0.2/artifact.jar, the second artifact is used, and the resulting version is 1.0.0.2. If there is no version placeholder in the artifact relative path, the most recently changed artifact is considered the latest version.

    • Based on artifact path: Select the latest version based on the artifact path. The version should be written in the following format: <major>.<minor>.<revision>[-<qualifier>][-<build>] or <major>.<minor>.<revision>.<build>[-<qualifier>]. The plugin automatically selects the latest version.

    • Based on creation date: Select the latest version based on the artifact creation date. The last created artifact is considered the latest version.

Retrieve to Directory

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

Artifact path refers to a file?

If selected, the artifact path refers to a file. If not selected (default), the artifact path is assumed to refer to a directory.

Overwrite?

If selected, artifact files overwrite any existing files in the target location. Any files in the target location that do not exist in the source location remain as-is. If not selected (default), artifact files are copied to the target location only if the target location is empty, otherwise the procedure fails with an error.

Examples

The following examples demostrate artifact version storage schemas supported by the FileSysRepo plugin.

In the following example, the artifact storage schema where the artifact name is Jupiter and the artifact version is part of a subdirectory name:

Flexible schema
Figure 1. Flexible artifact storage schema

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 the selected option)

In the following example, there is a fixed file artifact storage schema supported prior to version 1.0.0:

Fixed schema
Figure 2. Fixed artifact storage schema

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

Parameter Value

Root Directory

/path/to/folder

Relative Artifact Path

Leave this field empty (the default $[artifact]/$[version] is used)

Version

Latest (as the selected option)

FileSysRepo plugin release notes

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.

1.0.4

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

1.0.3

  • Renamed to "CloudBees CD".

1.0.2

  • Renamed to "CloudBees".

1.0.1

  • Added metadata required for the 9.0 release.

1.0.0

  • Added support for a flexible artifact 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 does not overwrite any existing files and fails with an error unless the Overwrite option is selected.

    Previously, any overlapping files were overwritten without prompting, and you were required to update scripts and procedures to set the override parameter to true or 1 to allow the Retrieve File Artifact procedure to overwrite an existing files in the target location.

0.0.5

  • Added diagrams and screenshots to the documentation.

0.0.1

  • Initial release of the plugin.