Jenkins

Introduction

Jenkins is an easy-to-use, continuous integration system to manage and control the application development lifecycle, including build, documentation, testing, and packaging. It can watch for code changes in uberSVN repositories, and automatically do builds, initiate tests, notify users, roll changes backward or forward, schedule, monitor, and manage external time-based cron jobs, and perform operations on remote machines.

Jenkins at your service.

Installation

Jenkins is downloaded through uberAPPS. You'll need to have system admin permission in order to download, install and activate it.

tip" Caution
Windows users, upgrading to 11.7 from earlier versions need to manually update the java heap settings if they plan to add applications like Jenkins. See Changing the default Java Heap Size

1. Jenkins can be downloaded from the product page, or depending on whether users have made a request, from the requested apps screen. Click the Buy button.

'Buy' Jenkins (for free) if you have purchaser or system admin permissions.
2. You'll be asked to confirm that you want to download Jenkins. It's possible, if you only have purchaser permissions that you'll not be able to continue the installation - as only users with System Admin permissions can install apps. Click Confirm to place Jenkins on the Manage Apps screen.

Confirmation.
3. Providing that you have System Admin permissions, you'll be able to see Jenkins appear on the Manage Apps screen. Click the Download/Install button to continue.

Download/Install
4.Installation may take a few minutes. Once installed, Jenkins is ready to deploy, click Activate.

Activate Jenkins.
5. Activating Jenkins will require that uberSVN is restarted. Just wait a minute before logging back in.

Restarting uber.
6. Jenkins is now active, although you need to now select who can see it, by clicking on the Configure button.

Configure.
7. Jenkins can be made available to all uberSVN users, in which case the Jenkins tab will apear to all users who login to the uberSVN portal. It's possible to limit the visibility of Jenkins by specifying some users.

User Access.

tip" Important
The User Access screen controls which users will see the Jenkin when the log into uberSVN, it doesn't yet offer any access control or authorization. Any user with the URL for Jenkins will be able to access it.

Getting started with Jenkins

When Jenkins is installed a new tab appears. This tab links directly to Jenkins, and although it appears within the uberSVN portal, it is running completely separately from uberSVN. You'll notice that there's also a Jenkins sub-tab added to repository screen. This link will take you to uberSVN's integrated JENKINS screens, from where you can add new build jobs.

tip" Caution
There's a browser related problem that may occur when creating a first job in Jenkins, whereby authentication will fail on the first attempt. When this happens, just re-enter your details or clear your browser cache.

1. For getting started and creating your first job, use the Jenkins link that appears on your repositories sub-tabs. Jobs created in this way can be easily tracked through the uberSVN portal - via the Jenkins tab that appears in the side bar along with Users and Teams.

Jenkins tabs.

Integration limitations
The current Jenkins integration lets you create new jobs through uberSVN's own interface. However, once these jobs are in place, any modification that is made through Jenkin's own interface won't be communicated back to uberSVN. Should you delete a job when logged into the main Jenkins interface, the job will still appear on the uberSVN screen.

2. Click ADD to add a new job

Add.
3. Enter a Name and Description and indicate whether you are wanting to Copy Existing Job (Yes or No). To continue, click the Create button.

Jenkins Job Creation.

4. The screen will update to show the Jenkins project form, pre-configured to use the selected repository. However, there's
a quirk in Jenkins that will cause the form to show an error when you set up your first job. Jenkins will fail to login to the
repository and will display the message:
Uable to access http://repository url:svn: Options/repo name failed (show details)
(Maybe you need to enter credential?

Setup failes first time..
5. To sort out the failed authentication, click on the link enter credential. Enter the username and password for an account that is valid for the repository - it must have read permissions. Select encryption options (svn+ssh or https) if required, then click OK.

Jenkins installed).
6. Providing the username and password are valid, you'll next see a confirmation message saying that:
Authentication was successful. Information is stored in Hudson (sic) now.

