Papyrus/Job Configuration Example

This page serves as an example of a job configuration using a simple job such as the requirement one. As a reminder: you can always clone an existing job and tailor it to your needs if it can be adapted without much hassle.

Configuring a Git job

Here is the screenshot of a basic job, which we will detail further after the image: File:PapyrusHudsonWikiJobExample.png A Git job configuration page excerpt

setting up the header

Every job should have a name and a description. A good rule of thumb is to aggregate the component's name and the branch on which it is based, separating the two by a dash. As for the description, a quick description of the job and what it is used for is always appreciated, as well as a default update site if the job provides the users with build artifacts. Note that you can use html syntax to polish the description and add references to other web pages/jobs.

managing the build products

If you are mindful, and you should, about the disk space your job occupies on the shared instance this is where you can manage it. Usually you should adjust the number of builds you want to keep and limit the number of build artifacts you keep. Keeping the last 2 or 3 is a good general rule. If your job is solicited frequently, such as multiple builds per day, you should instead look to keep the last X number of days. Usually keeping the same number of days as the frequency of your team meetings is a good general rule, but this should not go past the last 15 days.

managing the authorizations

There you can refine the authorizations given to a group of individuals or specific ones. This can be especially useful if the main contributors are not yet committers but need to be able to manage the job.

keeping the workspace clean

You should also clean your workspace before every build to get rid of unwanted remaining files or folders. As such, activating this option or running a shell script before the build (git clean -fdx that will remove files and folders from the old git configuration and preceding builds) is advised. The Clean after checkout option can also be activated to be safe as it will remove all untracked files after each checkout and prior to the build.

automating the builds

Then you will have to decide if you want to have automated builds, which you should because it makes ones life easier, and what kind of trigger should be used to launch a new one. In the example I used a reccurent trigger that launch the job every 6 hours on the 6th minute. Another way, the checkbox just after, is to set the job to check every X minutes or hours the state of the repository and launch a build if the repository has been altered. Of course, a combination of both can be done.

defining the build strategy

The example is done for a maven build and therefore we invoke our build strategy and the tool used to do it. The build tool will need you to give it the path to the pom to execute and the goals of the build, here clean and install, as well as any additional properties and profiles that you would like to add and trigger.

archiving the build results / defining your update site

To build the update site you will need to archive the features contents declared in your site's category.xml and generated through the build. Hudson will then keep the specified, by the provided path, artifacts and make them available on the web interface. By filling the exclude box you can further limit the scope of the artifacts that should be published after each build. An important rule to follow is that nobody should be pointing to the workspace for other jobs/actions to feed upon, unless there are no alternative, as the state of the workspace is bound to change regularly and disappear completely if emptied.

keeping an eye on the builds

The person responsible for the job should always be added in the notification box so as to get a current status on the build state should it fail.

keeping your house clean

Finally you have the possibility, and should use it whenever possible, to empty the workspace after each build. This is particularly useful in case of workspace degenerating in several gigabytes of files that can cannibalize the pooled disc resources on the shared instance.

Configuring a Gerrit job

Here is the screenshot of a basic gerrit job, which we will detail further after the image:

setting up the referenced git repository

The job will need to know where to get the code its supposed to build the contribution against, the URL repository, as well as the remote's name, given through the name of repository field, and the contribution to build, defined by the refspec parameter (defining the change to get, e.g. refs/changes/xx/gerrit_change_number/gerrit_patch_number) given by the gerrit trigger. If you have only one branch this can be left as is. In case of multiple branches present in a same repository, the gerrit job can specify against which it is supposed to build the change. This can be done by adding the $GERRIT_BRANCH parameter, or name it by hand (e.g. plainly state the name of the branch such as master).

Choosing the feedback strategy

This particular strategy is provided through the addition of the gerrit plugin to the Hudson instance. It allows the admin to configure the gerrit server and set the values returned by the gerrit genie when building a contribution (e.g. -1 when the build fails, the 29418 port used for ssh contributions,...). The admin can view them by clicking the Manage Hudson> Gerrit Trigger menu.

Setting up the build trigger

The gerrit event parameter state the the build will be triggered each time a new gerrit contribution is published and the second states that the quotes that may be contained in a commit message won't be interpreted as a command variable so as to not upset the launch configuration during the builds. Unless this introduce problems, this last option should always be checked.

Defining the setup

Here you can see a way to specify which projects should be build after the trigger. You can also specify which branches should be built or avoided through regex expressions. These options are available by clicking on he drop-down menus under type and path.

Additional actions

Under the build environment you can then finalize your build by adding several useful steps or limitations, such as adding time-stamps to your build log or add a timeout to set the abort limit if the build should find itself stuck for whatever reasons.

Unmentioned steps

There are missing steps in this short gerrit presentation but those are very similar to the previous job, such as the first three steps. The main difference should be that usually a simple clean and verify (for the maven goals) should suffice to determine if a gerrit contribution can be added or not to the repository. You should still be mindful that this will only compile the code and if you need to always run integration tests this won't be the solution for you and adding the tests and do a clean install will be what you need, as well as cleaning the previously produced maven artifacts. And of course, don't forget to keep an eye on the job by adding an email notification. ;)