Learning objectives

In this tutorial, you learn how to complete these tasks:

System requirements

To run this tutorial, you need the following resources:

Prerequisites

To complete this tutorial, you must have an account on the server with permissions to create and edit projects, jobs, and repositories, and to create and run processes.

Configure the tutorial system

About this task

To complete the tutorial, you must have an agent that is running on a target computer. An agent is a lightweight process that runs on a target computer and does the actual work of building the project. This target computer can be a virtual image, or a physical computer, including the one where the server is installed. You must have access to this computer and be able to install the agent on it.

To prepare the tutorial system:

Procedure

  1. Prepare a computer for use as the target system. This computer must meet the system requirements that are listed in System requirements.
  2. Install the plug-ins used in the tutorial. The tutorial uses the following plug-ins: Git, Maven, and JUnit. The Maven plug-in is installed with the product. Download and install the Git and JUnit plug-ins. Plug-ins can be downloaded from the IBM® UrbanCode™ Buildplug-in site: https://developer.ibm.com/urbancode/plugins/ibm-urbancode-build/. For information about installing plug-ins,
  3. Install an agent on the target computer. For performance reasons, agents are generally not installed on the same computer where the IBM UrbanCode Build server is located. For the tutorial, installing the agent on the computer where the server is located is fine.
  4. Configure the agent. Your agent must be included in the list of configured agents on the Agents page with a status of Online.
  5. Create an agent pool and add the installed agent to it.
  6. Install the open source tools Git and Maven on the computer where the IBM UrbanCode Build agent is located. Add the home directory for each tool to the PATH variable on the target system. Add the MAVEN_HOME variable to the PATH variable.
  7. Ensure that the artifact set included with the product, maven, is available. If it is not installed, create the artifact set by completing these steps:
    1. From the IBM UrbanCode Build dashboard, click System, then click Artifact Sets.
    2. In the Artifact Sets page, click Create New.
    3. In the New Artifact Set dialog box, in the Name field, type maven.
    4. Click Save.
  8. Optional: Configure Java™. The agent that runs the tutorial project must be configured to use a Java JDK instance, and not a JRE. If the agent is configured to use a JRE (identified by the agent's java.home property), reconfigure the agent to point to a JDK. Alternately, you can add the JDK_HOME property to the installed.properties file, which is in the agent_installation/conf/agent directory. In addition, the tutorial's Maven Build step must reference that property with the JAVA_HOME setting.

Lesson 1: Create a Git repository

Procedure

  1. On the IBM UrbanCode Build dashboard, click System > Repositories.
  2. Using the Repositories page, click Create Repository.
  3. In the Source Plug-in list, select Git and then click Set.
  4. In the Name field, type demoHub.
  5. In the Repository Base URL field, type https://github.com/junit-team. This GitHub project contains the JUnit source code.
  6. Click Save.

Lesson 2: Creating a job and adding steps

Creating a job

Most job steps are created from plug-ins. Plug-in steps can be thought of as distinct pieces of automation.

About this task

By combining steps from various plug-ins, you can create fully automated build processes. The number of steps that are provided by a particular plug-in can vary, and each step has a variable number of properties. Property values can be supplied when you define a step or at process run time.

Create a job by completing the following steps:

Procedure

  1. On the IBM UrbanCode Build dashboard, click Templates > Jobs.
  2. On the Jobs page, click Create.
  3. In the Create a Job window, specify the name to be Demo Job.
  4. Click Save. The Main tab for the new job is displayed.

Results

Use the Main tab to add steps to the job. Except for the first step, steps can be inserted before or after other steps. When you run the job, the steps are run in the order you specify.

Creating a stamp step

A stamp is a custom identifier that is applied to a build. Stamps are often used in addition to the automatically generated build life identifiers. A stamp step is part of most jobs.

Procedure

  1. If the Main tab for the Demo Job is not displayed, then from the IBM UrbanCode Build dashboard, click Templates > Jobs, and then click Demo Job.
  2. Click Create Step.
  3. Using the Steps dialog, click Build. The Build list expands to display the available build-type steps and plug-ins.
  4. Click Create Stamp step, and then click Select. The Stamp dialog is displayed. The dialog that is displayed after selecting a step contains properties for the selected step, and other properties common to all steps.
  5. In the Name field, type Create Stamp.
  6. In the Stamp field, enter a script to define the stamp: 1.0.0.${p:buildlife/id}. The simplest way to make a unique stamp is to associate it with the build-life number. This short script looks-up the current build-life ID and applies it to the stamp. This script references a property that is part of every build life. Another option might be to reference a property that you can create and define later. For the tutorial, the build life property is fine. For information about the available properties, see the Scripting API Reference server_url/tools/scripting/ibm-ucb-scripting/.
  7. Click Save.

 

Cleaning the workspace

Procedure

  1. Click the Insert After action for the Create stamp step. After a job has its first step, steps are inserted before or after other steps. The Insert After action, as the name implies, inserts the new step after the selected step.
    The Insert After action
  2. On the Steps dialog, click Source and then click Clean Workspace.
  3. Click Select. The Clean Workspace step is selected.
  4. In the Name field, type Clean.
  5. Click Save.

Populating the workspace

This step places the checked-out code (defined later in the project's source configuration) in the agent's workspace.

Procedure

  1. Use the Insert After action for the Clean step.
  2. On the Steps dialog, click Source and then click Populate Workspace.
  3. Click Select.
  4. In the Name field, type Populate.
  5. Click Save.

Creating a get changelog step

This step retrieves source changes since the last build. The prior build life is located by using status or stamp parameters.

Procedure

  1. Click the Insert After action for the Populate step.
  2. On the Steps dialog, click Source and then click Get Source Changes.
  3. Click Select.
  4. In the Name field, type Get Changelog.
  5. Select Success on the Start Status list. The value that is selected determines which source items are retrieved. In this case, only items with a value of Success are retrieved.
  6. Ensure that Save Changes in Database is selected (it is by default). This parameter can be used in build reports.
  7. Click Save.

 

Creating the set version step

Create a version ID that Maven can use.

Procedure

  1. Click the Insert After action for the Get Changelog step.
  2. On the Steps dialog, click Build > Build Tools > Maven, and then click Maven Build.
  3. In the Name field, type Set Version.
  4. Ensure that the default value pom.xml is set in the Maven POM File field. Maven uses the project object model file (POM) to control builds.
  5. In the Goals field, type versions:set. Goals are similar to Ant tasks and define the actions that Maven performs.
  6. Optional: If you did not put the Maven home variable on your system PATH variable, enter it in the Maven Home field.
  7. In the Properties field, type newVersion=${p:buildlife/latestStamp}.
  8. Click Save.

Creating the Maven build step

This step uses Maven to build the project.

Procedure

  1. Click the Insert After action for the Set Version step.
  2. On the Steps dialog, click Build > Build Tools > Maven, and then click Maven Build. This step uses the same plug-in step as the previous step, Set Version.
  3. In the Name field, type Maven Build.
  4. Ensure that the default value pom.xml is set in the Maven POM File field.
  5. In the Goals field, type ${p:maven.goals}. Unlike the other properties you used in the job, this value references a new property. Later, you create the property and define the value.
  6. Optional: If you did not put the Maven home variable on your system PATH variable, enter it in the Maven Home field.
  7. Click Save.

 

Creating the publish unit tests step

JUnit is a testing framework for Java™. This step runs tests and reports the results. It is configured to always run.

Before you begin

Before you begin this lesson, make sure that you complete the steps that are described in Configure the tutorial system.

Procedure

  1. Click the Insert After action for the Maven Build step.
  2. On the Steps dialog, click Quality > Unit Testing > JUnit, and then click JUnit Report.
  3. In the Name field, type Publish Unit Tests.
  4. In the Report Name field, type JUnit Report.
  5. In the Source Directory field, type target/surefire-reports.
  6. In the Include Patterns field, type TEST*.xml.
  7. Display the Pre-Condition Script list by clicking Show Additional Options, and then select Always. Unlike the other steps in this job, this step always runs even if the preceding step fails. Test reports are displayed on the Tests tab for a selected build life. Reports are also written to the location you specified with the Source Directory field. Test files that match the pattern that is specified in the Include Patterns field are written to the same directory.
  8. Click Save.

Creating the upload artifacts step

Upload the build artifacts to the CodeStation repository.

Procedure

  1. Click the Insert After action for the Publish Unit Tests step.
  2. On the Steps dialog, click Build Systems, and then click CodeStation.
  3. Click Upload Artifatcs, and then click Select.
  4. In the CodeStation-Upload Artifacts window, in the Name field, type Upload Artifacts.
  5. Click Save.

Creating the assign success step

If all previous steps are successful, this step assigns a status of Success to the entire job. If the preceding steps are not successful, this step does not run and the next step runs instead.

Procedure

  1. Click the Insert After action for the Upload Artifacts step.
  2. On the Steps dialog, click Build, and then click Assign Status.
  3. In the Name field, type Assign Success.
  4. In the Status list, select Success.
  5. Click Save. Because the Pre-Condition Script field is set to All Prior Success by default, you can accept the value.

Creating the assign failure step

This step assigns a status of Failure to the job. The step runs if any of the preceding steps fail.

Procedure

  1. Click the Insert After action for the Assign Success step.
  2. On the Steps dialog, click Build, and then click Assign Status.
  3. In the Name field, type Assign Failure.
  4. In the Status list, select Failure.
  5. Display the Pre-Condition Script list, and select Any Prior Failure.
  6. Click Save.

The finished Demo Job job

 

Lesson 3: Creating a project template

About this task

Because project templates are reusable, you can apply the same standards to similar projects. Properties can be defined and the values supplied later by the projects created from the templates. A project template might always use a particular type of build script, for example, but the name or location of the script can vary by project.

In this lesson, you create a project template that you use later to create the tutorial project.

Procedure

  1. On the IBM® UrbanCode™ Build dashboard, click Templates. The Projects tab is open by default .
  2. Click Create.
  3. In the Name field, type Demo Project Template.
  4. Click Save. The Main tab for the new project template is displayed.
  5. Click Build Pre-Processing, and click Edit..
  6. Click Agent Pool Selection, and then select the agent pool you created when you configured the tutorial system.
  7. Click Save.

Lesson 4: Creating a source template

A source template is a reusable source configuration that can be used by any project that requires the same source type.

Before you begin

Ensure that you installed the Git source-type plug-in before you start this lesson.

About this task

In this lesson, you define a Git configuration that is used by the tutorial project.

Procedure

  1. On the IBM® UrbanCode™ Build dashboard, click Templates, click Source, and then click Create.
  2. In the Source Type list, select Git. All installed source-type plug-ins are listed.
  3. Click Select. Fields that are related to the selected source type are displayed.
  4. In the Name field, type GitHub.
  5. In the Working Directory Script list, select Default Workflow Directory.
  6. In the Remote URL field, type ${p:git.project}. This refers to a property you create in the next section. You supply the property value when you configure the project.
  7. In the Branch field, type ${p?:git.branch}.
  8. Click Save.

Creating properties for the source template

Define the properties you referenced in the previous section.

Procedure

  1. If the Source tab is not already displayed, then on the IBM UrbanCode Build dashboard, click Templates, click Source, and then click the GitHub source template that you created earlier in the lesson.
  2. Click Properties, and then click Create.
  3. Create the git.project property by completing these steps.
    1. In the Name field, type git.project.
    2. In the Label field, type Git Project. The label text identifies the property to users that use the source template.
    3. In the Description field, type Path of the GitHub project within the account. The description text is displayed to users.
    4. In the Display Type list, select Text.
    5. In the Value area, accept the default option Defined. The Value option determines when and where the value for the property is defined. By selecting Defined, you can provide a value in the Default Value field, or supply the value on the project configuration before the project runs.
    6. Leave the Default Value field blank. You define the property value when you configure the project.
    7. Select the Value Required check box.
    8. Click Save.
  4. Create the git.branch property by completing these steps.
    1. On the Properties tab, click Create.
    2. In the Name field, type git.branch.
    3. In the Label field, type Git Branch.
    4. In the Description field, type Source branch. Leave the field blank for the master branch.
    5. In the Display Type list, select Text.
    6. Leave the Default Value field blank.
    7. Clear the Required check box.
    8. Click Save.

 

The GitHub source template properties

Lesson 5: Creating a process template

Build a process template for the tutorial project.

About this task

In this lesson, you create a process template, define a process, create a property, and an artifact set that is used by the project.

Procedure

  1. On the IBM® UrbanCode™ Build dashboard, click Templates, click Process, and then click Create.
  2. In the Name field, type Demo Build Process.
  3. Under Type, make sure that Build Process is selected.
  4. Click Save.

Results

The Main tab for the new process template is displayed.

Creating a process definition

Process definitions identify the jobs that comprise a build.

About this task

In order for a job to be used in a project, it must be assigned to the process. A process can have several jobs and their order in the process is determined similarly to the way steps are inserted into jobs. In this lesson, you assign the job you created in the last lesson to a process definition.

Procedure

  1. On the IBM UrbanCode Build dashboard, click Templates > Process.
  2. In the Process Templates page, click Demo Build Process, and then click Definition.
  3. Click Start, and then select Insert Job After. The Insert Job After action is displayed after you click Start, as show in the following figure:
    The Insert Job After action
  4. In the Insert Start Job window, in the Job list, select the job you created in the last lesson, Demo Job.
  5. In the Pre-condition list, select Always.
  6. In the Agent Selection area, select Agent Pool Selection, and then select the agent pool you created when you configured your tutorial system. An agent in the agent pool runs the jobs assigned to the workflow.
  7. In the Working Directory list, select Default Workflow Directory. An agent's default working directory is: 
    agent_directory/var/work/project/copy to clipboard
  8. Click Insert Job.

Process definition actions

Creating process template properties

Define the property you referenced in Lesson 2.

About this task

In this step, you define the property you referenced in the Maven Build step, ${p:maven.goals}

Procedure

  1. Using the Demo Build Process, click Properties, and then click Create.
  2. In the Name field, type maven.goals.
  3. In the Label field, type Maven Goals.
  4. In the Display Type list, select Text.
  5. In the Default Value field, type package. This is a Maven lifecycle build phase.
  6. Select the Value Required check box.
  7. Click Save.

Creating process artifact sets

Generated artifacts are assigned to an artifact set. An artifact set is a collection of build artifacts.

Before you begin

Ensure that you configured a Maven artifact set before you start this step.

About this task

In this lesson, you configure the artifact set that is used by the project.

Procedure

  1. Ensure that the window for your build process is displayed and click Artifacts, and then click New Artifact Config.
  2. In the Artifact Set list, select the artifact set you created earlier, maven.
  3. In the Base Directory field, type target.
  4. In the Include Artifacts field, type *.jar.
  5. Click Save.

Lesson 6: Creating a project

You use projects to configure and run builds. After a build runs, projects provide a wealth of information that you can use to manage the project lifecycle and troubleshoot problems.

Before you begin

Ensure that you completed all of the preceding steps before you start this lesson.

About this task

Projects are built from templates. In this lesson, you will use the templates that you made earlier to create the tutorial project. You can run builds automatically on a predetermined schedule, or you can run builds manually, as you do in the tutorial. To define the tutorial project, you select the process that you defined earlier. When you start the build, the workflow begins running the job that you created with the job template. The project determines the source code to use, and manages any dependencies. Each build generates a unique build life ID.

Procedure

  1. On the IBM® UrbanCode™ Build dashboard, click Projects, and then click Create.
  2. Select the project template that you created in Lesson 3, Demo Project Template.
  3. In the Name field, type Demo Project.
  4. Click Save.

Configuring the project build process

A project must be associated with a build process. A project might have any number of build processes associated with it.

Procedure

  1. Ensure that the Configuration tab for the Demo Project project is displayed, then, under Build Processes, click New.
  2. In the Template list, select Demo Build Process, and then click Select. The Maven Goals field is derived from the process template that you created in last lesson.
  3. In the Name field, type Demo Build.
  4. In the Maven Goals field, accept the value, package. The package value is a basic Maven lifecycle build phase. The packageattribute instructs Maven to put the compiled code into a distributable format, such as a JAR file. You can use the tutorial project to run other Maven builds and change the goals.
  5. Click Save.

Results

The Configuration tab for the new build process is displayed.

Configuring the project source

A project's build source is defined by assigning a source template to a build configuration.

Before you begin

Ensure that the Configuration tab for the build process you defined in the previous section is displayed.

About this task

You define the source configuration by selecting the source template that you created earlier, and by using template properties to identify the source location.

Procedure

  1. Under Source Configuration, click Create.
  2. In the Source Template list, select the source template that you created earlier, GitHub, and then click Select.
  3. In the Name field, type GitHub.
  4. In the Repository list, select the repository that you created earlier, demoHub.
  5. In the Git Project Path field, type junit. Because the project uses the master branch, you can leave the Git Branch field blank.
  6. Click Save.

 

The finished Demo Build process

Lesson 7: Running the build

Run the project build process to transform the source code into the finished application, JUnit.

Before you begin

Ensure that you completed all previous steps in the tutorial.

About this task

You run a build by running a build process that is defined for the project. The build process takes the source material and transforms it, using a job that is assigned to the project, into the final output.

Procedure

  1. On the IBM® UrbanCode™ Build dashboard, click Projects, and then expand the project that you created in the last lesson, Demo Project. Builds configured for the selected project are listed beneath the project, as shown in the following figure:
    The builds for the Demo Project listed
  2. Click DemoBuild. The Main tab for the DemoBuild project build is displayed.
  3. Click Build. The build process starts and the My Activity tab for the build is displayed. The build, with a new build life number, is listed with a status of Running, as shown in the following figure:
    The Demo Build is running
Refresh the My Activity page. If the build is successful, the status changes to Complete; otherwise, the status changes to Failed. A successful run is shown in the following figure:
A successful build

 

 

 


  Call us on +91 700 483 5930   |   +91 700 483 5706     Contact@DevopsSchool.com