Oracle Cloud Infrastructure Documentation

Build Specification

The build specification contains build steps and settings that the build pipeline uses to run a build.

The build specification is written in YAML. By default, the build specification is located in the root of your primary build source directory and is used when you run a build pipeline. The file is named as build_spec.yml or build_spec.yaml. If the build spec is not present in the root directory, then you have to provide a relative path of the file when adding the Managed Build stage.

The build specification is organized into the following sections:

  • Configuration of the build runner.
  • Setup of environment variables.
  • Input artifacts.
  • Steps to run in sequence.
  • Output artifacts.

Build Specification Syntax

version: 0.1
component: build
timeoutInSeconds: 10000
shell: bash
failImmediatelyOnError: true
env:
  variables:
    key: "value"
    key: "value"
  vaultVariables:
    key: "secret-id"
  exportedVariables:
    - variable
    - variable
    - variable

inputArtifacts:
  - name: artifact-name
    type: GENERIC_ARTIFACT
    artifactId: "artifact-ocid"
    registryId: OCID of the Artifact Registry
    path: path of the artifact in the Registry
    version: version of the artifact
    location: target-location
  - name: artifact-name
    type: STAGE_ARTIFACT
    location: target-location
  - name: artifact-name
    type: URL
    url: downloadable link
    location: target-location

steps:
  - type: Command
    name: step-name
    shell: shellType
    timeoutInSeconds: 650
    failImmediatelyOnError: true
    command: command
    onFailure:
      - type: Command
        command: |
          command
          command
        timeoutInSeconds: 400

  - type: Command
    name: step-name
    command: |
      command
      command
      command
    onFailure:
      - type: Command
        command: |
          command
        timeoutInSeconds: 400

outputArtifacts:
  - name: artifact-name
    type: artifact-type
    location: source-location
Note

sudo is not available on the build runner host. If you need superuser permissions, then run your build step as the root user.

Build Specification Parameters

Following are the build specification parameters and their details:

Parameter Description
version Mandatory. Indicates the build specification version. A missing or invalid version causes Build stage failure.

Supported value is 0.1.
component Mandatory. Indicates a particular component in DevOps. A missing or invalid value causes build failure.

Supported value is build.
timeoutInSeconds Optional. Specifies the timeout for the whole build specification file. Each 'step' can also optionally have its own timeout value.

If a value is not specified, then the default value of 8 hours is used. The maximum allowed value is 8 hours.
shell Optional. Specifies the shell to be used at the build specification global level. The value can be optionally overridden at the 'step' level.

Allowed values are /bin/sh and bash. If not specified, then the default value of bash is used.
failImmediatelyOnError Optional. Specifies whether the build must continue if any command in the step fails with a non-zero exit value. If not specified, then the default value is false and the step continues. Allowed values are true and false. OCI recommends setting the value of this attribute to true.
env

Optional. You can define custom variables. Three types of variables are supported:

  • env/variables: Optional. The key must be a string and POSIX environment variable compliant. The value can be any string. The scope of this variable is the execution of the build specification file. Any change to the value of the variable is visible in the subsequent steps. These variables are available as environment variables for all the steps inside the build specification file.

    If the value of the variable contains new line(\n) or carriage return(\r) character, then they are replaced with space in the subsequent steps.

  • env/vaultVariables: Optional. The key must be a string and POSIX environment variable compliant. The value must be an OCID of the secret from the vault. The vault and build pipeline must be of the same tenancy. The tenancy must have an appropriate policy to allow build pipeline resources to access the secret.

    The scope of this variable is the execution of the build specification file and is available to all the steps in the file. The value for these variables is retrieved from the vault and made available as environment variables for all the steps inside the build specification file.

  • env/exportedVariables: Optional. A list of variables can be declared here. The name of the variable must be a string and POSIX environment variable compliant. The value can be assigned in any of the steps inside the build specification file. The scope of this variable is the build pipeline. Any exported variable is available in subsequent stages of the same pipeline.
inputArtifacts

Optional. Used to define a list of input artifacts that are required for running the current Build stage.

