Managing Project Jobs, Builds, and Pipelines

Oracle Developer Cloud Service includes continuous integration services to build project source files.

The Build page, also called as the Jobs Overview page, displays information about all build jobs of the project and provides links to configure and manage them.

What is a Job, a Build, and a Pipeline?

A Job is a configuration that defines the software builds of your software application.

The Oracle Developer Cloud Service build system is pre-configured with some plugins that you can use while running builds. You can use the Oracle Developer Cloud Service build system for continuous integration and continuous delivery to Oracle Cloud services.

A Pipeline enables you to define dependencies of jobs and create a path or a chain to run builds. A pipeline helps in running continuous integration jobs and reduce network traffic.

Oracle Developer Cloud Service runs builds of jobs on Build VMs. To know more about Build VMs, see About Build VMs and Build VM Templates.

Job Status

A job can be in one of the various states including successful, failed, in progress, and aborted.

The following table describes the job status icons.

Status Icon Description

Success Success

Indicates the last build of the job was successful.

Failed Failed

Indicates the last build of the job failed.

In Progress In Progress

Indicates a build of the job is in progress.

Aborted Aborted

Indicates the last build of the job was aborted.

Unstable Unstable

Indicates the last build of the job was unstable.

Pending Pending

Indicates a build of the job has not run and is pending.

Disabled Disabled

Indicates builds of the job have been disabled.

Job Stability

The stability of a job is indicated by an icon in the Weather column of the Jobs table in the Jobs tab.

The following table describes the job stability weather icons in the Jobs table.

Weather Icon Description

Build stability 0%–20% Build stability 0%–20%

Indicates the build stability of the job is between 0% and 20%.

Build stability 20%–40% Build stability 20%–40%

Indicates the build stability of the job is between 20% and 40%.

Build stability 40%–60% Build stability 40%–60%

Indicates the build stability of the job is between 40% and 60%.

Build stability 60%–80% Build stability 60%–80%

Indicates the build stability of the job is between 60% and 80%.

Build stability 80%–100% Build stability 80%–100%

Indicates the build stability of the job is between 80% and 100%.

Managing and Configuring Jobs

You can create, manage, and configure jobs from the Jobs tab of the Build page.

Creating a Job

To run builds and generate artifacts that you can deploy, you must create a job. You can create a job from the Build page.

To create a job:
  1. In the navigation bar, click Build.
  2. Click the Jobs tab, if necessary.
  3. Click + New Job.
  4. In the New Job dialog, enter a unique name and description.
  5. Select the Use for Merge Request check box if you want to link this job with a merge request.
    The merge request parameters are automatically enabled for the job.
  6. To create a blank job, select Create New. To create a job with configuration copied from another job, select Copy existing job.
    From the From Job drop-down list, select the job whose parameters you want to copy to the new job. After the job is created, you can then change the parameters of the new job.
  7. In Software Template, select the Build VM template.
  8. Click Create Job.
  9. In the Configure Build Job page, specify the configuration options and click Save.

Viewing a Job’s Details

Click the job name in the Jobs Overview page to view its details.

The Job Details page displays the job build history, build trend, and links to various pages that show more details of the open job. You can also configure a job, enable or disable it, view build reports and history, download artifacts, and delete a job.

Configuring a Job

From the Configure Build Job page, you can configure or edit a job so that when the job is built, it will perform the specified tasks. The tasks may include enabling and disabling builds, discarding old builds, configuring parameters for the build, and configuring Git repositories for the builds.

The Configure Build page is categorized into two categories, where each category is divided into various tabs for the configuration settings of the job and its builds.

Tab Description

Build Configuration Build Configuration

Configure the job to use and set source control, build parameters, build environment, builders (or build steps), and post build options.

Job Settings Job Settings

Configure the settings, such as general settings, software settings, build triggers, and advanced options of the job.

Configuring the Source Code Management System for Builds

Use the Source Control tab in the Configure Build Job page to use project Git repositories when a build runs.

To configure Git source control:

  1. Open the Configure Build Job page of the job.

  2. Click Primary Settings Primary Settings, if necessary.

  3. Click the Source Control tab.

  4. Click the Add Source Control list and select the Git option.

  5. In Repository , select the Git repository.

    While creating the job, if you selected the Use for Merge Request check box in the New Job dialog, the field will be automatically populated with the${GIT_REPO_URL} value.

  6. Expand Advanced Repository Options to configure the advanced options for the selected Git repository.

    Element Description

    Name

    Enter the unique remote name of the repository. Leave the field empty to use the default remote name origin of the repository.

    Ref spec

    Specify the reference specification of the repository. This is an optional field.

    Leave the field empty to create a default reference specification.

    Local Checkout Directory

    Specify a local directory where the Git repository will be checked out. If left empty, the workspace root itself will be used.

  7. In Branch, select the branch name of the repository that you want to track. By default, master is set.

    While creating the job, if you selected the Use for Merge Request check box in the New Job dialog, the field will be automatically populated with the${GIT_REPO_BRANCH} value.

  8. Select the Automatically perform build on SCM commit check box if you want run a build on every push to the project Git repository.

    The builds do not run automatically for external Git repositories. To run automatic builds of external Git repositories, enable SCM polling. See Configuring SCM Polling Triggers.

  9. Expand the Advanced Git Settings to configure the advanced options for the Git repository.

    Element Description

    Included Region

    Enter the list of files and directories that will be tracked for changes in the SCM. If a change occurs in any of the specified files or directories, a build is triggered automatically.

    Each inclusion uses regular expression pattern matching, and must be separated by a new line. An empty list implies that all files and directories will be tracked.

    For example, the following list illustrates that a build will be triggered when any HTML, JPEG, or GIF file is committed to the /main/web/ directory in the SCM.

    myapp/src/main/web/.*\.html

    myapp/src/main/web/.*\.jpeg

    myapp/src/main/web/.*\.gif

    Excluded Region

    Enter the list of files and directories that will not be tracked for changes in the SCM. If a change occurs in any of the specified files or directories, a build will not run.

    If there is an overlap between included and excluded regions, exclusions take precedence over inclusion.

    Excluded User

    Enter the list of users whose commits to the SCM will not trigger builds.

    You can use literal pattern matching and users must be separated by a new line.

    Merge another branch

    Specify the branch name to merge to. If specified, checkout the revision to build as HEAD on this branch.

    Checkout revision

    If Merge another branch is specified, checkout the specified revision to build as HEAD on the value of Merge another branch.

    Config user.name

    Enter a user name value for the Git user.name variable.

    Config user.email

    Enter the user’s email address for the Git user.email variable.

    Merge from another repository

    Select the check box to perform a merge to a particular branch before running a build.

    • Repository: Enter or select the name of the repository to be merged.

    • Branch: Enter or select the name of the branch to be merged. If no branch is specified, the default branch of the repository is used.

    The build runs only if the merge is successful.

    Prune remote branches before build

    Select the check box to run the git remote prune command for each remote to prune obsolete local branches before running a build.

    Skip internal tag

    Selected by default to skip the internal tag. By default, a tag is applied to the local repository after the code is checked out. Deselect the check box to not to skip the internal tag.

    Clean after checkout

    Select the check box to run the git clean -fdx command after every checkout to ensure a clean build.

    Recursively update submodules

    Select the check box to retrieve all sub-modules recursively.

    Use commit author in changelog

    Select the check box to use the commit's Author value in the build's changesets. By default, the commit's Committer value is used.

    Git creates a changeset every time you do a checkin. All the files that are checked in together are included in the changeset.

    Wipe out workspace before build

    Select the check box to delete the contents of the workspace before running a build.

  10. Click Save.

You can specify multiple Git repositories for the job and then configure the job to access the files in the repositories. Note that if you specify more than one Git repository, the Local Checkout Directory field of the first Git repository can remain empty, but it must be set for other Git repositories.

Configuring Build Parameters

Using Build Parameters, you can pass additional information when a build runs that is not available at the time of job configuration.

When a build runs, a Enter Build Parameters dialog box opens where the user can enter or change the default values of the specified parameters.

You can add following types of build parameters to a job:

Parameter Type Description

Boolean

Appears as a check box and accepts true or false as its value. The parameter can be used as an environment variable or through variable substitution in other parts of the job configuration.

Choice

Appears as a drop-down list and accepts a value from the specified values. The parameter can be used during a build, either as an environment variable, or through variable substitution in some other parts of the configuration.

String

Appears as a text box and accepts a string value from the user when a build runs. The parameter can be used either as an environment variable or through variable substitution in some other parts of the configuration.

Password

Appears as a text box and accepts a password value from the user when a build runs. The value can be specified either as an environment variable or through variable substitution in some other parts of the configuration.

Merge Request

Appears as a text box and accepts a string value for the Git repository URL, the Git repository branch name, and the merge request ID as input.

To add a parameter to a build:

  1. Open the Configure Build Job page of the job.

  2. Click Primary Settings Primary Settings, if necessary.

  3. Click the Build Parameters tab.

  4. From the Add Parameter drop-down list, select the parameter type.

  5. Enter values such as name, default value, and description.

  6. Click Save.

Merge Request parameters are automatically added the Use for Merge Request check box was selected in the New Job dialog. The job configuration dialog creates three String parameters GIT_REPO_URL, GIT_REPO_BRANCH, and MERGE_REQ_ID to accept the Git repository URL, the Git repository branch name, and the merge request ID as input from the merge request respectively. The GIT_REPO_URL and GIT_REPO_BRANCH variables are automatically set in the Repository and Branch fields of the Source Control tab.

Configuring the Build Environment

Use the Build Environment tab to configure build environment options for the X virtual frame buffer (Xvfb), copy artifacts, SonarQube settings, SSH configuration, and Oracle Maven Repository.

To configure the build environment:

  1. Open the Configure Build Job page of the job.

  2. Click Primary Settings Primary Settings, if necessary.

  3. Click the Build Environment tab.

    Select the build environment from the Add Build Environment drop-down list to add the relevant section.

    You can add the following kinds of build parameters to your build:

Configuring the Build Environment to use the Xvfb Wrapper

Xvfb is an X server that implements the X11 display server protocol and can run on machines with no physical input devices or display.

Xvfb is supported on Oracle Linux 7 build VMs only.

To add the Xvfb Wrapper to the build environment:

  1. Open the Build Environment tab.

  2. Click Add Build Environment and select Xvfb Wrapper.

    The following table highlights what options you can set for the Xvfb Wrapper.

    Element Description

    Display Number

    Specify the ordinal number of the display the Xvfb server will be running on. The default value is 0. If left empty, a random number will be chosen.

    Screen offset

    Specify the offset for display numbers. The default value is 0.

    Screen Size (WxHxD)

    Specify the resolution and color depth of the created virtual frame buffer in the WxHxD format. The default value is 1024x758x24.

    Additional options

    Specify any additional Xvfb command line options. The default options are -nolisten inet6 +extension RANDR -fp /usr/share/X11/fonts/misc.

    Timeout in seconds

    Specify the timeout duration for the build to wait before returning control to the job. The default value is 0.

    Log Xvfb output

    The check box is selected by default to redirect the output of Xvfb to the job log. Deselect the check box if you do not want to redirect the output.

    Shutdown Xvfb with whole job, not just with the main build action

    The check box is selected by default to keep the Xvfb server running for post-build steps. Deselect the check box if you do not want to keep the server running.

  3. Click Save.

Configuring the Build Environment to use SonarQube

You can configure the build environment to use SonarQube, an open source quality management software that enables you to continuously analyze your application.

When configured, the build will generate an analysis summary that you can view from the job or the build details page. For more information about SonarQube, see its documentation at https://docs.sonarqube.org.
To configure SonarQube with the build environment:
  1. Open the Build Environment tab.
  2. Click Add Build Environment and select SonarQube Settings.

    The following table highlights options you can set for the SonarQube Settings.

    Element Description

    Sonar Server

    Select the pre-configured SoarQube server from the list.

    Username

    Displays your SonarQube user name.

    Password

    Displays your SonarQube SSO password.

    SonarQube Server URL

    Displays the URL of the SonarQube server.

    Advanced SonarQube Settings

     

    Project Key

    Enter or update the SonarQube project key. By default, the field is set to <organization>_<projectname>.<jobname>.

    The SonarQube project key must be unique.

    Project Name

    Enter or update the SonarQube project name. By default, the field is set to <projectname>.<jobname>.

    The SonarQubename will be displayed in the Analysis Report.

  3. Click Save.
