Creating items with CasC for controllers

Configuration as Code allows you to create items if the items.yaml file is included in the configuration bundle.

You can export individual CasC items or export all item configurations from an existing instance. However, the exported file should only be used as a starting point, as it may require modifications and adjustments to make it production-ready.

Configure variable resolution for items in a CasC bundle

You can configure variable resolution for items in a bundle by doing one of the following:

Configure the cascItemsConfiguration value in the jenkins.yaml file.
Enable the Enable or disable the variable resolution in the item creation for administrator on the System Configuration page in the UI.

Configure the `jenkins.yaml` file to handle variable resolution in the `items.yaml` file

Set variable resolutions for items in a bundle by configuring the cascItemsConfiguration value in the jenkins.yaml file.

unclassified:
  cascItemsConfiguration:
    variableInterpolationEnabledForAdmin: true (1)
    variableInterpolationEnabledForNonAdmin: true (2)▼

1	Set the `variableInterpolationEnabledForAdmin` value to `true` to allow administrators to use the variable resolution for items in the `items.yaml` file. The value is set to `false` by default.
2	Set the `variableInterpolationEnabledForNonAdmin` value to `true` to allow non-adminstrators to use the variable resolution for items in the `items.yaml` file. The value is set to `false` by default.

The variableInterpolationEnabledForNonAdmin setting is ignored if the variable resolution is not allowed (false) for administrators. For example:

If variableInterpolationEnabledForAdmin is false for administrators, then the variable resolution is also not allowed for non-administrators even if variableInterpolationEnabledForNonAdmin is set to true.
If variableInterpolationEnabledForAdmin is true for administrators, then variable resolution is allowed for non-administrators if variableInterpolationEnabledForNonAdmin is also set to true.

Configure the variable resolution in the controller

To enable variable resolution in controllers, configure the CasC item configuration setting on the System Configuration page.

To configure CasC item configuration in the controller:

From the dashboard, select Manage Jenkins System.
Navigate to CasC Items configuration.

Figure 1. Enable variable resolution

Select one of the following:

Enable or disable the variable resolution in the item creation for administrator: This allows administrators to use the variable resolution for items imported in the item.yaml file. This setting is disabled by default.

Enable or disable the variable resolution in the item creation for non-administrator: This allows non-administrators to use the variable resolution for items in the items.yaml file. This setting is disabled by default.

The Enable or disable the variable resolution in the item creation for non-administrator setting is ignored if the variable resolution is not allowed (disabled) for administrators. For example:

If Enable or disable the variable resolution in the item creation for administrator is disabled, then the variable resolution is also not allowed for non-administrators even if Enable or disable the variable resolution in the item creation for non-administrator is selected.
If Enable or disable the variable resolution in the item creation for administrator is selected, then variable resolution is allowed for non-administrators if Enable or disable the variable resolution in the item creation for non-administrator is also selected.

Select Save.

For more information, refer to Exports of individual CasC items and Exporting a CasC configuration.

Escape variable expressions

To prevent exposure of variable resolution values and potentially leaking secrets, items.yaml files in a CasC bundle can escape variable expressions.

In the example below, the items.yaml contains a folder with a display name escaped: ^${testkey} and a folder with the display name variable: ${testkey}.

items:
  - kind: folder
    name: b
    displayName: "escaped: ^${testkey}"
  - kind: folder
    name: a
    displayName: "variable: ${testkey}"▼

The variables.yaml contains variable named testkey: testvalue.

variables:
  - testkey: testvalue▼

When the variable resolution setting is enabled in the UI or the jenkins.yaml file, CasC removes the circumflex (^) character and treats the following $ as plain text. In the UI, the first folder name is displayed without ^ character. For the second folder’s display name, the variable is substituted with its value.

Figure 2. Folder name without the ^ charater when the variable resolution is enabled

When the variable resolution setting is disabled, CasC treats the displayName values as plain text in both cases. In the UI, the folder names displays all the characters of the configured strings including the circumflex (^).

folder name with all characters displayed

Figure 3. Folder name with all charaters displayed when the variable resolution is disabled

