What Are YAML Files Used for in VB Studio ?

All YAML files must reside in the .ci-build directory in the root directory of any hosted Git repository’s main branch. YAML files in other branches will be ignored. Any text file that has a .yml file extension and resides in the main branch’s .ci-build directory is considered to be a YAML configuration file. Each YAML file can contain configuration data for exactly one job or one pipeline. You can have YAML files in multiple Git repositories, or use a separate Git repository to host all your YAML configuration files. You cannot, however, use an external Git repository to host YAML files. Because these configuration files are stored using Git, you can track changes made to the job or pipeline configuration and, if a job or pipeline is deleted, you can use the configuration file to recreate it.

The build system constantly monitors the project’s Git repositories. When it detects an update to a file with the .yml extension in the .ci-build directory of a Git repository’s main branch, it scans the file to determine if it is a job or a pipeline, and creates or updates the corresponding job or pipeline. First, it verifies whether the job or the pipeline of the same name (as in the configuration file) exists on the Builds page. If the job or the pipeline exists, it’s updated. If the name of the job or pipeline has changed in the configuration file, it’s renamed. If the job or the pipeline doesn’t exist, it’s created.

Note: Jobs and pipelines created with YAML can’t be edited on the Builds page. They must be edited using YAML. Similarly, jobs and pipelines created on the Builds page can’t be edited using YAML.

YAML stores data as a key-value pair in the field: value format. A hyphen (-) before a field identifies it as an array or a list. It must be indented to the same level as the parent field. To indent, always use spaces, not tabs. Make sure that number of indent spaces before a field name matches the number of indented spaces in the template. YAML is sensitive to number of spaces used to indent fields. Also, the field names in a YAML file are similar to the field names in the job configuration user interface:


name: MyFirstYAMLJob
vm-template: Basic Build Executor Template
git:
- url: "https://mydevcsinstance-mydomain/.../scm/employee.git"
steps:
- shell:
    script: "echo Build Number: $BUILD_NUMBER"
- maven:
    goals: clean install
    pom-file: "employees-app/pom.xml"

If you’re editing a YAML file on your computer, always use a text editor with the UTF-8 encoding. Don’t use a word processor.

Here are some additional points to consider about YAML files before you begin creating or editing them:

The name field in the configuration file defines the job’s or pipeline’s name. If no name is specified, the build system creates a job or a pipeline with name as <repo-name>_<name>, where repo-name is the name of the Git repository where the YAML file is hosted and <name>.yml is the name of the YAML file.

For example, if the YAML file’s name is MyYAMLJob and it’s hosted in the YAMLJobs Git repository, then the job’s or pipeline’s name would be YAMLJobs_MyYAMLJob.

If you add the name field later, the job or pipeline will be renamed. Its access URL will also change.
Each job’s configuration must define the vm-template field.
When you define a string value, you can use quotes, if necessary. If any string values contain special characters, always enclose the values with quotes.

Here are some examples of special characters: *, :, {, }, [, ], ,, &, #, ?, |, -, <, >, =, !, %, @, `.

You can use single quotes (' ') or double quotes (" "). To include a single quote in a single quoted string, escape the single quote by prefixing it with another single quote. For example, to set Don's job in the name field, use name=Don's job in your YAML file. To use a double quote in a double quoted string, escape the double quote with a backslash (\) character. For example, to set My "final" job in the name field, use name=My "final" job in your YAML file. There’s no need to escape backslashes in a single quoted string.

Named Password/Private Key parameters must be specified in the format {PSSWD_Docker} # surrounded by quotes, as shown in bold in the following example:


params:
- string:
    name: myUserName
    value: "don.developer"
    description: My Username
steps:
- docker-login:
    username: $myUserName
    password: "{PSSWD_Docker}"

Password/Private Key parameters are specified using the format $myPassword, as shown in bold in the following example:


params:
- string:
    name: myUserName
    value: "don.developer"
    description: My Username

  - password:
      name: myPwd
      password: {PSSWD_Docker}
      # description: Defining the build password
steps:
- docker-login:
    username: $myUserName
    password: $myPwd

If you specify a field name but don’t specify a value, YAML assumes the value to be null. This can cause errors. If you don’t need to define a value for a field, you should remove the field name.

For example, if you don’t want to define Maven goals and use the default clean install, remove the goals field. The following YAML code can cause error because goals isn’t defined:
```
steps:
- shell:
    script: "echo Build Number: $BUILD_NUMBER"
- maven:
    goals: 
    pom-file: "employees-app/pom.xml"
```
You don’t need to define every one of the job’s fields in the YAML file. Just define the ones you want to configure or change from the default values, and make sure that you’re adding the parent field(s) when you define a child field:
```
steps:
- maven:
    pom-file: "employees-app/pom.xml"
```
To run a build of the job automatically when its Git repository is updated, use the auto field or set build-on-commit to true.

For the current Git repository, using auto is equivalent to setting build-on-commit to true. So, don’t use auto and build-on-commit: true together.

Here’s an example that uses auto:
```
name: MyFirstYAMLJob
vm-template: Basic Build Executor Template
auto:
  branch: patchset_1
```
If you use auto, don’t specify the Git repository URL. The job automatically tracks the Git repository where the YAML file is committed.

Here’s an example that uses build-on-commit:
```
name: MyFirstYAMLJob
vm-template: Basic Build Executor Template
git:
- url: "https://mydevcsinstance-mydomain.developer.ocp.oraclecloud.com/mydevcsinstance-mydomain/s/mydevcsinstance-mydomain_my-project_902/scm/employee.git"
  branch: patchset_1
  build-on-commit: true
```

A commit when pushed to the patchset_1 branch triggers a build of the MyFirstYAMLJob job.

To add comments in the configuration file, precede the comment with the pound sign (#):
```
steps:
# Shell script
- shell:
    script: "echo Build Number: $BUILD_NUMBER"
```
On the Builds page, to configure an existing job or a pipeline, click its Configure button or icon. If the job or the pipeline was created in YAML, VB Studio opens the YAML file in the code editor on the Git page so you can view or edit the configuration.
The branch value is dependent on the default branch of the repository that is specified in the YAML. If the head of the Git repository is main, then that is the default. If the head is master, then that will be the default.

The default behavior has been dependent on the head of the Git repository. Until this release, though, that has always been master.