Configuration as Code reference

Technical specification for Configuration as Code (CasC) folder structure, YAML schemas, and configuration parameters in CloudBees Unify feature management.

Folder structure

CasC organizes feature management configurations using a standardized directory hierarchy within the .cloudbees/casc folder of your repository.

.cloudbees/casc/
└── feature-management/
    ├── flags/
    ├── flag-configurations/
    │   ├── [environment-name]/
    │   ├── [environment-name]/
    │   └── [environment-name]/
    ├── properties/
    └── target-groups/▼

Root directories

.cloudbees/casc/ : Root Configuration as Code directory containing all CloudBees Unify configurations.

feature-management/ : Container for all feature flag-related configurations.

Configuration directories

flags/ : Contains flag definitions that apply across all environments. Includes flag metadata such as names, descriptions, labels, and variations.

flag-configurations/[environment-name]/ : Contains environment-specific flag configurations. Each environment has its own subdirectory containing YAML files for flag rules and targeting. Environment names must match those defined in CloudBees Unify.

properties/ : Contains custom property definitions used in flag targeting conditions.

target-groups/ : Contains target group definitions that apply across environments.

Deleting an environment in CloudBees Unify removes the corresponding environment folder and all contained files. Deleting an environment folder in source control only removes flag configurations, not the environment itself.

File naming conventions

File names must end with .yaml or .yml
File names should match the flag name: flag-name.yaml
Use lowercase letters, numbers, and hyphens in file names
Namespace separators in flag names become dots: namespace.flag-name.yaml

Flag definition schema

Flag definitions in the flags/ directory use this YAML structure:

flag: [flag-name]
type: flags
description: [flag-description]
labels:
  - [label-1]
  - [label-2]
variations:  # For string/number flags only
  - [value-1]
  - [value-2]▼

Flag definition fields

flag (required) : String. Unique flag identifier matching the flag name used in application code.

type (optional) : String. Always flags for flag definitions. Informational only, no functional impact.

description (optional) : String. Human-readable description of the flag’s purpose.

labels (optional) : Array of strings. Organizational labels for filtering and categorization.

variations (optional) : Array. Predefined values for string or number flags. Not used for boolean flags.

Flag configuration schema

Flag configurations in flag-configurations/[environment]/ directories use this structure:

flag: [flag-name]
type: flags
conditions:
  - [condition-block]
  - [condition-block]
value: [default-value]▼

Configuration fields

flag (required) : String. Must match a flag name defined in the flags/ directory.

type (optional) : String. Always flags for flag configurations. Informational only.

conditions (optional) : Array. Conditional rules that determine flag values based on user properties, target groups, or other flags.

value (required) : Boolean, string, or number. Default value when no conditions match.

Condition block schema

Conditions define targeting rules using properties, target groups, and flag dependencies:

Property conditions

- property:
    propertyConditions:
      - operator: [operator]
        property: [property-name]
        operand: [value] # For operators requiring comparison values
  value: [condition-value]▼

Target group conditions

- group:
    name:
      - [target-group-name]
      - [target-group-name]
  value: [condition-value]▼

Flag dependency conditions

- flag:
    flag: [dependency-flag-name]
    value: [dependency-flag-value]
  value: [condition-value]▼

Version conditions

- version:
    operator: [version-operator]
    semver: [semantic-version]
  value: [condition-value]▼

Property operators

Property conditions support these comparison operators:

is-undefined : Property is not set. No operand required.

is-true : Boolean value is true. No operand required.

is-false : Boolean value is false. No operand required.

in-array : Value exists in the provided array.

eq : Exact string or numeric match.

ne : String or numeric inequality.

gte : Numeric comparison: property >= operand.

gt : Numeric comparison: property > operand.

lt : Numeric comparison: property < operand.

lte : Numeric comparison: property ⇐ operand.

regex : Regular expression pattern match.

Version operators

Version conditions support semantic version comparisons:

semver-eq : Version equals specified semantic version.

semver-ne : Version does not equal specified semantic version.

semver-gte : Version greater than or equal to specified version.

semver-gt : Version greater than specified version.

semver-lte : Version less than or equal to specified version.

semver-lt : Version less than specified version.

Target group schema

Target groups in the target-groups/ directory use this structure:

type: target-group
name: [target-group-name]
conditions:
  - operator: [operator]
    property: [property-name]
    operand: [value]▼

Target group fields

type (required) : String. Always target-group for target group definitions.

name (required) : String. Unique target group identifier.

conditions (required) : Array. Property conditions that define group membership.

Custom property schema

Custom properties in the properties/ directory use this structure:

type: property
name: [property-name]
defaultValue: [default-value]▼

Property fields

type (required) : String. Always property for property definitions.

name (required) : String. Unique property identifier.

defaultValue (optional) : String, number, or boolean. Default value when property is not provided.

Configuration examples

Basic flag configuration

Flag always disabled:

flag: feature.new-dashboard
value: false▼

Flag always enabled:

flag: feature.new-dashboard
value: true▼

Property-based targeting

Enable feature for beta users who are logged in:

flag: feature.new-dashboard
conditions:
  - property:
      propertyConditions:
        - operator: is-true
          property: isBetaUser
        - operator: is-true
          property: isLoggedIn
    value: true
value: false▼

Target group targeting

Enable feature for QA and Beta Users target groups using version 3.0.1 or later:

flag: feature.new-dashboard
conditions:
  - group:
      name:
        - QA
        - Beta Users
    version:
      operator: semver-gte
      semver: 3.0.1
    value: true
value: false▼

Multiple conditions

Complex targeting with multiple condition blocks:

flag: feature.premium-features
conditions:
  - property:
      propertyConditions:
        - operator: equals
          property: subscriptionTier
          operand: premium
    value: true
  - group:
      name:
        - Internal Employees
    value: true
value: false▼

Split release configuration

Percentage-based rollout (requires additional platform configuration):

flag: feature.new-checkout
conditions:
  - property:
      propertyConditions:
        - operator: equals
          property: region
          operand: US
    value: true  # 50% split configured in platform
value: false▼

Target group definition

Define target group for specific user IDs:

type: target-group
name: QA
conditions:
  - operator: in-array
    property: userId
    operand:
      - user123
      - user456
      - user789▼

Define target group for geographic region:

type: target-group
name: US-Users
conditions:
  - operator: equals
    property: country
    operand: US▼

Custom property definition

Define custom property with default value:

type: property
name: subscriptionTier
defaultValue: free▼

Define numeric property:

type: property
name: accountAge
defaultValue: 0▼

Validation rules

All YAML files must be valid YAML syntax
Flag names in configurations must exist in flag definitions
Target group names referenced in conditions must exist in target group definitions
Property names must be defined in properties or be built-in properties
Version operators require valid semantic version format
Operand values must match expected data types for operators

Built-in properties

These properties are available without explicit definition:

rox.distinct_id : Unique user identifier (UUID). Used for split release consistency.

rox.environment : Current environment name.

rox.application : Current application name.

version : Application version for version-based conditions.

Synchronization behavior

Changes in source control sync to CloudBees Unify within minutes
Changes in CloudBees Unify create commits to source control automatically
Bidirectional sync maintains consistency between code and platform
Sync scope is limited to the application containing the CasC configuration