Supports the following types of input artifacts:
  • Artifacts from any of the previous build stages.
  • Artifacts from any external downloadable HTTP URL.
  • Generic artifacts from Artifact Registry.

The parameters are as follows:

  • inputArtifacts/*/url: Optional. The input artifact external downloadable HTTP URL must be provided. The URL must be publicly available. Currently authentication/authorization is not supported.
  • inputArtifacts/*/name: Mandatory. If the URL is not present, then this name is used to search for the artifacts produced by the previous Build stages in the same pipeline. Hence, the outputArtifacts/name and inputArtifacts/name must match to consume a specific artifact produced by the previous Build stage in the pipeline.
  • inputArtifacts/*/location: Mandatory. A destination path of the local file system where the input artifact needs to be downloaded. The path can be specified in one of these methods:
    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • Relative path from project home, pom.xml

    With any one of the values, the input artifact is downloaded to the primary source home directory with a file name, pom.xml.

    Location does not support exportedVariables or pipeline variables.

  • inputArtifacts/*/type: Mandatory. The type of the input artifact that has to be downloaded. Allowed values are URL, STAGE_ARTIFACT, and GENERIC_ARTIFACT.
  • inputArtifacts/*/artifactld: Mandatory. The OCID of the artifact. If you have provided the OCID, then the build pipeline ignores the registryId, path, and version.
  • inputArtifacts/*/registryld: Mandatory. The OCID of the Artifact Registry.
  • inputArtifacts/*/path: Mandatory. The destination path of the artifact.
  • inputArtifacts/*/version: Mandatory. The version of the artifact.
Note

For GENERIC_ARTIFACT type of input artifact, you can provide as a mandatory parameter either OCID of the artifact or a combination of registry ID, path, and artifact version.
steps

Mandatory. This section defines a list of steps that need to be run.

  • steps/*/type: Mandatory. Specifies the type of the step. Supports the following values: Command, VulnerabilityAudit. For more information, see Step Types.
  • steps/*/name: Optional. A user-friendly name for the step.
outputArtifacts

Optional. Specifies the artifacts produced by the Build stage. The artifacts produced as output in this section are saved for the lifetime of the current build run. They can be used in the subsequent stages in the build pipeline.

  • outputArtifacts/*/name: Mandatory. The name can contain lowercase letters (a-z), uppercase letters (A-Z), underscore (_), and hyphens (-). The name is the unique identifier for the output artifact. In the subsequent stages of the build pipeline, name is used to identify an artifact.
  • outputArtifacts/*/type: Mandatory. Allowed values are BINARY and DOCKER_IMAGE.

    BINARY: Specifies binary files as output artifacts.

    outputArtifacts/*/location: A source path of the local file system where the output artifact can be found. The path can be specified in either of these methods (assume that the pom.xml file is present in the primary source home directory):

    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • Relative path from project home, pom.xml

    If the file is not found in the provided location, then the Build stage fails.

    DOCKER_IMAGE: Specifies a Docker image as the output artifact.

    outputArtifacts/*/location: A built Docker image tag that is built on one of the steps in the build specification file.

    For example, if in any one of the steps in the build specification file, a Docker image is built as, docker build -t iad.ocir.io/id204we8d65n/hello-world:1.0, then the location field must contain iad.ocir.io/id204we8d65n/hello-world:1.0 for producing this artifact.

    The image must be built or pulled and made available in one of the build specification steps. Otherwise, the outputArtifact step fails and eventually the Build stage also fails.

    Location does not support exportedVariables or pipeline variables.

Step Types

Command