Supported items using CasC

The following items are supported using CasC. You must install the prerequisite CloudBees CI software and plugins based on the item type you are creating.

If using RBAC to define roles and groups for items, you must also install the Configuration as Code plugin and CloudBees Role-Based Access Control plugin.

Table 1. Supported item types and prerequisites

Item type

Prerequisites

Folders with limited fields

CloudBees CI 2.249.3.1 - 2.289.3.2
CloudBees CasC API (Deprecated) plugin, version 1.2 - 1.14

Folders with extended fields (recommended)

If using CloudBees CI 2.303.1.5 - 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.24 - 1.41
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Items Commons plugin, version 1.0 or later

Freestyle jobs

If using CloudBees CI 2.303.1.5 - 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.24 - 1.41
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Items Commons plugin, version 1.0 or later

Pipeline jobs

If using CloudBees CI 2.303.1.5 - 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.24 - 1.41
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Items Controller plugin, version 1.1 or later

Multibranch Pipeline jobs

If using CloudBees CI 2.303.1.5 - 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.24 - 1.41
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Items Controller plugin, version 1.1 or later
Pipeline: Multibranch plugin

GitHub Organization

If using CloudBees CI 2.303.1.5 - 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.24 - 1.41
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Items Controller plugin, version 1.1 or later
GitHub Branch Source plugin

Bitbucket Team/Project

If using CloudBees CI 2.303.1.5 - 2.303.3.3: the CloudBees CasC API (Deprecated) plugin, version 1.24 - 1.41
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Items Controller plugin, version 1.1 or later
Bitbucket Branch Source plugin

GitLab Organization

If using CloudBees CI 2.414.3.5: CloudBees CasC Items Controller plugin, version 2.39 or later.

Other organization folders

If using CloudBees CI 2.452.1.1 and the CloudBees CasC Items Controller plugin and CloudBees CasC Items API plugin version 2.62 or later.

CloudBees support for these items is only restricted to the possibility of creating organization folders extending the SCMNavigator class. Items created using this organization folder can be exported and imported using CloudBees CasC.

However, CloudBees does not support, by any means:

The plugin that extends the SCMNavigator class.
Any misfunction, misconfiguration or error that may arise from the plugin.

Instance based on a CloudBees template

CloudBees CI 2.319.2.5
CloudBees CasC Items Controller plugin, version 1.6 or later
CloudBees Template plugin, if creating an instance based on a CloudBees template
CloudBees Pipeline: Templates plugin, if creating a job based on a Pipeline Template Catalog

Backup and restore

If using CloudBees CI 2.303.3.3: CloudBees CasC API (Deprecated) plugin version 1.41
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Items Commons plugin, version 1.0 or later
CloudBees Backup plugin

Other SCMNavigator classes configuring the organization folder

Starting with CloudBees CI version 2.452.1.1, in addition to organization folder items for a GitHub Organization, Bitbucket Team/Project, or GitLab Organization, you can create organization folders that extend the SCMNavigator class and these organization folders can be exported and imported using CloudBees CasC.

CloudBees support for these items is only restricted to the possibility of creating other organization folders.

However, CloudBees does not support:

The plugin that extends the SCMNavigator class.
Any misfunction, misconfiguration or error that may arise from the plugin.

This organization folder that extends SCMNavigator class can display new properties that can be exported and imported using CloudBees CasC and displayed in the UI when you create a new item of this type. Guidelines, rules, and examples for this extension are described below.

Class, properties and methods

You must define an unique @Symbol for the class that extends the SCMNavigator class. This symbol is used to identify the class in the YAML file.

You must extend the SCMNavigator class.

public class MyCustomSCMNavigator extends SCMNavigator {
    // Class implementation
}▼

Not all the properties can be exported or imported using CasC.
- Java primitive types, wrapper classes, enums, and strings are supported.
- To be displayed in the UI, objects implementing the Describable interface are supported. SCMNavigator is an example of a Describable object.
- List of the types above are supported.
- Maps and Non Describable objects are not supported.
If a constructor has parameters, you must add the @DataBoundConstructor annotation. The name of the parameters is used during the import and export process. Those parameters must have a getter mechanism.

