Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Table of Contents

Jenkins can be used to perform the typical build server work, such as doing continuous/official/nightly builds, run tests, or perform some repetitive batch tasks. This is called "free-style software project" in Jenkins.

Setting up the project

Go to Jenkins top page, select "New Job", then choose "Build a free-style software project". This job type consists of the following elements:

  • optional SCM, such as CVS or Subversion where your source code resides.
  • optional triggers to control when Jenkins will perform builds.
  • some sort of build script that performs the build (ant, maven, shell script, batch file, etc.) where the real work happens
  • optional steps to collect information out of the build, such as archiving the artifacts and/or recording javadoc and test results.
  • optional steps to notify other people/systems with the build result, such as sending e-mails, IMs, updating issue tracker, etc.

For more details, click the (question) icons in the configuration page.

Jenkins Set Environment Variable

Jenkins sets some environment variables that are available to shell scripts, Windows batch files, Ant and Maven^#1^ files that are executed by Jenkins. A list of environment variables and how they are used are shown #below.

Builds for Non-Source Control Projects

There is sometimes a need to build a project simply for demonstration purposes or access to a SVN/CVS repository is unavailable. By choosing to configure the project  as "None" under "Source Code Management" you will have to:

  1. Build the Project at least once, (it will fail), but Jenkins will create the structure jenkins/workspace/PROJECTNAME/
  2. Copy the project files to jenkins/workspace/PROJECTNAME/
  3. Build again and configure appropriately

Jenkins Set Environment Variables

When a Jenkins job executes, it sets some environment variables that you may use in your shell script, batch command, Ant script or Maven POM #1. The following table contains a list of all of these environment variables.

Environment Variable



The current build number, such as "153"


The current build id, such as "2005-08-22_23-59-59" (YYYY-MM-DD_hh-mm-ss, defunct since version 1.597)