Configuring the Build Environment to Copy Artifacts from Another Job

You can configure the build environment to copy artifacts from another build job.

To configure a build environment to copy artifacts from another job:
  1. Open the Build Environment tab.
  2. Click Add Build Environment and select Copy Artifacts.

    The following table highlights what you can set in the Copy Artifacts section.

    Element Description

    From Job

    Select the job whose artifacts you want to import.

    Which Build

    Select the build that generated the artifacts. You can choose from the following options:

    • Last Successful Build: Import artifacts from the last successful build.

    • Last keep forever build: Import artifacts from the latest build that is marked as Keep Forever.

      For more information about how to mark a build as Keep Forever, see Viewing a Build’s Details

    • Upstream build that triggered this job: Import artifacts from the upstream build.

      Select the Use last successful build as fallback check box to use the artifacts from the last successful build if an error occurs in the upstream build.

    • Specified by permalink: Import artifacts from the job specified by Permalink.

      In the Permalink list, select the desired permalink option (Last build, Last successful build, Last failed build, Last test failed build, or Last unsuccessful build).

    • Specific build: Import artifacts from the selected build number in Build Number.

      In Build Number, specify the build number of the job whose artifacts you want to copy.

    • Specified by a build parameter: Import artifacts from the build with the parameter specified in Parameter Name. By default, the value of Parameter Name is BUILD_SELECTOR.

    Artifacts to copy

    Specify the artifacts that you want to import with their relative paths. If no value is specified, all artifacts are copied. Note that the archive.zip file is never copied.

    In the Job Details page or the Build Artifacts section of the Build Details page, you can find the artifacts generated by the job.

    Target Directory

    Specify the target directory where the artifacts will be imported.

    Flatten Directories

    Select the check box to flatten the target directory structure after importing artifacts.

    Optional (Do not fail build if artifacts copy failed)

    Select the check box to not to mark the build as failed if the artifacts specified in the Artifacts to copy are not copied to the current build.

  3. Click Save.
Configuring the Build Environment to use the Oracle Maven Repository

You can configure the build environment to use and access the Oracle Maven Repository.

Before you run a build, you must accept the Oracle Maven repository license agreement at https://www.oracle.com/webapps/maven/register/license.html using your Oracle Technology Network (OTN) Single-Sign On (SSO) credentials.

To configure the Oracle Maven Repository to the build environment and to download artifacts and dependencies for your application.:

  1. Open the Build Environment tab.

  2. Click Add Build Environment and select Oracle Maven Repository Connection.

    The following table highlights what options you can set for the Oracle Maven Repository.

    Element Description

    Use Existing Connection

    The toggle button is enabled by default to use an existing and pre-configured OTN connection to connect to the Oracle Maven Repository. In the Select Connection list, select the desired connection. Disable the toggle button if you do not want to use an existing connection and want to provide your own details.

    OTN Login

    Enter your OTN SSO user name.

    The field is enabled if the Use Existing Connection toggle button is disabled.

    OTN Password

    Enter your OTN SSO password.

    The field is enabled if the Use Existing Connection toggle button is disabled.

    Server Id

    If required, enter the ID to use for the <server> element of the Maven settings.xml file. If not provided, the ID will default to maven.oracle.com.

    Custom settings.xml

    If you are using a custom settings.xml file, enter the path of the file in the project Git repository.

  3. Click Save.

Configuring the Build Environment to use SSH

You can configure a job to use SSH to access any Oracle Cloud service that has SSH enabled, such as Oracle Cloud Infrastructure Compute Classic VMs.

You can configure the job to use any of the following options, or both.
  • Create an SSH tunnel to access a process running on a remote system, including an on-premise system, via the SSH port. The SSH tunnel is created at the start of the build job and is destroyed automatically when the job finishes.

  • Set up the default ~/.ssh directory with provided keys in the build system workspace for use with the command-line tools. The modifications are reverted when the job finishes.

To configure SSH Configuration of a job:
  1. Open the Build Environment tab.
  2. Click Add Build Environment and select SSH Configuration.

    The following table highlights what options you can set for the SSH configuration.

    Element Description

    Private Key

    Enter the private key of your SSH Private-Public key pair.

    Public Key

    Enter the public key of your SSH Private-Public key pair.

    Leave the field empty to use fingerprint.

    Pass Phrase

    Enter the pass phrase of your SSH Private-Public key pair.

    Leave the field empty if keys are not encrypted with a pass phrase.

    SSH Server Public Key

    Enter the public key of the SSH server.

    If you are using command-line SSH tools require, note that the host name and the IP address must match exactly. The host name and the IP address can be comma separated. Example: ssh1.example.com,10.0.0.13 ssh-rss ... .

    Leave the field empty to skip host verification. For command-line tools like ssh the option -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null must be added explicitly to skip host verification.

    Create SSH Tunnel

    SSH tunnel provides an additional layer of security and can only be set up between trusted hosts. Select the check box to create an SSH tunnel and enter details in the following fields:

    • Username: Name of the user who can connect to the SSH server

    • Password: Password of the SSH user. Leave the field empty to use the key based authentication.

    • Local Port: Port number of the client to used for local port forwarding

    • Remote Host: Name of the remote host, or an interface on the SSH server

    • Remote Port: Port number of the remote host or interface

    • SSH Server: Name or IP address of the target SSH server

    • Connect String: Displays the connect string to be used to set up the SSH tunnel

    Setup files in ~/.ssh for command-line ssh tools

    To use command line tools such as ssh, scp, or sftp, select the check box. When a build runs, necessary files with the information that you have provided are created for you in the known_hosts file of the ~/.ssh directory in the build system workspace. The files are removed automatically after the build is complete.

  3. Click Save.

Configuring Build Steps

Use the Builders tab in the Configure Build Job page to configure various types of build steps that can then be incorporated in the build.

To configure the build steps:

  1. Open the Configure Build Job page of the job.

    See Configuring a Job.

  2. Click Primary SettingsPrimary Settings, if necessary.

  3. Click the Builders tab.

  4. Click Add Build Step and choose the desired build step.

    The following table highlights what you can set from the Add Build Step menu of the Build Steps tab.

    Element Reference

    Unix Shell Builder

    See Adding an Unix Shell Builder.

    Ant Builder

    See Adding an Ant Builder.

    Maven Builder

    See Adding a Maven Builder.

    Gradle Builder

    See Adding a Gradle Builder.

    Node.js Builder

    See Adding a Node.js Builder.

    SQLcl Builder

    See Adding a SQLcl Builder.

    PSMCli Builder

    See Adding a PSMcli Builder.

    OCICli Builder

    See Adding a OCIcli Builder.

    Docker Builder

    See Adding a Docker Builder.

  5. Click Save.

To remove the section, on the right side of the section header, click the Remove icon. To move the section, mouse over the section title, and then drag-and-drop it above or below another section.

Adding an Unix Shell Builder

You can use the Unix shell builder to run a shell script for building the job.

To add and configure Unix Shell Builder:

  1. Open the Builders tab.

    See Configuring Build Steps.

  2. Click Add Builder and select Unix Shell Builder.

    The following table highlights what you can set in the Unix Shell Builder section.

    Element Description

    Script

    Enter the contents of your shell script. This is a required field.

    The script runs with the workspace as the current directory. If there is no header line such as #!/bin/sh — in your shell script, then the shell configured system-wide will be used, but you can also use the header line to write a script in another language (such as #!/bin/perl) or control the options that shell uses.

    By default, the shell is invoked with the -ex option. All commands are printed before they run, and the build is considered a failure if any of the commands exits with a non-zero exit code. You can change this behavior by adding the #!/bin/... line.

    Tip: Do not enter a long shell script in this field. For a long script, create a script file and add it in the SCM. You can run the script with a command (such as bash -ex myscript.sh) and track changes in your shell script.

    You can also use Kubernetes, PSMcli, Docker, Terraform, Packer, and OCIcli commands in the Shell script. Make sure that you have the required software in the job’s Build VM template before you run a build.

    If both Python 2 and Python 3 are available in the job’s Build VM template, then to invoke Python 2 use python (or python2). To invoke Python 3, use python3. To invoke pip of Python 2, use pip. To invoke pip of Python 3, use pip3.

    Command print option

    Select the Expand variables in commands, don’t show I/O redirection (-x) option to show the values of the variables and hide the input-output redirection in the command log.

    Select the Show commands exactly as written (-v) option to show the command as it is in the log.

  3. Click Save.

Adding an Ant Builder

You can use the Ant Builder option to use Ant as the build system. When the build runs, Ant is invoked with the given targets and options. Any non-zero exit code marks the build as a failure.