private Integer property1;
public Boolean property2;

@DataBoundConstructor
public DescribableField(Integer property1, Boolean property2) {
    this.property1 = property1;
    this.property2 = property2;
}

public Integer getProperty1() {
    return property1;
}▼

This code snippet is exported as:

describableField:
  property1: 12
  property2: true▼

Either a constructor annotated as DataBoundConstructor or a default constructor without parameters should be defined. Otherwise, the import and export processes fail.
For the rest of the properties, to be properly exported or imported:
- Property type is a supported type.
- Public fields with the @DataBoundSetter annotation.
- Properties with a getter and setter methods with the @DataBoundSetter annotation.
- Read-only properties (getter but no setter method) that are collections

Export and import configuration files

It’s possible to customize what properties from the Describable objects are part of the YAML file using the .casc-items file. This file must be located in the resources folder for the Describable classes in your project.

The .casc-items file can be used by any Describable object, not only by classes extending the SCMNavigator class.

As an example, if the Describable class is com.example.ThisDescribableClass then the file should be located in com/example/ThisDescribableClass/.casc-items.

properties: (1)
  - property1
  - anotherProperty
ignored: (2)
  - ignored1
  - anotherIgnored
alias: (3)
  property1: alias1
  property2: alias2▼

1	List of properties to be exported and imported.
2	List of properties to be ignored during the export and import process.
3	List of properties to be exported and imported with an alias.

This configuration does not apply to the properties used in the DataBoundConstructor.

The GitHub Branch Source Plugin is an example of a plugin that extends the SCMNavigator class. For additional information, review the code here.

Example CasC configuration bundle with items

Example bundle.yaml file

id: "remove-bundle"
version: "1"
apiVersion: "1"
description: "CasC bundle with removeStrategy in descriptor"
allowCapExceptions: true
availabilityPattern: "folder1/.*"
parent: "bundle-global"
jcasc:
  - "jenkins.yaml"
jcascMergeStrategy: "errorOnConflict"
plugins:
  - "plugins.yaml"
catalog:
  - "plugin-catalog.yaml"
itemRemoveStrategy:
  items: "remove-all"
  rbac: "sync"
rbacRemoveStrategy: "sync"
items:
  - "items.yaml"
rbac:
  - "rbac.yaml"
variables:
  - "variables.yaml"▼

Example jenkins.yaml file

jenkins:
  systemMessage: "Controller configured using CloudBees CasC"
  numExecutors: 0
  securityRealm:
    ldap:
      configurations:
      - displayNameAttributeName: "cn"
        groupMembershipStrategy:
          fromGroupSearch:
            filter: "member={0}"
        groupSearchBase: "ou=Groups"
        inhibitInferRootDN: false
        managerDN: "cn=admin,dc=example,dc=org"
        managerPasswordSecret: ${LDAP_MANAGER_PASSWORD}
        rootDN: "dc=example,dc=org"
        server: "ldap://ldap-openldap:389"
        userSearchBase: "ou=People"
      disableMailAddressResolver: false
      groupIdStrategy: "caseInsensitive"
      userIdStrategy: "caseInsensitive"
  authorizationStrategy: "cloudBeesRoleBasedAccessControl"(1)
globalCloudBeesPipelineTemplateCatalog:(2)
  catalogs:
  - branchOrTag: "main"
    scm:
      git:
        credentialsId: "credentials-id"
        id: "cf504eg3-4y5d-34w2-97b1-2q7xt2nm9731"(3)
        remote: "git@github.com:company/project-alpha.git"
    updateInterval: "1d"▼

1	Required to use CloudBees RBAC configured using CasC.
2	Required if using CasC to create a job based on a Pipeline Template Catalog.
3	Required property that defines the unique ID for the SCM repository where the Pipeline Template Catalog is stored.

Example plugins.yaml file

