Break New Ground

Using YAML for Build Configuration in Oracle Developer Cloud

Abhinav Shroff
Principal Product Manager

In the April release, we introduced support for YAML-based build configuration in Oracle Developer Cloud. This blog will introduce you to scripting YAML-based build configurations in Developer Cloud.

Before I explain how to create your first build configuration using YAML on Developer Cloud, let’s take a look at a few things.

Why do we need YAML configuration?

A YAML-based build configuration allows you to define and configure build jobs by creating YAML files that you can push to the Git repository where the application code that the build job will be building resides.

This allows you to version your build configuration and keep the older versions, should you ever need to refer back to them.  This is different from user interface-based build job configuration where once changes are saved there is no way to refer back to an older version.

Is YAML replacing the User Interface based build configuration in Developer Cloud?

No, we aren’t replacing the existing UI-based build configuration in Developer Cloud with YAML. In fact, YAML-based build configuration is an alternative to it. Both configuration methods will co-exist going forward.

Are YAML and User Interface-based build configurations interchangeable in Developer Cloud?

No, not at the moment. What this means for the user is that a build job configuration created as a YAML file will always exist as and can only be edited as a YAML file. A build job created or defined through the user interface will not be available as a YAML file for editing.

Now let’s move on to the fun part, scripting our first YAML-based build job configuration to build and push a Docker container to Docker registry.


Set Up the Git Repository for a YAML-Based Build

To start, create a Git repository in your Developer Cloud project and then create a .ci-build folder in that repository. This is where the YAML build configuration file will reside. For this blog, I named the Git repository NodeJSDocker, but you can name it whatever you want.

In the Project Home page, under the Repositories tab, click the +Create button to create a new repository.


Enter the repository Name and a Description, leave the default values for everything else, and click the Create button.



In the NodeJSDocker Git repository root, use the +File button and create three new files: Main.js, package.json, and Dockerfile.  Take a look at my NodeJS Microservice for Docker blog for the code snippets that are required for these files.

Your Git repository should look like this.


Create a YAML file in the .ci-build folder in the Git repository. The .ci-build folder should always be in the root of the repository.

In the file name field, enter .ci-build/my_first_yaml_build.yml, where .ci-build is the folder and my_first_yaml_build.yml is the YAML file that defines the build job configuration. Then add the code snippet below and click the Commit button.

Notice that the structure of the YAML file is very similar to the tabs for the Build Job configuration. The root mapping in the build job configuration YAML is “job”, which consists of “name”, “vm-template”, “git”, “steps”, and “settings”. The following list describes each of these:

  • name”: Identifies the name of the build job and must be unique within the project.
  • vm-template”: Identifies the VM template that is used for building this job.
  • git”: Defines the Oracle Developer Git repository url, branch, and repo-name.
  • steps”:  Defines the build steps. In YAML, we support all the same build steps as we support in a UI-based build job.


In the code snippet below, we define the build configuration to build and push the Docker container to DockerHub registry. To do this, we need to include the Docker Login, Docker Build, and Docker Push build steps in the steps mapping.


For the Docker Login step, you’ll need to include your password. However, storing your password in plain text in a readable file, such as in a YAML file, is definitely not a good idea. The solution is to use the named password functionality in Oracle Developer Cloud.

To define a named password for the Docker registry, we’ll to click Project Administration tab in the left navigation bar and then the Build tile, as shown below.


In the Named Password section, click the +Create button.


Enter the Name and the Password for the Named Password. You’ll refer to it in the build job. Click the Create button and it will be stored.

You’ll be able to refer this Named Password in the YAML build job configuration by using #{DOCKER_HUB}.


docker-build: Under source, put DOCKERFILE and, if the Dockerfile does not reside in the root of the Git repository, include the mapping that defines the path to it. Enter the image-name (required) and version-tag information.

docker-push: You do not need the registry-host entry if you plan to use DockerHub or Quay.io. Otherwise, provide the registry host. Enter the image-name (required) and version-tag information.

**Similarly for docker-login, You do not need the registry-host entry if you plan to use DockerHub or Quay.io

  name: MyFirstYAMLJob
  vm-template: Docker
  - url: "https://alex.admin@devinstance4wd8us2-wd4devcs8us2.uscom-central-1.oraclecloud.com/devinstance4wd8us2-wd4devcs8us2/s/devinstance4wd8us2-wd4devcs8us2_featuredemo_8401/scm/NodeJSDocker.git"
    branch: master
    repo-name: origin
  - docker-login:
      username: "abhinavshroff"                                # required
      password: "#{DOCKER_HUB}"                                # required
  - docker-build:
      source: "DOCKERFILE"
        image-name: "abhinavshroff/nodejsmicroservice"         # required
        version-tag: "latest"
  - docker-push:
        image-name: "abhinavshroff/nodejsmicroservice"         # required
        version-tag: "latest"
    - discard-old:
        days-to-keep-build: 5
        builds-to-keep: 10
        days-to-keep-artifacts: 5
        artifacts-to-keep: 10

Right after you commit the YAML file in the .ci-build folder of the repository, a job named MyFirstYAMLJob will be created in the Builds tab. Notice that the name of the job that is created matches the name of the job you defined in the my_first_yaml_build.yml file.

Click the MyFirstYAMLJob link and then, on the Builds page, click the Configure button. The Git tab will open, showing the my_first_yaml_build.yml file in the .ci-build folder of the NodeJSDocker.git repository. Click the Edit File button and edit the YAML file.


After you finish editing and commit the changes, return to the Builds tab and click the Build Job link. Then click the Build Now button.


When the build job executes, it builds the Docker image and then pushes it to DockerHub.

You’ll also be able to create and configure pipelines using YAML. To learn more about creating and configuring build jobs and pipelines using YAML, see the documentation link.

To learn more about other new features in Oracle Developer Cloud, take a look at the What's New in Oracle Developer Cloud Service document and explore the links it provides to our product documentation. If you have any questions, you can reach us on the Developer Cloud Slack channel or in the online forum.

Happy Coding!

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.