Configure and Run Project Jobs and Builds

Oracle Developer Cloud
Service (DevCS) includes continuous integration services to build project source files. You can configure the builds from the Builds page.

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

What is a Build VM and a Build VM Template?

A Build Virtual Machine (VM) is an OCI Compute or an OCI Compute Classic VM that runs builds of jobs defined in the DevCS projects. A Build VM Template defines the operating system and the software installed on Build VMs.

An Organization Administrator creates Build VM templates and Build VMs. If you're an Organization Administrator, you first create Build VM templates with software that your organization members use. After creating the templates, you allocate some Build VMs to each Build VM template. When your organization's members create jobs, they associate the Build VM template with each job.

To configure a job to use software, such as Node.js or Docker, assign the Build VM template to the job. If you're a project member, you assign the Build VM template to the job from the job's configuration page.

Read these steps to understand what happens when a build runs:

The build executor checks the Build VM template of the job and then looks for a VM that's allocated to the template.

If a VM is available, the build executor immediately runs the build on it.

If all VMs are busy running builds of other jobs using the same Build VM template, the build executor waits until a VM becomes available and then runs the current job's build on it.

If a build is running on a VM for the first time or a VM wakes up after its sleep timeout period, the build executor first installs the software defined in the Build VM template. This takes some time.

After the build is complete, the executor copies the artifacts (if generated) to the OCI Object Storage bucket or the OCI Object Storage Classic container, as defined by the Organization Administrator.

The Build VM waits for some time for any queued builds. If no builds run in the wait time period, the Build VM uninstalls its software and stops.

What is a Job and a Build?

A Job is a configuration that defines the builds of your application. A Build is a result of a job’s run.

A job defines where to find the source code files, how and when to run builds, the software and the environment required to run builds. When a build runs, it creates packaged archives of the application that you can deploy to a web server. A job can have hundreds of builds. Each build would’ve its artifacts, logs, and reports.

Build Concepts and Terms

Here are some terms that this documentation uses to describe the build features and components.

Term

Description

Build System

Software that automates the process of compiling, linking and packaging the source code into an executable form.

Build executor

A basic block that enables a build to run a Build VM. Each build uses one build executor, or one Build VM.

Workspace

A temporary directory used by the build executor to download source code files and generate artifacts when a build runs.

Build artifact

A file generated by a build. It could be a packaged archive file, such as a .zip or .ear file, that you can deploy to a build server.

Trigger

A condition to run a build.

Software Versions in the Software Catalog

Some software in the Software Catalog are available in multiple versions. For example, Gradle is available in Gradle 2, Gradle 3, and Gradle 4 versions. Such software are called as Software Packages. The version number shown in the title is their base version (or the major version) and the number shown in Version is the minor version. The minor version is the actual software version that’ll be installed on the VM.

Here's an example. In this image, Gradle 2, 3, and 4 are the major versions and 2.14.1, 3.5.1, and 4.1 are the minor versions.

When a new minor version of a software package is available in the Software Catalog, all VM templates using that software package are updated automatically. For example, when Gradle 4.2 is available in the Software Catalog, all VM templates using the Gradle 4 package update automatically to use Gradle 4.2. If there’s an incompatibility between the upgraded software and other installed software of the VM template, an error is reported with suggestions about the cause of the error.

When a new major version of a software is available in the catalog, VM templates using the older versions of the software package aren’t updated automatically. The new major version of the software is added to the catalog as a separate package. For example, when Gradle 5 is available in the Software Catalog, all VM templates using Gradle 2, Gradle 3, or Gradle 4 aren’t updated automatically. You must manually update the VM templates to use the new package.

Set Up the Build System

Before your organization’s members can run builds, you must create Build VM templates and allocate Build VMs to those templates.

You must be the Organization Administrator to create and manage Build VM templates and Build VMs.

Create and Manage Build VM Templates

You can create and manage Build VM templates from the VM Templates page in Organization Administration.

Action

How To

Create a Build VM template

In the navigation bar, clickOrganization.

Click the Virtual Machines Templates tab.

Click + Create Template.

In the New VM Template dialog box, enter a name and description of the VM template. In Platform, select the operating system to run on the VM.

Click Create.

Configure a VM template’s software

In the navigation bar, clickOrganization.

Click the Virtual Machines Templates tab.

Select the template and click Configure Software.

If necessary, in Filter Software Packages, enter the search term and click the Search icon.

To see the latest version of the software, select the Show latest versions only check box. This is helpful if multiple versions of the same software are available in the catalog.

In the Software Catalog, click Add.

If a software is dependent on another software, a message informs you about the dependencies that must be added along to use the software.

Click Done.

Delete a VM template

In the navigation bar, clickOrganization.

Click the Virtual Machines Templates tab.

Select the template and click Delete.

In the Delete VM dialog box, click Yes to confirm.

Add and Manage Build VMs

When you add a Build VM, you allocate a VM on the linked Oracle Cloud Infrastructure
Compute Classic service to be used to run builds of jobs.

Tip:

To minimize build execution delays, set the number of VMs of a
specific Build VM template to the number of jobs that you expect to run in
parallel using that template. If the VM quota is available, that number of Build
VMs will be added to the Build Virtual Machines tab.

You can always return to the Build Virtual
Machines tab to add or remove VMs, based on your actual usage.
Note that the more VMs you have running at a specific time, the higher the cost.
To minimize the higher cost, use the Sleep Timeout setting on the Virtual
Machines page to automatically shut down inactive VMs.

Each build runs in one build executor, or one VM. You can build up to 99 builds in parallel using the same Build VM template.

Action

How To

Add a Build VM

In the navigation bar, clickOrganization.

Click the Build Virtual Machines tab.

In the Build VMs tab, click + Create VM.

In the Add Build VM dialog box, in Quantity, specify the number of VMs you want to allocate. In VM Template, select the Build VM template.

Click Add.

View a Build VM’s log

The Build VM’s log has entries for all events along with information about when the events occurred, the type of event, and event details.

In the Build VMs tab, select the VM. From the Template list, and select another template.

Delete a Build VM

When you delete a Build VM, it waits for all builds running on it to complete and won't accept new builds while it’s waiting for the running builds to complete. After all the builds are complete, it shuts down and is removed.

In the navigation bar, clickOrganization.

Click the Build Virtual Machines tab.

In the Build VMs tab, select the VM, click Actions, and select Delete.

The sleep timeout defines the duration (in minutes) a VM would be available in the active state if no builds run on it. By default it is 1500 minutes.

In the navigation bar, clickOrganization.

Click the Build Virtual Machines tab.

Click Sleep Timeout.

In the Sleep Timeout dialog box, change the timout duration, and clickSave.

After adding Build VMs, you can configure the jobs to use the VM templates.

Create and Manage Jobs

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

Action

How To

Create a blank job

In the navigation bar, clickBuilds.

In the Jobs tab, click + Create Job.

In the New Job dialog box, in Job Name, enter a unique name.

To link this job to a merge request, select the Use for Merge Request check box.

Select Create New.

In Software Template, select the Build VM template.

Click Create Job.

Copy an existing job

Sometimes, you may want to copy parameters and configuration of a job to another. You can do that when you create a job. You can’t copy the configuration of an existing job to another existing job.

