CloudBees CD/RO allows you to take a fully code-native approach to continuous delivery and release orchestration using the CloudBees CD/RO Groovy-based Domain Specific Language (DSL). The CloudBees CD/RO model-based approach means that every object in CloudBees CD/RO, including release pipelines, deployment automation and strategies, environments, configurations, and application models are all backed by code.
The DslDeploy plugin makes it easy to synchronize CloudBees CD/RO DSL code with your local repository, allowing you to treat your pipeline as a product, making it versionable, testable, and reusable, exactly like your application code. This plugin maintains your code in a file structure that maps directly to the CloudBees CD/RO model-based structure, making it easy to reuse, collaborate, and maintain. It supports:
-
Management of all CloudBees CD/RO objects as code.
-
Per-project synchronization.
-
The use of
.dsl
and.groovy
extensions. -
The ability to create generic DSL files.
-
Artifacts to support CloudBees CD/RO code-promotion pipelines.
-
Continuous integration (CI) support for your DEV environment.
-
Compatibility with the
ectool
CLI.
Updated Perl version required
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 4.3.0.2023101388
Procedures
InstallDsl
Deploy a DSL file structure from an Artifact Version on your CloudBees CD/RO server.
Parameter | Description |
---|---|
Artifact Name |
Required. The name of your artifact. |
Artifact Version |
The version of the artifact you want to deploy. If empty, the latest version is deployed.
NOTE: Use an empty version only in your |
Server Pool or Resource |
Required. The name of the pool or resource where the artifact will be retrieved. The DSL is evaluated on the server so all system actions, such as file reads, will be evaluated on a server node. Default value is |
Retrieve on All server nodes |
Required (By default, is set to false). Use this option when running in a cluster with a local workspace, as the artifact version needs to be retrieved on all nodes (as the system pick a random server node for each action). Use alongside a resource pool covering all server node agents for the parameter above. Default is |
Overwrite mode |
Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files. |
InstallDslFromDirectory
Deploy a DSL file structure from a directory on your CloudBees CD/RO server.
This procedure’s main usage is to set up a CI process. It extracts your code from your SCM in a local directory on your Dev
CloudBees CD/RO server, and deploys it.
Parameter | Description | ||
---|---|---|---|
Directory Path |
Required. The location of the DSL code on your |
||
Server Pool or Resource |
Required. The name of the pool or resource where the artifact will be retrieved. Use |
||
Overwrite mode |
Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files. |
||
Additional argument(s) |
For evalDsl calls, additional arguments such as |
||
Ignore failures |
Ignore failures during import of DSL files. |
||
Local mode |
Do not send files to the server with help of clientFiles argument of the evalDsl operation in local mode. |
||
Include objects |
New line separated list of paths to objects to synchronize. If set, only these objects are synchronized. If empty, all available objects are synchronized. Examples:
|
||
Exclude objects |
New line separated list of paths to exclude (See Include objects for examples). Exclude nothing by default. |
InstallDslFromDirectory input example
In the following InstallDslFromDirectory input example, /projects
is being used to install the projects catalogTest
, testProject
, and testPipeLine
.
├── projects
├── catalogTest
│ ├── catalogs
│ │ └── Test\ Catalog
│ │ ├── catalog.dsl
│ │ └── catalogItems
│ │ └── Service\ OnBoarding
│ │ └── catalogItem.dsl
│ ├── procedures
│ │ └── catalogProcedure1
│ │ ├── procedure.groovy
│ │ └── steps
│ │ └── echo.pl
│ └── project.groovy
├── testProject
│ ├── procedures
│ │ └── testProcedure1
│ │ ├── procedure.groovy
│ │ └── steps
│ │ └── echo.pl
│ ├── project.groovy
│ └── properties
│ └── prop1.txt
└── testPipeline
├── pipelines
│ └── UC1
│ └── pipeline.groovy
└── project.groovy
InstallProject
Deploy DSL file structure from a directory on your CloudBees CD/RO server as a project.
The main purpose of the procedure to be a part of installDslFromDirectory procedure.
Parameter | Description |
---|---|
Project Name |
Name of the project to install. |
Project directory |
The location of the project DSL code on your |
Overwrite mode |
Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files. |
Additional argument(s) |
For evalDsl calls, additional arguments such as |
InstallProject input example
In the following InstallProject input example, you can see a sample directory structure to install a project. In this example, project1
project with the procedure1
and procedure2
procedure.
project1
├── procedures
│ ├── procedure1
│ │ ├── procedure.groovy
│ │ └── steps
│ │ └── echo.pl
│ └── procedure2
│ ├── procedure.groovy
│ └── steps
│ └── echo.pl
├── project.groovy
└── properties
└── prop1.txt
GenerateDslToDirectory
Export DSL for a top level CloudBees CD/RO object, with options for which child objects and values to include. Export the DSL in separate files in a directory tree representing the object hierarchy, for ease of editing and management.
Parameter | Description |
---|---|
Directory path |
Required. Folder where the code is generated. |
Server Pool or Resource |
Required. Server pool to use for a cluster setup. |
Object Type |
Required. Object type to generate DSL for. |
Object Name |
Required. Object name to generate DSL for. |
Suppress Nulls |
Exclude from the generated DSL properties with null value. |
Suppress Defaults |
Exclude from the generated DSL properties with default value. |
Suppress Parent |
Exclude from the generated DSL properties referred to object parent. |
Include ACLs |
Include in ACLs for objects. |
Include All Children |
Include in the generated DSL all object children. If |
Include children |
A comma-separated list of object children the DSL should be generated for. |
Include Children in Same File |
Include in the generated DSL all object children. If |
Children in Different Files |
A comma-separated list of patterns to include, like pipelines, procedures. |
GenerateDslToDirectory project output example
In the following GenerateDslToDirectory output example, you can see the directory structure generated for an example project, testProject1
into a /tmp/dsl
directory.
/tmp/dsl
├── projects
│ ├── testProject1
│ │ ├── acls
│ │ │ └── acl.dsl
│ │ ├── procedures
│ │ │ ├── testProcedure1
│ │ │ │ ├── acls
│ │ │ │ │ └── acl.dsl
│ │ │ │ ├── procedure.dsl
│ │ │ │ ├── properties
│ │ │ │ │ ├── testProperty1
│ │ │ │ │ │ └── property.dsl
│ │ │ │ │ ├── testProperty1.txt
│ │ │ │ │ └── testPropertySheet1
│ │ │ │ │ ├── propertySheet.dsl
│ │ │ │ │ ├── testProperty2
│ │ │ │ │ │ └── property.dsl
│ │ │ │ │ └── testProperty2.txt
│ │ │ │ └── steps
│ │ │ │ ├── metadata.json
│ │ │ │ ├── testStep1
│ │ │ │ │ ├── acls
│ │ │ │ │ │ └── acl.dsl
│ │ │ │ │ └── step.dsl
│ │ │ │ ├── testStep1.cmd
│ │ │ │ ├── testStep2
│ │ │ │ │ ├── acls
│ │ │ │ │ │ └── acl.dsl
│ │ │ │ │ └── step.dsl
│ │ │ │ └── testStep2.cmd
│ │ │ └── testProcedure2
│ │ │ ├── acls
│ │ │ │ └── acl.dsl
│ │ │ ├── procedure.dsl
│ │ │ ├── properties
│ │ │ │ ├── testProperty1
│ │ │ │ │ └── property.dsl
│ │ │ │ ├── testProperty1.txt
│ │ │ │ └── testPropertySheet1
│ │ │ │ ├── propertySheet.dsl
│ │ │ │ ├── testProperty2
│ │ │ │ │ └── property.dsl
│ │ │ │ └── testProperty2.txt
│ │ │ └── steps
│ │ │ ├── metadata.json
│ │ │ ├── testStep1
│ │ │ │ ├── acls
│ │ │ │ │ └── acl.dsl
│ │ │ │ └── step.dsl
│ │ │ ├── testStep1.cmd
│ │ │ ├── testStep2
│ │ │ │ ├── acls
│ │ │ │ │ └── acl.dsl
│ │ │ │ └── step.dsl
│ │ │ └── testStep2.cmd
└───└───└── project.dsl
GenerateDslToDirectory resources output example
In the following GenerateDslToDirectory output example, you can see the directory structure generated for two example resources, testResource1
(line 3) and testResource2
(line 16) into a /tmp/dsl
directory.
/tmp/dsl
├──resources
├── testResource1
│ ├── acls
│ │ └── acl.dsl
│ ├── properties
│ │ ├── testProperty1
│ │ │ └── property.dsl
│ │ ├── testProperty1.txt
│ │ └── testPropertySheet1
│ │ ├── propertySheet.dsl
│ │ ├── testProperty2
│ │ │ └── property.dsl
│ │ └── testProperty2.txt
│ └── resource.dsl
└── testResource2
├── acls
│ └── acl.dsl
├── properties
│ ├── testProperty1
│ │ └── property.dsl
│ ├── testProperty1.txt
│ └── testPropertySheet1
│ ├── propertySheet.dsl
│ ├── testProperty2
│ │ └── property.dsl
│ └── testProperty2.txt
└── resource.dsl
ImportDslFromGit
This procedure is deprecated and relies on the ECSCM-Git plugin, which is no longer supported. Unless you have legacy installations of CloudBees CD/RO, you should not use it and use ImportDslFromGitNew instead. |
Import DSL file structure from a Git repository.
This procedure main usage is to set up a CI process.
Parameter | Description | ||
---|---|---|---|
Server Resource |
Required. The resource where the DSL files are checked out from Git and imported to the CloudBees CD/RO server. |
||
Destination Directory |
Required. The directory on the resource where the source tree is created and from where the DSL files are read to be imported in CloudBees CD/RO server. |
||
Relative path to DSL files |
If the DSL files are not located at the top-level in the repository, then specify the relative path to the directory containing the DSL files within the repository. |
||
Cleanup? |
This option will delete the destination directory with the source tree after the job execution. |
||
Overwrite mode |
Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files. |
||
Configuration |
Required. The name of a saved SCM configuration. |
||
Git repository |
Required. The URL to the repository to pull from, for example |
||
Commit Hash |
The Commit Hash to update the index.
|
||
Remote Branch |
The name of the Git branch to use, for example |
||
Clone? |
This option will clone a repository into a newly created directory. |
||
Overwrite? |
This option will overwrite a repository if it already exists. |
||
Depth |
Create a shallow clone with a history truncated to the specified number of revisions. |
||
Tag |
Provide the name of a specific tag to check out after the clone command. |
||
Ignore failures |
Ignore failures during import of DSL files. |
||
Local mode |
Do not send files to the server with help of clientFiles argument of the evalDsl operation in local mode. |
||
Additional DSL Arguments |
Additional argument for |
ImportDslFromGitNew
Import DSL file structure from a Git repository.
This procedure main usage is to set up a CI process.
This procedure uses the Git plugin. |
When using ImportDslFromGitNew, the count of imported entities does not increment for manually modified DSL files. The plugin expects each DSL file to contain one CloudBees CD/RO entity, which is how DSL files are generated by plugin itself, and the count of entities is based on this format. |
Parameter | Description | ||
---|---|---|---|
Server Pool or Resource |
Required. The resource or one of the pool resources where the DSL files are checked out from Git and imported to the CloudBees CD/RO server. |
||
Destination Directory |
Required. The directory on the resource where the source tree is created and the DSL files are stored. |
||
Relative path to DSL files |
If the DSL files are not located at the top level in the repository, then specify the relative path to the directory containing the DSL files within the repository. For example, |
||
Cleanup? |
This option deletes the destination directory with the source tree after the job execution. |
||
Overwrite mode |
Select to enable overwrite mode. If the object exists, all attributes and child objects are overwritten by the values in the DSL files. |
||
Configuration |
Required. |
||
Git repository |
Required. URL to the repository to pull from. For example, |
||
Remote Branch |
The name of the Git branch to use. For example, |
||
Ignore failures |
Ignore failures during import of DSL files. |
||
Local mode |
Do not send files to the server with help of |
||
Additional DSL arguments |
Additional argument(s) for the |
||
Include objects |
New line separated list of paths to objects to synchronize. If set, only these objects are synchronized. If empty, all available objects are synchronized.
|
||
Exclude objects |
New line separated list of paths to exclude (See Include objects for examples). Exclude nothing by default. |
||
Incremental import |
Select to only import the incremental changes that have occurred since the previous run of the procedure. When selected, the previous run’s commit ID is compared to the current commit ID in the Git repository and a change list is created. This can potentially reduce the import time because the entire DSL file structure is not re-imported from the Git repository each time the procedure runs.
|
Release notes
EC-DslDeploy 4.2.2
-
Fixed issue where plugin could not set warning statuses in job steps. If warnings occured, the plugin attempted to set the status, which would result failure of the complete job.
-
Fixed issue with set job step status in the overwrite mode during DSL evaluation
EC-DslDeploy 4.2.1
-
Fixed issue with import environment reservations
-
Supported new option 'suppressEmpty' in the 'generateDsl' plugin procedure
EC-DslDeploy 4.2.0
-
Added 'httpIdleTimeout' argument into the 'generateDsl' plugin procedure
-
Fixed import issue with entity names that contain special characters in the overwrite mode
-
Improved logging in the 'generateDslToDirectory' procedure for properties and property sheets
-
Fixed issue with 'timeout' argument in the 'generateDslToDirectory' procedure
-
Fixed import issue for CD entities with names contain punctuated characters
-
Fixed issue with import new properties in the overwrite mode
EC-DslDeploy 4.1.8
-
Added support to run sub procedure 'importDslFromGitNew' for EC-DslDeploy plugin
-
Fixed issue with import non project entities in case remote agent is used
EC-DslDeploy 4.1.7
-
Added support for property detail information like description, etc
-
Fixed incremental imports in the importDslFromGitNew procedure when used as a subprocedure
-
Instrumented EC-DslDeploy code to help debug performance issue where importing a release from a nested DSL file structure
EC-DslDeploy 4.1.6
-
Added DSL import of completed releases - EC-DslDeploy side
-
Fixed incremental import in the importDslFromGitNew procedure when it is used as a subprocedure
EC-DslDeploy 4.1.4
-
Fixed issue with exceptions that should be retried
-
Added support for serviceAccount objects
EC-DslDeploy 4.1.2
-
Added support for overwrite mode in the main deploy step for single DSL files
-
Added support for triggers import/export
EC-DslDeploy 4.0.3
-
Fixed importDslFromGitNew doesn’t proceed additionalArguments property into installDslFromDirectory step
EC-DslDeploy 4.0.0
-
Added new procedure to provide import from Git functionality using EC-Git plugin
-
Fixed command task contents duplicates for tasks contained in a task group
-
Added metadata for GitSync and scmType level propertysheet
-
Fixed an issue with exports not generating the Groovy command task
-
Removed import old services from EC-DslDeploy Plugin
-
Fixed import DSL for projects with application microservice model when all children are in separate files
EC-DslDeploy 3.0.3
-
Added credentials import/export support
-
Fixed files path to fix deletion issue on Windows
-
Fixed
Relative path to DSL files
parameter in importDslFromGit
EC-DslDeploy 3.0.0
-
The plugin is made CloudBees Supported and moved under the private repository
-
Speedup noop deploy steps
-
Added ignoreFailed and localMode parameters for import procedures
-
Added support for object names with slash and backslash symbols
-
Fixed wrong counts in step summary for import procedures
EC-DslDeploy 2.2.1
-
The plugin is adopted to use new
clientFiles
argument in evalDsl API what allows to remove limitation of shared folder usage for DSL import -
Fixed issue with import of
release
property sheet under the project -
Fixed issue for
generateDslToDirectory
withincludeAcls='1'
EC-DslDeploy 2.2.0
-
Added
overwrite
parameter to install procedures -
Added
generateDslToDirectory
procedure -
Added
importDslFromGit
procedure -
Enhanced
installDsl
procedure to support deploy of more types of objects