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

Plugin Information

View Build Name and Description Setter on the plugin site for more information.

This plugin sets the display name of a build to something other than #1, #2, #3, ...so that you can use an identifier that makes more sense in your context. When you install this plugin, your job configuration page gets additional setting that lets you specify a build name for each new build.

You'll normally use some tokens that evaluates dynamically to some interesting values, such as the unique sequential number, Subversion revision ID, git branch name, formatted build timestamp, etc. The token expansion mechanism is provided by the Token Macro Plugin and therefore extensible. You can click the help button on the right to see the tokens available in your Jenkins.

You also could set a build name at any point of the build process in order to do that just add a setter build step to your job:

New build name consists of text file content and macro (which is also evaluated using Token Macro Plugin):


you could change the order by checking a checkbox "Insert macro first" so build will be:


After the build name is set it looks like this:

Also note that the build name can be manually modified any time through the UI. People interested in this plugin may be also interested in the Description Setter Plugin, which does similar things for build description and instead of the name.


Version 1.6.9 (Mar 03, 2018)

  • (error) JENKINS-39674 - Prevent file descriptor leak in the "Update Build Name" step

Version 1.6.8 (Jan 16, 2018)

Version 1.6.7 (Jul 12, 2017)

  • (error) JENKINS-33527 - Prevent concurrency issues in Environment VarSetter
  • (info)  PR #15 - Update minimal core requirement to 1.609 and fix issues

Version 1.6.6 - skipped

Version 1.6.5 (Apr 24, 2016)

  • (error) Fix JENKINS-34415 - Fixed bug with broken backward compatibility
  • (error) Fix JENKINS-33687 - Fixed bug with BUILD_DISPLAY_NAME environment variable not updated