After you create the new job, you can change the copied parameters and configuration.

In the navigation bar, clickBuilds.

In the Jobs tab, click + Create Job.

In the New Job dialog box, in Job Name, enter a unique name.

To link this job to a merge request, select the Use for Merge Request check box.

Select Copy existing job.

From the From Job drop-down list, select the source job.

In Software Template, select the Build VM template.

Click Create Job.

Configure a job

The job configuration page opens immediately after you create a job. You can also open it from the Jobs tab. Click Configure.

Run a build of a job

In the Jobs tab, click Build Now.

Delete a job

In the Jobs tab, click Delete.

Configure a Job

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

To open a job’s configuration page, in the Jobs tab of the Builds page, click the job’s name. In the job’s details page, click Configure. You can also open a job’s configure page from the Builds page. In the Jobs tab, for the job you want to configure, click Configure.

Access Project Git Repositories

You can configure a job to access project’s Git repositories and their source code files.

Open the job’s configuration page.

Click Configure, if necessary.

Click the Source Control tab.

From the Add Source Control list, select Git.

In Repository, select the Git repository to track.

When you created the job, if you selected the Use for Merge Request check box, the field is automatically populated with the ${GIT_REPO_URL} value. Don’t change it.

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

When you created the job, if you selected the Use for Merge Request check box, Branch is automatically populated with the ${GIT_REPO_BRANCH} value. Don’t change it unless you don’t want to link the job with a merge request.

Click Save.

You can specify multiple Git repositories. If you do, set Local Checkout Directory for all Git repositories.

Trigger a Build Automatically on SCM Commit

You can configure a job to monitor its Git repositories and trigger a build automatically after a commit is pushed to the Git repository.

Open the job’s configuration page.

Click Configure, if necessary.

Click the Source Control tab.

For the Git repository you want to monitor, select the Automatically perform build on SCM commit check box.

To specify a list of files and directories to track for changes in the repository, expand Advanced Git Settings, and enter the list in Included Region.

You can use regular expressions to specify files. Each entry must be separated by a new line. An empty list implies that all files and directories must be tracked.

For example, this list configures the job to trigger a build when a user adds or updates an .html, .jpeg, or .gif file in the myapp/src/main/web/ directory of the specified Git repository.

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

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

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

To specify a list of files and directories not to track for changes in the repository, expand Advanced Git Settings, and enter the list in Excluded Region.

You can use regular expressions to specify files. Each entry must be separated by a new line. An empty list implies that all files and directories must be tracked. If a change occurs in any of the specified files or directories, a build won’t run. If there’s an overlap between included and excluded regions, exclusions take precedence over inclusion.

To exclude users whose commits to the repository don’t trigger builds, in Excluded User, enter the list of user names.

Trigger a Build Automatically on SCM Polling

SCM polling enables you to configure a job to periodically check the job’s Git repositories for any commits pushed since the job’s last build. If updates are found, it triggers a build. You can configure the job and specify the schedule in Coordinated Universal Time (UTC). UTC is the primary time standard by which the world regulates clocks and time.

You specify the schedule using Cron expressions. If you’re not a Cron expert, use the novice mode and set the schedule by specifying values. If you’re a Cron expert, use the Expert mode.

Open the job’s configuration page.

In the Source Control tab, add the Git repository.

Click Settings.

Click the Triggers tab.

Click Add Trigger and select SCM Polling Trigger.

To use the expert mode, select the Expert mode check box and enter the schedule in the text box.

The default pattern is 0/30 * * * *, which runs a build every 30 minutes.

After you edit the expression, it’s validated immediately when the cursor moves out of the text box. Note that other fields of the section aren’t available when the check box is selected.

To use the novice mode, deselect the Expert mode check box and specify the schedule information. The page displays the generated Cron expression next to the Expert mode check box.

To use the novice mode, deselect the Expert mode check box and specify the schedule information in Minute, Hour, Day of the Month, Month, and Day of the Week.

Click Toggle Recurrence to add or remove 0/or 1/ at the beginning of the value in the Cron expression.

The page displays the generated Cron expression next to the Expert mode check box.

Tip:

To check the job’s Git repositories every minute, deselect all check boxes. Remember that this may consume large amounts of system resources.

If necessary, in Comment, enter a comment.

To view and verify the build schedule of the next ten builds, from the timezone drop-down list, select your time zone and then click View Schedule.

Click Save.

To see the SCM poll log of the job after the build runs, in the job's details page or the build's details page, click SCM Poll Log.

Generate Cron Expressions

You can use Cron expressions to define periodic build patterns.

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

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

Use External Git Repositories

If you use an external Git repository to manage source code files, you can configure a job to access its files when a build runs.

If the external Git repository is a public repository, mirror it in the project or use its direct URL in the job configuration. If the external Git repository is a private repository, you must mirror it in the project. See Mirror an External Git Repository.

To configure a job to use an external Git repository:

Open the job’s configuration page.

Click Configure, if necessary.

Click the Source Control tab.

From the Add Source Control list, select Git.

If the external Git repository is mirrored with the project, in Repository, select the repository name. Note that the build executor uses the internal address URL of the mirrored repository.

If the external Git repository isn't mirrored with the project, enter the repository's direct URL. Don't enter the direct URL of a private repository.

Configure other fields of the page and click Save.

To trigger a build on an update to the external Git repository, set up SCM polling according to the frequency of commits. DevCS can't trigger a build immediately on an update to the external Git repository.

Before you set SCM polling, note that if you use the internal address URL of a mirrored repository, there's a wait time of at least 5 minutes. If you use the external address URL or the direct URL of the repository, there's a wait time of at least 1 minute. Remember that polling every few minutes consumes large amounts of system resources.

Publish Git Artifacts to a Git Repository

Git artifacts, such as tags, branches, and merge results can be published to a Git repository as a post-build action.

Open the job’s configuration page.

Click Configure.

In the Source Control tab, add the Git repository where you want to publish Git artifacts..

Click the Post Build tab.

Click Add Post Build Action and select Git Publisher.

To push Git artifacts to the Git repository only if the build succeeds, select the Publish only if build succeeds check box.

To push merges back to the target remote name, select the Merge results check box.

To push a tag to the remote repository, in Tag to push, specify the Git repository tag name. You can also use environment variables. In Target remote name, specify the target remote name of the Git repository where the tag is pushed. By default, origin is used.

The push fails if the tag doesn’t exist. Select the Create new tag check box to create the tag and enter a unique tag name.

To push a branch to the remote repository, in Branch to push, specify the Git repository branch name. You can also use environment variables. In Target remote name, specify the target remote name of the Git repository where the branch is pushed. By default, origin is used.

Click Save.

Advanced Git Options

When you configure the Git repositories of a job, you can also configure the job with some advanced Git options, such as change the remote name of the repository, set the checkout directory in the workspace, and whether to clean the workspace before a build runs.

You can perform these configuration actions from the Source Control tab of the job configuration page.

Action

How To

Change the remote name of a repository

For the Git repository, expand Advanced Repository Options, and specify the new name in Name. The default remote name is origin.

Specify a reference specification of a repository

A reference repository helps to speed up the builds of the job by creating a cache in the workspace and hence reducing the data transfer. When a build runs, instead of cloning the Git repository from the remote, the build executor clones it from the reference repository.