plugins:
  # In CloudBees Assurance Program (CAP)
  - id: "bitbucket-branch-source"
  - id: "branch-api"
  - id: "cloudbees-casc-client"
  - id: "cloudbees-casc-items-api"
  - id: "cloudbees-casc-items-commons"
  - id: "cloudbees-casc-items-controller"
  - id: "cloudbees-template"
  - id: "cloudbees-workflow-template"
  - id: "configuration-as-code"
  - id: "git"
  - id: "github-branch-source"
  - id: "infradna-backup"
  - id: "support-core"
  - id: "workflow-multibranch"
  # Not in CAP (see plugin-catalog.yaml)
  - id: "manage-permission"▼

Example plugin-catalog.yaml file

type: "plugin-catalog"
version: "1"(1)
name: "my-plugin-catalog"
displayName: "My Plugin Catalog"
configurations:
  - description: "Extensions to CAP"
    includePlugins:
      manage-permission:(2)
        version: 1.0.1(3)
      #my-custom-plugin:
        #url: http://www.example.org/jenkins-plugins/my-custom-plugin-1.2.3.hpi
    beekeeperExceptions:
      support-core:
        version: "2.70"▼

1	`version` (required) - must currently have the value 1, which defines the current metadata format for the plugin catalog.
2	Add the `manage-permission` plugin to enable the Overall/Manage permission.
3	Replace 1.0.1 with the most recent version.

Example items.yaml file

If a CloudBees CI GitHub Organization is used to configure a repository from a GitHub Enterprise server and you add the server to the Configure System screen, API endpoint is a required field. You must verify that the apiUri property is configured in the items.yaml file. If the GitHub server is not an enterprise server, you can optionally remove the apiUri property from the items.yaml file.

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "folder"
    name: project-${team_group}
    displayName: "Project Alpha"
    description: "Project Alpha is going to change the world!"
    properties:
      - folderCredentialsProperty:
          folderCredentials:
            - credentials:
                - usernamePassword:
                    password: ${secret_location}
                    scope: GLOBAL
                    description: description
                    id: test-id
                    usernameSecret: false
                    username: test-user
              domain: {}
    groups:
      - name: "Project Alpha Developers"
        members:
          external_groups:
            - ldap-project-${team_group}
        roles:
          - name: "developer"
    items:(1)
      - kind: "folder"
        name: "project-alpha-tests"
        displayName: "Project Alpha Tests"
        items:
          - kind: "folder"
            name: "test-1"
          - kind: "folder"
            name: "test-2"
  - kind: "folder"
    name: "project-beta"
    displayName: "Project Beta"
    description: "Secret project! Only Admins can see this!"
    filteredRoles:(2)
      - "developer"
      - "browser"▼

1	Items can be nested within other items, enabling users to create a folder structure.
2	Roles can be filtered, for example to allow only administrators to view certain projects.

removeStrategy:
  items: "none"
  rbac: "sync"

