Child pages
  • Build Name Setter Plugin
Skip to end of metadata
Go to start of metadata

Plugin Information

View build-name-setter on the plugin site for more information.

This plugin is up for adoption. Want to help improve this plugin? Click here to learn more!

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):

<file_if_defined><macro_if_defined>

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

<macro_if_defined><file_if_defined>

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.

History

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

22 Comments

  1. Hello,
    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,
    Julien

  2. 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.

    Thanks

    Greg

    1. filed JENKINS-9159 for this issue.

  3. 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

    Thanks

    Dan

    1. 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. 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. 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. Does the Build Name Setter plugin provide an environment variable that I can use to access the resultant build name?  The

    ${BUILD_NUMBER}

     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. 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.

      Thanks,

      Mike

      1. 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. 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. 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. Does this override the display name of builds in queue? Or will it still display the projected build number?

  9. 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. 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. How is it possible that the version was bounced up to 1.5, but Git pom.xml is still showing 1.4-SNAPSHOT???

  12. 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

  13. 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. The bug is fixed in version 1.6.3

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

  15. 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. What was changed in the latest version? Where is changelog?

Write a comment…