Jenkins authenticated (Hudson is the old name for Jenkins).

7. Run through the available options for how you want the job to be set up.

Jenkins installed).

Discard Old Builds

This controls the disk consumption of Jenkins by managing how long you'd like to keep records of the builds (such as console output, build artifacts, and so on.) Jenkins offers two criteria:

Driven by age. You can have Jenkins delete a record if it reaches a certain age (for example, 7 days old.)
Driven by number. You can have Jenkins make sure that it only maintains up to N build records. If a new build is started, the oldest record will be simply removed.

Jenkins also allows you to mark an individual build as 'Keep this log forever', to exclude certain important builds from being discarded automatically. The last stable and last successful build are always kept as well.

This build is parameterized

When you are using Jenkins for various automations, it's sometimes convenient to be able to "parameterize" a build, by requiring a set of user inputs to be made available to the build process. For example, you might be setting up an on-demand test job, where the user can submit a zip file of the binaries to be tested.
This section configures what parameters your build takes. Parameters are distinguished by their names, and so you can have multiple parameters provided that they have different names.
See the Wiki topic for more discussions about this feature.

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

Sometimes you want to temporarily stop building a project. For example, maybe you are in the middle of a large migration and you know new builds are going to fail. Or maybe a project is built every hour but you know that the CVS server will be down for the next 24 hours.

When this option is set, no new build is performed on this project. This allows you to disable new builds without changing any of the build dependency chain or changing the notification set up.

Execute concurrent builds if necessary (beta)

If this option is checked, Jenkins will schedule and execute multiple builds concurrently (provided that you have sufficient executors and incoming build requests.) This is useful on builds and test jobs that take a long time, as each build will only contain a smaller number of changes, and the total turn-around time decreases due to the shorter time a build request spends waiting for the previous build to complete. It is also very useful with parameterized builds, whose individual executions are independent from each other.
For other kinds of jobs, allowing concurrent executions of multiple builds may be problematic, for example if it assumes a monopoly on a certain resource, like database, or for jobs where you use Jenkins as a cron replacement.
If you use a custom workspace and enable this option, all your builds will run on the same workspace, thus unless a care is taken by your side, it'll likely to collide with each other. Otherwise, even when they are run on the same node, Jenkins will use different workspaces to keep them isolated.

Advanced Project Options

Quiet period

If set, a newly scheduled build waits for this many seconds before actually being built. This is useful for:

Collapsing multiple CVS change notification e-mails into one (some CVS changelog e-mail generation scripts generate multiple e-mails in quick succession when a commit spans across directories).
If your coding style is such that you commit one logical change in a few cvs/svn operations, then setting a longer quiet period would prevent Jenkins from building it prematurely and reporting a failure.
Throttling builds. If your Jenkins installation is too busy with too many builds, setting a longer quiet period can reduce the number of builds.

If not explicitly set at project-level, the system-wide default value is used.

Retry Count

If a build fails to checkout from the repository, Jenkins will retry the specified number of times before giving up.

Block build when upstream project is building

When this option is checked, Jenkins will prevent the project from building when a dependency of this project is in the queue, or building. The dependencies include the direct as well as the transitive dependencies.

Block build when downstream project is building

When this option is checked, Jenkins will prevent the project from building when a child of this project is in the queue, or building. The children include the direct as well as the transitive children.

Use custom workspace

For each job on Jenkins, Jenkins allocates a unique "workspace directory." This is the directory where the code is checked out and builds happen. Normally you should let Jenkins allocate and clean up workspace directories, but in several situations this is problematic, and in such case, this option lets you specify the workspace location manually.
Once such situation is where paths are hard-coded and the code needs to be built on a specific location. While there's no doubt that such a build is not ideal, this option allows you to get going in such a situation.
Another situation where this is useful is when you are using the free-style project type not to perform a software build, but execution of a certain batch task, perhaps as a cron replacement. In such case, you can use this option to map the relevant directory as the workspace, so that people can look at files through the Jenkins web UI, and you can kick relevant commands more easily.
If you are in a distributed build environment, unless you tie a job to a specific node, Jenkins may still move around jobs to different slaves. Sometimes this is desirable, sometimes this is not. Also, you can map multiple projects to have the same workspace, but if you do so, make sure concurrent executions of those jobs won't have nasty interferance with each other.
If this path is relative, it's resolved against the "remote FS root" directory of the slave, or $JENKINS_HOME on the master.

