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.
Note:
Compute-based builds are not available to DevCS users in the Traditional identity domain. The built-in shared build executor is available only, so there are no Build VMs, no Build VM templates, and no need to configure the OCI account. The ability to use compute-based builds is only available for DevCS users on OCI.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 installing the software, it clones the job’s Git repositories (if configured) to the VM, runs the defined build steps, creates artifacts (if configured), and performs post-build steps (if configured).
- 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 on 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, such as Node.js and Java, are available in multiple versions in the Software Catalog. Such software are called as Software Packages.
The version number of a package can be categorized into two: the major version and the minor version. If a software's version is 1.2.3
, then 1
is its major version and 2.3
is its minor version. In a software's tile, the major version number is displayed in the title of the package. In Configure Software page, the number shown in Version is the installed version, which includes both major and minor versions.
Here's an example. In this image, Node.js 0.12, 8, 10, and 12 are shown in the software catalog. In the Node.js 12 tile, 12
is the major version and 3.1
is its minor version. The installed version of the software is 12.3.1
.
Description of the illustration odcs_software_catalog_version.png
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, assume that Node.js 10.13 is available in the Software Catalog for the Node.js 10 package. When Node.js 10.15 is made available in the Software Catalog, all VM templates using the Node.js 10 package update automatically to use Node.js 10.15. 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 package 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 Node.js 12 is available in the Software Catalog, all VM templates using Node.js 0.12, Node.js 8, or Node.js 10 aren’t updated automatically. To use the new version, you must manually update the VM templates to use the new package.
When a major version of a software is removed from the catalog, all VM templates using that software version are updated automatically to use the next higher version. For example, when Node.js 8 phases out, VM templates using Node.js 8 will be automatically updated to use Node.js 10.
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.
Note:
Compute-based builds are not available to DevCS users in the Traditional identity domain. So, there are no Build VMs, no Build VM templates, and no need to configure the OCI account.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 |
|
Configure a VM template’s software |
|
Edit a VM template's name or description |
|
Delete a VM template |
When you delete a VM template, its Build VMs are deleted too.
|
Add and Manage Build VMs
When you add a Build VM, you allocate a VM on the linked OCI Compute or OCI Compute Classic 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 |
|
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.
|
Start or stop a VM manually | When a build of a job triggers, its VM starts automatically if it was in the stopped state. It takes some time to start a VM and the user must wait for a VM to start before the job's build runs on it. Similarly, a VM stops automatically if no builds run on it during the sleep timeout period.
At times, you may want to manually start a VM before triggering a job's build or stop it to free resources immediately.
|
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.
The deleted VMs are listed in the Deleted VMs tab. |
Change the sleep timeout of all VMs | 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.
|
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 |
|
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.
|
Create a job to associate it with a merge request and accept build parameters |
|
Create a job using YAML | In DevCS, you can use a YAML file (a file with .yml extension) to create a job and define its configuration. The file is stored in a project's Git repository. See Create and Configure Jobs and Pipelines Using YAML.
|
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 .
Configure the Privacy Setting of a Job
In a job, any project member can view its configuration, edit it, or run its build. To restrict access of members, mark the build job as Private and authorize some members who can view the job's configuration, edit it, or run its build.
You must be assigned the project Owner role to configure the privacy setting of a job. You can't change the privacy setting of a YAML job.
If a non-authorized user tries to view a private job, the message This job is private. You need permission from your project owner o view this job. is displayed.
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 Git tab.
- From the Add Git 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 Git 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 (regex) or glob to specify fileset. 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 themyapp/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 (regex) or glob to specify fileset. 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 Git 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/
or1/
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 as1-5
-
/
or*/X
to specify skips of X's value through the range, such as0/15
in theMINUTE
field for0,15,30,45
-
A,B,...,Z
can be used to specify multiple values, such as0,30
or1,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.
To configure a job to use an external Git repository:
Access Files of a Git Repository's Private Branch
To access a Git repository's private branch, configure the job to use SSH.
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.
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 Git 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 |
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 If necessary, in Checkout revision, specify the branch to checkout and build as |
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. The build runs only if the merge is successful. |
Prune obsolete local branches before running a build |
Expand Advanced Git Settings and select the Prune remote branches before build check box. |
Skip the internal tag |
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. |
Remove untracked files before running a build |
Expand Advanced Git Settings and select the Clean after checkout check box. |
Retrieve sub-modules recursively |
Expand Advanced Git Settings and select the Recursively update submodules check box. |
Display commit’s author in the log |
By default, the Git change log shows the commit’s |
Delete all files of the workspace before a build runs |
Expand Advanced Git Settings and select the Wipe out workspace before build 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.
The log shows build ID, commit messages, commit IDs, and affected files.
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/
or1/
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 a job to use a 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 so you can enter or change the default values of the parameters.
- Open the job’s configuration page.
- Click Configure .
- Click the Parameters tab.
- From the Add Parameter drop-down list, select the parameter type.
You can add these types of build parameters:
Use this parameter type ... To: String
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
orfalse
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 drop-down list in the Configure Parameters dialog box. The first value is the default selected value.
Merge Request
Accepts string values for the Git repository URL, the Git repository branch name, and the merge request ID as input. The parameter fields appear as a text box in the Configure Parameters dialog box.
Use this parameter if you want to link an existing job with a merge request.
- Enter values, such as name, default value, and description.
- Click Save.
For example, if you want a job to change the default values of Gradle's version, OCI username, and OCI user's password when a build runs, create the Choice, String, and Password build parameters to accept the values. The Password parameter's value isn't displayed in the input field.
To use a build parameter, use it in the ${BUILD_PARAMETER}
format. For example, this image shows the Gradle version, OCI username, and OCI password parameters used in the build step fields of a job. Note that the password parameter's variable name isn't displayed.
When a build runs, the Configure Parameters dialog box opens where you can enter or change the default values of parameters. All parameter values, except the Password parameter's value,display as string in the dialog box and later in the build log.
Example:
If you selected the Use for Merge Request check box while creating the job, 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 Git tab.
- Upstream job parameters are passed to downstream jobs.
For example, in a pipeline that flows from Job A to Job B to Job C, if parameter P1 is defined in Job A and parameter P2 is defined in Job B, then parameter P1 will be passed to Job B and parameters P1 and P2 will be passed to Job C.
- An upstream job with the same named parameter as a downstream job
will overwrite the default value of the named parameter from the downstream job.
For example, if parameters P1 and P2 are defined in Job A and parameters P2 and P3 are defined in Job B, then the value of parameter P2 from Job A will overwrite the default value of parameter P2 in Job B. If there was a Job C downstream from Job B, then the initial default value of P2 (from Job A) plus the values of P1 and P3 would be passed to Job C.
- When a build of the pipeline runs, the Configure Parameter dialog box displays all parameters of the jobs in the pipeline. Duplicate parameters are displayed once and its value is used by all jobs that use the parameter. The default value of a duplicate parameter comes from the first job in the pipeline where it is defined.
For example, in a pipeline that flows from Job A to Job B to Job C, if parameter P1 is defined in Job A; parameters P2 and P3 are defined in Job 2; and parameters P1 and P4 are defined in Job C; then when the pipeline runs, it displays parameters P1, P2, P3, and P4 once in the Configure Parameter dialog box though parameter P1 is defined in two jobs. The default value of P1 would come from Job 1 and is passed to subsequent jobs of the pipeline.
In the pipeline, if the Auto start when pipeline jobs are built externally is selected, then the Configure Parameter dialog box isn't displayed when a build of a pipeline's job runs. In the pipeline, the subsequent jobs of the job that trigger the build use the default values of their parameters. If a parameter is duplicate, then the job uses the default value of the first job where the parameter was defined.
For example, in a pipeline that flows from Job A to Job B to Job C, if parameter P1 is defined in Job A; parameters P2 and P3 are defined in Job B; and parameters P1 and P4 are defined in Job C; then when a build of Job A runs, it passes the default value of P1 to Job B and Job C, and overwrites the default of P1 in Job C. If a build of Job B runs, then the builds use the default values of P2, P3, P1 (defined in Job C) and P4.
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.
-
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.
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.
-
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. -
Configure the POM file and add the Oracle Maven Repository details.
-
Add a
<repository>
element to refer tohttps://maven.oracle.com
.Example:
<repositories> <repository> <name>OracleMaven</name> <id>maven.oracle.com</id> <url>https://maven.oracle.com</url> </repository> </repositories>
Depending on your application, you may also want to add the
<pluginRepository>
element to refer tohttps://maven.oracle.com
.Example:
<pluginRepositories> <pluginRepository> <name>OracleMaven</name> <id>maven.oracle.com</id> <url>https://maven.oracle.com</url> </pluginRepository> </pluginRepositories>
-
Commit the POM file to the project Git 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.
Action | How To |
---|---|
Add an Oracle Maven Repository connection |
|
Edit a connection |
To change the connection’s user credentials or provide another server ID, you can edit the connection.
|
Delete the connection |
|
Configure a Job to Connect to the Oracle Maven Repository
- Open the job’s configuration page.
- Click Configure .
- Click the Before Build tab.
- Click Add Before Build Action and select Oracle Maven Repository Connection.
- 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 Mavensettings.xml
file, or use the defaultmaven.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:
pip3 list cd $WORKSPACE python3 -m venv mytest cd mytest/bin ./pip3 list ./pip3 install --upgrade pip requests setuptools selenium ./pip3 list ./python3 -c 'import requests; r=requests.get('\''https://www.google.com'\''); print(r.status_code)' ./pip3 uninstall -y requests ./pip3 list
-
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 3pip3
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 removealex.admin@
from the URL and usehttps://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 Git 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
andinstall
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.
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.
-
Open the job’s configuration page.
-
Click Configure .
-
Click the Steps tab.
-
From Add Step, select Unix Shell.
-
In Script, enter this command:
mvn install:install-file -Dfile=$WLS_HOME/server/lib/weblogic-maven-plugin.jar -DpomFile=$WLS_HOME/server/lib/pom.xml mvn com.oracle.weblogic:weblogic-maven-plugin:deploy
-
Click Save.
Upload to or Download Artifacts from the Project Maven Repository
To upload artifacts to the Maven repository, you'll use the distributionManagement
snippet in the POM file. To download artifacts from the Maven repository, use the repositories
snippet in the POM file.
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.
Generate a Dependency Vulnerability Analysis Report
For a Maven application, you can configure a job to generate a Dependency Vulnerability Analysis (DVA) report, which helps you analyze any publicly known vulnerabilities in the application.
To find more about NVD, see https://nvd.nist.gov/
.
- Issue ID, if the Create issue for every affected POM file check box was selected. Click the issue link to open it.
You can also open the Project Home page and check the recent activities feed about the issue's create notification. Example: System created Defect 2: Vulnerabilities in -MavenJavaApp. For a recurring issue, a comment is added to the issue and notification is added to the activities feed. Example: System commented Defect 2: Vulnerabilities in - MavenJavaApp.
- Merge request ID, if the Resolve button was clicked to resolve the vulnerabilities. Click the merge request link to open it.
- Number of vulnerabilities
- Name of each dependency where a vulnerability is found
- Each dependency's type (direct or transitive)
If it's a transitive dependency, a Transitive label displays next to the name. If it's a direct dependency, no label is displayed.
- Number of alerts and alert categories of vulnerabilities (High, Medium, or Low)
- Expand each dependency to view its vulnerabilities
If you want to mute alerts of a vulnerability, expand the vulnerability in the Report section, and click Mute in Alerts. In the Mute Vulnerability dialog box, review the details, and click Mute. For future builds, the alerts are muted in the job that generated the report.
The Mute is available in the DVA report of the latest build only.
To fix a reported vulnerability, in the POM file, change the dependency's version number to a version where the vulnerability is fixed.
Resolve Reported Vulnerabilities Automatically
After the Dependency Vulnerability Analysis (DVA) report is generated, review the report to identify the vulnerabilities in the POM files, and click the Resolve button to resolve it.
The Resolve button helps you resolve vulnerabilities found in the direct dependencies of the POM file. The vulnerabilities found in the transitive dependencies must be resolved manually. If a POM file has transitive dependencies only and vulnerabilities are reported in it, the Resolve button is disabled. The button is not available in the DVA reports of older builds of the job, but only in the latest build of the job.
- In the Report section of the vulnerability analysis report, expand the affected POM file.
Example:
- Click Resolve.
If a merge request exists, you can cancel the dialog and use it or continue to create another merge request.
- In the Resolve Vulnerability dialog box, review the reported vulnerabilities.
- If an issue was created when the report was generated, its ID is displayed. If an issue wasn't created, select the Create issue to track this resolution check box to create it.
In Linked Builds, add an existing build to link it to the merge request.
In Reviewers, add team members to review the merge request.
Example:
- For each vulnerability, in Available Versions, select a version of the dependency that doesn't have the reported vulnerability.
If you don't want to resolve the dependency or no versions are available, select Do Not Resolve.
- Click Create New Merge Request.
When you click the button, DevCS does the following:
- Creates a merge request with details about the vulnerabilities found.
- Creates a branch with the job's Git repository branch as the base branch, and then sets it as the review branch of the merge request.
- Sets the job's Git repository branch as the target branch of the merge request.
- Updates the POM file of the review branch to use the specified versions of the dependencies.
For example, if the job that generated the vulnerability report uses the
JavaMavenApp
Git repository and itsrelease1.1
branch, then a new branch is created inJavaMavenApp
usingrelease1.1
as the base branch and is used as the review branch of the merge request. Therelease1.1
branch is used as the target branch.If a merge request with same review and target branches was created in an older build of the job, DevCS uses the same merge request to merge the POM file updates.
- Click the merge request link to open it in another tab or window of the browser, and click OK.
- In the Merge Request, review the details of the vulnerabilities in the Conversation tab and the POM file changes in the Changed Files tab.
Example:
- If you've invited other reviewers, wait for their feedback.
- If you've linked a build job to the merge request, in the Linked Builds tab, run a build and verify its stability.
- When you're done and are ready to merge the POM file's updates, click Merge.
- In the Merge dialog box, to delete the review branch, select the Delete branch check box. To resolve linked issues, select the Resolve linked issues check box and the check boxes of issues you want to resolve.
- Click Create a merge request.
- Run a build of the job that reported dependency vulnerabilities and verify that the POM file's update has fixed the vulnerability.
If a vulnerability is still found, repeat the above steps to create another merge request and try another version of the dependency.
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
andbuild.properties
) to the project Git repository. -
Open the job’s configuration page.
-
Click Configure .
-
In the Git 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, usevarname=
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/
.
https://docs.gradle.org/current/userguide/gradle_wrapper.html
.
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.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.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.
Configure a Job to Run SQLcl Commands
- DevCS doesn’t support SQL commands to edit buffer (such as
set sqlformat csv
) or edit console. - DevCS doesn’t support build parameters in the SQL file.
- If you are using Oracle REST Data Services (ORDS), some SQLcl commands, such as the BRIDGE command, requires a JDBC URL.
Example:
BRIDGE table1 as "jdbc:oracle:thin:DEMO/demo@http://examplehost.com/ords/demo"(select * from DUAL);
- To mark a build as failed if the SQL commands fail, add the
WHENEVER SQLERROR EXIT 1
line to your script.
When a build runs, DevCS stores your Oracle Database credentials in the Oracle Wallet. Check the build’s log 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.
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.
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.Access Oracle Cloud Infrastructure Services Using OCIcli
Using Oracle Cloud Infrastructure command line interface (OCIcli) commands, you can create and manage Oracle Cloud Infrastructure objects and services when a build runs.
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 Required 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.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 theHTTP_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.Trigger a Wercker Pipeline
Wercker is a Docker-based platform that provides continuous integration and continuous delivery (CI/CD) capabilities.
To learn more about Wercker, see https://devcenter.wercker.com/
.
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.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.
You must be assigned the project Owner role to add and manage SonarQube connections.
Action | How To |
---|---|
Add a SonarQube connection |
|
Edit a connection |
To change the connection’s user credentials or provide another server ID, you can edit the connection.
|
Delete the connection |
|
Configure a Job to Connect to SonarQube
You can configure a job to use SonarQube from the Before Build tab and add a post-build action to publish its reports.
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. Named passwords 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 |
After creating the named password, share its name with your project users. |
Edit a named password |
|
Delete the named password |
After deleting the named password, let your project users know that it's no longer available. |
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 After Build tab.
-
From Add After 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 astarget/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.
-
To archive videos and image files, select the Archive Media Files check box.
-
Click Save.
After a build runs, you can view its test result.
View Test Results
You can view the JUnit test results of a build from the Test Results page.
Action | How To |
---|---|
View test results of the last build |
|
View test results of a particular build |
|
View test suite details |
On the Test Results page, click the All Tests toggle button. From the Suite Name, click the suite name. |
View details of a test |
Open the test suite details page and click the test name. To view details of a failed test, on the Test Results page, click the All Failed Tests toggle button, and then click the test name. |
View test results history |
On the Test Results page, click View Test Results History. |
If you configure the job to archive videos and image files, click Show to download the test image and click Watch to download the test video file.
The supported image formats are .png
, .jpg
, .gif
, .tif
, .tiff
, .bmp
, .ai
, .psd
, .svg
, .img
, .jpeg
, .ico
, .eps
, and .ps
.
The supported video formats are .mp4
, .mov
, .avi
, .webm
, .flv
, .mpg
, .gif
, .wmv
, .rm
, .asf
, .swf
, .avchd
, and .m4v
.
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.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.
Archive Artifacts
If you want builds of a job to archive artifacts, you can do so as a after 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 After Build tab.
-
Click Add After 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
. -
In Files to exclude, enter comma separated list of files (with path) to exclude.
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 Before Build tab.
-
Click Add Before Build Action 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.
Deploy Build Artifacts to Oracle Cloud Services
The recommended way to deploy your project's build artifacts to Oracle Cloud Services, including Oracle Java Cloud Service (JCS) and Oracle Application Container Cloud Service (ACCS), is to do so in an Oracle Deploy build step. To deploy build artifacts to Oracle Java Cloud Service - SaaS Extension (JCS-SX) from Oracle Developer Cloud Service (DevCS), you need to create and use a deployment configuration from the Deployments page.
Before. you create a build step for deployment, you need to create an environment and add the JCS and ACCS instances to it. These instances will be used for your deployment targets. If you do not add them in the Environments page, you will not be able to select them in the build step. See Set Up an Environment for information about creating an environment and adding instances to it.
You can either add a build step that deploys the build artifact to the job that creates and packages the artifact or create a separate job for each task. If you choose to use separate jobs, you can create a pipeline that begins with a job that builds and packages the application, followed by a job that deploys the build artifact to the desired target environment. Using pipelines gives you the flexibility of adding testing and other tasks to the flow.
Create a Build Step to Deploy an Application to JCS
You can create a separate job that copies build artifacts generated by another job and deploys those artifacts to a JCS deployment target.
Create a Build Step to Deploy an Application to ACCS
You can create a separate job that copies build artifacts generated by another job and deploys those artifacts to an ACCS deployment target.
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 |
|
Check the software available on the job’s Build VM template |
|
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:
|
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.
|
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.
|
Abort a build if it’s stuck for some duration |
|
Remove timestamps from the build log |
By default, build logs are timestamped, however you can configure a job to remove them from the log.
|
Set the maximum size of the console log |
|
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 . |
Run a build on SCM commit |
|
Run a build on a schedule |
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.
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 theQueued
status to see a message about the problem.If the build is using a Build VM, you may also contact the Organization Administrator to check the VM’s status.
-
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.
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. To keep a build forever, click Configure, select the Keep Build Forever check box, and click Save. |
Add a name and description to a build |
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 |
|
Disable email notifications of the job to all subscribed members |
|
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.
To use a variable, use the $VARIABLE_NAME
syntax. Example: $BUILD_ID
.
Common Variables
This table describes some common environment variables.
Environment Variable | Description |
---|---|
|
The current build’s ID. |
|
The current build number. |
|
The full URL of the current build. |
|
The build output directory. |
|
The name of the job. |
|
The unique number that identifies the current executor (among executors of the same machine) that's running the current build. |
|
The HTTP proxy for outgoing connections. |
|
The HTTP proxy host for outgoing connections. |
|
The HTTP proxy port for outgoing connections. |
|
The HTTPS proxy for outgoing connections. |
|
The HTTPS proxy host for outgoing connections. |
|
The HTTPS proxy port for outgoing connections. |
|
The name of the current job. |
|
The full URL of the current job. |
|
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. |
|
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. |
PATH |
The PATH variable set in the build executor specifying the path of executables in the build executor. |
WORKSPACE |
The absolute path of the build executor's workspace. |
Software Variables
Environment Variable | Description |
---|---|
|
The path of the Oracle ATG |
|
The path of the Oracle ATG root directory. |
|
The path of the Gradle directory. |
|
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, |
|
The path of the Node.js home directory. |
|
The path of the Node.js modules directory. |
To access JDeveloper or SOA, use these variables.
- Use
JAVACLOUD_HOME
variables to access the Java SDK - Use
ORACLE_HOME
variables to access JDeveloper - Use
MIDDLEWARE_HOME
variables to access Oracle Fusion Middleware. TheMIDDLEWARE_HOME
directory includes the JDeveloper installation directory, WebLogic Server installation directory, and the Oracle Common library dependencies. - Use
WLS_HOME
variables to access the WebLogic server binary directory bundled with JDeveloper
Make sure that you have the right software available in the Build VM Template of your job.
Software | Variables |
---|---|
JDeveloper Studio 12 |
|
JDeveloper 11g |
|
SOA 12.2.1.3 |
|
SOA 12.2.1.2 |
|
SOA 12.2.1.1 |
|
SOA 12.1.3 |
|
Tip:
-
You can run the
env
command as a Shell build step to view all environment variables of the build executor. -
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
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 |
C++ Compiler | 4.4.x | Yes |
Docker |
1.12.x (Oracle Linux 6) 17.12.x (Oracle Linux 6 and 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) |
GraalVM | 1.0.0-14 (Oracle Linux 7) | Yes |
Gradle |
5.x |
No |
Groovy | 2.5.x | No |
Java |
12.x 11.x 1.8.x 1.7.x |
Yes
1.8.x (by default) |
Kubectl |
1.8.4 |
No |
Maven |
3.3.3 |
Yes |
Node.js |
0.12.x (Oracle Linux 6 and 7) 8.x (Oracle Linux 6 and 7) 10.x (Oracle Linux 6 and 7) 12.x (Oracle Linux 7) |
No |
Node.js Driver for Oracle Database |
12.1.0.2 |
No |
OCIcli |
2.5.x |
No |
Oracle ATG 11 |
11.1.x |
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.3.x |
No |
PSMcli |
1.1.x |
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 |
18.x 17.x 4.x |
No |
Terraform |
0.11.x |
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.