To create a reference specification of a Git repository, expand Advanced Repository Options, and specify the name in Ref Spec.

Leave the field empty to create a default reference specification.

Specify a local checkout directory

The local checkout directory is a directory in the workspace where the Git repository is checked out when a build runs.

To specify the directory of a Git repository, expand Advanced Repository Options, and specify the path in Local Checkout Directory. If left empty, the Git repository is checked out on the root directory of the workspace.

Checkout the remote repository’s branch and merge it into a local branch

Expand Advanced Git Settings, in Merge another branch, specify the branch name to merge to. If specified, the build executor checks out the revision to build as HEAD on this branch.

If necessary, in Checkout revision, specify the branch to checkout and build as HEAD on the value of Merge another branch.

Configure Git user.name and user.email variables

Expand Advanced Git Settings and in Config user.name and Config user.email, specify the user name and the email address.

Merge to a branch before a build runs

Expand Advanced Git Settings and select the Merge from another repository check box.

In Repository, enter or select the name of the repository to be merged. In 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.

When a build runs, the build executor checks out the Git repository to the local repository of the workspace and applies a tag to it. To skip this process, expand Advanced Git Settings and deselect Skip internal tag check box.

View 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.

You can view the SCM changes log from the job’s details page and a build’s details page. The Recent SCM Changes page that you open from the job’s details page displays SCM commits from last 20 builds in the reverse order. The SCM Changes page that you open from a build’s details page displays SCM commits that happened after the previous build.

Trigger a Build Automatically on a Schedule

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

You can specify the schedule using Cron expressions. If you’re not a Cron expert, use the novice mode and set the schedule by specifying values. If you’re a Cron expert, use the Expert mode.

Open the job’s configuration page.

Click Settings.

Click the Triggers tab.

Click Add Trigger and select Periodic Build Trigger.

To use the expert mode, select the Expert mode check box, and enter the schedule in the text box.

The default pattern is 0/30 * * * *, which runs a build every 30 minutes.

After you edit the expression, it’s validated immediately when the cursor moves out of the text box. Note that other fields of the section aren’t available when the check box is selected.

To use the novice mode, deselect the Expert mode check box and specify the schedule information. The page displays the generated Cron expression next to the Expert mode check box.

To use the novice mode, deselect the Expert mode check box and specify the schedule information in Minute, Hour, Day of the Month, Month, and Day of the Week.

Click Toggle Recurrence to add or remove 0/ or 1/ at the beginning of the value in the Cron expression.

The page displays the generated Cron expression next to the Expert mode check box.

If necessary, in Comment, enter a comment.

To view and verify the build schedule of the next ten builds, from the timezone drop-down list, select your time zone and then click View Schedule.

Click Save.

Use Build Parameters

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

You can configure the job to use the parameter and its value as an environment variable or through variable substitution in other parts of the job configuration. When a build runs, a Configure Parameters dialog box opens where the user can enter or change the default values of the parameters.

Accept a string value from the user when a build runs. The parameter field appears as a text box in the Configure Parameters dialog box.

Password

Accept a password value from the user when a build runs. The parameter field appears as a password box in the Configure Parameters dialog box.

Boolean

Accept true or false as input from the user when a build runs. The parameter field appears as a check box in the Configure Parameters dialog box.

Choice

Accept a value from a list of values when a build runs. The parameter field appears as a check box in the Configure Parameters dialog box.

Merge Request

Accept a string value for the Git repository URL, the Git repository branch name, and the merge request ID as input. The parameter field appears as a text box in the Configure Parameters dialog box.

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

Click Save.

While creating the job, if you selected the Use for Merge Request check box, GIT_REPO_URL, GIT_REPO_BRANCH, and MERGE_REQ_ID Merge Request parameters are automatically added 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.

To learn about how to use build parameters in a Shell build step, see the GNU documentation on Shell Parameter Expansion at https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html.

Access an Oracle Cloud Service Using SSH

You can configure a job to use SSH to access any Oracle Cloud service instances 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 the provided keys in the build’s workspace for use with the command-line tools. The modifications revert when the job finishes.

To connect to the Oracle Cloud service instance, you need IP address of the server, credentials of a user who can connect to the service instance, and local and remote port numbers.

Open the job’s configuration page.

Click Configure, if necessary.

Click the Build Environment tab.

Click Add Build Environment and select SSH Configuration.

In Private Key and Public Key, enter the private and the public key of your SSH Private-Public key pair.

Leave the Public Key empty to use fingerprint.

In Pass Phrase, enter the pass phrase of your SSH Private-Public key pair. Leave it empty if the keys aren’t encrypted with a pass phrase.

In SSH Server Public Key, enter the public key of the SSH server.

If you’re using a command-line SSH tool, note that the host name and the IP address must match. 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, such as ssh, add the -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null option explicitly to skip host verification.

To use an SSH tunnel, select the Create SSH Tunnel check box.

SSH tunnel provides an additional layer of security and can only be set up between trusted hosts. After you select the check box, enter the SSH server details.

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 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.

To use command line tools (such as ssh, scp, or sftp), select the Setup files in ~/.ssh for command-line ssh tools check box.

When a build runs, necessary files with the information that you’ve 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.

Click Save.

Access the Oracle Maven Repository

The Oracle Maven Repository contains artifacts, such as ADF libraries, provided by Oracle. You may require these artifacts to compile, test, package, perform integration testing, or deploy your applications. For more information about the Oracle Maven repository, see https://maven.oracle.com/doc.html.

To build your applications and access the Oracle Maven Repository, you configure the job and provide your credentials to access the repository.

If you’re a project owner, set up Oracle Maven Repository connections for the project’s team members.

Create and configure a job to access Oracle Maven Repository.

Create and Manage Oracle Maven Repository Connections

If your project users access the Oracle Maven Repository frequently, you can create a pre-defined connection for them. Project users can then configure a job and use the connection to access the artifacts of the Oracle Maven Repository while running builds.

To create a connection, you’d need the Oracle Technology Network (OTN) Single Sign-On (SSO) credentials of a user who has accepted the Oracle Maven Repository license agreement.

You must be assigned the project Owner role to add and manage Oracle Maven Repository connections.

Configure a Job to Connect to the Oracle Maven Repository

From Use Existing Connection, select a pre-defined connection. Your project owner has created a connection so that you don't have to worry about setting it up.

If there’s no pre-defined connection available or you want set up your own connection, click the toggle button. In OTN Username and OTN Password, enter the credentials of a user who has accepted the Oracle Maven Repository license agreement.

In Server Id, if required, enter the ID to use for the <server> element of the Maven settings.xml file, or use the default maven.oracle.com ID.

If you’re using a custom settings.xml file, in Custom settings.xml, enter the file’s path.

Click Save.

Run UNIX Shell Commands

You can configure a job to run a shell script or commands when a build runs.

Open the job’s configuration page.

Click Configure.

Click the Steps tab.

From Add Step, select Unix Shell.

In Script, enter the shell script or commands.

The script runs with the workspace as the current directory. If there is no header line, such as #!/bin/sh specified in the shell script, then the system shell is used. You can also use the header line to write a script in another language, such as Perl (#!/bin/perl) or control the options that shell uses.

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.

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

