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>
, whererepo-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 setDon's job
in thename
field, usename=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 setMy "final" job
in thename
field, usename=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 thegoals
field. The following YAML code can cause error becausegoals
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 setbuild-on-commit
totrue
.For the current Git repository, using
auto
is equivalent to settingbuild-on-commit
totrue
. So, don't useauto
andbuild-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 ismaster
, 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
.