Work With the YAML Format for Release

DevOps as Code uses a declarative YAML format to construct specifications that can be executed by Deploy and Release using the XL CLI. This topic provides a reference for the DevOps as Code YAML file structure for each available kind for Release. It also includes information on using the Spec section of the YAML file which provides the details of the configuration.

YAML file fields

Release YAML files include a common set of root fields and a kind field that identifies the type of YAML file.

Root fields

Field name	Description
apiVersion	Digital.ai API (xl-release/v1 or xl/v1) and XL CLI version (v1, v2 and so on)
kind	See Kind fields for details
spec	Specifications based on kind. See the Spec section for details
metadata	Used to define a list of other YAML files to import and home directories

Kind fields

Product	Kind	Description
Release	Templates	Used to model the release flow process. Can include configuration details and have multiple spec sections
Release	Release	Creates and starts a release from a Release template
Release	Permissions	Specify global and directory-level permissions for users and roles
Release	Users	Users that can be assigned to roles
Release	Roles	Roles that can be assigned global permissions
Release	Import	Used to list multiple YAML files for sequential execution
Release	Blueprint	Blueprints YAML files are created from templates that streamline the provisioning process using standardized configurations built on best practices

Spec section

The spec section of the Release YAML file has unique fields available depending on the YAML file's kind. Due to the scope, complexity and flexibility of this section, the best way for you to understand the capabilities and constructs used in this section is to:

• Review YAML generated from existing configurations - You can use the XL CLI generate command to generate YAML files for specific kinds from existing configurations or new configurations that you create in Release.

• Use YAML snippets - You can choose from a list of useful, customizable snippets to get started when writing a YAML file. See the YAML snippets reference for DevOps as Code

• Utilize the Visual Studio Code extension - If you are using the Visual Studio Code editor, Digital.ai provides an extension that adds YAML support for the DevOps Platform to Visual Studio Code. The extension adds the following features:

  • Syntax highlighting
  • Code completion
  • Code validation
  • Code formatting
  • Code snippets
  • Context documentation

  To install the extension, and for more information on the supported features, search for "DevOps as Code by Digital.ai" in the Visual Studio Code Marketplace.

Review YAML generated from existing configurations

If you have existing applications and pipelines configured in Release, you can get started with DevOps as Code by using the xl generate command to generate YAML files with details from these existing configurations. Because the resulting YAML files and syntax represent familiar constructs used in your development environment, you can use the information as a starting point to extend and expand your own YAML files, helping to bootstrap your transition to an "as code" development and release model.

Here are a few simple XL CLI command line examples to generate YAML files from your existing configurations.

Generate a YAML file for an Release Template configuration

To generate a YAML file for an existing Template configuration from Release:

xl generate xl-release -p Pipeline -f /tmp/mypipeline.yaml

The resulting YAML file might look like:

apiVersion: xl-release/v1
kind: Templates
spec:
- name: MyTemplate
  type: xlrelease.Release
  scheduledStartDate: 2018-10-25T07:00:00Z
  phases:
  - name: My Phase
    type: xlrelease.Phase
    tasks:
    - name: My Task
      type: xlrelease.Task
    color: #0099CC

Handling special boolean characters

The characters Y, N, 1, and 0 by themselves in a string-type field will be interpreted as boolean values by the YAML specification if they are not enclosed in quotes. This could result in unexpected behavior when applying a file in Release, if the fields are not correctly declared.

For example, if you create a template with the name Y without enclosing it in quotes, then use xl apply to generate the template, the template name will be created as true. To avoid this outcome, in the YAML file you should always ensure that the characters above are enclosed in quotes in the form "Y".

Note that if you use xl generate for fields already in Release with the characters above, they will automatically be generated with quotations to avoid this outcome.