To show the command as-it-is in the build log, select the (-v) Show commands exactly as written option.

Click Save.

Tip:

By default, when a build runs, it invokes the shell with the -ex option. It prints all commands before they run. The build fails if any of the commands exits with a non-zero exit code. You can change this behavior by adding the #!/bin/... line in the shell script.

Don’t enter a long shell script. For a long script, create a script file, add it to the Git repository, and run the script with a command (such as bash -ex /myfolder/myscript.sh).

To run Python 3, create an isolated environment using virtualenv. To learn more, see https://virtualenv.pypa.io/en/stable/.

For example, add these commands as a Shell build step to create a virtual environment:

If both Python 2 and Python 3 are available in the job’s Build VM template, to call Python, use these commands.

Command

Version

python

python2

Python 2

python3

Python 3

pip

pip of Python 3

pip3

pip of Python 3

To clone an external Git repository using a shell command, use the internal URL of the external Git repository. To copy the URL, open the Git page and, from the Repositories drop-down list, select the external Git repository. From the Clone menu, click Copy to clipboard of the Clone with HTTPS from internal address URL.

If you’re using an Oracle Linux 6 VM in your job, remove the username from the URL before using it in a shell command. For example, if the copied URL is https://alex.admin@developer.us2.oraclecloud.com/mydomain-usoracle22222/s/developer1111-usoracle22222_myproject/scm/myextrepo.git, then remove alex.admin@ from the URL and use https://developer.us.oraclecloud.com/mydomain-usoracle22222/s/mydomain-usoracle22222_myproject/scm/mydomain-usoracle22222_myproject.git in your shell command.

Build Maven Applications

Using Apache Maven, you can automate your build process and download dependencies, as defined in the POM file.

Upload the Maven POM files to the project Git repository.

Open the job’s configuration page.

Click Configure.

In the Source Control tab, add the Git repository where you uploaded the build files.

Click the Steps tab.

From Add Step, select Maven.

In Goals, 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.

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

If necessary, specify the advanced Maven options.

Action

How To

Use a private repository for builds

Select the Use Private Repository check box.

You may want to use it to make sure that other Maven build artifacts don’t interfere with the artifacts of this job’s builds. When a build runs, it creates a Maven repository .maven/repo directory in the build executor workspace. Remember selecting this option consumes more storage space of the workspace.

Use a private temporary directory for builds.

Select the Use Private Temp Directory check box.

You may want to use it to create a temporary directory for artifacts or temporary files. When a build runs, it creates a .maven/tmp directory in the workspace. The temporary files may consume large amount of storage, so, remember to clean up the directory regularly.

Work offline and don’t access remote Maven repositories

Select the Offline check box.

Activate Maven profiles

In Profiles, enter a list of profiles, separated by commas.

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

Set custom properties

In Properties, enter custom system properties in the key=value format, specifying each property on its own line. When a build runs, the properties are passed to the build executor in the standard way (example: -Dkey1=value1 -Dkey2=value2)

Set the Maven verbosity level

From Verbosity, select the level.

You may want to use it to set the verbosity of the Maven log output to the build log.

Set the checksum mode

From Checksum, select the mode.

You may want to use it to set the check-sum validation strictness when the build downloads artifacts from the remote Maven repositories.

Set handling of the SNAPSHOT artifacts

From Snapshot, select the mode.

Include other Maven projects to the reactor

In Projects, enter the comma or space separated list of Maven project jobs to include in the reactor. The reactor is a mechanism in Maven that handles multi-module projects. A project job can be specified by [groupId]:artifactId or by its relative path.

Resume a Maven project from the reactor

In 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.

Set the failure handling mode

From Fail Mode, select the mode.

You may want to use it to set how the Maven build proceeds in case of a failure.

Set the Make-like reactor mode

From Make Mode, select the mode. You may want to use it enable Make-like build behavior.

Configure the reactor threading model

In Threading, enter the value for experimental support for parallel builds. For example, a value of 3 indicates three threads for the build.

Pass parameters to Java VM

In JVM Options, enter the parameters. The build passes the parameters as MAVEN_OPTS.

Click Save.

Use 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 DevCS build executor.

When a build runs, the build executor creates an empty Maven repository in the workspace. To install the WebLogic plugin every time a build starts, in the job configuration, add a shell command to install the plugin and then deploy it.

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.

Note that the credentials in settings.xml aren’t required to access the project’s Maven repository when running a build. The Build job has full access to the project’s Maven repository for uploads and downloads.

Build Ant Applications

Using Apache Ant, you can automate your build processes as described in its build files. For more information, see https://ant.apache.org/.

Upload the Ant build files (such as build.xml and build.properties) to the project Git repository.

Open the job’s configuration page.

Click Configure.

In the Source Control tab, add the Git repository where you uploaded the build files.

Click the Steps tab.

From Add Step, select Ant.

In Targets, specify the Ant targets or leave it empty to run the default Ant target specified in the build file.

In Build File, specify the path of the build file.

If necessary, in Properties, specify the values for properties used in the Ant build file.

Example:

# comment
name1=value1
name2=$VAR2