Attribute name Description
command Both single line and multiple line commands are supported. All the commands specified in one step are run in the same shell session. Based on the steps/*/shell value, commands can either be shell or bash.

Fail fast is not enabled. For the step to be successful, output of the last command in a step is considered. If the last command exit code is 0, then the step is considered as successful.
timeoutInSeconds (Optional) Specifies the timeout for the step. If not provided, then the value is inherited from the global timeoutInSeconds parameter. The maximum allowed value is 8 hours.
shell (Optional) Specifies the shell type of the current step. If not specified, then the value is inherited from the global shell parameter. Allowed values are /bin/sh and shell.
onFailure (Optional) A list of steps that must be run on failure to gracefully exit the build stage. Run if the corresponding step fails, and after execution, the build specification is exited.

Handling the failure does not affect the status of the build stage. If any one of the steps fails, then the build stage status remains failed, although handled using the onFailure block.
failImmediatelyOnError (Optional) Specifies whether the build must continue if any command in the step fails with a non-zero exit value. If not specified, then the default value is false and the step continues. Allowed values are true and false. OCI recommends setting the value of this attribute to true.

The failImmediatelyOnError attribute value defined under steps takes precedence over the same attribute value defined outside the steps.

Vulnerability Audit

A vulnerability audit describes the vulnerabilities of your application and its dependencies. When you run a build using the OCI DevOps service, you can initiate a code scan for a new commit to the code repository. The vulnerability audit happens in the Managed Build stage.

In the build spec file, a vulnerability audit step of type VulnerabilityAudit is added, which the DevOps build pipeline uses during the build run for code scan. The attributes of this step are listed as follows:

Attribute name Description Parametrized value support
name (Optional) Name of the step. N/A
vulnerabilityAuditName (Optional) Name of the vulnerability audit resource. Yes
vulnerabilityAuditCompartmentId (Optional)

Defaults to knowledgeBaseCompartmentId

 OCID of the compartment where audit resource needs to be created. Yes
knowledgeBaseId (Mandatory) OCID of the placeholder/tag for maintaining vulnerability audit resource details. Parent resource of the vulnerability audit resource. Yes
configuration/buildType (Mandatory) Build tool type. N/A
configuration/pomFilePath (Mandatory) Location of the pom.xml file. Yes
configuration/packagesToIgnore (Optional) List of Java packages to ignore when calculating the scan result while doing the vulnerability audit. N/A
configuration/maxPermissibleCvssV2Score (Optional)

Defaults to 0.0

 Maximum v2 CVSS score, which is permissible for vulnerability audit. Anything above this configuration must mark the build as Failed. N/A
configuration/maxPermissibleCvssV3Score (Optional)

Defaults to 0.0

 Maximum v3 CVSS score, which is permissible for vulnerability audit. Anything above this configuration must mark the build as Failed. N/A
freeFormTags (Optional) Accepts key-value pair. N/A

Predefined System Variables

DevOps provides a set of predefined system variables with default values that you can use such as environment variables in the build specification.

Variable Description
OCI_STAGE_ID The OCID of the current stage.
OCI_PIPELINE_ID The OCID of the current build pipeline.
OCI_BUILD_RUN_ID The OCID of the current build run.
OCI_TRIGGER_COMMIT_HASH Commit hash of the current trigger.
OCI_TRIGGER_SOURCE_BRANCH_NAME Branch that triggers the build.
OCI_TRIGGER_SOURCE_URL Repository URL that triggered the build
OCI_TRIGGER_EVENT_TYPE Trigger that started the event.
OCI_PRIMARY_SOURCE_DIR Default working directory of the build (primary source working directory).
OCI_WORKSPACE_DIR Working directory value. Contains /workspace as the default value.
${OCI_WORKSPACE_DIR}/<source-name> Build source directory path.

source-name is the name of the build source given by the user while creating the Build stage.
OCI_BUILD_STAGE_NAME Build stage name.
OCI_PRIMARY_SOURCE_NAME Primary build source name.
OCI_PRIMARY_SOURCE_COMMIT_HASH Primary build source commit hash used in the current build run.
OCI_PRIMARY_SOURCE_URL Primary build source URL.
OCI_PRIMARY_SOURCE_BRANCH_NAME Primary build source branch used in the current build run.

Build Specification Examples

Example 1:

version: 0.1             
component: build
timeoutInSeconds: 1000
shell: bash           

steps:
  - type: Command
    name: "Build app"
    command: |
      mvn clean install

Example 2:

version: 0.1
component: build
timeoutInSeconds: 6000
shell: bash
failImmediatelyOnError: true
env:
  exportedVariables:
    - BuildServiceDemoVersion

steps:
  - type: Command
    name: "Build Source"
    timeoutInSeconds: 4000
    failImmediatelyOnError: true
    command: |
      echo $PATH
      mvn clean install
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer"
    command: |
      BuildServiceDemoVersion=`echo ${OCI_BUILD_RUN_ID} | rev | cut -c 1-7`
      echo $BuildServiceDemoVersion
      docker build -t build-service-demo

  - type: VulnerabilityAudit
    name: "Scan my maven repo"
    vulnerabilityAuditName: Report-${buildRunId}
    vulnerabilityAuditCompartmentId: ocid1.compartment.oc1.iad.restoftheocid
    knowledgeBaseId: ocid1.knowledgebase.oc1.iad.restoftheocid
    configuration:
      buildType: maven
      pomFilePath: ./pom.xml
      packagesToIgnore:
        - "oracle.jdbc.*"
        - "org.apache.logging.log4j:1.2"
      maxPermissibleCvssV2Score: 5.0  
      maxPermissibleCvssV3Score: 5.1
      freeFormTags:
                  key1: value1
                  key2: value2

outputArtifacts:
  - name: build-service-demo
    type: DOCKER_IMAGE
    location: build-service-demo
  - name: build-service-demo-kube-manifest
    type: BINARY
    location: deployment/app.yml

Example 3:

version: 0.1
component: build
timeoutInSeconds: 6000
shell: bash

# Variables
env:
  variables:
    "testEnv" : "testValue1"
  vaultVariables:
    docker_registry_password : <secret-ocid>
  exportedVariables:
    - patch_number
    - build_Result

inputArtifacts:
  - name: hello-dev-jar 
    type: STAGE_ARTIFACT
    location: /workspace/Source/hello123.class
  - name: public-artifact
    type: URL
    url: https://raw.githubusercontent.com/apache/kafka/trunk/README.md  #URL must be publicly accessible
    location: /workspace/Source/readme.md
  - name: shell_script
    type: GENERIC_ARTIFACT
    artifactId: ocid1.genericartifact.oc1.iad.0.restoftheocid #appropriate policy is required for access
    location: /workspace/Source/script.sh
  - name: shell_script
    type: GENERIC_ARTIFACT
    registryId: ocid1.artifactrepository.oc1.iad.0.restoftheocid #appropriate policy is required for access
    path: some_script.sh
    version: 2.0
    location: /workspace/Source/script.sh

steps:
  - type: Command
    name: "Build Source"
    timeoutInSeconds: 4000
    shell: /bin/sh
    command: |
      # oci cli pre configured with build pipeline resource principal
      oci os ns get
      javac HelloWorld.java
    onFailure:
      - type: Command
        timeoutInSeconds: 400
        shell: /bin/sh
        command: |
          echo "Handling Failure"
          build_result=FAILURE
          echo "Failure successfully handled"
        timeoutInSeconds: 400
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer & Test"
    command: |
      docker build -t test-image .
    onFailure:
      - type: Command
        command: |
          echo "Handling Failure"
          build_result=FAILURE
          echo "Failure successfully handled"
        timeoutInSeconds: 400
  - type: Command
    timeoutInSeconds: 400
    name: "Dockerizer & Test"
    command: |
      build_result=SUCESS
      patch_number==`echo ${OCI_BUILD_RUN_ID} | rev | cut -c 1-7`
        
outputArtifacts:
  - name: kube-manifest
    type: BINARY
    location: ${OCI_WORKSPACE_DIR}/Source/app.yml
  - name: hello-dev-image
    type: DOCKER_IMAGE
    location: test-image
Note

To build high-performance Java applications, you can use Oracle GraalVM in the build pipeline. To install and use Oracle GraalVM in the DevOps build pipeline, you have to update your build specification file. For more information and examples, see Using Oracle GraalVM in DevOps Build Pipelines.