Source Code Management

Subversion Modules: Specify the subversion repository URL to check out.
Local module directory (optional): Specify a local directory (relative to the workspace root) where this module is checked out. If left empty, the last path component of the URL is used as the default, just like the svn CLI. A single period (.) may be used to check out the project directly into the workspace rather than into a subdirectory.
Repository browser: Adds links in "changes" views within Jenkins to an external system for browsing the details of those changes. The "Auto" selection attempts to infer the repository browser from other jobs, if supported by the SCM and a job with matching SCM details can be found.

Build Triggers

Build after other projects are built: Set up a trigger so that when some other projects finish building, a new build is scheduled for this project. This is convenient for running an extensive test after a build is complete, for example.
This configuration is the opposite view of the "Build other projects" section in the "Post-build Actions". Updating one will change the other automatically.

Post-build Actions and finally, Save.

Post-build Actions

Publish JUnit test result report

Jenkins understands the JUnit test report XML format (which is also used by TestNG). When this option is configured, Jenkins can provide useful information about test results, such as historical test result trends, a web UI for viewing test reports, tracking failures, and so on. To use this feature, first set up your build to run tests, then specify the path to JUnit XML files in the Ant glob syntax, such as **/build/test-reports/*.xml. Be sure not to include any non-report files into this pattern.

Once there are a few builds running with test results, you should start seeing something like this.

Build other projects

Trigger builds of the other projects once a build is successfully completed. Multiple projects can be specified by using comma, like "abc, def".
Other than the obvious use case where you'd like to build other projects that have a dependency on the current project, this can also be useful to split a long build process in to multiple stages (such as the build portion and the test portion).

Archive the artifacts

Archives the build artifacts (for example, distribution zip files or jar files) so that they can be downloaded later. Archived files will be accessible from the Jenkins webpage. Normally, Jenkins keeps artifacts for a build as long as a build log itself is kept, but if you don't need old artifacts and would rather save disk space, you can do so.

Aggregate downstream test resultsM

Because tests often dominates the execution time, a Jenkins best practice involves splitting test executions into different jobs, possibly in multiple different jobs.

When you do that, setting test aggregation is a convenient way of collecting all the test results from such downstream test jobs and display it along with the build that they are testing. In this way, people can see the overall test status of the given build quickly.

Record fingerprints of files to track usage

Jenkins can record the 'fingerprint' of files (most often jar files) to keep track of where/when those files are produced and used. When you have inter-dependent projects on Jenkins, this allows you to quickly find out answers to questions like:

I have foo.jar on my HDD but which build number of FOO did it come from?
My BAR project depends on foo.jar from the FOO project.
Which build of foo.jar is used in BAR #51?
Which build of BAR contains my bug fix to foo.jar #32?

To use this feature, all of the involved projects (not just the project in which a file is produced, but also the projects in which the file is used) need to use this and record fingerprints.

E-mail Notification

If configured, Jenkins will send out an e-mail to the specified recipients when a certain important event occurs.

Every failed build triggers a new e-mail.
A successful build after a failed (or unstable) build triggers a new e-mail, indicating that a crisis is over.
An unstable build after a successful build triggers a new e-mail, indicating that there's a regression.
Unless configured, every unstable build triggers a new e-mail, indicating that regression is still there.

For lazy projects where unstable builds are the norm, Uncheck "Send e-mail for every unstable build".

Jenkins installed).

uberSVN 11.7 Build:7270
Last doc build: 14:25 - Tuesday 2nd August 2011