Modern cloud platforms upgrade
Traditional platforms upgrade

Creating items with CasC for controllers

11 minute readScalabilityAutomation

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. For more information, refer to Exports of individual CasC items and Exporting a CasC configuration.

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

Folders with extended fields (recommended)

Freestyle jobs

Pipeline jobs

Multibranch Pipeline jobs

GitHub Organization

Bitbucket Team/Project

Instance based on a CloudBees template

Backup and restore

Example CasC configuration bundle with items

Example bundle.yaml file

id: "bundle-1"
version: "1"
apiVersion: "1"
description: "My CloudBees Configuration as Code (CasC) bundle"
allowCapExceptions: true
availabilityPattern: "folder1/.*"
parent: "bundle-global"
jcasc:
  - "jenkins.yaml"
jcascMergeStrategy: "errorOnConflict"
plugins:
  - "plugins.yaml"
catalog:
  - "plugin-catalog.yaml"
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.
Folders with limited fields
Folders with extended fields
Freestyle job
Pipeline job
Multibranch Pipeline job
GitHub Organization
Bitbucket Team/Project
Instance based on a CloudBees template
Job based on a Pipeline Template Catalog
Backup
Restore
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".

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:

Exporting the CasC item

To export a CasC item:

  1. Ensure you are signed in to the controller as a user with the Administer permission.

  2. 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.

  3. From the controller dashboard, select the item, and then select Export CasC item in the left pane.

  4. From the Export CasC item screen, select Download YAML to export the item as a YAML snippet.

  5. Add the exported YAML snippet to your items.yaml file.

  6. Add the removeStrategy, items, and rbac required properties to your items.yaml file, if not already present. For more information, refer to items.yaml.

  7. 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:

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:

  1. Ensure you are signed in to the controller as a user with the Administer permission.

  2. Create a CloudBees job template. For more information, refer to CloudBees Template plugin.

  3. Create a job based on the template and specify the required attributes.

  4. Select Export CasC item to export the job in YAML format. For more information, refer to Exports of individual CasC items.

  5. 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.
  6. 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:

  1. Ensure you are signed in to the controller as a user with the Administer permission.

  2. Create a Pipeline Template Catalog and add a template to it. For more information, refer to Pipeline Templates.

  3. Create a new job based on the template in the Pipeline Template Catalog and specify the required attributes.

  4. Export the current configuration from the controller.

  5. Open the controller’s jenkins.yaml file from the exported configuration.

  6. 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.
  7. Open the controller’s items.yaml file from the exported configuration.

  8. 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.
  9. Update the controller CasC bundle.

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