items:(1)
  - kind: "folder"
    name: project-${team_group}
    displayName: "Project Alpha"
    description: "Project Alpha is going to change the world!"
    groups:
      - name: "Project Alpha Developers"
        members:
          external_groups:
            - ldap-project-${team_group}
        roles:
          - name: "developer"
    items:
      - kind: "folder"
        name: "project-alpha-tests"
        displayName: "Project Alpha Tests"
        items:
          - kind: "folder"
            name: "test-1"
          - kind: "folder"
            name: "test-2"
    properties:
      - envVars:
          vars:
            FOO: "BAR"
            BAR: "BAZ"
      - folderLibraries:
          libraries:
            - libraryConfiguration:
                implicit: false
                allowVersionOverride: true
                retriever:
                  modernSCM:
                    scm:
                      github:
                        traits:
                          - gitHubBranchDiscovery:
                              strategyId: 1
                          - gitHubPullRequestDiscovery:
                              strategyId: 1
                          - gitHubForkDiscovery:
                              trust:
                                gitHubTrustEveryone: {}
                              strategyId: 1
                        repoOwner: "company"
                        id: "library-id"
                        repository: "project-alpha"
                        configuredByUrl: true
                        repositoryUrl: "https://github.com/company/project-alpha"
                name: "my-library"
                includeInChangesets: true
      - folderCredentialsProperty:
          folderCredentials:
            - credentials:
                - usernamePassword:
                    password: ${secret_location}
                    scope: GLOBAL
                    description: description
                    id: test-id
                    usernameSecret: false
                    username: test-user
              domain: {}
      - itemRestrictions:
          allowedTypes:
            - "org.jenkinsci.plugins.workflow.job.WorkflowJob"
            - "hudson.matrix.MatrixProject"
            - "hudson.model.FreeStyleProject"
            - "com.cloudbees.hudson.plugins.modeling.impl.jobTemplate.JobTemplate"
            - "com.cloudbees.hudson.plugins.folder.Folder"
            - "com.cloudbees.hudson.plugins.modeling.impl.builder.BuilderTemplate"
            - "com.cloudbees.hudson.plugins.modeling.impl.auxiliary.AuxModel"
            - "org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject"
            - "com.cloudbees.hudson.plugins.modeling.impl.publisher.PublisherTemplate"
            - "com.cloudbees.hudson.plugins.modeling.impl.folder.FolderTemplate"
            - "com.infradna.hudson.plugins.backup.BackupProject"
          filter: true
    items:
      - kind: "freeStyle"
        name: "project-alpha-freestyle"
        displayName: "Freestyle job in the Project Alpha folder"
  - kind: "folder"
    name: "project-beta"
    displayName: "Project Beta"
    description: "Secret project! Only Admins can see this!"
    filteredRoles:(2)
      - "developer"
      - "browser"▼

