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 the 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 isn't present in the root directory, then you must 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
sudo
isn't 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
|
component |
Mandatory. Indicates a particular component in DevOps. A missing
or invalid value causes build failure. Supported value is
|
timeoutInSeconds |
Optional. Specifies the timeout for the whole build specification file. Each 'step' can also optionally have its own timeout value. If a value isn't 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 |
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:
|
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:
The parameters are as follows:
Note: For |
steps |
Mandatory. This section defines a list of steps that need to be run.
|
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.
|
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 doesn't affect the status of the build stage. If any one of the steps fails, then the build stage status remains |
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 |
Vulnerability Audit
A vulnerability audit describes the vulnerabilities of the application and its dependencies. When you run a build using the OCI DevOps service, you can start 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
|
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.
|
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=SUCCESS
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
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 must update the build specification file. For more information and examples, see Using Oracle GraalVM in DevOps Build Pipelines.