To add and configure Ant Builder:

  1. Open the Builders tab.

    See Configuring Build Steps.

  2. Click Add Builder and select Ant Builder.

    The following table highlights what you can set in the Ant Builder section.

    Element Description

    Targets

    Specify a list of Ant targets to be invoked, or leave it empty to invoke the default Ant target specified in the build script. You can also use this field to specify other Ant options.

    Build File

    If your build requires a custom -buildfile, specify it here. By default, Ant will use the build.xml in the root directory; this option can be used to use build files with a different name or in a subdirectory.

    Properties

    Properties needed by your Ant build can be specified here (in standard properties file format):

    # comment
    name1=value1
    name2=$VAR2

    These are passed to Ant like -Dname1=value1 -Dname2=value2. Always use $VAR style for parameter references (do not use %VAR% style, even when the build runs on Windows). Slashes are used for escaping, so use \\ for a single slash. Avoid double quotes (") because Ant on UNIX wraps parameters in quotes and runs them through eval, and Windows has its own issues with escaping. In either case, the use of quotes may result in a build failure. To define an empty property, simply write varname=.

    Java Options

    If your build requires a custom ANT_OPTS, specify it here. Typically this may be used to specify Java memory limits to use, for example -Xmx512m. Note that other Ant options (such as -lib) should go to the Targets field.

  3. Click Save.

Adding a Maven Builder

You can use Maven Builder to use Maven as the build system. When a build runs, Maven is invoked with the given goals and options. A non-zero exit code marks the build as a failure. Some Maven versions have a bug that causes Maven not to return the exit code correctly.

To add and configure Maven Builder:

  1. Open the Builders tab.

    See Configuring Build Steps.

  2. Click Add Builder and select Maven Builder.

    The following table highlights what you can set in the Maven Builder section.

    Element Description

    Goals

    (Required) Enter Maven goals, or phases, along with their options.

    By default, clean and install goals are added.

    For more information about Maven goals, see the Maven Lifecycle Reference documentation at http://maven.apache.org.

    POM File

    Enter the Maven POM file name and location, relative to the workspace root. The default value is pom.xml at the Git repository root.

    Turn On SonarQube

    Select the check box to create SonarQube analysis reports for the job’s builds.

    Advanced Maven Settings

    Expand to configure advanced options for the Maven builder.

    Use Private Repository

    Select the check box to use a private repository for builds.

    Use Private Temp Directory

    Select the check box to use a private temporary directory for builds.

    Offline

    Select the check box to work offline.

    Show Errors

    Select the check box to produce execution error detail messages.

    Recursive

    Indicates that all sub-modules will build recursively. The check box is selected by default.

    Profiles

    Enter the list of profiles to activate. The list can be comma or space separated. This is an optional field.

    For more information about Maven profiles, see the Maven documentation at http://maven.apache.org.

    Properties

    Enter custom system properties in the key=value format.

    Verbosity

    Select the Maven verbosity level from the list. You can select the level as NORMAL (default), QUIET, or DEBUG.

    Checksum

    Select the checksum handling mode from the list. You can select the mode as NORMAL (default), STRICT, or LAX.

    Snapshot

    Select how SNAPSHOT artifact updates are handled. You can select the handling mode as NORMAL (default), FORCE, or SUPPRESS. This is an optional field.

    Projects

    Enter the list of Maven project jobs to include in the reactor. The reactor is a mechanism in Maven that handles multi-module projects. This is an optional field.

    A project job can be specified by [groupId]:artifactId or by its relative path. The list can be comma or space separated.

    Resume From

    Enter the Maven job project name from where you would like to resume the reactor. The Maven job project can be specified by [groupId]:artifactId or by its relative path.

    Fail Mode

    Select the failure handling mode from the list. You can select the handling mode as NORMAL (default), AT_END, FAST, or NEVER. This is an optional field.

    Make Mode

    Select the Make-like reactor mode from the list. You can select the mode as NONE (default), DEPENDENCIES, DEPENDENTS, or BOTH.

    Threading

    Enter the configuration of the reactor threading model.

    JVM Options

    Enter the parameters to be passed to the Java VM when running Maven via the MAVEN_OPTS environment variable.

  3. Click Save.

Adding a Gradle Builder

You can use Gradle Builder to use Gradle as the build system. When a build runs, Gradle is invoked with the given goals and options. A non-zero exit code marks the build as a failure.

For more information about Gradle, see https://gradle.org/.
To configure a Gradle Builder:
  1. Open the Builders tab.
  2. Click Add Builder and select Gradle Builder.

    The following table highlights what you can set in the Gradle Builder section.

    Element Description

    Gradle

    Select Invoke From (default) to invoke the default Gradle script to run builds.

    Select Use wrapper to use the specified Gradle wrapper script to run builds.

    • Select the Make gradlew executable check box to make the gradlew command as an executable command.

    • Select the From Root Build Script Dir check box to use the gradlew command from the root build script directory.

    Tasks

    Enter Gradle tasks to be invoked. The default tasks are clean build.

    Build file

    Enter the name of the Gradle build file if it is not named as build.gradle.

    Build file folder

    Enter the path and directory name of the top-level build.gradle file if it is available in a directory other than the module root directory. The specified path must be relative the module root directory.

    If left empty, the path defaults to build.gradle in the root directory.

    Switches

    Enter Gradle switches to be invoked.

    Force GRADLE_USER_HOME to use workspace

    If you are using a multi-executor slave, select the check box to set the GRADLE_USER_HOME to the workspace and avoid collisions while accessing Gradle cache.

    By default, GRADLE_USER_HOME is set to $HOME/.gradle.

  3. Click Save.

To view the dependency information of an artifact, see Using the Project Maven Repository.

Note:

To download the external dependencies during a build, configure the proxy settings using the Gradle proxy configuration. See https://docs.gradle.org/current/userguide/build_environment.html.
Adding a Node.js Builder

You can add a Node.js builder that invokes a Node.js script when the build runs.

To configure a builder to invoke a Node.js script:
  1. Open the Builders tab.
  2. Click Add Builder and select Node.js Builder.

    The following table highlights what you can set in the Node.js Builder section.

    Element Description

    Source

    Select NodeJS File to specify a NodeJS file in the Git repository. Select Script to enter the NodeJS script manually. The Script option is selected by default.

    NodeJS File Path

    Enter the path of the Node.js script file that you want to run. You can copy the path of the file from the Code page. The field is available if you selected NodeJS File as Source.

    NodeJS Script

    Enter the Node.js script code that you want to run. The field is available if you selected NodeJS File as Source. The field is available if you selected Script as Source.

    If you have the Node.js code in a snippet file, you can copy the code using the context menu Insert from Snippet option.

    Note:

    You can view the Node.js version from the Software tab. See Configuring Build Software.
  3. Click Save.
Adding a SQLcl Builder

You can add a SQLcl builder that invokes SQL statements on an Oracle Database when the build runs.

SQLcl requires JDK 1.8 or later. Make sure that the job configuration is configured to use Java SE 8 (or later) version.

You can use the SQLcl builder to access any Oracle Database that you can connect to using a JDBC connect string. You can run DML, DDL, and SQL Plus statements. You can also use the SQLcl build step in a test scenario to run SQL scripts to initialize seed data or validate database changes. To know more about SQLcl, see http://www.oracle.com/technetwork/developer-tools/sqlcl/overview/index.html.

Also see Using the help command in SQLcl in Using Oracle Database Exadata Express Cloud Service and the SQL Developer Command-Line Quick Reference documentation to know more about using SQLcl supported commands.

To configure a builder to invoke SQL statements:
  1. Open the Builders tab.
  2. Click Add Builder and select SQLcl Builder.

    The following table highlights what you can set in the SQLcl Builder section.

    Element Description

    Username

    Enter the user name of the Oracle Database account.

    Password

    Enter the password of the Oracle Database account.

    Credentials File

    Enter the workspace path of the uploaded credentials zip file required to connect to Oracle Database Exadata Express Cloud Service.

    You can download the credentials zip file from the Oracle Database Exadata Express Cloud Service service console. See Downloading Client Credentials in Using Oracle Database Exadata Express Cloud Service.

    Connect String

    Enter the JDBC or HTTP connection string of the Oracle Database account using any of the host_name:port:SID or host_name:port/service_name formats.

    JDBC Example: test_server.us.oracle.com:1521:adt1100 where adt1100 is the SID, and test_server.us.oracle.com:1521/ora11g where ora11g is the service name.

    HTTP Example: http://test_server.us.oracle.com:8085/ords/demo

    Source

    Select SQL File if the SQL statements are in a file uploaded to the project Git repository.

    Select Inline SQL to specify the SQL statements.

    SQL File Path

    If you selected SQL File in Source, enter the path of the SQL file in the Git repository. You can copy the file’s path from the Code page.

    SQL Statements

    If you selected Inline SQL in Source, enter the SQL statements in the code editor.

    Role

    Select the database role of the user. By default, it is set to Default.

    Restriction Level

    Specify the restriction level on the type of SQL statements that are allowed to run. By default, it is set to Default.

  3. Click Save.

When a build runs, your Oracle Database credentials are stored in an Oracle Wallet. Check the build’s console for the SQL output or errors.

Note:

  • SQL commands that are specific to editing buffer (such as set sqlformat csv) or editing console are not supported.

  • You can use build parameters in Username, Password, Connect String, and SQL Statements fields. See Configuring Build Parameters.

  • You cannot use build parameters in the SQL file.

  • If you are using Oracle REST Data Services (ORDS), some SQLcl commands, such as the BRIDGE command, would require a JDBC URL.

    Example: BRIDGE table1 as "jdbc:oracle:thin:DEMO/demo@http://examplehost.com/ords/demo"(select * from DUAL);

Adding a PSMcli Builder

You can add a PSMcli builder that invokes Oracle PaaS Service Manager command line interface (CLI) commands when the build runs.

You use PSMcli commands to manage the lifecycle of various services in Oracle Public Cloud. For more information about PSMcli and its commands, see About the PaaS Service Manager Command Line Interface in PaaS Service Manager Command Line Interface Reference.

To configure a builder to invoke PSMcli commands:
  1. Open the Builders tab.
  2. Click Add Builder and select PSMcli Builder.

    The following table highlights what you can set in the PSMcli Builder section.

    Element Description

    Username

    (Required) Enter the user name of the Oracle Cloud account.

    Password

    (Required) Enter the password of the Oracle Cloud account. The password is saved in a keystore plug-in in an encrypted format.

    Identity Domain

    (Required) Enter the identity domain.

    Region

    Select your identity domain’s region: US ("us") (default) or EMEA ("emea").

    Output Format

    Select the preferred output format: JSON ("json") (default) or HTML ("html").

    You can also use build parameters in above fields. See Configuring Build Parameters.

Tip:

To add PSM Commands, add an Unix Shell Builder (see Adding an Unix Shell Builder) and enter PSM commands as the shell commands that you want to run when the build runs. For example, you can run commands to start or stop other Oracle Cloud PaaS environments when you run the build.

After adding the Invoke PSMcli section, you can add multiple Unix Shell Builder build steps to run PSM commands and Linux commands. Enter the commands on separate lines of the Command field. No need to add the Invoke PSMcli build step again.

Adding a OCIcli Builder

You can add a OCIcli builder that invokes Oracle Cloud Infrastructure command line interface (CLI) commands when the build runs.

You use OCIcli commands to work with Oracle Cloud Infrastructure objects and services. For more information about OCIcli and its commands, see the Oracle Cloud Infrastructure Command Line Interface documentation.
To configure a builder to invoke OCIcli commands:
  1. Open the Builders tab.
  2. Click Add Builder and select OCIcli Builder.

    The following table highlights what you can set in the OCIcli Builder section.

    Element Description

    User OCID

    (Required) Enter the user’s Oracle Cloud ID (OCID).

    Every Oracle Cloud Infrastructure  resource has an Oracle-assigned unique ID called an Oracle Cloud Identifier (OCID). You can find the user OCID in the web interface of Oracle Cloud Infrastructure Console.

    Fingerprint

    (Required) Enter the fingerprint of the public key of the RSA key pair in PEM format.

    If you have not generated an RSA key pair, generate it in the PEM format, not SSH-RSA format.

    Tenancy

    (Required) Enter the tenancy OCID.

    You can find the user tenancy in the web interface of Oracle Cloud Infrastructure Console.

    Private Key

    Enter the private key of the RSA key pair in PEM format.

    Region

    Select the Oracle Cloud Infrastructure tenancy’s region.

  3. Click Save.

To add OCI Commands, add an Unix Shell Builder and enter OCI commands as the shell commands that you want to run when the build runs. For example, oci and oci iam user list. See Adding an Unix Shell Builder.

Adding a Docker Builder

You can add a Docker builder that invokes Docker commands such as login, build, and push when the build runs.

To run docker commands in a build, you must configure the job to use a Build VM template with the Docker software. See Configuring a Job. For more information about Docker commands, see https://docs.docker.com/.

Tip:

  • You should use the Docker container for short tests and builds. Do not run a Docker container for long tests or builds, else the builds might not finish. For example, a Docker image that is listening on a certain port and behaves like a web server, the build will never exit.

  • If you face any network issue while running a Docker command, it is recommended to add the HTTP_PROXY and HTTPS_PROXY environment variables into the Docker file. See About the Build Executor Environment Variables.

To configure a builder to invoke Docker commands:
  1. Open the Builders tab.
  2. Click Add Builder, select Docker, and then select the desired command.
    • login

    • build

    • tag

    • push

    • images

    • save

    • load

    • rmi

    • version

  3. Click Save.

The following sections describe the available Docker commands:

Docker login command

You use the login command to log in to the registry. The following table highlights the fields of the Docker login command section.

Element Description

Registry Host

Select a pre-linked Docker registry, or enter the host name of the registry where Docker images are stored.

If left empty, Docker Hub is set as the default registry host.

If you are a project Owner, click + Link External Registry to link an external Docker registry. See Adding a Link to an External Docker Registry.

Username

(Required) Enter the registry login user name.

If you select a pre-linked docker registry, its username is automatically filled in.

Password

(Required) Enter the registry login user password.

If you select a pre-linked docker registry, its password is automatically filled in.

Note:

The Docker logout command runs automatically after all Docker commands have run.

Docker build command

You use the build command to build Docker images from a Dockerfile. The following table highlights the fields of the Docker build command section.

Element Description

Registry Host

(Required) Select a pre-linked Docker registry, or enter the host name of the registry where Docker images are stored.

If left empty, Docker Hub is set as the default registry host.

Image Name

Enter the Docker image name.

Version Tag

Enter the version tag name of the Docker image. The tag name must start with a letter or a number.

Full Image Name

Displays the complete Docker image name in the <registry_host/image_name:version_tag> format.

Options

Enter the Docker build command options.

For more information, see https://docs.docker.com/engine/reference/commandline/build/.

Source

(Required) Specify the source of the Dockerfile.

  • Select Context Root in Workspace (default) if the Dockerfile is available in the build’s workspace.

  • Select Dockerfile Text if you want to enter the contents of the Dockerfile manually.

  • Select Remote Context Root if the Dockerfile is available on an external source.

Context Root in Workspace

If you selected Context Root in Workspace as Source, specify the workspace context root of the build context.

Dockerfile Text

If you selected Dockerfile Text as Source, enter the Dockerfile code.

Remote Context Root

If you selected Remote Context Root as Source, specify the external context root URL of the build context.

Tip:

Include the protocol (example, http) if you are referencing a remote tar file (example: http://55.555.555.555/me/mydocker.tar.gz). Ignore the protocol if you are referencing a remote repository (example: git://github.com/me/my.git#mybranch:myfolder).

Dockerfile

If you selected Context Root in Workspace or Remote Context Root as Source, specify the name and path of the Dockerfile relative to the build context root.

Docker tag command

You use the tag command to create a target image tag that refers to the source image. The following table highlights the fields of the Docker tag command section.

Element Description

Source Image

 

Registry Host

(Required) Select a pre-linked Docker registry, or enter the host name of the registry where Docker images are stored.

If left empty, Docker Hub is set as the default registry host.

Image Name

(Required) Enter the source Docker image name.

Version Tag

Enter the version tag name of the source Docker image. The tag name must start with a letter or a number.

Full Image Name

Displays the complete source Docker image name in the <registry_host/image_name:version_tag> format.

Target Image

 

Registry Host

(Required) Select a pre-linked Docker registry, or enter the host name of the registry where Docker images are stored.

If left empty, Docker Hub is set as the default registry host.

Image Name

(Required) Enter the target Docker image name.

Version Tag

Enter the version tag name of the target Docker image. The tag name must start with a letter or a number.

Full Image Name

Displays the complete target Docker image name in the <registry_host/image_name:version_tag> format.

Docker push command

You use the push command to push an image to the Docker registry. The following table highlights the fields of the Docker push command section.

Element Description

Options

Specify the push command options. For more information, see https://docs.docker.com/engine/reference/commandline/push/.

Registry Host

(Required) Select a pre-linked Docker registry, or enter the host name of the registry where Docker images are stored.

If left empty, Docker Hub is set as the default registry host.

Image Name

(Required) Enter the Docker image name.

Version Tag

Enter the version tag name of the Docker image. The tag name must start with a letter or a number.

Full Image Name

Displays the complete Docker image name in the <registry_host/image_name:version_tag> format.

Docker images command

You use the images command to list available images. The images (without any parameters specified) shows image names, version tags, and size of all top level images. The following table highlights the fields of the Docker images command section.

Element Description

Options

Specify the images command options. For more information, see https://docs.docker.com/engine/reference/commandline/images/.

Registry Host

(Required) Select a pre-linked Docker registry, or enter the host name of the registry where Docker images are stored. The images are stored in the registry if they are pushed there.

If left empty, Docker Hub is set as the default registry host.

Image Name

Enter the Docker image name.

Version Tag

Enter the version tag name of the Docker image. The tag name must start with a letter or a number.

Full Image Name

Displays the complete Docker image name in the <registry_host/image_name:version_tag> format.

Docker save command

You use the save command to save an image to a .tar archive file. The following table highlights the fields of the Docker save command section.

Element Description

Output File

(Required) Specify the relative path and name of the output .tar file in the workspace.

Registry Host

(Required) Select a pre-linked Docker registry, or enter the host name of the registry where Docker images are stored.

If left empty, Docker Hub is set as the default registry host.

Image Name

(Required) Enter the Docker image name.

Version Tag

Enter the version tag name of the Docker image. The tag name must start with a letter or a number.

Full Image Name

Displays the complete Docker image name in the <registry_host/image_name:version_tag> format.

Docker load command

You use the load command to load an image from a .tar archive file. The following table highlights the fields of the Docker load command section.

Element Description

Input File

(Required) Specify the relative path and name of the input .tar file in the workspace.

Docker rmi command

You use the rmi command to remove an image from the client. The following table highlights the fields of the Docker rmi command section.

Element Description

What To Remove

Select Newly Created Images to remove all newly created images.

Select One Specific Image to remove a particular image from the registry.

Select All Images to remove all images.

Registry Host

If you selected One Specific Image in the Remove field, enter the host name of the registry where the Docker images are stored. The images are stored in the registry if they are pushed there. Until the images are pushed, the Registry Host is used to form the fully qualified name of the Docker image on the machine where the image is being created.

If left empty, Docker Hub is set as the default registry host.

Image Name

(Required) Enter the Docker image name.

Version Tag

Enter the version tag name of the Docker image. The tag name must start with a letter or a number.

Full Image Name

Displays the complete Docker image name in the <registry_host/image_name:version_tag> format.

Options

Specify the rmi command options. For more information, see https://docs.docker.com/engine/reference/commandline/rmi/.

Docker version command

You use the version command to view the version of Docker. The following table highlights the fields of the Docker version command section.

Element Description

Options

Specify the version command options. For more information, see https://docs.docker.com/engine/reference/commandline/version/.

Note:

The Docker logout command runs automatically after all Docker commands have run.

Configuring Post Build Actions

You use the Post-build tab in the Configure Build Job page to configure actions you want the system to perform after the build completes.

These actions can include archiving artifacts, publishing JUnit results, publishing javadoc, publish to a Git repository, and configure Oracle Cloud deployment tasks.

To configure the post build steps:

  1. Open the Configure Build Job page of the job.

    See Configuring a Job.

  2. Click Primary Settings Primary Settings, if necessary.

  3. Click the Post Build tab.

  4. Click Add Post Build Action and choose the desired action.

    The following table highlights what you can set from the Add Post Build Action menu of the Post Build tab.

    Element Reference

    Artifact Archiver

    Archiving Artifacts Post Build

    JUnit Publisher

    Publishing JUnit Results Post Build

    SonarQube Result Publisher

    Publishing SonarQube Result Post Build

    Javadoc Publisher

    Publishing Javadoc Post Build

    Git Publisher

    Publishing Git Artifacts Post Build

    Oracle Cloud Service Deployment

    Deploying to Oracle Cloud Post Build
  5. Click Save.

To remove the section, on the right side of the section header, click the Remove icon. To move the section, mouse over the section title, and then drag-and-drop it above or below another section.

Archiving Artifacts Post Build

You can use the Artifact Archiver post build action to archive artifacts of the build.

In the Artifact Archiver section, you can specify how to archive the build artifacts (for example, distribution ZIP files or JAR files) so that they can be downloaded later. By default, artifacts of a build are kept as long as the build log is kept.

To archive artifacts post build:
  1. Open the Post Build tab.
  2. Click Add Post Build Action and select Artifact Archiver.

    The following table highlights what you can set in the Artifact Archiver section.

    Element Description

    Artifacts from files

    Specify how and where the file artifacts are archived.

    Files to archive

    Enter comma or space separated list of the file names that you want to archive. You can also use wildcards. Example: module/dist/**/*.zip. The base directory is the build executor workspace.

    Files to exclude

    Enter comma or space separated list of the file names that you want to exclude from archive. You can also use wildcards. Example: foo/bar/**/*. A file that matches the specified pattern will not be archived even if it matches the pattern specified in the Files to archive field.

    Archive Maven Artifacts

    Select the check box to archive Maven artifacts created by the build.

    Select the Include POM.xml check box to archive the Maven POM file from the build.

  3. Click Save.
Publishing JUnit Results Post Build

You can use the JUnit Publisher post build action to get useful information about test results, such as historical test result trends, failure tracking, and so on.

To use this feature, you must first set up your build to run tests, then specify the path to JUnit XML files. If you are using Ant, specify the path such as **/build/test-reports/*.xml. If you are using Maven, specify the path such as target/surefire-reports/*.xml. Be sure not to include any non-report files into this pattern.

To publish JUnit results:
  1. Open the Post Build tab.
  2. Click Add Post Build Action and select JUnit Publisher.

    The following table highlights what you can set in the JUnit Publisher section.

    Element Description

    Include JUnit XMLs

    Specify the build executor workspace path and names of generated raw XML report files to include. You can also use wildcards. By default, **/surefire-reports/*.xml is used. The base directory of the fileset is the workspace root.

    Exclude JUnit XMLs

    Specify the build executor workspace path and names of XML report files to exclude. You can also use wildcards. The base directory of the fileset is the workspace root.

    Retain long standard output/error

    Select the check box to see standard output and errors in the test results after the build completes. The output is always saved in case the test fails, but by default, lengthy output is truncated to save space. Select the check box to see every log message, but note that memory consumption can substantially increase as a result and can slow the performance of the build executor.

    Organize test output by parent location

    Select the check box to combine the test results into a single table of results. If you use multiple browsers, then the results will be categorized by browsers, that is you will see a table for each browser you use for testing.

    Fail the build on fail tests

    Select the check box to mark the build as failed if the JUnit tests fail.

    Archive Media Files

    Select the check box to archive videos and image files.

  3. Click Save.
Publishing SonarQube Result Post Build

You can use the SonarQube Publisher post build action to get useful information about SonarQube test results.

To publish SonarQube Result post build:
  1. Open the Post Build tab.
  2. Click Add Post Build Action and select SonarQube Result Publisher.

    Note:

    If you see the SonarQube settings not available in the Build environment warning, contact the project Owner to configure an external SonarQube server with your project.

    The following table highlights what you can set in the SonarQube Result Publisher section.

    Element Description

    Apply SonarQube quality gate status as build status

    Select the check box to use the SonarQube Quality Gate status as the build status. If the SonarQube Quality Gate status is Passed, the build would be marked as successful. If the SonarQube Quality Gate status is Failed, the build would be marked as failed.

    To know more about SonarQube Quality Gates, see https://docs.sonarqube.org/display/SONAR/Quality+Gates.

    Archive Analysis Files

    Select the check box to create an archive file of the SonarQube analysis files.

  3. Click Save.
(Optional) Enter the result of the procedure here.
Publishing Javadoc Post Build

You can publish the Javadoc and specify how and where to publish Javadoc that is generated during a build.

To publish Javadoc post build:
  1. Open the Post Build tab.
  2. Click Add Post Build Action and select Javadoc Publisher.

    The following table highlights what you can set in the JUnit Publisher section.

    Element Description

    Javadoc Directory

    Specify the path relative to the root of the workspace where generated Javadoc is published. By default, the path is set to target/site/apidocs .

    Retain Javadoc for each build

    Select the check box to configure the build executor to retain Javadoc for each successful build. This enables you to browse Javadoc of older builds, but at the expense of additional disk space. The check box is not selected by default, so the build executor only keeps the latest Javadoc, and overwrites Javadoc of the old build.

  3. Click Save.
Publishing Git Artifacts Post Build

You can publish the Git artifacts, such as tags, and branches, and push merge results to Git repository.

To publish Git artifacts post build:
  1. Open the Post Build tab.
  2. Click Add Post Build Action and select Git Publisher.

    The following table highlights what you can set in the Git Publisher section.

    Element Description

    Publish only if build succeeds

    Select the check box to push artifacts to the Git repository only if the build succeeds.

    Merge results

    Select the check box to push merges back to the target remote name.

    Tag to push to remote repositories

     

    Tag to push

    Specify the Git repository tag name to push at the completion of build. Environment variables can also be used in the tag name. They will be replaced when the build runs. The push will fail if the tag does not already exist.

    Select the Create new tag check box to create the tag if the tag name does not exist. The push will fail if a tag with the given name already exists.

    Target remote name

    Specify the target remote name of the Git repository where the tag will be pushed. By default, origin is used

    Branch to push to remote repositories

     

    Branch to push

    Specify the Git repository branch name to push. Environment variables can also be used in the branch name. They will be replaced when the build runs. The push will fail if the branch does not already exist.

    Target remote name

    Specify the target remote name of the Git repository where the branch will be pushed. By default, origin is used.

    The target remote name needs to be one of the repositories configured in the Source Control tab. See Configuring the Source Code Management System for Builds.

  3. Click Save.
Deploying to Oracle Cloud Post Build

You can configure deployment actions of the specified deployment configuration and deploy the build artifacts. The build will be successful if the deployment action is successful.

A deployment configuration must exist before you configure the deployment actions of the job. If required, create a deployment configuration to meet your requirements. See Creating a Deployment Configuration.

To deploy to Oracle Cloud post build:
  1. Open the Post Build tab.
  2. Click Add Post Build Action and select Oracle Cloud Service Deployment.
  3. In the Add Deploy Task list, select the desired deploy task.

    The following table highlights the deploy tasks that you can set in the Oracle Cloud Service Deployment section.

    Deploy Task Description

    Deploy

    In Deployment Configuration, select the deployment configuration whose build generated artifacts that you want to deploy to the target Oracle Cloud Service instance when the build is complete. The list shows only those deployment configurations where the name of the job and the name of the deployment configuration match, and the deployment configuration is of type On Demand.

    The list is empty if the names do not match, or deployment configurations are of type Automatic.

    Undeploy

    In Deployment Configuration, select the deployment configuration whose build generated artifacts that you want to undeploy from the target Oracle Cloud Service instance when the build is complete.

    Start

    In Deployment Configuration, select the deployment configuration whose deployment you want to start on the target Oracle Cloud Service instance when the build is complete.

    Stop

    In Deployment Configuration, select the deployment configuration whose deployment you want to stop on the target Oracle Cloud Service instance when the build is complete.

  4. Click Save.

You can configure more than one deployment actions in a job.

Note:

  • If you change a deployment configuration or delete it after specifying the deployment action in the job, the changes are not reflected in the job and the build might not run as expected.

    For example, if you change the deployment configuration’s type to Automatic after specifying the deployment action in the job, the artifact will get deployed twice. The first deployment will happen when the build is successful. The deployment will then trigger the next automatic deployment action of the deployment configuration.

  • If you delete a deployment configuration or rename it after specifying the deployment action in the job, the build will attempt to deploy the artifact and will fail as the deployment configuration has been deleted or renamed.

  • When you change a deployment configuration, make sure that you update the build’s deployment action as well.

Configuring the General Settings of a Job

You can configure the general settings of job such as name and description, JDK version to be used, and discarding old builds.

To configure general settings of a job:
  1. Open the Configure Build Job page of the job.
  2. Click Additional Settings Additional Settings.
  3. Click the General tab, if necessary.

    The following table highlights what you can set in the General tab.

    Element Description

    Name

    Edit the name of the job.

    Description

    Edit the description of the job.

    Disable Build (No new builds will be executed until the job is re-enabled)

    Select the check box to disable job builds. To enable job builds, deselect the check box.

    If you created the job as a copy of an existing job, it is disabled by default. You must enable it to run builds.

    Execute concurrent builds if necessary

    Select the check box to perform concurrent builds, if necessary.

    Discard old builds

    Deselect the check box to retain old builds. The check box is selected by default and discards old builds as specified. See Discarding Old Builds and Artifacts.

  4. Click Save.

Configuring Build Software

Using the Software tab of the build configuration page, you can view the versions of software available on the build executor. For some software, you can change their default versions.

To view and change the default version of build software:

  1. Open the Configure Build Job page of the job.

    See Configuring a Job.

  2. Click Additional Settings Additional Settings.

  3. Click the Software tab.

    The following table highlights what you can set in the Software tab.

    Element Description

    Select a Software Template

    In Software Template, select the Build VM template that you want to use for your builds.

    Available Software

    View the versions of the software installed on the selected Build VM.

    Some software, such as Java, allow you to change their default version.

    To create a Build VM template or install a software to a template, contact the Organization Administrator.

  4. Click Save.

Configuring Build Triggers

Use the Build Triggers tab in the Configure Build Job page to configure options that trigger a build.

To configure build triggers:

  1. Open the Configure Build Job page of the job.

    See Configuring a Job.

  2. Click Additional Settings Additional Settings.

  3. Click the Triggers tab.

    The following table highlights what you can set in the Configure Triggers section.

    Trigger Reference

    Periodic Build Trigger

    Configuring Periodic Build Triggers

    SCM Polling Trigger

    Configuring SCM Polling Triggers

  4. Click Save.

Configuring Periodic Build Triggers

Coordinated Universal Time (UTC) is the primary time standard by which the world regulates clocks and time. You can schedule a job to run builds at specified period and schedule in UTC.

You specify the schedule using Cron expressions. If you are not a Cron expert, you can set the schedule easily by specifying values and the Cron expression will be created for you. If you are a Cron expert, use the Expert mode to enter the Cron expression manually.

To configure periodic build triggers:
  1. Open the Triggers tab.
  2. Click Add Trigger and select Periodic Build Trigger.

    The following table highlights what you can set in the Periodic Polling Trigger section.

    Element Description

    Expert Mode

    Select the check box to enter the schedule information in the form of a Cron expression in the text box. See Specifying Cron Expressions. By default, the default pattern is 0/30 * * * *, which runs a build every 30 minutes.

    The Cron expression is validated immediately when the cursor moves out of the text box. Note that other fields of the section are not available when the check box is selected.

    If the check box is not selected, it displays the Cron expression of the schedule based on the values entered in the following fields.

    Minute

    Select the check box to specify the schedule in minutes within the hour. Valid values are 0-59. By default, the check box is selected and 30 is set as the default value.

    Click Toggle Recurrence to add or remove 0/ in the beginning of the minute’s value in the Cron expression.

    Hour

    Select the check box to specify the schedule in hour of the day. Valid values are 0-23.

    Click Toggle Recurrence to add or remove 0/ in the beginning of the hour’s value in the Cron expression.

    Day of the Month

    Select the check box to specify the schedule in the day of the month. Valid values are 1-31.

    Click Toggle Recurrence to add or remove 1/ in the beginning day of the month’s value in the Cron expression.

    Day of the Month is not available if Day of the Week is selected.

    Month

    Select the check box to specify the schedule in the month. Valid values are JAN–DEC, which translates to 1-12.

    Click Toggle Recurrence to add or remove 1/ in the beginning of the month’s value in the Cron expression.

    Day of the Week

    Select the check box to specify the schedule in the day of the week. Valid values are SUN–SAT, which translates to 1-7.

    Click Toggle Recurrence to add or remove 1/ in the beginning of the day of the week’s value in the Cron expression.

    Day of the Week is not available if Day of the Month is selected.

    Comment

    Enter a comment for the schedule.

    View Schedule

    Click to view the build schedule of the next ten builds, as per the specified time zone in the list next to the button. By default, it is set to UTC.

    To check the build schedule in a different timezone, select it from the list. Click View Schedule again to view the schedule.

  3. Click Save.
Configuring SCM Polling Triggers

Coordinated Universal Time (UTC) is the primary time standard by which the world regulates clocks and time. You can schedule a job to run builds on SCM polling and at the specified schedule in UTC.

If a schedule is specified, polling is triggered at a commit according to the schedule. You specify the schedule using Cron expressions. If you are a Cron expert, you can use the Expert mode. If you are not a Cron expert, you can use the novice mode and set the schedule by specifying values.

To configure SCM polling triggers:
  1. Open the Triggers tab.
  2. Click Add Trigger and select SCM Polling Trigger.
  3. To use the export mode, select the Expert mode check box, and enter the schedule in the text box.

    To create a Cron expression, ee Specifying Cron Expressions. By default, the default pattern is 0/30 * * * *, which runs a build every 30 minutes.

    The Cron expression is validated immediately when the cursor moves out of the text box. Note that other fields of the section are not available when the check box is selected.

  4. To use the novice mode, deselect the Expert mode check box and specify the schedule information. The generated Cron expression is displayed next to the Expert mode check box.
    Element Description

    Minute

    Select the check box to specify the schedule in minutes within the hour. Valid values are 0-59. By default, the check box is selected and 30 is set as the default value.

    Click Toggle Recurrence to add or remove 0/ in the beginning of the minute’s value in the Cron expression.

    For example, to run a build job every 30 minutes, enter 30, and then click Toggle Recurrence. In Expert mode, the value changes to 0/30. A build of the job now runs in 30 minutes, such as 02:30, 03:00, and 03:30.

    To run a build job on the half hour mark, enter 30. Do not click Toggle Recurrence, A build of the job now runs on the half hour mark, such as 02:30, 03:30, and 04:30.

    Hour

    Select the check box to specify the schedule in hour of the day. Valid values are 0-23.

    Click Toggle Recurrence to add or remove 0/ in the beginning of the hour’s value in the Cron expression.

    Remember that the schedule is specified in UTC. To set schedule for your time zone, calculate the difference between UTC and your time zone and then enter the values.

    Day of the Month

    Select the check box to specify the schedule in the day of the month. Valid values are 1-31.

    Click Toggle Recurrence to add or remove 1/ in the beginning day of the month’s value in the Cron expression.

    Day of the Month is not available if Day of the Week is selected.

    Month

    Select the check box to specify the schedule in the month. Valid values are JAN–DEC, which translates to 1-12.

    Click Toggle Recurrence to add or remove 1/ in the beginning of the month’s value in the Cron expression.

    Day of the Week

    Select the check box to specify the schedule in the day of the week. Valid values are SUN–SAT, which translates to 1-7.

    Click Toggle Recurrence to add or remove 1/ in the beginning of the day of the week’s value in the Cron expression.

    Day of the Week is not available if Day of the Month is selected.

    Comment

    Enter a comment for the schedule.

    View Schedule

    Click to view the build schedule of the next ten builds, as per the specified time zone in the list next to the button. By default, it is set to UTC.

    To check the build schedule in a different timezone, select it from the list. Click View Schedule again to view the schedule.

  5. Click Save.
Specifying Cron Expressions

You can use Cron expressions to define periodic build patterns.

You can specify the Cron schedule information in the following format:

MINUTE HOUR DOM MONTH DOW

where:

  • MINUTE is minutes within the hour (0-59)

  • HOUR is the hour of the day (0-23)

  • DOM is the day of the month (1-31)

  • MONTH is the month (1-12)

  • DOW is the day of the week (1-7)

To specify multiple values, you can use the following operators:

  • * to specify all valid values

  • - to specify a range, such as 1-5

  • / or */X to specify skips of X's value through the range, such as 0/15 in the MINUTE field for 0,15,30,45

  • A,B,...,Z can be used to specify multiple values, such as 0,30 or 1,3,5

For more information about Cron, see http://en.wikipedia.org/wiki/Cron.

Setting Advanced Options for the Job

Use the Advanced tab in the Configure Build Job page to configure the advanced options for the job, such as quiet period and retry count.

To configure the advanced options build environment:

  1. Open the Configure Build Job page of the job.

    See Configuring a Job.

  2. Click Additional Settings Additional Settings.

  3. Click the Advanced tab.

    The following table highlights what you can set in the Advanced tab.

    Element Description

    Quiet period

    Select the check box and specify the period in In seconds that a new build should wait before it runs in Quiet Period. The default value is 0.

    If the build server is busy with too many builds, setting a longer quiet period can reduce the number of builds.

    Retry count

    Select the check box to specify how many times a build of a job would run if it fails.

    In Build Retries specify the number of times the build executor will retry the build. The default value is 5.

    In SCM Retries specify the number of times the build executor will retry the build to checkout files from the Git repository. The default value is 5.

    Abort the build if it is stuck

    Select the check box and specify the timeout duration in Hours and Minutes. The default value is 0 for both the fields.

    If a build does not complete in the specified amount of time, then the build will be terminated automatically and marked as aborted. Select the Fail the build on abort check box to mark the build as failed rather than marking it as aborted.

    Add Timestamps to the Console Output

    Select the check box to add a time stamp for each log line in the build console.

    Note that the time on the build executor is UTC and the time displayed in the build job log is UTC - 7 hours.

    Max Log Size (MB)

    Specify the maximum size of the console log output retained by the job.

    The default value is 50 MB and the maximum value is 1000 MB.

  4. Click Save.

Viewing a Job’s Build History

A job’s build history can be viewed in the Build history section of the Job Details page. It displays the status of the running builds, and completed job builds in descending order (recent first) along with their build numbers, date and time, and a link to the console output of the build.

The build history shows information abut who or how the build was triggered, its status, build number, date-time stamp, Console icon to open the build’s console, and Delete Delete to delete the build.

Note:

  • In the By column, the icons indicate the following:

    • User User: Indicates the build was initiated by a user.

    • SCM Change SCM Change: Indicates the build was initiated by an SCM change.

    • Pipeline Pipeline: Indicates the build was initiated by a pipeline. Click to open the build’s pipeline instance.

    • Periodic Build Trigger Periodic Build Trigger: Indicates the build was triggered by a periodic build trigger.

  • In the Build column, an * in the build number indicates the build is annotated with a description. Mouse over the build number to see the description.

  • Discarded and deleted jobs are not displayed.

  • If a running build is stuck in the Queued status for a long time, mouse over the Queued status to see a message about the problem.

  • To sort the table data in ascending or descending order, click the header column name and then click the Previous or Next icon in the column header.

    You can also right-click inside table column and then select the sort order from the Sort context menu.

  • A project non-member cannot delete a build.

Disabling or Enabling a Job

You can disable or enable a job from the Job Details page.

Copied jobs are disabled, by default. When a job is disabled, its manual or automatic builds won’t run.
To disable or enable a job:
  1. In the navigation bar, click Build.
  2. Click the Jobs tab, if necessary.
  3. In the Jobs table, click the job name link.
  4. Click the Disable or Enable button.

Deleting a Job

You can delete a job from the Job Details page.

When deleted, all builds and deployment artifacts of the job are also deleted.
To delete a job:
  1. In the navigation bar, click Build.
  2. Click the Jobs tab, if necessary.
  3. In the Jobs table, click the job name link.
  4. In the Job Details page, click the Delete button.
  5. In the Delete Job dialog box, select the I understand that this job will be permanently deleted check box and click Delete.
You can also delete the job from the Jobs table. In the table, on the right side of the job row, click Delete Delete.

Managing and Configuring Pipelines

You can create, manage, and configure job pipelines from the Pipelines tab of the Builds page.

About Pipelines

Using a Pipeline, you can define dependencies of jobs and create a path or a chain to run builds. A pipeline helps in running continuous integration jobs and reduce network traffic.

You can create a pipeline using a pipeline diagram where you can define the dependencies of jobs. When you create a dependency of a job over another, you define the order of automatic builds of the dependent jobs. The dependent jobs can be configured to use artifacts of the parent job too.

For example, in the following diagram, Job 2 is dependent on Job 1 and will run after Job 1 is successful.

Job 2 is dependent on Job 1 and will run after Job 1 is successful

In the following diagram, Job 2, Job 3, and Job 4 are dependent on Job 1 and will run after Job 1 is successful.

Job 2, Job 3, and Job 4 are dependent on Job 1 and will run after Job 1 is successful

The following diagram shows a complex example.

Complex dependency of jobs

The above diagram defines the following dependencies:

  • Job 2 and Job 3 are dependent on Job 1 and will run after Job 1 is successful

  • Job 4 and Job 5 are dependent on Job 2 and will run after Job 2 is successful

  • Job 6 and Job 7 are dependent on Job 4 and will run after Job 4 is successful

  • Job 8 is dependent on Job 6 and Job 7 and will run after Job 6 and Job 7 are successful

  • Job 1 is the master job. Running Job 1 triggers a chain and all jobs from Job 1 through Job 8 will run automatically one after the other.

You can create multiple pipeline diagrams of jobs. If multiple pipelines have some common jobs, then multiple builds will run of those jobs. For example, in the following figure, Pipeline 1 and Pipeline 2 have common jobs.

Multiple pipelines using common jobs

Let’s assume that in the Pipelines tab, Pipeline 1 is defined first and Pipeline 2 is defined second. The builds of these jobs will run in the following order:

  1. A build of Job 1 runs.

  2. Builds of Job 2 and Job 3 of Pipeline 1 get in the build executor queue after Job 1 is successful. A build of Job 2 of Pipeline 2 also gets in the build executor queue after Job 1 is successful.

  3. Builds of jobs in build executor queue start running on first-come first-served basis. So, Job 2 and Job 3 of Pipeline 1 will run first. Let’s call the build as build 1 of Job 2 and Job 3. Then, another build of Job 2 of Pipeline 2 will run. This will be the build 2 of Job 2.

  4. A build of Job 4 of Pipeline 1 joins the build executor queue as soon as Job 2 is successful. A build of Job 3 of Pipeline 2 will also join the queue when Job 2 is successful.

  5. As soon as the build executor is available, build 1 of Job 4 starts running and build 2 of Job 3 starts running. Remember that build 1 of Job 3 ran in Pipeline 1.

  6. After a build of Job 3 of Pipeline 2 is successful, a build of Job 4 of Pipeline 2 will join the queue and run when the build executor is available. Remember that this will be build 2 of Job 4 as build 1 ran in Pipeline 1.

While creating multiple pipeline diagrams with common jobs, be careful if a job is dependent on artifacts of the parent job.

Creating a Pipeline

To run builds of jobs that are dependent on another job, you must create a pipeline. You can create a pipeline from the Build page.

To create a pipeline:
  1. In the navigation bar, click Build.
  2. Click the Pipelines tab.
  3. Click + New Pipeline.
  4. In the Create Pipeline dialog box, in Name and Description, enter a unique name and description.

    Select the Auto start when pipeline jobs are build externally check box to trigger the pipeline build if a job of the pipeline is triggered externally (outside the pipeline). All jobs following the triggered job in the pipeline will be built, but jobs preceding the triggered job will not be built.

    Select the Disallow pipeline jobs to build externally when the pipeline is building check box to disable manual or automatic builds of the jobs that are part of the pipeline when the pipeline build is running.

  5. Click Create.
  6. In the Designing Pipeline page, design the pipeline, and click Save. See Designing Pipeline Diagrams.

Viewing Instances of a Pipeline

When a pipeline build is triggered, an instance of it is created and is available in the pipeline’s instances page.

To view instances of a pipeline, click its name link in the Pipelines tab. The Pipeline Instances page displays the history of the pipeline run.

For each pipeline instance, the page shows the pipeline diagram and its status.

A pipeline's status is determined by the builds of its jobs.

  • Success Success: Indicates that all builds of the pipeline are successful.

  • Failed Failed: Indicates that a build of a pipeline job failed, hence the pipeline has failed too.

  • Cancelled Cancelled: Indicates the pipeline was cancelled.

  • In Progress In Progress: Indicates a pipeline is in progress.

In the pipeline diagram, the color of job nodes indicate their status.

  • Green: Indicates the last build of the job was successful

  • White: Indicates a build of the job is running or has not run yet

  • Red: Indicates the last build of the job failed

Configuring a Pipeline

You can configure a job pipeline from the Pipelines tab of the Builds page. While configuring a pipeline, you can design or edit the pipeline diagram, change the pipeline settings, edit the pipeline name name and description.

To configure a job pipeline:
  1. In the navigation bar, click Build.
  2. Click the Pipelines tab.
  3. For the pipeline you want to edit, click Configure Configure.

Editing a Pipeline

You can edit a pipeline and edit the pipeline diagram from the Configure Pipeline page.

To configure the pipeline diagram, click Configure Pipeline Diagram Configure Pipeline Diagram. See Designing Pipeline Diagrams.

To edit pipeline settings, click Edit Pipeline Settings Edit Pipeline Settings. See Creating a Pipeline to know about the fields you can update.

Designing Pipeline Diagrams

Using a pipeline diagram, you can define the dependency of jobs and the order of their builds.

The Jobs list shows all jobs of the project on the left side of the page. Drag-and-drop the jobs to the designer area to design the pipeline diagram. Click Configure Configure to configure the dependency condition between the parent and the child job.

Creating a One-to-One Dependency

A one-to-one dependency is formed between a parent and a child job. When a build of the parent job is successful, a build of the child job runs automatically.

To create a one-to-one dependency of a child job to its parent job:

  1. From the Jobs list, drag-and-drop the parent job to the designer area.

  2. From the Jobs list, drag-and-drop the dependent (or child) job to the designer area.

  3. To indicate the parent job, the job that will trigger the pipeline build, mouse over the Grey circle on the right of the Start node handle of the Start node. The cursor icon changes to the + cursor icon.

    Example:

    + mouse cursor over the Start node

    In the above example, the Start node indicates the staring point of the pipeline. The Start node is available in all pipelines and cannot be removed. Job 1 is the parent job and Job 2 is the dependent job.

  4. Drag the cursor from the Grey circle Grey circle on the right of the Start node handle to the White circle White circle on the left side of the job node handle of the job. An arrow line will appear.

    Example:

    Dependency formed between the parent and dependent jobs
  5. Similarly, mouse-over the Blue circle Blue circle on the right side of the job node handle of the parent job, click, and drag-and-drop the arrow head over the White circle White circle on the left side of the job node of the child job.

    Job 2 is dependent on Job 1 and will run after Job 1 is successful

A dependency is now formed. In the above example, Job 2 is now dependent on Job 1. A build of Job 2 will run automatically after every Job 1 build is successful.

To delete a job node or a dependency, click to select it, and then click DeleteDelete.

Creating a One-to-Many Dependency

A one-to-many dependency is formed between one parent job and multiple child jobs. When a build of the parent job is successful, builds of child jobs run automatically.

To create a one-to-many dependency between jobs:

  1. From the Jobs list, drag-and-drop the parent job to the designer area.

  2. From the Jobs list, drag-and-drop all dependent (or child) jobs to the designer area.

    Example:

    Design diagram for a Fork and multiple dependent jobs pipeline
    Here, Job 1 is the parent job and Job 2, Job 3, and Job 4 are the dependent jobs.
  3. To indicate the parent job, the job that will trigger the pipeline build, mouse over the Grey circle Grey circle on the right of the Start node handle of the Start node. The cursor icon changes to the + cursor icon.

  4. Drag the cursor from the Grey circle Grey circle on the right of the Start node handle to the White circle White circle on the left side of the job node handle of the job. An arrow line will appear.

    Example:

    Dependency formed between the parent and dependent jobs
  5. Similarly, mouse-over the Blue circle Blue circle on the right side of the job node handle of the parent job, click, and drag-and-drop the arrow head over the White circle White circle on the left side of the job node of the child jobs.

    Job 2, Job 3, and Job 4 are dependent on Job 1 and will run after Job 1 is successful

A dependency is now formed. In the above example, Job 2, Job 3, and Job 4 are now dependent on Job 1. A build of Job 2, Job 3, and Job 4 will run automatically after every Job 1 build is successful.

To delete a job node or a dependency, click to select it, and then click Delete Delete.

Creating a Many-to-One Dependency

A many-to-one dependency is formed between multiple parent jobs and one child job. When a builds of all parent jobs are successful, a build of the child job runs automatically.

To create a many-to-one dependency of parent jobs with a child job:

  1. From the Jobs list, drag-and-drop all parent jobs to the designer area.

  2. From the Jobs list, drag-and-drop the dependent (or child) jobs to the designer area.

    Example:

    Design diagram for a Join and multiple parent jobs pipeline

    Here, Job 2, Job 3, and Job 4 are the parent jobs and Job 5 is the dependent job.

  3. To indicate the parent job, the job that will trigger the pipeline build, mouse over the Grey circle Grey circle on the right of the Start node handle of the Start node. The cursor icon changes to the + cursor icon.

  4. Drag the cursor from the Grey circle Grey circle on the right of the Start node handle to the White circle White circle on the left side of the job node handle of the parent job. Repeat the steps for all parent nodes.

  5. Drag the cursor from the White circle White circle on the left side of the job node handle of the parent job. An arrow line will appear. Repeat the steps for all parent nodes.

  6. Similarly, mouse over the Blue circle Blue circle on the right side of the job node handle of the parent jobs and drag-and-drop the arrow head over the White circle White circle on the left side of the job node handle of the dependent job.

    Example:

    Design diagram for a Join and multiple parent jobs pipeline

A dependency is now formed. In the above example, Job 5 is dependent on Job 2, Job 3, and Job 4. A build of Job 5 will run automatically after Job 2, Job 3, and Job 4 are successful.

To delete a job node or a dependency, click to select it, and then click Delete Delete.

Configuring the Dependency Condition

When you create a dependency between a parent and a child job, by default, a build of the child job runs after the parent job’s build is successful. You can configure the dependency to run a build of the child job after the parent job’s build fails.

To configure the dependency condition between two jobs:

  1. In the pipeline designer, click to select the dependency condition arrow.

  2. In the pipeline designer toolbar, click Configure Configure.

  3. In the Pipeline config flow editor, in Result Condition, select Failed or Successful.

    You can also double-click the dependency arrow to open the Pipeline config flow editor.

  4. Click Apply.

Running a Pipeline

You can a pipeline from the Build page.

To run a job pipeline:
  1. In the navigation bar, click Build.
  2. Click the Pipelines tab.
  3. For the pipeline you want to run, click Build Build.
The jobs defined in the pipeline start running.

Deleting a Pipeline

You can delete a job pipeline from the Builds page.

To edit a job pipeline:
  1. In the navigation bar, click Build.
  2. Click the Pipelines tab.
  3. For the pipeline you want to delete, click Delete Delete.
Deleting a pipeline does not delete related jobs, but the dependency or the order of job builds is removed.

Using the Oracle Maven Repository

You can configure the POM file of your application to access the Oracle Maven Repository and configure the job to download artifacts and dependencies while running a build.

For more information about Oracle Maven repository and how to use it, see http://www.oracle.com/webfolder/application/maven/index.html.

Here are some tips for accessing the Oracle Maven repository from Oracle Developer Cloud Service build executor:

  • Before configuring the POM file to access the Oracle Maven Repository, open https://www.oracle.com/webapps/maven/register/license.html in your web browser, sign-in with your Oracle Account credentials, and accept the license agreement.

  • To run local Maven builds on your computer, configure the Maven settings.xml file and the settings-security.xml file.

    • Configure the Oracle Maven Repository definition and add your Oracle Account user name and the password in the settings.xml file.

      Example:

      <servers>
      	<server>
      		<id>maven.oracle.com</id>
      		<username>alex.admin</username>
      		<password>password</password>
      		<configuration> ... </configuration>
      	</server>
      </servers>

      For more information, see the Configuring the Oracle Maven Repository chapter in Oracle® Fusion Middleware Developing Applications Using Continuous Integration.

    • If you want to use encrypted password, create a master password in the settings-security.xml file before you encrypt your Oracle Account password. Note that Oracle Developer Cloud Service does not store credentials in the executor Maven settings file.

      For more information about the settings.xml file and password encryption, see http://maven.apache.org/settings.html and https://maven.apache.org/guides/mini/guide-encryption.html.

    • To ensure that you are using the correct Oracle Developer Cloud Service proxy settings for your Maven build job, set the HTTP_PROXY_HOST (or HTTPS_PROXY_HOST) and HTTP_PROXY_PORT (or HTTPS_PROXY_PORT) proxy related environment variables in settings.xml.

      Example:

      <proxies>
      	<proxy>
      		<port>${env.HTTP_PROXY_PORT}</port>
      		<host>${env.HTTP_PROXY_HOST}</host>
      		<nonProxyHosts>
      			localhost|localhost.localdomain|127.0.0.1|[::1]|*.test_server.com
      		</nonProxyHosts>
      	</proxy>
      </proxies>
  • To configure a build job in Oracle Developer Cloud Service to access the Oracle Maven repository, see Configuring the Build Environment to use the Oracle Maven Repository. You don’t need to upload the local Maven files to the Git repository to run builds.

    When a build runs, Oracle Developer Cloud Service creates an internal environment to access the Oracle Maven repository. It updates the internal settings.xml (not accessible to you) to add your Oracle Account credentials, encrypts your password, run the Maven commands defined in the Builders tab of the Job Configuration page, and then reverts the updates made to the Maven files after the build is complete.

About the Build Executor Environment Variables

When you run a build job, you can use the environment variables in your shell scripts and commands to access the software on the Oracle Developer Cloud Service build executor.

Common Variables

The following table describes some common environment variables.

Environment Variable Description

BUILD_ID

The current build’s ID.

BUILD_NUMBER

The current build number.

BUILD_URL

The full URL of the current build.

BUILD_DIR

The build output directory.

JOB_NAME

The name of the job.

EXECUTOR_NUMBER

The unique number that identifies the current executor (among executors of the same machine) that's running the current build.

HTTP_PROXY

The HTTP proxy for outgoing connections.

HTTP_PROXY_HOST

The HTTP proxy host for outgoing connections.

HTTP_PROXY_PORT

The HTTP proxy port for outgoing connections.

HTTPS_PROXY

The HTTPS proxy for outgoing connections.

HTTPS_PROXY_HOST

The HTTPS proxy host for outgoing connections.

HTTPS_PROXY_PORT

The HTTPS proxy port for outgoing connections.

JOB_NAME

The name of the current job.

JOB_URL

The full URL of the current job.

NO_PROXY

Specify the comma separated list of domain names or the IP addresses for which the proxy should not be used. You can also specify port numbers.

NO_PROXY_ALT

Specify the pipe ( | ) separated list of domain names or the IP addresses for which the proxy should not be used. You can also specify port numbers.

Software Variables

Environment Variable Description

DYNAMO_HOME

The path of the Oracle ATG home directory.

DYNAMO_ROOT

The path of the Oracle ATG root directory.

GRADLE_HOME

The path of the Gradle directory.

JAVA_HOME

The path of the directory where the Java Development Kit (JDK) or the Java Runtime Environment (JRE) is installed.

If your job is configured to use a specific JDK, the build executor sets the variable to the path of the specified JDK. When the variable is set, PATH is also updated to have $JAVA_HOME/bin.

JAVACLOUD_HOME

The path of the Oracle Java Cloud Service - SaaS Extension Software Development Kit directory.

The following JDeveloper and SOA related variables are also available:

  • JAVACLOUD_HOME_11_1_1_7_1=/opt/Oracle/Middleware_11.1.1.7.1/jdeveloper/cloud/oracle-javacloud-sdk/lib

  • JAVACLOUD_HOME_11G=/opt/Oracle/Middleware_11.1.1.7.1/jdeveloper/cloud/oracle-javacloud-sdk/lib

  • JAVACLOUD_HOME_12C3=/opt/Oracle/MiddlewareSOA_12.1.3/jdeveloper/cloud/oracle-javacloud-sdk/lib

  • JAVACLOUD_HOME_SOA=/opt/Oracle/MiddlewareSOA_12.1.3/jdeveloper/cloud/oracle-javacloud-sdk/lib

  • JAVACLOUD_HOME_SOA_12_1_3=/opt/Oracle/MiddlewareSOA_12.1.3/jdeveloper/cloud/oracle-javacloud-sdk/lib

  • JAVACLOUD_HOME_SOA_12_2_1=/opt/Oracle/MiddlewareSOA_12.2.1.1/jdeveloper/cloud/oracle-javacloud-sdk/lib

ORACLE_HOME

The path of the directory where JDeveloper is installed on the build executor.

The following variables are available:

  • ORACLE_HOME=/opt/Oracle/Middleware_11.1.1.7.1/jdeveloper

  • ORACLE_HOME_11G=/opt/Oracle/Middleware_11.1.1.7.1/jdeveloper

  • ORACLE_HOME_11_1_1_7_1=/opt/Oracle/Middleware_11.1.1.7.1/jdeveloper

Use the following variables for JDeveloper with SOA :

  • ORACLE_HOME_12C3=/opt/Oracle/MiddlewareSOA_12.1.3/jdeveloper

  • ORACLE_HOME_SOA=/opt/Oracle/MiddlewareSOA_12.1.3/jdeveloper

  • ORACLE_HOME_SOA_12_1_3=/opt/Oracle/MiddlewareSOA_12.1.3/jdeveloper

  • ORACLE_HOME_SOA_12_2_1=/opt/Oracle/MiddlewareSOA_12.2.1/jdeveloper

MIDDLEWARE_HOME

The path of the directory where Oracle Fusion Middleware is installed on the build executor.

The MIDDLEWARE_HOME directory includes the JDeveloper installation directory, WebLogic Server installation directory, and the Oracle Common library dependencies.

The following variables are available:

  • MIDDLEWARE_HOME=/opt/Oracle/Middleware_11.1.1.7.1

  • MIDDLEWARE_HOME_11G=/opt/Oracle/Middleware_11.1.1.7.1

  • MIDDLEWARE_HOME_11_1_1_7_1=/opt/Oracle/Middleware_11.1.1.7.1

Use the following variables for SOA :

  • MIDDLEWARE_HOME_12C3=/opt/Oracle/MiddlewareSOA_12.1.3

  • MIDDLEWARE_HOME_SOA=/opt/Oracle/MiddlewareSOA_12.1.3

  • MIDDLEWARE_HOME_SOA_12_1_3=/opt/Oracle/MiddlewareSOA_12.1.3

  • MIDDLEWARE_HOME_SOA_12_2_1=/opt/Oracle/MiddlewareSOA_12.2.1.1

WLS_HOME

The path of the WebLogic server binary directory bundled with the JDeveloper install on the build executor.

The following variables are available:

  • WLS_HOME=/opt/Oracle/Middleware_11.1.1.7.1/wlserver_10.3

  • WLS_HOME_11G=/opt/Oracle/Middleware_11.1.1.7.1/wlserver_10.3

  • WLS_HOME_11_1_1_7_1=/opt/Oracle/Middleware_11.1.1.7.1/wlserver_10.3

Use the following variables for SOA :

  • WLS_HOME_12C3=/opt/Oracle/MiddlewareSOA_12.1.3/wlserver

  • WLS_HOME_SOA=/opt/Oracle/MiddlewareSOA_12.1.3/wlserver

  • WLS_HOME_SOA_12_1_3=/opt/Oracle/MiddlewareSOA_12.1.3/wlserver

  • WLS_HOME_SOA_12_2_1=/opt/Oracle/MiddlewareSOA_12.2.1/wlserver

NODE_HOME

The path of the Node.js home directory.

NODE_PATH

The path of the Node.js modules directory.

Tip:

  • You can run the env command as a Shell build step to view all environment variables set on the Oracle Developer Cloud Service build executor. See Adding an Unix Shell Builder.

  • Some Linux programs, such as curl, only support lower-case environment variables. Change the build steps in your job configuration to use lower-case environment variables.

    Example:

    export http_proxy="$HTTP_PROXY"
    export https_proxy="$HTTPS_PROXY"
    export no_proxy="$NO_PROXY"
    curl -v http://www.google.com

About the Software Installed on the Build Executor

Various software, such as Docker, JDeveloper, Xvfb, and Node.js, are installed on the Oracle Developer Cloud Service Build Executor and are available to the Executor threads when running on Oracle Cloud.

Executables from the software bundles are available on the builder's PATH variable, which is set to/usr/bin, and can be invoked directly from the Unix Shell builder. You should use the PATH variable and other environment variables to access the installed software.

The following table lists software installed on the Oracle Developer Cloud Service Build Executor in addition to the software installed on the operating system.

Software Version

Ant

1.9.6

Docker

1.12.6

Findbugs

3.0.1

Firefox

45.x (Oracle Linux 6)

52.x (Oracle Linux 7)

Git

1.7.1

Gradle

4.x

3.x

2.x

Java

10.x

9.x

1.8.x

1.7.x

1.6.x

Kubectl

1.8.4

Maven

3.3.3

Node.js

0.12.x

4.x

6.x

8.x

Node.js – grunt

0.4.5

Node.js – gulp

3.9.0

Node.js – grunt-cli

0.1.13

Node.js – gulp-cli

0.3.0

Node.js – bower

1.7.7

Node.js – oracledb

1.7

Node.js Driver for Oracle Database

12.1.0.2

OCIcli

2.4.10

Oracle ATG 11

11.1.0.1

Oracle Developer Studio 12c 12.5

12.5

Oracle Forms Developer 12

12.2.1.3.0

Oracle Instant Client 12c

12.1.0.2.0

Oracle JDeveloper Studio 12

12.2.1.3.0

Oracle JDeveloper Studio 11

11.1.1.7.1

Oracle SOA Suite 12

12.2.1.3.0

12.2.1.2.0

12.2.1.1.0

12.1.3.0.0

Packer

1.2.3

PSMcli

1.1.19

Python

3.6.x

3.5.x

2.6.x (Oracle Linux 6)

2.7.x (Oracle Linux 7)

Python – pip3

9.0.x

Ruby

1.9.3p488

SQLcl

17.x

4.x

SFTP

yum:latest

Terraform

0.11.3

Xvfb

1.15.0 (Oracle Linux 7)

To know about the environment variables that you can use to access the software, see About the Build Executor Environment Variables.

Note:

Various plugins such as Gradle, Node, Xvfb, and Maven 3 ported from Eclipse/Community Hudson are also available in the build executor.

Running a Build

You can run a job’s build from the job’s details page and Jobs Overview page.

To run a build of a job:
  1. In the navigation bar, click Build.
  2. Click the Jobs tab, if necessary.
  3. In the Jobs table, click the job name link.
  4. In the job’s details page, click Build Now.
You can also run a job’s build from the Jobs Overview page. In the jobs table, click Build Now Build Now to run the build of the corresponding job.

Configuring a Job to Run a Build Automatically on Git Repository Updates

You can configure a job to monitor the project Git repository and trigger a build automatically after an update is pushed to the Git repository.

To configure a job to run build automatically after a Git repository is updated:
  1. In the navigation bar, click Build.
  2. Click the Jobs tab, if necessary.
  3. In the Jobs table, click the job name link.
  4. In the Configure Build Job page, click the Source Control tab.
  5. For the Git repository whose updates you want to track, select the Automatically perform build on SCM commit check box.
  6. Click Save.

The builds do not run automatically for external Git repositories. To run automatic builds of external Git repositories, enable time-based trigger. See Configuring Periodic Build Triggers.

Configuring a Job to Run a Maven Build

Apache Maven is pre-installed on the Oracle Developer Cloud Service build executor. You can use Maven 2.0 or 3.0 to run builds of your application.

To run Maven builds:

  1. Configure your application to use the Maven POM file.

    If you are new to Maven, see https://maven.apache.org/.

  2. Commit and push the application files to the project Git repository.

  3. Create a job and configure it

    See Creating a Job and Configuring a Job.

  4. Configure the job to use Maven as a build step.

    See Adding a Maven Builder.

  5. Save the job and run a build.

    See Running a Build.

While you are configuring a job to use Maven, you might also want to take a look at the following topics:

Configuring a Job to Run an Ant Build

Apache Ant is pre-installed on the Oracle Developer Cloud Service build executor.

To run Ant builds:

  1. Configure your application to use the Ant build files.

    If you are new to Ant, see https://ant.apache.org.

  2. Commit and push the application files to the project Git repository.

  3. Create a job and configure it

    For more information, see Creating a Job and Configuring a Job.

  4. Configure the job to use Ant as a build step.

    For more information, see Adding an Ant Builder.

  5. Save the job and run a build.

    For more information, see Running a Build.

While you are configuring a job to use Ant, you might also want to take a look at the following topics:

Configuring the POM File to Upload or Download Dependencies from the Project Maven Repository

You can configure the pom.xml file to upload or download dependencies from the project Maven repository while running a build.

To configure the pom.xml file:
  1. In the navigation bar, click Maven.
  2. In the Browse view of the Maven page, click the Maven tab in Distribution Management.
  3. Click Copy Copy to clipboard to copy the <distributionManagement> code snippet to the clipboard.
  4. Open the pom.xml file of your project in a code editor (or a text editor) and paste the contents of the clipboard under the <project> element.
  5. Save the file, commit it to the Git repository, and then push the commit.

Note:

The credentials in settings.xml are not required to access the project Maven repository when running a build. The Build job has full access to the project Maven repository for uploads and downloads.

Discarding Old Builds and Artifacts

You can configure a job to discard its old builds and artifacts.

The old builds are discarded after the job configuration is saved and after a job is built.

To discard old builds and artifacts:

  1. Open the Configure Build Job page of the job.

    See Configuring a Job.

  2. Click Additional Settings Additional Settings.

  3. Click the General tab, if necessary.

  4. Select the Discard Old Builds check box.

  5. Configure the discard options.

  6. Click Save.

Downloading Build Artifacts

From the Artifacts page, you can download the job’s last successful build’s artifacts from the job’s details page and a build’s artifacts from the build’s details page.

The build artifacts are displayed in a directory tree structure. You can click the link to download parts of the tree including individual files, directories, and subdirectories.

To download artifacts of the job’s last successful build:

  1. In the navigation bar, click Build.

  2. Click the Jobs tab, if necessary.

  3. In the Jobs table, click the job name link.

  4. Click Latest Artifacts.

  5. In the Artifacts Archived page, click the artifact link (file or directory) to download it. Click All files in a zip to download a zip file of all artifacts.

To download artifacts of a particular build, open the build’s details page, click Artifacts, and download the artifacts from the Artifacts Archived page.

Disable or Enable Job’s Build Email Notifications

You can disable or enable a job’s build email notifications for subscribed users. The email notifications are enabled by default when a job is created.

To disable or enable a job’s build email notifications:
  1. In the navigation bar, click Build.
  2. Click the Jobs tab, if necessary.
  3. In the Jobs table, click the job name link.
  4. To disable notifications, in Notifications, click Off.
    To enable notifications, click On.

Subscribing to a Job’s Build Email Notifications

You can subscribe to email notifications when a build of a job is successful or fails.

Before you subscribe to build email notifications, enable the build activity notifications in your account preferences. See Setting Email Notifications.

To subscribe to a job’s build email notifications:

  1. In the navigation bar, click Build.

  2. Click the Jobs tab, if necessary.

  3. In the Jobs table, click the job name link.

  4. If necessary, click the On toggle button to enable build notifications of the job for all subscribed users. The email notifications are enabled by default.

  5. Click the CC Me icon to subscribe yourself to the job’s build email notifications.

  6. In the CC Me dialog, select the Successful Builds check box to receive email when the build is successful. Select Failed Builds to receive email when the build fails.

  7. Click OK.

When you are subscribed to a job’s build email notifications, the CC Me icon changes to CCed Me.

To unsubscribe to email notifications, click CCed Me, and deselect the required check box.

Note:

Do not click the Off toggle button to unsubscribe to your email notifications. The Off toggle button disables email notifications for all users.

Viewing a Build’s Details

From the build’s details page, you can view its status, duration, and download the artifacts.

To view a build’s details:

  1. In the navigation bar, click Build.

  2. Click the Jobs tab, if necessary.

  3. Click the build number link in the Build History table. You can also click the build number link in the job page.

Configuring a Build’s Details

You can update and configure a build’s details such as name and description. You can also mark a build to be kept forever and not removed by the job’s configuration of removing old builds.

To update and configure a build’s details:
  1. Click the build number link and open the build’s details page.
  2. Click Configure.
  3. In Build Description and Build Name, enter a description and a name.

    Adding a description and a name is helpful if you mark a particular build to keep it forever and not get discarded automatically. When you add a description to a build, an * is added to the build number in the Build History table.

  4. To keep a build forever, select the Keep Build Forever check box.
    The build is not discarded if the job is configured to remove old builds automatically. The Delete button is also disabled. The build is deleted only when the parent job is deleted.
  5. Click Save.

Viewing a Build’s Reports

A build generates various types of reports and logs such as SCM Changes, test results, and action history. You can open these reports from the Job Details page or the Build Details page.

The following table lists the various types of reports generated by a build. On the Job Details page or the Build Details page, click the report icon to view its details.

Report Description

SCM Changes SCM Changes

View all files that have changed in the build.

When a build is triggered, the build system checks the job’s Git repositories for any changes to the SCM. If there are any updates, the SCM Change log displays the files that were added, edited or removed.

Javadoc Javadoc

View Javadoc of the build.

The report is available only if the application’s build generated a Javadoc.

SCM Poll Log SCM Poll Log

View the Git SCM polling log of the build.

In the Job Details page of a job, click Latest SCM Poll Log Latest SCM Poll Log to view the Git SCM polling log of the last build.

Test Results Test Results

View the log of build’s JUnit test results.

To open the Test Suite details page, on the Test Results page, click the All Tests toggle button and click the suite name in the Suite Name column.

To view details of a test, on the Test Results page, click the All Failed Tests toggle button and then click the test name link in the Test Name column. You can also click the All Tests toggle button, open the test suite details page, and then click the test name link in the Test Name column.

Audit Audit

View the Audit log of user actions.

You can use the Audit log to track the user actions on a build. Use the log to see who performed particular actions on the job. For example, you can see who cancelled a build of the job, or who disabled the job and when was it disabled.

SonarQube Analysis Summary SonarQube Analysis Summary

View the SonarQube analysis report of the job.

Viewing a Build’s Log

After a build has run, you can view its log in the build console. The Build Log page displays the selected build’s log and provides a link to download the log file.

To view a build’s console:
  1. Open the build’s details page.
  2. Click Build Log Build Log.
    You can also click Build Log Build Log in the Build History label.
In the Console Output page, review the build log. If the log is displayed partially, click the Full Log link to view the entire log. To download the log as a text file, click the Download Console Output link.

Tip:

  • In the Jobs table of the Jobs Overview page, click Last Build Log Last build log to view the log of the last build of a job.

  • In the Job Details page of a job, click Latest Build Log Latest Build Log to view the build log of the last build.

Viewing SCM Changes Log

The SCM Change log displays the files that were added, edited, or removed from the job’s Git repositories before the build was triggered.

The Recent SCM Changes page that you open from the Jobs Overview page displays SCM commits from last 20 builds in the reverse order. The SCM Changes page that you open from the Build Details page displays SCM commits that happened after the previous build.

The log shows build ID, commit messages, commit IDs, and affected files.

Viewing a Build’s Test Results

You can view the JUnit test results of a build from the build’s details page.

From a build’s details page, click Test Results Test Results. The Test Results page displays details about all tests and all failed tests of the build. It also shows test metrics for total tests, passed tests, failed tests, skipped tests, error tests, and total duration of tests.

Click Show Show to download the test image. The image file name is same as the test name followed by —failed.

For example, if the test name is TestBuildPage.checkBuildCopyJob, the image file name would be TestBuildPage.checkBuildCopyJob-failed.png.

The supported image formats are .png, .jpg, .gif, .tif, .tiff, .bmp, .ai, .psd, .svg, .img, .jpeg, .ico, .eps, and .ps.

Video: Click Watch Watch to download the test video file. The video file name is same as the test suite name.

For example, if the test suite name is TestBuildPage, the video file name would be TestBuildPage.webm.

The supported formats are .mp4, .mov, .avi, .webm, .flv, .mpg, .gif, .wmv, .rm, .asf, .swf, .avchd, and .m4v.

Viewing Test Details

The Test Details page shows the test result, parent suite name, status, and duration of a test in a test suite.

To open the Test Details page, open the Test Results page, click the All Failed Tests toggle button and then click the test name link. You can also click the All Tests toggle button, open the test suite details page, and then click the test name link.

If the test has failed, click the image to download it. The image file name is same as the test name followed by -failed. Expand Error Message to see the error message and Stack Trace to see the stack trace report.

Viewing Test Suite Details

The Test Suite Details page shows all tests of the suite along with their status and duration.

You can open the Test Suite Details page from the Test Results page. Click the All Tests toggle button and then click the suite name link.

Viewing Test Results History

The Test Results History page displays a graphical representation of all tests of the job and a table summarizing the tests.

To open the Test Results History page, open the test results page, and click Test JUnit Results History.

Viewing a Build’s SCM Polling Log

If you have configured the build to run on a Git SCM polling schedule, you can view the Git SCM polling log in the Build details page.

To view the SCM polling log of a build, open the build’s details page and click SCM Poll Log SCM Poll Log. The SCM Poll Logs page displays the log of builds triggered by SCM polling. The log includes scheduled builds and builds triggered by SCM updates.

Viewing a Job’s User Action History

You can use the Audit log to track the user actions on a build. Use the log to see who performed particular actions on the job. For example, you can see who cancelled a build of the job, or who disabled the job and when was it disabled.

To open the Audit log, from the job’s details page, click Audit Audit.

The following information is displayed for the actions performed on the selected job.

  • Who created the job

  • Who started a build or how a build was triggered (followed by the build number), when the build succeeded or failed, and the duration of the build

    A build can also be triggered by a timer, a commit to a Git repository, or an upstream job.

  • Who aborted a build

  • Who changed the configuration of the job

  • Who disabled a job

  • Who enabled a job

Viewing a Job’s SonarQube Analysis Summary

The SonarQube Analysis Summary page displays the code quality report of the build.

To view the SonarQube analysis summary, from the job’s details page, click SonarQube Analysis Summary SonarQube Analysis Summary. The SonarQube Analysis Summary displays SonarQube server URL of the job and the analysis summary.

Viewing a Project’s Recent Build History

The Recent Build History page displays builds of all jobs of the project.

To view the build history, in the Build Queue box of the Build page, click the View Recent Build History link. The history page shows the log of all jobs and their builds. Click a job name link to open its job details page. Click a build number link to open its build details page. Click Console to open the build’s console and view the console log output.

Tip:

To sort the table data by a column, right-click inside the build history table column and select the sort order from the Sort context menu.

Deleting a Build

You can delete a build from the Build Details page.

When you delete a build, its artifacts, logs, and reports are deleted too. You cannot delete a build that is marked as Keep Forever.
To delete a build:
  1. Open the build’s details page.
  2. Click Delete.

Viewing a Project’s Recent Build History

You can use the Recent Build History page to view the builds of all jobs of the project.

To view recent build history:
  1. In the navigation bar, click Build.
  2. In the Build Queue box, click the View Recent Build History link.

Monitoring Jobs and Builds from IDEs

You can monitor jobs and builds from IDEs such as OEPE, NetBeans IDE, and JDeveloper.

See following topics for more information:

Using the WebLogic Maven Plugin

The WebLogic server includes a Maven plugin that you can use to perform various deployment operations against the server, such as deploy, redeploy, and update. The plugin is available in the Oracle Developer Cloud Service build executor.

To install and invoke the WebLogic Maven plugin from a project build job:
  1. Install the WebLogic Maven plugin (weblogic-maven-plugin.jar) into the Maven repository.
    As the Maven repository is always empty when a jobs starts, configure the job to install the plugin every time a build runs.
    1. Open the Configure Build Job page of the job.

      See Configuring a Job.

    2. Add a Unix Shell Builder.

      See Adding an Unix Shell Builder.

    3. Enter the following command in Script:

      mvn install:install-file -Dfile=$WLS_HOME/server/lib/weblogic-maven-plugin.jar -DpomFile=$WLS_HOME/server/lib/pom.xml

    4. Click Save.

  2. Invoke the WebLogic Maven plugin from your application’s pom.xml file.
    For example, to invoke the deploy operation:

    mvn com.oracle.weblogic:weblogic-maven-plugin:deploy

For more information about how to use the WebLogic Maven plugin, see Fusion Middleware Deploying Applications to Oracle WebLogic Server in Oracle Fusion Middleware Online Documentation Library.