1	Items can be nested within other items, enabling users to create a folder structure.
2	Roles can be filtered, for example to allow only administrators to view certain projects.

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "freeStyle"
    name: "project-alpha-freestyle"
    displayName: "Project Alpha Freestyle"
    description: "This is Project Alpha's Freestyle job!"
    disabled: false
    scm:
      gitSCM:
        extensions:
          - checkoutOption:
              timeout: 4
        gitTool: git
        userRemoteConfigs:
          - userRemoteConfig:
              name: "developer-a"
              credentialsId: "credentials-id"
              url: "git@github.com:company/project-alpha.git"
        browser:
          githubWeb:
            repoUrl: "https://github.com/company/project-alpha"
        doGenerateSubmoduleConfigurations: false
        branches:
          - branchSpec:
              name: "*/main"
    buildDiscarder:
      logRotator:
        artifactDaysToKeep: 3
        daysToKeep: 1
        numToKeep: 2
        artifactNumToKeep: 4
    scmCheckoutStrategy:
      standard: { }
    builders:
      - shell:
          command: "pwd"▼

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "pipeline"
    name: "project-beta-pipeline-job"
    displayName: "Project Beta Pipeline job"
    description: "This is Project Beta's Pipeline job!"
    definition:
      cpsScmFlowDefinition:
        scriptPath: "Jenkinsfile"
        scm:
          gitSCM:
            gitTool: "git"
            userRemoteConfigs:
              - userRemoteConfig:
                  name: "developer-b"
                  credentialsId: "credentials-id"
                  url: "git@github.com:company/project-beta.git"
            extensions:
              - checkoutOption:
                  timeout: 2
              - cloneOption:
                  reference: "/workspace/git"
                  noTags: false
                  honorRefspec: false
                  shallow: true
                  timeout: 5
            branches:
              - branchSpec:
                  name: "*/main"▼

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "multibranch"
      name: "project-beta-multibranch-pipeline"
      displayName: "Project Beta Multibranch Pipeline"
      description: "This is Project Beta's Multibranch Pipeline job!"
      orphanedItemStrategy:
        defaultOrphanedItemStrategy:
          pruneDeadBranches: true
          daysToKeep: 3
          numToKeep: 4
      projectFactory:
        workflowBranchProjectFactory:
          scriptPath: "Jenkinsfile"
    sourcesList:
      - branchSource:
          source:
            github:
              traits:
                - gitHubBranchDiscovery:
                    strategyId: 1
                - gitHubPullRequestDiscovery:
                    strategyId: 1
                - gitHubForkDiscovery:
                    trust:
                      gitHubTrustEveryone: {}
                    strategyId: 1
                - headWildcardFilter:
                    excludes: "feature/*"
                    includes: "*"
                - gitHubSshCheckout:
                    credentialsId: "github-ssh"
              repoOwner: "company"
              id: "scm-source-id"
              repository: "project-alpha"
              configuredByUrl: true
              repositoryUrl: "https://github.com/company/project-beta"
          strategy:
            allBranchesSame: {}▼

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "organizationFolder"
    name: "project-alpha-github-org"
    displayName: "Project Alpha GitHub Organization job"
    description: "This is Project Alpha's Github Organization job!"
    navigators:
      - github:
          traits:
            - checkoutOptionTrait:
                extension:
                  checkoutOption:
                    timeout: 5
            - cloneOptionTrait:
                extension:
                  cloneOption:
                    reference: main
                    noTags: false
                    honorRefspec: false
                    shallow: true
                    timeout: 6
          repoOwner: "company"
    projectFactories:
      - customMultiBranchProjectFactory:
          factory:
            customBranchProjectFactory:
              marker: ".my-marker-file"
              definition:
                cpsScmFlowDefinition:
                  scriptPath: "pipelines/default/Jenkinsfile"
                  scm:
                    gitSCM:
                      extensions:
                        - checkoutOption:
                            timeout: 4
                      gitTool: "git"
                      userRemoteConfigs:
                        - userRemoteConfig:
                            name: "admin-a"
                            credentialsId: "credentials-id"
                            url: "git@github.com:company/project-alpha.git"
                      browser:
                        githubWeb:
                          repoUrl: "git@github.com:company/project-alpha"
                      branches:
                        - branchSpec:
                            name: "*/main"
                  lightweight: false▼

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "organizationFolder"
    name: "project-beta-bitbucket-org"
    displayName: "Project Beta Bitbucket Organization job"
    description: "This is Project Beta's Bitbucket Organization job!"
    navigators:
      - bitbucket:
          traits:
            - bitbucketBranchDiscovery:
                strategyId: 1
            - bitbucketPullRequestDiscovery:
                strategyId: 1
            - bitbucketForkDiscovery:
                trust:
                  bitbucketTrustTeam: {}
                strategyId: 1
          repoOwner: "company"
    projectFactories:
      - workflowMultiBranchProjectFactory:
          scriptPath: "Jenkinsfile"▼

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "cloudbeesTemplatedJob"
    name: "job-template-alpha"
    model: "folder1/template"(1)
    attributes:(2)
      - value: job-template-alpha(3)
        key: name
      - value: the description
        key: description
      - value: pwd
        key: command▼

1	The full path to the template.
2	Attributes defined in the CloudBees job template.
3	The name of the new instance you are creating based on the template.

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "cloudbeesTemplatedJob"
    name: "my-new-job"
    catalog: "project-alpha-pipeline-template-catalog"(1)
    model: "template-alpha"(2)
    attributes:(3)
      - value: template-alpha(4)
        key: name
      - value: the description
        key: description
      - value: pwd
        key: command▼

1	The name of the Pipeline Template Catalog that is defined in the `catalog.yaml` file.
2	The name of the template within the Pipeline Template Catalog.
3	Attributes defined in the CloudBees job template.
4	The name of the new job you are creating based on the template.

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: backupAndRestore
    name: project-alpha-backup
    displayName: "Project Alpha backup"
    description: "This is Project Alpha's backup job!"
    buildersList:
      - backupBuilder:
          subjects:
            - buildRecordSubject:
                excludes: foo
            - jobConfigurationSubject:
                excludes: bar
            - systemConfigurationSubject:
                excludes: baz
                omitMasterKey: true
          format:
            zipFormat: {}
          exclusive: false
          store:
            s3Store:
              bucketName: bucket
              sse: true
              bucketFolder: bucketFolder
              credentialsId: testCredential
              region: us-east-1
          retentionPolicy:
            exponentialDecayRetentionPolicy: {}
          safeDelaySeconds: 42
    label: agent-for-backup
    triggers:
      - cron:
          spec: 0 0 * * *
    buildDiscarder:
      logRotator:
        numToKeep: 5▼

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: backupAndRestore
    name: project-alpha-restore
    displayName: "Project Alpha restore"
    description: "This is Project Alpha's restore job!"
    buildersList:
      - restoreBuilder:
          ignoreConfirmationFile: false
          preserveJenkinsHome: true
          ignoreDigestCheck: true
          store:
            s3Store:
              bucketName: bucket
              sse: true
              bucketFolder: bucketFolder
              credentialsId: testCredential
              region: us-east-1
          restoreDirectory: /tmp
    label: agent-for-restore
    buildDiscarder:
      logRotator:
        numToKeep: 5▼