Version 1.6.3 (Apr 16, 2016)

  • (error) Fix JENKINS-34181 - Fixed bug with NPE
  • From this versin the plugin is also available in Jucies UC (alternative update center). It means that you can install Jucies Plugin on your Jenkins client (follow these steps https://github.com/jucies/releases) and get the most recent version of this plugin faster. Please note that page of Jucies plugin is not available at the moment because of maintenance.

Version 1.6.0 (Apr 11, 2016)

  • (error) Fix JENKINS-31681 - Fix bug with optional token-macro dependency

Version 1.5.1 (Nov 11, 2015)

  • (error) Fixed bug with file name check (requires Jenkins 1.426)

Version 1.5 (Nov 3, 2015) is potentially broken

  • (plus) Added setter build step to set build name at any point of the build process (requires Jenkins 1.426)

Version 1.3 (Aug 2, 2011)

  • Made to work correctly with matrix projects (requires Jenkins 1.426)

Version 1.2

  • Added description for update center

Version 1.0 (Mar 1, 2011)

  • First release


  1. Unknown User (foch)

    I'm highly interested in this plugin, as it will give to my users a readable name. In fact I would need to display a parameter provided to the build in the build name. How could I do that?
    Thanks and regards,

  2. Unknown User (gregveres)

    This really needs to work with the Version Name plugin. That plugin creates an environment variable. Can we get this plugin to work with environment variables? That would make it much more useful immediately until other plugins start using the Token Macro Plugin.



    1. Unknown User (farshidce)

      filed JENKINS-9159 for this issue.

  3. Unknown User (ddrew)

    I've been trying to use this but it just seem fundamentally broken. If I use the ${VARNAME} syntax then it logs an unrecognized variable error for anything other than ${BUILD_REVISION}, including obvious things that should work like ${SVN_REVISION}. If I use the ${ENV,var=VARNAME} syntax then it just inserts the text verbatim without expansion ("mybuild.${ENV,var=VARNAME}")

    Any plans to fix this because I really need to be able to set build names :P



    1. Unknown User (odonnelp)

      The ${ENV,var="VARNAME"} syntax does work, but you MUST put quotes around the VARNAME. I tried it without the quotes and got the same result as you. With the quote it works fine.

  4. Unknown User (toniocus)

    Strange behaviour on this plugin, not sure if its correct (and will help me solve my problem too :-) )

    Seems that Macro replacer just logs error messages when something is wrong with the definition, except
    when a file (from PROPFILE Macro) is not found, in this case the BUILD fails, with a IOException FileNotFound.

    In my case the PROPFILE will be generated after the build, so it is correct not to find it, before the build,
    any possibility of handling it somehow ?

    Is this the correct behaviour ?

    After thinking a bit: perhaps a "default" optional macro-property will help
    solving it ?

    1. Unknown User (tom_alex)

      I've a similar issue, i'm generating the PROPFILE after the SVN checkout.  Not sure how to handle it, since build-name-setter runs "pre-build".  

      Would be good if this can be ran as a "post build task".

  5. Unknown User (bduffy)

    Does the Build Name Setter plugin provide an environment variable that I can use to access the resultant build name?  The


     environment variable gives me the actual build number of a build, but I don't seem to be able to access the build name set by the Build Name Setter plugin through the environment.  Should I log a request for this?

    1. Unknown User (mdobrindt)

      Can we can an answer for this question?

      It would be nice to be able to address the build name the same way we can address the build number or the job name.



      1. Unknown User (demogorgonx)

        I recommend trying out the Version Number Plugin: https://wiki.jenkins-ci.org/display/JENKINS/Version+Number+Plugin

        It offers similar functionality to the Build Name Setter (if you check the "Build Display Name" option), but also gives you an environmental variable that can be used to access the resultant build name.

  6. Unknown User (kaibutsux)

    Is it possible to use set the build name from a push notification? I want to build all branches in my project and I have polling enabled (no schedule) but I just want to label the build with the approrpriate branch.

    I am using: 

    #${BUILD_NUMBER}: ${ENV,var="BRANCH"}

    for the "Set Build Name" option.

    And my push notification url is: curl --data "url=[projectName]&BRANCH=$branch" "http://[jenkinsServer]:8080/git/notifyCommit"

  7. Unknown User (ddenlinger)

    As a fan of logging it would be nice to get a log line any time the plugin is setting the name.

    Build name setter plugin setting name to '#${BUILD_NUMBER}:${GIT_BRANCH}' resolves to '#123:master'
  8. Unknown User (toshee2000)

    Does this override the display name of builds in queue? Or will it still display the projected build number?

  9. Unknown User (toshee2000)

    Maybe it would be better to provide an option to update the build name before checkout (instead of after) for cases that do not rely on checkouts for the build name.

    Sometimes it takes time to checkout and build name is not updated until it finishes. It would be nice if the build name updates the soonest possible time.

  10. Unknown User (joltmans)

    To the author of this plugin. It would be appreciated if the plugin was placed under some kind of license.

    MIT License is the most common for Jenkins plugins.

  11. Unknown User (brantone)

    How is it possible that the version was bounced up to 1.5, but Git pom.xml is still showing 1.4-SNAPSHOT???

  12. Unknown User (poochie)

    I searched all around for documentation on how to use capture groups successfully, with BUILD_LOG_REGEX. I kept putting my capture syntax into the regex, and it would always dump out the whole line that matched, instead of my group. I only found it with some trial and error, that you have to use the "substText" attribute and reference your groups with "$X", where X is the index of the group. I also couldn't find any good documentation on what exactly the syntax IS for using the token macro stuff. After much playing around, and combining this information, I finally got the following syntax to work:

    #${BUILD_NUMBER} ${BUILD_LOG_REGEX,regex="Computed the package version to be ([0-9]+-[0-9]+)",maxMatches=1,showTruncatedLines=false,substText="$1"}

    I'm leaving this comment here in case someone else spends a few hours stumbling around this and trying to reverse engineer it as I ended up doing.

    Edit: Formatting

    1. Unknown User (slawko)

      Thank you Blake! You helped a lot. Your post was the only information I have found over the Internet on how to use BUILD_LOG_REGEX properly. I didn't have enough time to go through the plugin's sources to find it out ion my own, so thanks a lot for sharing this!

      The so called "help" displayed in jenkins is useless and lack of documentation is disturbing (smile) 

  13. Unknown User (vhout)

    Version 1.6.0 breaks our jobs:java.lang.NullPointerException
    at org.jenkinsci.plugins.buildnamesetter.BuildNameSetter.setUp(BuildNameSetter.java:41)
    at hudson.model.Build$BuildExecution.doRun(Build.java:156)
    at hudson.model.AbstractBuild$AbstractBuildExecution.run(AbstractBuild.java:534)
    at hudson.model.Run.execute(Run.java:1738)
    at hudson.model.FreeStyleBuild.run(FreeStyleBuild.java:43)
    at hudson.model.ResourceController.execute(ResourceController.java:98)
    at hudson.model.Executor.run(Executor.java:410)

    1. Unknown User (le0)

      The bug is fixed in version 1.6.3

  14. Unknown User (ssbarnea)

    It would be great if this page would also document the Jekinsfile approach of setting the build name.

  15. Unknown User (munsingh)

    Is there any way via this plugin or some other plugin to update the Build Name of the Parent Job as well in a multi-configuration job? What I have observed is that in case of a multi-config job, if the Update Build Name is used, it does update the build name of the child jobs but not of the parent. I need to update the Parent Build Name as well.

    Any pointers folks?

  16. Unknown User (bahdad)

    What was changed in the latest version? Where is changelog?

  17. Unknown User (sudha_paridi)

    Using Jenkins version 2.107.1 and this plugin 1.67 and want to update to 1.69. But it does not show up in update center. Dont want to update manually and restart Jenkins. 

  18. Unknown User (tobeychris)

    Does anyone know if it is possible to have the Build Name Setter execute before the Slack plugin? Right now the slack plugin will only send the build number when builds start, but sends the changed build name when they are done.

  19. Unknown User (valeriefdes)

    We use the description setter plugin to create a static link that triggers another project in the same Jenkins. How can we pass the value of the logged in user to the job that is being triggered? Is there any variable for the same? Maybe a script? 

    http://<myJenkins>/job/dummyJob/buildWithParameters?token=dummyToken&USER=${BUILD_USER} doesn't work for obvious reasons (smile) 

  20. Unknown User (brockers)

    I'm having an issue with the ${FILE,path="PATH"} macro that maybe someone can help with.  It seems to add an extra space at the end of the file.  So


    Produces something like 1.0.0 -15  Things I've tried so far is to verify that the file doesn't include a newline or extra space and using the bash style parameter expansion (which doesn't seem to be available on the ${FILE,path=}

    Thanks for any help in advance

  21. Unknown User (thuongshoo)

    Unknown User (brockers) the same. When I see the log content, it seems that this plugin cannot handle windows style new line character

  22. Unknown User (jitenjha11)

    Dear All,

    When I am using, "Build-Name-Setter" Plugin to Display branch name. It is going to display, GIT branch name, but when I am trying to use it for SVN, it is not working. I have tried ${"SVN_BRANCH"},  ${"SVN_BRANCHES"},  ${"BRANCH"},  ${"EVN_BRANCH"},  ${"env_BRANCH"},  ${"branch"}.

    SVN URL: http://svnurl/branches/_pre_trunk

    I want to display "_pre_trunk or any SVN branch name" on build history job.

    Can anyone tell me right parameter or any other way for display branch name in build history for SVN?