When a build runs, these are passed to Ant as -Dname1=value1 -Dname2=value2. You should always use $VAR for parameter references (don’t use%VAR%). Use \\to escape a \ and avoid using double-quotes ("). To define an empty property, use varname=in the script.

If your build requires a custom ANT_OPTS, specify it in Java Options. You may use it to specify Java memory limits (example: -Xmx512m). Don’t specify other Ant options here (such as -lib), but specify them in Targets.

Click Save.

Build Gradle Applications

Using Gradle, you can automate your build processes as defined in its build script. For more information about Gradle, see https://gradle.org/.

Set Up a Build VM and a Build VM Template with Gradle

Before you can use Gradle, you must create a Build VM template that includes Gradle and then add a Build VM that uses the VM template. If you don’t want to create a template, you can add the software to an existing template. After adding a Build VM, create and configure a job to use the Build VM template and add Gradle commands.

You must be the Organization Administrator to create a Build VM template and add a Build VM.

In the Software Catalog, search for Gradle. To see the latest version only, select the Show latest versions only check box.

Select the software tile and click Done.

Click Build Virtual Machines tab.

Click + Create VM.

In the Add Build VM dialog box, in Quantity, specify the number of VMs you want to allocate. In VM Template, select the Gradle template.

Click Add.

Configure a Job to Run Gradle Commands

Upload the build.gradle file to the project Git repository.

Open the job’s configuration page.

If you're creating a job, in Software Template of the New Job dialog box, select the Gradle template. Jump to step 5.

Click Settings.

In the Software tab, select the Gradle template.

Click Configure.

In the Source Control tab, add the Git repository where you uploaded the build file.

Click the Steps tab.

From Add Step, select Gradle.

To call the default Gradle script, select Invoke From.

To use a Gradle wrapper script, select Use Gradle Wrapper. To use the gradlew command as an executable command, select the Make gradlew executable check box. To use the gradlew command from the root build script directory, select the From Root Build Script Dir check box.

In Tasks, enter Gradle tasks.

In Build File, enter the name and path of the Gradle build.gradle file.

In Build file folder, enter the path and directory name of the top-level build.gradle file if it’s available in a directory other than the module root directory. The path must be relative to the root directory.

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

In Switches, enter Gradle switches.

If you’re using a multi-executor slave, select the Force GRADLE_USER_HOME to use workspace 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.

Click Save.

Build Node.js Applications

Using Node.js, you can develop applications that run JavaScript on a server. For more information, see https://nodejs.org.

Set Up a Build VM and a Build VM Template with Node.js

Before you can use Node.js, you must create a Build VM template that includes Node.js and then add a Build VM that uses the VM template. If you don’t want to create a template, you can add the software to an existing template. After adding a Build VM, create and configure a job to use the Build VM template and add a Node.js script.

You must be the Organization Administrator to create a Build VM template and add a Build VM.

In the Software Catalog, search for Node.js. To see the latest version only, select the Show latest versions only check box.

Select the software tile and click Done.

Click Build Virtual Machines tab.

Click + Create VM.

In the Add Build VM dialog box, in Quantity, specify the number of VMs you want to allocate. In VM Template, select the Node.js template.

Click Add.

Configure a Job to Build a Node.js Application

If you have a Node.js script, upload it to the project Git repository.

Open the job’s configuration page.

If you're creating a job, in Software Template of the New Job dialog box, select the Node.js template. Jump to step 5.

Click Settings.

In the Software tab, select the Node.js template.

Click Configure.

In the Source Control tab, add the Git repository where you uploaded the script file.

Click the Steps tab.

From Add Step, select Node.js.

To specify the script file, in Source select NodeJS File. In NodeJS File Path, specify the file path in the Git repository.

To specify the script, in Source select Script. In NodeJS Script, enter the script.

Click Save.

Access an Oracle Database Using SQLcl

Using SQLcl, you can run SQL statements from a build to connect and access an Oracle Database. You can use SQLcl to access any Oracle Database available on public internet that you can connect to using a JDBC connect string. You can run DML, DDL, and SQL Plus statements. You can also use SQLcl in a test scenario and run SQL scripts to initialize seed data or validate database changes.

SQLcl requires Java SE 1.8 or later. To learn 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 connect to Oracle Database Exadata Express Cloud
Service, download the ZIP file that contains its credentials and upload it to the job’s Git repository. You can download the ZIP file from the Oracle Database Cloud Service service console. See Downloading Client Credentials in Using Oracle Database Exadata Express Cloud
Service.

Set Up a Build VM and a Build VM Template with SQLcl

Before you can use SQLcl, you must create a Build VM template that includes SQLcland then add a Build VM that uses the VM template. If you don’t want to create a template, you can add the software to an existing template. After adding a Build VM, create and configure a job to use the Build VM template and add a SQLcl commands.

You must be the Organization Administrator to create a Build VM template and add a Build VM.

In 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.oracle.com:1521:adt1100 where adt1100 is the SID, and test_server.oracle.com:1521/ora11g where ora11g is the service name.

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

You can also use build parameters in Connect String.

If the SQL statements are available in a file uploaded to the project Git repository, in Source, select SQL File. In SQL File Path, enter the Git repository path of the SQL file. You can copy the file’s path from the Git page.

To enter SQL statements, in Source, select Inline SQL. In SQL Statements, enter the SQL statements. You can also use build parameters in SQL Statements.

In Role, if necessary, select the database role of the user.

In Restriction Level, if necessary, specify the restriction level on the type of SQL statements that are allowed to run.

Click Save.

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

Run Oracle PaaS Service Manager Commands Using PSMcli

Using Oracle PaaS Service Manager command line interface (PSMcli) commands, you can create and manage the lifecycle of various services in Oracle Public Cloud. You can create service instances, start or stop instances, or remove instances when a build runs.

Set Up a Build VM and a Build VM Template with PSMcli

Before you can use PSMcli, you must create a Build VM template that includes PSMcli and then add a Build VM that uses the VM template. If you don’t want to create a template, you can add the software to an existing template. After adding a Build VM, create and configure a job to use the Build VM template and add PSMcli commands.

You must be the Organization Administrator to create a Build VM template and add a Build VM.

To configure the job, you need the User OCID, private key, and fingerprint of a user who can create and access the resources, and the tenancy name. Contact the OCI administrator and get the required OCI input values. See Get the OCI Input Values to learn where to find the input values.

Set Up a Build VM and a Build VM Template with OCIcli

Before you can use OCIcli, you must create a Build VM template that includes OCIcli and then add a Build VM that uses the VM template. If you don’t want to create a template, you can add the software to an existing template. After adding a Build VM, create and configure a job to use the Build VM template and add OCIcli commands.

You must be the Organization Administrator to create a Build VM template and add a Build VM.

In the Software Catalog, search for OCIcli. To see the latest version only, select the Show latest versions only check box.

Select the software tile and click Done.

Click Build Virtual Machines tab.

Click + Create VM.

In the Add Build VM dialog box, in Quantity, specify the number of VMs you want to allocate. In VM Template, select the OCIcli template.

Click Add.

Configure a Job to Run OCIcli Commands

Open the job’s configuration page.

If you're creating a job, in Software Template of the New Job dialog box, select the PSMcli template. After creating the job, jump to step 4.

Click Settings.

In the Software tab, select the OCIcli template.

Click Configure.

Click the Steps tab.

From Add Step, select OCIcli.

In User OCID, enter the OCID of the user who can access or create OCI resources.

In Fingerprint, enter the public key fingerprint of the user.

In Tenancy, enter the tenancy OCID.

In Private Key, enter the private key of the user.

In Region, select the Oracle Cloud
Infrastructure tenancy’s region.

Scroll up and from Add Step, select Unix Shell.

In Script, enter the OCIcli commands on separate lines.

Click Save.

You can add multiple Unix Shell steps to run different group of commands. Don’t add the OCIcli build step again.

Run Docker Commands

You can configure a job to run Docker commands on a Docker container when a build runs.

You should use the Docker container for short tests and builds. Don’t run a Docker container for long tests or builds, else the builds might not finish. For example, if you use a Docker image that’s listening on a certain port and behaves as a web server, the build won’t exit.

For more information about Docker commands, see https://docs.docker.com/.

Tip:

If you face a network issue while running a Docker command, add the HTTP_PROXY and HTTPS_PROXY environment variables in the Docker file.

Set Up a Build VM and a Build VM Template with Docker

Before you can use Docker, you must create a Build VM template that includes Docker and then add a Build VM that uses the VM template. If you don’t want to create a template, you can add the software to an existing template. After adding a Build VM, create and configure a job to use the Build VM template and add Docker commands.

You must be the Organization Administrator to create a Build VM template and add a Build VM.

In the Software Catalog, search for Docker. To see the latest version only, select the Show latest versions only check box.

Select the software tile and click Done.

Click Build Virtual Machines tab.

Click + Create VM.

In the Add Build VM dialog box, in Quantity, specify the number of VMs you want to allocate. In VM Template, select the Docker template.

Click Add.

Configure a Job to Run Docker Commands

Open the job’s configuration page.

If you're creating a job, in Software Template of the New Job dialog box, select the Docker template. Jump to step 4.

Click Settings.

In the Software tab, select the Docker template.

Click Configure.

Click the Steps tab.

From Add Step, select Docker, and then select the Docker command.

Use this command ...

To ...

login

Log in to the Docker registry.

In Registry Host, select a pre-linked Docker registry, or enter the Docker registry’s host name where the images are stored. Leave it empty to use Docker Hub.

In Username and Password, enter the credentials of the user who can access the Docker registry.

build

Build Docker images from a Dockerfile.

Specify the registry host name, Docker image name, its version tag, Docker options, and name and the source of the Dockerfile. You can upload the Dockerfile in the Git repository and provide its path, add the Dockerfile code manually, or provide its URL if it’s available on an external source.

To specify an external source, include the protocol (example, http) in the URL if you’re referencing a remote tar file (example: http://55.555.555.555/me/mydocker.tar.gz). Ignore the protocol if you’re referencing a remote repository (example: git://github.com/me/my.git#mybranch:myfolder).

To learn more about Docker build command options, see https://docs.docker.com/engine/reference/commandline/build/.

tag

Create a target image tag that refers to the source image.

Specify the registry host name, Docker image name, and its version tag name for the source and target images.

push

Push an image to the Docker registry.

To learn more about push options, see https://docs.docker.com/engine/reference/commandline/push/.

images

List available images.

To learn more about images, see https://docs.docker.com/engine/reference/commandline/images/.

save

Save an image to a .tar archive file.

In Output File, specify the relative path and name of the output .tar file in the workspace.

load

Load an image from a .tar archive file.

In Output File, specify the relative path and name of the output .tar file in the workspace.

rmi

Remove an image. You can remove new images, a specific image, or all images.

To remove a specific image, enter the host name of the registry where the Docker images are stored. Remember that 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 computer where the image is being created.

version

View the version of Docker on the build executor.

Click Save.

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

Get Wercker Authentication Token

To trigger the Wercker pipeline from a job’s build, you need your Wercker account’s token.

In a web browser, open https://app.wercker.com/sessions/new and log in using your Wercker or GitHub account.

In the top-right corner of the page, click the user icon and select Settings.

In the left navigation bar, click Personal Tokens.

In Token Name, enter a name and click Generate.

This is required if you create a new build.

Copy the generated token value and keep it safe.

It is important that you save the generated token because you can’t view or copy the token later.

Configure a Job to Trigger the Wercker Pipeline

Open the job’s configuration page.

Click Configure.

Click the Steps tab.

From Add Step, select Wercker.

In Token, paste the copied Wercker’s authentication token.

Verify the values of Application, Pipeline, and Branch.

The fields are automatically populated.

In Message, enter a message to be passed to Wercker. When a build runs, the message is displayed in the Runs tab of Wercker.

Click Save.

When a build of the job runs, it triggers the specified Wercker pipeline.

Run Fn Commands

Fn, or Fn Project, is an open-source, container-native, serverless platform for building, deploying, and scaling functions in multi-cloud environments. To run Fn commands when a build runs, you must have access to a Docker container that has a running Fn server.

For more information about Fn, see https://fnproject.io/.

Set Up a Build VM and a Build VM Template with Fn

Before you can use Fn, you must create a Build VM template that includes Fn and then add a Build VM that uses the VM template. If you don’t want to create a template, you can add the software to an existing template. After adding a Build VM, create and configure a job to use the Build VM template and add Fn commands.

You must be the Organization Administrator to create a Build VM template and add a Build VM.

In the Software Catalog, search for Fn. To see the latest version only, select the Show latest versions only check box.

Select the software tile and click Done.

Click Build Virtual Machines tab.

Click + Create VM.

In the Add Build VM dialog box, in Quantity, specify the number of VMs you want to allocate. In VM Template, select the Fn template.

Click Add.

Configure a Job to Run Fn Commands

Open the job’s configuration page.

If you're creating a job, in Software Template of the New Job dialog box, select the Fn template. Jump to step 4.

Click Settings.

In the Software tab, select the Fn template.

Click Configure.

Click the Steps tab.

From Add Step, select Fn, and then select the command.

Use this option ...

To ...

Fn Build

Build a new function.

Specify the relative path of the working directory to build the function, Fn build arguments, Docker registry host, and its user name. If you don’t want to use Docker registry’s cache, deselect the Use Docker Cache check box. To display the command’s log in the build’s log, select the Verbose Output check box.

Fn Push

Push the image to the Docker registry.

Specify the relative path of the working directory, Docker registry host, and its user name. To display the command’s log in the build’s log, select the Verbose Output check box.

Fn Bump

Bump the version of the func.yaml file.

Specify the relative path of the working directory and the bump type (Major, Minor, or Patch). To display the command’s log in the build’s log, select the Verbose Output check box.

Fn Test

Run Fn tests, if available, against the Fn server.

Specify the relative path of the working directory. To run tests of all functions, select the Test all functions in the app check box. To display the command’s log in the build’s log, select the Verbose Output check box.

Fn Deploy

Deploy functions to the function server. Using the deploy command, you can bump, build, push and update a function.

In Deploy to App, specify the Fn app name to deploy to. In other fields, specify the working directory, build arguments, Docker registry host, user name, API URL, and the Call URL. Select the desired check boxes, if necessary.

Click Save.

Use SonarQube

SonarQube is an open source quality management software that enables you to continuously analyze your application. When you configure a job to use SonarQube, the build generates an analysis summary that you can view from the job or the build details page.

To learn about SonarQube, see its documentation at https://docs.sonarqube.org.

Set Up SonarQube

To set up a SonarQube system for your project users, you can create a pre-defined SonarQube connection for your users.

To create the connection, you need the URL of a SonarQube Server available on the public internet.

You must be assigned the project Owner role to add and manage SonarQube connections.

Action

How To

Add a SonarQube connection

In the navigation bar, clickProject Settings.

Click Build.

Expand SonarQube Server.

Click Add SonarQube Server Connection.

In the Create SonarQube Server dialog box, enter a name for the server, provide the SonarQube server’s URL, and the credentials of a user who has access to the server.

Click Create.

Edit a connection

To change the connection’s user credentials or provide another server ID, you can edit the connection.

In the navigation bar, clickProject Settings.

Click Build.

Expand SonarQube Server.

Click the connection name and then click the Edit icon.

In the Edit SonarQube Server dialog box, as necessary, update the SonarQube server’s URL and the credentials of a user who can access the server.

Click Update.

Delete the connection

In the navigation bar, clickProject Settings.

Click Build.

Expand SonarQube Server .

Click the connection name and then click .

In the Delete SonarQube Server dialog, click Delete.

Configure a Job to Connect to SonarQube

You can configure a job to use SonarQube from the Build Environments tab and add a post-build action to publish its reports.

Open the job’s configuration page.

Click the Build Environment tab.

From Add Build Environment, select SonarQube Settings.

From Sonar Server, select the pre-configured SonarQube server.

The Username, Password, and SonarQube Server URL display the details of the selected user. To add a server, contact the organization administrator.

To provide the SonarQube project name and the SonarQube project key, expand Advanced SonarQube Settings, and update the values. Make sure that the SonarQube project key is unique.

By default, the project key is set to <organization>_<projectname>.<jobname>and the project name is set to <projectname>.<jobname>.

Click the Post Build tab.

From Add Post Build Action, select SonarQube Result Publisher.

To use the SonarQube Quality Gate status as the build status, select the Apply SonarQube quality gate status as build status check box.

If the SonarQube Quality Gate status is Passed, the build is marked as successful. If the SonarQube Quality Gate status is Failed, the build is marked as failed. To learn about SonarQube Quality Gates, see https://docs.sonarqube.org/display/SONAR/Quality+Gates.

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

Use Named Passwords

A named password is a variable that users can use across a project's build job configurations. The named password can be used in any password field in the job configuration, such as external Git repositories, SQLcl, PSMcli, and Docker configurations.

When the password changes, change the value of the variable and the new password is applied to all jobs and configurations where the variable is used. Note that the named password is not an environment variable. To use a named password as an environment variable, create a Password build parameter and set it to use the named password.

Create a Named Password

You must be assigned the project Owner role to create a named password.

Action

How To

Create a named password

In the navigation bar, clickProject Settings.

Click Build.

Expand Named Passwords.

Click + Create.

In the Create New Named Password dialog box, in Name, enter a name for the variable. In Password, enter the password.

Click Create.

After creating the named password, share its name with your project users.

Edit a named password

In the navigation bar, clickProject Settings.

Click Build.

Expand Named Passwords.

Click the password name and then click .

In the Edit Named Password dialog box, update the password.

You can't change the named password's name.

Click Update.

Delete the named password

In the navigation bar, clickProject Settings.

Click Build.

Expand Named Passwords.

Click the named password name and then click .

In the Delete Named Password dialog box, click Delete.

After deleting the named password, let your project users know that it's no longer available.

Configure a Job to Use a Named Password

Open the job’s configuration page.

In the Password field of the component you want to configure, enter the named variable as #{password_name}.

For example, if the name of the named password is my_password, enter #{my_password}.

Click Save.

Publish JUnit Results

If you use JUnit in your application to run test scripts, you can configure your job to publish JUnit test reports and get useful information about test results, such as historical test result trends, failure tracking, and so on.

Upload your application with test script files to the Git repository.

Open the job’s configuration page.

Click the Post Build tab.

From Add Post Build Action, select JUnit Publisher.

In Include JUnit XMLs, specify the path and names of XML files to include. You can also use wildcards.

For example, if you’re using Ant, specify the path as **/build/test-reports/*.xml. If you’re using Maven, specify the path as target/surefire-reports/*.xml. Make sure that you don’t include any non-report files into this pattern.

In Exclude JUnit XMLs, specify the path and names of XML report files to exclude. You can also use wildcards.

To see and retain the standard output and errors in the build log, select the Retain long standard output/error check box.

If you don’t select the check box, the build log is saved, but the build executor truncates it to save space. If you select the check box, every log message is saved, but this might increase memory consumption and can slow the performance of the build executor.

To combine all test results into a single table of results, select the Organize test output by parent location check box.

If you use multiple browsers, then the build executor categorizes results by browsers.

To mark the build as failed if the JUnit tests fail, select the Fail the build on fail tests check box.

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.

Set Up a Build VM and a Build VM Template with Xvfb

Before you can use Xvfb, you must create a Build VM template with minimum required software and then add a Build VM that uses the VM template. You can use any existing Oracle Linux 7 VM template to run Xvfb, or create a VM template if you don’t want to use an existing VM template. Xvfb isn’t available on an Oracle Linux 6 VM template.

You must be the Organization Administrator to create a Build VM template and add a Build VM.

In Timeout in seconds, specify the timeout duration for the build to wait before returning control to the job. The default value is 0.

If you don’t want to log the Xvfb output in the build log, deselect the Log Xvfb output check box. The check box is selected by default.

If you don’t want to keep the Xvfb server running for post-build steps, deselect the Shutdown Xvfb with whole job, not just with the main build action check box. The check box is selected by default.

Click Save.

Publish Javadoc

If your application source code files are configured to generate Javadoc, then you can configure a job to publish Javadocs when a build runs.

Open the job’s configuration page.

Click the Post Build tab.

In Javadoc Directory, specify the workspace path where the build executor would publish the generated Javadoc. By default, the path is set to target/site/apidocs .

To configure the build executor to retain Javadoc for each successful build, select the Retain Javadoc for each build check box.

You may want to do this to browse Javadoc of older builds, but remember that retaining old Javadoc would consume more disk space. By default, the check box isn’t selected.

Click Save.

Archive Artifacts

If you want builds of a job to archive artifacts, you can do so as a post build action. Once archived, you can download the artifacts manually and deploy them. By default, artifacts of a build are kept as long as the build log is kept.

Open the job’s configuration page.

Click Configure.

Click the Post Build tab.

Click Add Post Build Action and select Artifact Archiver.

In Files to archive, enter comma separated list of files (with path) to archive. You can use wildcards too. Example: module/dist/**/*.zip.

A file that matches the exclude pattern isn’t archived even if it matches the pattern specified in Files to archive.

If your application is a Maven application and you want to archive Maven artifacts, select the Archive Maven Artifacts check box.

To archive the Maven POM file along with Maven artifacts, select the Include POM.xml check box.

Click Save.

Discard Old Builds and Artifacts

To save storage space, 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.

Open the job’s configuration page.

Click Settings.

Click the General tab, if necessary.

If not selected, select the Discard Old Builds check box.

Configure the discard options.

Click Save.

Copy Artifacts from Another Job

If your application depends on another job’s artifacts, you can configure the job to copy those artifacts when a build runs.

Open the job’s configuration page.

Click Configure.

Click the Build Environment tab.

Click Add Build Environment and select Copy Artifacts.

In From Job, select the job whose artifacts you want to copy.

In Which Build, select the build that generated the artifacts.

In Artifacts to copy, specify the artifacts to copy. When a build runs, the artifacts are copied with their relative paths.

If you specify no value, the build copies all artifacts. The archive.zip file is never copied.

In Target Directory, specify the workspace directory where the artifacts will be copied.

To flatten the directory structure of the copied artifacts, select the Flatten Directories check box.

By default, if a build can’t copy artifacts, it’s marked as failed. If you don’t want the build to be marked as failed, select the Optional (Do not fail build if artifacts copy failed) check box.

Click Save.

Configure General and Advanced Job Settings

You can configure several general and advanced job settings, such as name and description, the JDK version used in the build, discarding old builds, running concurrent builds, adding timestamps to the build log, and more.

Action

How To

Update the job’s name and description

Open the job’s configuration page.

Click Settings.

Click the General tab.

In Name and Description, update the job name and description.

Click Save.

Check the software available on the job’s Build VM template

Open the job’s configuration page.

Click Settings.

Click the Software tab.

See the software and their versions. You can change versions of some software, such as Java SE. Select the version from the drop-down list.

Click Save.

Run concurrent builds

By default, DevCS runs one build of a job at a time. The next build runs after the running build finishes.

To configure the job to run concurrent builds, do this:

Open the job’s configuration page.

Click Settings.

Click the General tab.

Select the Execute concurrent builds if necessary check box.

Click Save.

Set a quiet period

You can specify a period (in seconds) before a new scheduled build of the job should wait before it runs. If the build server is busy with too many builds, setting a longer quiet period can reduce the number of builds.

Open the job’s configuration page.

Click Settings.

Click the Advanced tab.

Select the Quiet period check box.

Click Save.

Set a retry count

If the builds of a job fail, by default, the build executor tries five times to run the build. You can increase or decrease the count.

Open the job’s configuration page.

Click Settings.

Click the Advanced tab.

Select the Retry Count check box.

In Build Retries specify the number of times the build executor tries the build.

In SCM Retries specify the number of times the build executor tries the build to checkout files from the Git repository.

Click Save.

Abort a build if it’s stuck for some duration

Open the job’s configuration page.

Click Settings.

Click the Advanced tab.

Select the Abort the build if it is stuck check box.

In Hours and Minutes, specify the duration.

If a build doesn’t complete in the specified amount of time, the build is terminated automatically and marked as aborted. Select the Fail the build on abort check box to mark the build as failed, rather than aborted.

Click Save.

Remove timestamps from the build log

By default, build logs are timestamped, however you can configure a job to remove them from the log.

Open the job’s configuration page.

Click Settings.

Click the Advanced tab.

Deselect the Add Timestamps to the Console Output check box.

Click Save.

Set the maximum size of the console log

Open the job’s configuration page.

Click Settings.

Click the Advanced tab.

In Max Log Size (MB), set the size. The default value is 50 MB and the maximum value is 1000 MB.

Click Save.

Change a Job’s Build VM Template

You can change a job’s Build VM template after you create the job.

Contact the Organization Administrator to create a Build VM template or install software to a template.

Open the job’s configuration page.

Click Settings.

Click the Software tab.

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

Click Save.

Run a Build

You can run a job’s build manually or configure the job to trigger it automatically on an SCM commit or according to a schedule.

Action

How To

Run a build manually

Open the job’s details page and click Build Now.

You can also run a job’s build from the Jobs Overview page. In the jobs table, click Build Now.

View a Job’s Builds and Reports

To view a job’s builds, reports, build history and perform actions such as run a build or configure the job, on the Build page, click the job name to open its details page.

View a Build’s Logs and 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.

Log/Report

Description

Build Log

View the last build’s log. In the log 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.

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

View Javadoc of the build.

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

SCM Poll Log

View the Git SCM polling log of the builds that displays the log of builds triggered by SCM polling. The log includes scheduled uilds and builds triggered by SCM updates.

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

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

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

View the SonarQube analysis report of the job.

View a Project’s 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 Builds page, click the View Recent Build History link. The history page shows the last 50 builds of the project. Click a job name to open its details page. Click a build number to open its details page. Click 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.

View 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 how the build was triggered, its status, build number, date-time stamp, a Console icon to open the build’s console, and a Delete icon to delete the build.

To review the build history, note these points:

In the By column, the icons indicate the following:

This icon ...

Indicates:

User

The build was initiated by a user.

SCM Change

The build was triggered by an SCM change.

Pipeline

The build was initiated by a pipeline. Click to open the build’s pipeline instance.

Periodic Build Trigger

The build was triggered by a periodic build trigger.

Build System

The build was started or rescheduled by the build system.

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.

The list doesn’t show the discarded and deleted jobs.

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 can’t delete a build.

View a Job’s User Action History

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

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

The log displays information about these user actions:

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

View a Build’s Details

To open the a build’s details page, click the build number in the Build History.

A build’s details page shows its status, links to open build reports, download artifacts, and logs. You can perform these common actions from a build’s details page.

Action

How To

Keep a build forever

A build that’s marked as ‘forever’ isn’t removed if a job is configured to discard old builds automatically. You can’t delete it either.

Adding a description and a name is especially 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.

To keep a build forever, click Configure. In Name and Description, enter the details, and click Save.

Open a build’s log

Click Build Log.

Delete a build

Click Delete.

Download Build Artifacts

If the job is configured to archive artifacts, you can download them to your computer and then deploy to your web server.

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.

Open the job’s details page.

Click Artifacts.

To download artifacts of a particular build, in the Build History, click the build number, and then click Artifacts.

Expand the directory structure and click the artifact link (file or directory) to download it.

To download a zip file of all artifacts, click All files in a zip.

Save the file to your computer.

Watch a Job

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

To get email notifications, enable them in your user preferences, and then set up a watch on the job.

Action

How To

Enable your email notifications preference

In your user preferences page, select the Build Activities check box.

Watch a job

Open the job’s details page.

Click the On toggle button, if necessary.

Click CC Me.

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

Click OK.

Disable email notifications of the job to all subscribed members

Open the job’s details page.

Click the Off toggle button, if necessary.

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 build executor.

Common Variables

This 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:

Software Installed on the Build Executor

Various software are available in the Software Catalog of Build VM templates. Some of them are available by default when a VM template is created.

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. You should use the PATH variable and other environment variables to access the installed software.

This table lists software available in the software catalog, in addition to the software installed by default.

Software

Version

Installed by default?

Ant

1.9.6

Yes

Docker

1.12.6 (Oracle Linux 6)

17.12 (Oracle Linux 7)

No

Findbugs

3.0.1

No

Firefox

60.3.x

Yes

Fn

0.5.x (Oracle Linux 7)

No

Git

1.7.x (Oracle Linux 6)

1.8.x (Oracle Linux 7)

Yes

1.7.x (Oracle Linux 6)

1.8.x (Oracle Linux 7)

Gradle

4.x

3.x

2.x

No

Java

10.x

9.x

1.8.x

1.7.x

1.6.x

Yes

1.8.x (by default)

Kubectl

1.8.4

No

Maven

3.3.3

Yes

Node.js

0.12.x

4.x

6.x

8.x

No

Node.js – grunt

0.4.5

No

Node.js – gulp

3.9.0

No

Node.js – grunt-cli

0.1.13

No

Node.js – gulp-cli

0.3.0

No

Node.js – bower

1.7.7

No

Node.js – oracledb

1.7

No

Node.js Driver for Oracle Database

12.1.0.2

No

OCIcli

2.4.32

No

Oracle ATG 11

11.1.0.1

No

Oracle Developer Studio 12c 12.5

12.5

No

Oracle Forms Developer 12

12.2.1.3.0

No

Oracle Instant Client 12c

12.1.0.2.0

No

Oracle JDeveloper Studio 12

12.2.1.3.0

No

Oracle JDeveloper Studio 11

11.1.1.7.1

No

Oracle SOA Suite 12

12.2.1.3.0

12.2.1.2.0

12.2.1.1.0

12.1.3.0.0

No

Packer

1.2.4

No

PSMcli

1.1.19

No

Python

3.6.x

3.5.x

2.6.x (Oracle Linux 6)

2.7.x (Oracle Linux 7)

Yes

2.6.x (Oracle Linux 6)

2.7.x (Oracle Linux 7)

Python – pip3

9.0.x

No

Ruby

1.9.3p488

Yes

SQLcl

17.x

4.x

No

SFTP

yum:latest

No

Terraform

0.11.8

No

Xvfb

1.15.0 (Oracle Linux 7)

Yes

To know about the environment variables that you can use to access the software, see Build Executor Environment Variables. Various plugins such as Gradle, Node, Xvfb, and Maven 3 ported from Eclipse/Community Hudson are also available in the build executor.

Monitor Jobs and Builds from IDEs

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