Example rbac.yaml file

removeStrategy:
  rbac: "SYNC"(1)

roles:
  - name: administer
    permissions:
      - hudson.model.Hudson.Administer
  - name: developer
    permissions:
      - hudson.model.Hudson.Read
      - hudson.model.Item.Read
      - hudson.model.Item.Create
      - hudson.model.Item.Configure
    filterable: "true"(2)
  - name: browser
    permissions:
    - hudson.model.Hudson.Read
    - hudson.model.Item.Read
    filterable: "true"
  - name: authenticated
    filterable: "true"
    permissions:
    - hudson.model.Hudson.Read

groups:
  - name: Administrators
    roles:
      - name: administer
        grantedAt: current(3)
    members:
      users:
        - admin
      external_groups:
        - ${external_admin_group}
  - name: Developers
    roles:(4) (5)
      - name: developer
    members:
      users:
        - developer
      internal_groups:
        - "some-other-group"
      external_groups:
        - "ldap-cb-developers"
  - name: Browsers
    roles:
      - name: browser
    members:
      users:
        - read▼

1	For security reasons, SYNC is here to remove groups/roles from CloudBees Continuous Integration when they are removed from this file.
2	If filterable is not included, the default value is “false”.
3	Other options that could be used here include: "child" or "grandchild".
4	If propagates is not included, the default value is "true".
5	If grantedAt is not included, the default value is "current".

Example variables.yaml file

  variables:
    - key: value
    - long_text: |-
        multiline string without
        quotes
    - another: text
    - team_name: Team Alpha
    - team_group: alpha
    - external_admin_group: ldap-cb-admins▼

Exports of individual CasC items

You can export an existing item as a YAML snippet and add it to the items.yaml file. However, the exported item should only be used as a starting point, as it may require modifications and adjustments to make it production-ready.

Exporting an individual CasC item is not supported for the auto-generated children of folder-type items for Multibranch Pipeline jobs, GitHub Organizations, and Bitbucket Teams/Projects.

Prerequisites

The following software and plugins must be installed to export the item:

If using CloudBees CI 2.303.3.3: CloudBees CasC API (Deprecated) plugin, version 1.41 or later
If using CloudBees CI 2.319.1.5 or later: CloudBees CasC Items API plugin, version 1.1.1 or later

Exporting the CasC item

To export a CasC item:

Ensure you are signed in to the controller as a user with the Administer permission.
Create a new item in the UI and configure it. Or, if you have an existing item that is already configured, you can skip this step.
From the controller dashboard, select the item, and then select Export CasC item in the left pane.
From the Export CasC item screen, select Download YAML to export the item as a YAML snippet.
Add the exported YAML snippet to your items.yaml file.
Add the removeStrategy, items, and rbac required properties to your items.yaml file, if not already present. For more information, refer to items.yaml.
If you created a new item in the UI and it is no longer needed, you can delete it.

Creating items based on CloudBees templates

You can use CasC to create an item based on a CloudBees template.

This can be useful if you want to:

Create an instance based on a CloudBees template
Create a Pipeline Template Catalog and job using CasC

Creating an instance based on a CloudBees template