The URL where the results of this build can be found (e.g. http://buildserver/jenkins/job/MyJobName/666/)


The name of the node the current build is running on. Equals 'master' for master node.


Name of the project of this build. This is the name you gave your job when you first set it up. It's the third column of the Jenkins Dashboard main page.


String of jenkins-${JOB_NAME}-${BUILD_NUMBER}. Convenient to put into a resource file, a jar file, etc for easier identification.


Set to the URL of the Jenkins master that's running the build. This value is used by Jenkins CLI for example


The unique number that identifies the current executor (among executors of the same machine) that's carrying out this build. This is the number you see in the "build executor status", except that the number starts from 0, not 1.


If your job is configured to use a specific JDK, this variable is set to the JAVA_HOME of the specified JDK. When this variable is set, PATH is also updated to have $JAVA_HOME/bin.


The absolute path of the workspace.


For Subversion-based projects, this variable contains the revision number of the module. If you have more than one module specified, this won't be set.


For CVS-based projects, this variable contains the branch of the module. If CVS is configured to check out the trunk, this environment variable will not be set.


For Git-based projects, this variable contains the Git hash of the commit checked out for the build (like ce9a3c1404e8c91be604088670e93434c4253f03) (all the GIT_* variables require git plugin)    


For Git-based projects, this variable contains the Git url (like git@github.com:user/repo.git or [https://github.com/user/repo.git])


For Git-based projects, this variable contains the Git branch that was checked out for the build (normally origin/master)

Promoted Build Plugin Environment Variables

If you are using the Promoted Build Plugin, you will have access to the following environment variables. This allows you to access information about your Jenkins build since certain environment variables stated above (such as BUILD_TAG now refer to the Promoted Build Plugin's job.

Environment Variable





The URL of the original Jenkins job that is involved with the promotion. BUILD_URL now refers to the Promotion's URL



The name of the original Jenkins job that is involved with the promotion. JOB_NAME now refers to the Promotion's job's name



The Build Number of the job being promoted. BUILD_NUMBER now refer's the the Promotion Number



The Build ID (ex. "2005-08-22_23-59-59" (YYYY-MM-DD_hh-mm-ss) ) of the original Jenkins job. BUILD_ID now refer's to the Promotion's build ID.

Shell Scripts and Windows Batch Commands

If you're using a shell script to do your build, you can either put these environment variables directly into your shell scripts, or call them as parameters in your shell script. Below is an example how this can be done:

If you are executing a Windows Batch Command, the variables should be referenced using the %VARIABLE_NAME% pattern. For example:

Ant Scripts

If you're using an Ant script to do your build, you may include environment variables in property settings. Click on the Advanced... button just below where you put the Ant targets you want to build. This will display the Properties box. Below is an example how to use the Properties box to set Ant properties with Jenkins Environment variables:

As an alternative, you can use the Environmental prefix to pull in all environmental variables as properties right inside your build.xml file. Below is an example how to set the property "label" to include the Project Name and the Build Number:

<property environment="env"/>
<property name="label" value="${env.JOB_NAME}-${env.BUILD_NUMBER}"/>

Configuring automatic builds

Builds in Jenkins can be triggered periodically (on a schedule, specified in configuration), or when source changes in the project have been detected, or they can be automatically triggered by requesting the URL:


This allows you to hook Jenkins builds into a variety of setups. For more information (in particular doing this with security enabled), see Remote access API.

Builds by source changes

You can have Jenkins poll your Revision Control System for changes. You can specify how often Jenkins polls your revision control system using the same syntax as crontab on Unix/Linux. However, if your polling period is shorter than it takes to poll your revision control system, you may end up with multiple builds for each change. You should either adjust your polling period to be longer than the amount of time it takes to poll your revision control system, or use a post-commit trigger. You can examine the Polling Log for each build to see how long it took to poll your system.

Alternatively, instead of polling on a fixed interval, you can use a URL trigger (described above), but with /polling instead of /build at the end of the URL. This makes Jenkins poll the SCM for changes rather than building immediately. This prevents Jenkins from running a build with no relevant changes for commits affecting modules or branches that are unrelated to the job. When using /polling the job must be configured for polling, but the schedule can be empty.

Using a post-commit trigger in CVS

With some revision control systems, like Subversion, polling is very quick. Subversion can poll your project in a few seconds to see if there are any changes. In some revision control systems like CVS, polling can take quite a long time.

In this case, you should probably use a post-commit hook to trigger the build. In CVS, you can add a post commit trigger to the $CVSROOT/loginfo file. To edit this file, check out the CVSROOT project, edit the file, and then do a commit. Don't edit the file directly.

The loginfo file consists of two entries. The first is the repository, and the second is the post-commit hook to run. If you name your Jenkins projects as <project>-<branch>, you can use the following shell script trigger:

#! /bin/bash
/usr/bin/sed -n '/^  *Tag:/s/.*: *//p' | while read branch
    #  You need to set these
    wgetCmd=/usr/bin/wget           #Location of wget command
    logName=/usr/home/cvs/log.txt   #Logfile name
    projectBase=jenkins             # First part of the Jenkins project name
    hudsonUrl="http://hudson:8080"  #URL to trigger Jenkins
    triggerString="BUILD"           #String to trigger builds


    # Possible exceptions to Jenkins Name Rule
    if [ "$branch" == "REL_1_0_2" ]

    $wgetCmd -q $hudsonUrl/job/$hudsonJob/build?token=$triggerString
    echo "$wgetCmd -q $hudsonUrl/job/$hudsonJob/build?token=$triggerString" >> $logName
    echo "---------------------------------------------------" >> $logName

Builds by e-mail (sendmail)

If you have the root account of your system and you are using sendmail, I found it the easiest to tweak /etc/aliases and add the following entry:

jenkins-foo: "|/bin/wget -o /dev/null http://YOURHOST/jenkins/job/PROJECTNAME/build"

and then run "newaliases" command to let sendmail know of the change. Whenever someone sends an e-mail to "jenkins-foo@yoursystem", this will trigger a new build. See this for more details about configuring sendmail.

Builds by e-mail (qmail)

With qmail, you can write /var/qmail/alias/.qmail-jenkins as follows:

|/bin/wget -o /dev/null http://YOURHOST/jenkins/job/PROJECTNAME/build"


1 Maven requires that you include the parameter as part of the build goals.
Example Jenkins configuration for the Maven "Goals" field: clean install -DBUILD_NUMBER=${BUILD_NUMBER}

  • No labels


  1. Anonymous

    I am using the $

    Unknown macro: {BUILD_NUMBER}

    notation in a maven build successfully.


    mvn -Dbuild.id=$

    clean install

  2. Anonymous

    You can reference Hudson variables as any other property when building with Maven2.

    Hudson version 1.184

  3. Anonymous

    I am using Hudson 1.44, and I have two versions of JDK installed: 1.4 and 1.6. Some projects I need to build in 1.4 and others in 1.6. I created two JDK instances in Hudson in the configuration file (config.xml):

          <name>jdk 1.4</name>
          <name>jdk 1.6</name>

    Inside of my project definition, I select jdk 1.6, and I set the Ant build command in the following way:  

    -DJAVA_HOME=C:\jdk1.6.0_04 -DPATH=C:\jdk1.6.0_04\bin

    Unfortunately, when I build I get the following error:

     [javac] C:\hudson\jobs\<project>\workspace\<class>.java:18: cannot access java.lang.Object
        [javac] bad class file: C:\jdk1.6.0_04\jre\lib\rt.jar(java/lang/Object.class)
        [javac] class file has wrong version 49.0, should be 48.0
        [javac] Please remove or make sure it appears in the correct subdirectory of the classpath.
        [javac] private String text;
        [javac]                 ^
        [javac] 1 error

    What am I doing wrong?

  4. Unknown User (bilabee)


     Is there a way to customize the BUILD_NUMBER value?  (ie. padded 0's)

    Also, how can I reset this value to 1 after doing a few test builds?



    1. Unknown User (mark@kempster.org)

      I was able to do this by updating the number in nextBuildNumber text file inside of the jobs directory (and all sub-projects), and then bouncing the hudson server.

  5. Unknown User (machowy)


    what is the value of BUILD_ID in case of triggering builds by scheduled "Poll SCM" . Because it looks like this variable keeps time of starting "scanning" not the time of build (at least value of BUILD_ID is different than the name of folder with particaular build in build history). Could somebody help me?



  6. Unknown User (amitanand123@gmail.com)


    I am unable to customize my build process number ?

    I want to set my build number as TMT-100 so that when i trigger the build next time it becomes TMT-101,

    updating the number in nextBuildNumber is not effective for me.

    can anyone help me out of this issue.



  7. Unknown User (rmorrey)

    We are using Hudson to manage a bunch of custom builds and like the quickness afforted by Hudson in configuring a build. One of the issues we are trying to resolve is when there are two different branches involved in producing a build.  For example, many of our products use a common library, and occasionally a new branch of that common library is needed, along with the branch of a module (different modules).  It appears that Hudson's CVS setup only allows us to identify one branch, when what we need is a second CVS setup to identify an additonal branch. 

    Does anyone know how to handle such a situation?

  8. Unknown User (clementm)

    Does Hudson accept SVN Read-only repository ? Because i have some problems to configure it.

    In fact i can make update in command line but when i try to enter credential, it indicate that kind of message :

    "FAILED: svn: OPTIONS of '/svn/projectname/trunk': 403 Forbidden (http://servername:serverport)"

    With same repository url and same account of course.


  9. Unknown User (wthai@rockwellcollins.com)


     I have a problem when using the 'use update' checkbox.  I need to have it unchecked to ensure a clean environment.

     The project I'm building generates files that is owned by 'root'.  So when hudson tries to deletes these files, the build fails.

     How do I fix this problem?


  10. Unknown User (fabrice@xeberon.net)


    I am trying to develop a post-commit svn hook script in order to run hudson build but it is a hard task !

    It would be a good idea to write on the wiki a such script in order to avoid to lose time writting it

    Here my incomplete scrip (I have to find a way to get the projectName because REPOS is only ther path of the repo -..., maybe see svnlook changed -r $REV)



    Array=( $REPOS )


    Unknown macro: {#Array[@]}



    Unknown macro: {Array[$LastElementIndex]}

    HUDSON_URL=$( echo "$HUDSON_URL" | sed s/#PROJECT#/$ProjectName/g )

    echo $REPOS >> /tmp/commit.txt

    /usr/bin/wget -o /dev/null "$HUDSON_URL"

  11. Unknown User (jusyes@gmail.com)

    what is the variable that stores user who initiated build in hudson.
    This is so that to the email that is sent from hudson it can have who initiated build in hudson..

    Thanks in advance....

    1. Unknown User (cpendleton)

      Did you ever figure this out?  I displayed out all environment variables when my job ran and the user name is not in there.  Was you able to figure out a different way of getting the user into ant?

  12. Unknown User (martin.kropp)


    I've been using Hudson for a while for very simple projects. Now we are working on a larger web-portal project which has a recursive project structure.

    In the project root we have a "master" build.xml which calls all concrete subprojects' build.xml files.


    proj-root/build-app/builld.xml - here is the master build

    proj/app/firstapp/build/build.xml - here is build file of the Eclipse project firsapp

    How do I have to setup this in Hudson?

    Thank's a lot for your help.


  13. Unknown User (tim)

    Is the console output saved anywhere ?
    If so, which directory?

    1. Unknown User (rmorrey)

      The logs are stored in the C:/Documents and Settings/.hudson/jobs/<job name>/builds/<buildtime> folder in a file called simply "log".  It is a simple text file.

  14. Unknown User (rmorrey)

    We use Hudson to manage a release schedule of about twice a month.  These releases include code held on branches of various CVS modules, and any module can go at any given release.  A module can have two or more branches under development at any given time.  To manage the build cycle, we create a new Hudson job for each module in a release and include the expected release date of that module in the job name.  By creating a new tab for each release date, we can organize our releases and keep them straight. 

    That said, we want to preserve our build logs for audit purposes even after the build is no longer active.  We zip the job directory after a reasonable period of time, and remove it from the .hudson/jobs directory, so that it does not clutter the Hudson screen, and restart the Hudson service.  If we need to revisit a past module build, we simply unzip the job back into the jobs directory and restart Hudson.

  15. Unknown User (anna)


    when i was building a software,there would be an error message "java.exe cannot find ordinal number"

    I am very confused with this problem, could anyone else help me and tell me what to do?


  16. Unknown User (xav)


    Is there a way to use a script to trig the build other than these solutions:

    • you can setup a scheduler... But how to stop the build wihtout failling if nothing new to build
    • you can use an extern cron tab to trig the build using URL submission (need external hudson tool & setup)
    • you can add the plugin Dos Trigger, but dos script :'( (Why not a shell script?!?)

    If i'm missing something, thanks to tell me


  17. Unknown User (aputhiye)


    I am trying to build a software project on the CVS,but doesnt seem to be working,the same project builds successfully on the local machine but doesnt work on CVS.It gives an error saying "artifacts not found in the specified nexus repo.But when i check the specifies url  in the repo,all the artifacts are present .Checked the pom.xml file too,everything looks perfect and hence works fine fine on the local system.Can anyone help me in this regard.What might be the reasons for this?

  18. Unknown User (joe_matrox)


    I have a  software project using SVN and ANT. I purposely introduce some bad logic and commit to SVN. The ANT build is invoked and as expected Make errors

    pop up  BUT the errors go unnoticed by Jenkins.Jenkins reports in the LOGS as build SUCCESSFUL. Is there something that needs to be done in the ANT script or in the Jenkins



  19. Hi,

    I'm new to Jenkins. I try to build a free style project on Linux with Ant and additional Java options: ANT_ARGS="-lib ${WORKSPACE}/lib/..." in advanced settings.

    The environment variable WORKSPACE is expanded to: <path>//jenkins/jobs/<path>", so all the "." are changed to "/" and of course, the build fails.

    What am I doing wrong?


    1. The problem is not the environment variable WORKSPACE, because when I run a script as build method and launch Ant manually with ${WORKSPACE}, it's o.k.

      There is maybe a problem in passing the ANT_ARGS from Jenkins to Ant?

  20. Unknown User (ecliffg)


    How does the application get back the BUILD_ID or BUILD_NUMBER that their HTTP Post has caused when submitting the build request by performing an HTTP Post to the Jenkins Job using ".../buildWithParameters?token=TOKEN" to kick off a build?

    For example, if I have 6 applications running that each kick off the same job, each build would get a different build_id, but how does one keep track of which invocation caused which build_id?


  21. Unknown User (vishalrekala)

    How do we define custom variables which I want to use anywhere in the job.  Like i want to define three variables called MAJOR, MINOR and MAINT and use them as the version numbers for my project. 


    1. Unknown User (freyport)

      I realize that this is an old post, but you should probably look into EnvInject Plugin

  22. Unknown User (mako)

    Is it possible to use %WORKSPACE% inside the Jenkins' wizard?

  23. Unknown User (lindon_fox)


    Sorry, I think this is not the correct place to ask this question, but I could not find a better place to ask it.

    I am currently using the Archive the artifacts post-build step with normal files (and very happy). But when I am trying to "archive" a directory, I can't seem to get it right. (It is actually a .app package, which OSX's Finder treats as a file, but Terminal treats as a directory, so I guess it is a directory). This is what I am adding to the Files to archive field:


    Which does not work. This will not work either:


    But this will:


    This .ipa file is an actual file (according to Terminal).

    I know I could just add another build step and manually zip it, but I want to avoid that if possible. Does anyone have any ideas? (I have looked at the linked reference page with no luck - http://ant.apache.org/manual/Types/fileset.html)



  24. Unknown User (dweintraub)

    What about attaching the Promoted Build Plugin environment variables too? This will give us a single place where all environment variables can be found.

  25. Unknown User (kiranccase)


    I want to trigger the build from unix machine, but the thing 

    first i have to login with user1 and then change to user2 then only i'll be able to execute the build script.

    could you please let me , how can i do this?

    In my current setup i manage to login with user1 from jenkins, but i'm not able to execute the build script because this script can be executed by user2 only.

  26. Unknown User (dlovell)

    FYI: Under Configuring Automatic Builds, it says to request 


    But running Jenkins ver. 1.532.1, I find I have to request

    (I also have to append :8080 to YOURHOST)