In the UI, you can create a CloudBees template and create a new instance based on the template. You can then export the instance in YAML format and use this to create new instances using CasC. The following example illustrates how to create a job based on a CloudBees job template.

To create a job based on a CloudBees template:

Ensure you are signed in to the controller as a user with the Administer permission.
Create a CloudBees job template. For more information, refer to CloudBees Template plugin.
Create a job based on the template and specify the required attributes.
Select Export CasC item to export the job in YAML format. For more information, refer to Exports of individual CasC items.

Copy the exported job and paste it into the controller’s items.yaml file. For example:

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "cloudbeesTemplatedJob"
    name: "job-template-alpha"
    model: "folder1/template"(1)
    attributes:(2)
      - value: job-template-alpha(3)
        key: name
      - value: the description
        key: description
      - value: pwd
        key: command▼

1	The full path to the template.
2	Attributes defined in the CloudBees job template.
3	The name of the new instance you are creating based on the template.

Update the controller CasC bundle.

Select Reload Configuration to apply the new configuration without restarting the controller.

Creating a Pipeline Template Catalog and job using CasC

You can export the current CasC configuration for the controller to create a Pipeline Template Catalog and job using CasC.

The credentials from the operations center cannot be used during the initial startup of the controller. If the credentials are required during the initial startup of the controller before the connection has been created, you must define the credentials in the controller.

To create a job based on a Pipeline Template Catalog:

Ensure you are signed in to the controller as a user with the Administer permission.
Create a Pipeline Template Catalog and add a template to it. For more information, refer to Pipeline Templates.
Create a new job based on the template in the Pipeline Template Catalog and specify the required attributes.
Export the current configuration from the controller.
Open the controller’s jenkins.yaml file from the exported configuration.

Copy the globalCloudBeesPipelineTemplateCatalog properties and paste them into the jenkins.yaml file in the controller CasC bundle. For example:

globalCloudBeesPipelineTemplateCatalog:(1)
  catalogs:
  - branchOrTag: "main"
    scm:
      git:
        credentialsId: "credentials-id"
        id: "cf504eg3-4y5d-34w2-97b1-2q7xt2nm9731"(2)
        remote: "git@github.com:company/project-alpha.git"
    updateInterval: "1d"▼

1	Required if using CasC to create a job based on a Pipeline Template Catalog.
2	Required property that defines the unique ID for the SCM repository where the Pipeline Template Catalog is stored.

Open the controller’s items.yaml file from the exported configuration.

Copy the CloudBees template item and paste it into the items.yaml file in the controller CasC bundle. For example:

removeStrategy:
  items: "none"
  rbac: "sync"

items:
  - kind: "cloudbeesTemplatedJob"
    name: "my-new-job"
    catalog: "project-alpha-pipeline-template-catalog"(1)
    model: "template-alpha"(2)
    attributes:(3)
      - value: template-alpha(4)
        key: name
      - value: the description
        key: description
      - value: pwd
        key: command▼

1	The name of the Pipeline Template Catalog that is defined in the `catalog.yaml` file.
2	The name of the template within the Pipeline Template Catalog.
3	Attributes defined in the CloudBees job template.
4	The name of the new job you are creating based on the template.

Update the controller CasC bundle.

Select Reload Configuration to apply the new configuration without restarting the controller.

Creating items with CasC for controllers

Configure variable resolution for items in a CasC bundle

Configure the jenkins.yaml file to handle variable resolution in the items.yaml file

Configure the variable resolution in the controller

Escape variable expressions

Supported items using CasC

Other SCMNavigator classes configuring the organization folder

Class, properties and methods

Export and import configuration files

Example CasC configuration bundle with items

Example bundle.yaml file

Example jenkins.yaml file

Example plugins.yaml file

Example plugin-catalog.yaml file

Example items.yaml file

Example rbac.yaml file

Example variables.yaml file

Exports of individual CasC items

Prerequisites

Exporting the CasC item

Creating items based on CloudBees templates

Creating an instance based on a CloudBees template

Creating a Pipeline Template Catalog and job using CasC

Configure the `jenkins.yaml` file to handle variable resolution in the `items.yaml` file