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 user build vars on the plugin site for more information.

This plugin provides a set of environment variables that describe the user who started the build.

Variables provided

This plugin defines the following environment variables to describe the user who started the build:




Full name (first name + last name)


First name


Last name


Jenkins user ID


Email address

Usage example

Select Set Jenkins user build variables and reference the variables during the build:

Pipeline Examples

node {
  wrap([$class: 'BuildUser']) {
    def user = env.BUILD_USER_ID

Jenkins core compatibility

This plugin requires Jenkins 1.609+ (since 1.5 version of plugin).


1.5 (Dec 11, 2015)

  • (plus)  -  Workflow support
  • Requires 1.609 or higher of Jenkins.

1.4 (Oct 10, 2014)

  • (plus) - Support of BUILD_USER_EMAIL. Currently, only the explicit e-mail definition in user properties will work (see Mailer Plugin)
  • (error) - NPE on non-existent upstream builds (JENKINS-22974)

1.3 (Apr 12, 2014)


* [JENKINS-21955] Set BUILD_USER to "SCMTrigger" if a build is run because of a source code change


* Now works with Jenkins starting from 1.396 version.


* Initial version

  • No labels


  1. Unknown User (gbois)

    In my opinion, it is always difficult to have again another plugin for this field.
    I suggest you should look at the envinject plugin and extend it with your plugin. EnvInject plugin eanbles you to manage injected variables and keep track of variables for each build. Your plugin will extend it by adding your specific variables and could have all features provided by the envinject plugin.

    Extending EnvInject plugin can be done for example with the shared-objects plugin.

    Let me know if you need help.

  2. Unknown User (gkonovalenko)

    Hi Gregory,

    thx for pointing out. Agreed with you. Before implementing this I looked through EnvInject, hoping that it provides such fields.

    I'll have a look.

    1. Unknown User (gbois)

      Any updates?

      1. Unknown User (gkonovalenko)

        Not yet. I've emailed you requesting if there are any example of such extension. If so, could you please share link for it?

        1. Unknown User (gbois)

          Just contribute to the EnvironmentContributor extension point.
          And automatically, all your environment variables will be captured by the EnvInject plugin

  3. Unknown User (zhh)

    We run into JENKINS-12528 using started-by-envvar. Can this plugin cope with the situation?

    1. Unknown User (gkonovalenko)

      Hi Hua,

        you can give it a test try. But more likely this won't work.

        This is because both plugins use User sub-types of Cause to identify the user started the build.  Started-By Environment Variable Plugin uses only deprecated UserCause, Build User Vars Plugin uses both deprecated UserCause & new UserIdCause (maybe usage of second will help you).

        And as per you bug report, you can see following message: "Legacy code started this job. No cause information is available"
        This message is output of jenkins itself, not plugins' and means that there is no source to get Username of user started the build.

        As I know there is no other way to get username, so if test try will also fail, I'd suggest you to reassign this bug (or transform to feature request) to Promoted Builds Plugin, asking to fix absence of build Cause.

        Let me know if you will need further help.

      1. Unknown User (zhh)

        I also suspected the same. Thanks for the clarification!

  4. Unknown User (btb3)

    @Gavriil Konovalenko (Plugin Implementer): Does this here plugin fully replace Started-By Environment Variable Plugin? (Apart from the different var-names of course?)

    1. Unknown User (gkonovalenko)

      Yes, you're right -- it does the same.

  5. Unknown User (nigel_robbins)


    The BUILD_USER variable is unset on downstream Solaris jobs for some reason. The initial job is on Solaris 10 which triggers jobs on Solaris 9, Solaris 10 (different host), Linux 32, Linux 64, HP Itanium, HP PA-RISC. The BUILD_USER variable is unset on the downstream Solaris 9 and 10 jobs. I've not checked the other downstream jobs (e.g. Linux 32) to see if BUILD_USER is unset.
    Thanks !

    1. Unknown User (gbois)

      Please could you report a bug?

      1. Unknown User (nigel_robbins)

        When creating a Jenkins JIRA Issue, what do I enter in the "Component/s" drop down since it doesn't seem to find "build-user-vars-plugin" ?

        Thanks !

    2. Unknown User (gkonovalenko)

      Hi Nigel.

      This is not a bug. Build user could be identified only in case if build was started by user. If build was triggered by other cause, f.e. by timer or by end of upstream job -- there is no data about user, who had started the build.

      1. Unknown User (larrycai)

        Are there any workaround solution to do this ?

        Currently in the console, I can see the real triggered user name even it is trigggered by upstream project

        Started by upstream project "abcd" build number 4
        originally caused by:
        Started by user larry
  6. Unknown User (bkraus)

    Thanks for your useful plugin which IMHO is truly a missing feature in Jenkins ;-)

    It would be very handy to also have the email of the user available. Is it possible for you to add this?

    Thanks in advance!

  7. Unknown User (jsirex)

    When I use this plugin with crowd2-plugin I got incorrect BUILD_USER_ID which looks like:

    FirtsName, Last Name (login_name)

    I'm not sure is this issue related to your plugin or to jenkins-crowd2 plugin.

    Did a little trick:

    USER=`echo ${BUILD_USER_ID} | sed 's/.*(\(.*\))/\1/'`


    1. Unknown User (gkonovalenko)

      Hi jsirex,

           Thanks for sharing workaround for this particular case.

           Actually this isn't and issue of build-user-vars-plugin or jenkins-crowd2 plugin. This plugin simply sets BUILD_USER_ID

       with appropriate value from jenkins build cause. And this value, I guess, is set by Jenkins basing on data provided by jenkins-crowd2 plugin. So it looks like from point of jenkins-crowd2 plugin view userId has format of "FirstName, LastName (login_name)."

           You can address this to jenkins-crowd2 plugin developers, but I think you workaround is better option.

  8. Unknown User (yurymilchenko)

    Chuck Norris Approved!

    Brilliant Plugin

  9. Unknown User (mrkk)

    kohsuke, why is this not part of jenkins core? :)

  10. Unknown User (epkaxma)

    I'm trying to use this with build-name-setter plugin but I can't get it to work. Am I missing something obvious?

    1. Unknown User (gkonovalenko)

      Hi Martin, what's going wrong? Please provide an example of what you're doing.

      1. Unknown User (epkaxma)

        It looks like the  build-name-setter plugin executes before the build user vars. When the build-name-setter tries to set the build name with BUILD_USER_ID there is no variable set and it fails. Is there some way to change the evaluation order in the Build Environment part of the job config?

        We have lots of jobs started by lots of users, I'll be the local hero if I can get this more visible.

  11. Unknown User (linusdsunil)

    Does this plug-in really work?

    I tried with my Jenkins setup 1.471; Did not find it working.

    1. Unknown User (gkonovalenko)

      Hi Sunil, yes it works. What's your issue? What is going wrong? Haven't you forgotten to enable "Set jenkins user build variables" checkbox?

      1. Unknown User (linusdsunil)

        I do have the checkbox checked. I am trying to do exactly same as shown in the Usage Example here on this page. Jenkins is on Windows hence I tried - Execute windows batch command  in Post build Step. I tried following variations - 

        echo "Full name: $BUILD_USER"

        echo "Full name: " $BUILD_USER

        echo "Full name: " ${BUILD_USER}

        echo "Full name: ${BUILD_USER}"

        For all these output was either - Full name:  $BUILD_USER 

        OR Full name: ${BUILD_USER}

        1. Unknown User (gkonovalenko)

          Hi Sunil, in case of windows batch you should use %BUILD_USER% instead of $BUILD_USER.

          echo "Full name: %BUILD_USER%"
          echo "Full name: %BUILD_USER_FIRST_NAME%"
          echo "Full name: %BUILD_USER_LAST_NAME%"
          echo "Full name: %BUILD_USER_ID%"

          1. Unknown User (linusdsunil)

            Thanks for that reply. 

            Here's what I found:

            • This works if Build gets triggered by Jenkins User.
            • Does not get any value if the build is triggered by SCM change
            • Does not get any value if the build is triggered by Timer

            I wish there was a way to distinguish if the build is triggered by Timer Or SCM Change.

            1. Unknown User (larrycai)

              This is what I want as well !

            2. Unknown User (roosto)

              Have you looked into the BUILD_CAUSE and/or BUILD_CAUSE_TIMERTRIGGER environment variables?

  12. Unknown User (jm0221)


    Having a bit of trouble with passing BUILD_USER_ID from one project (dev build) to a downstream project (to test it). I've "Set jenkins user build variables" set and when I do a build I can see them all if I do an env in the build shell step:


    So to pass them to the downstream I've "Trigger parameterized build on other projects" set and a few predefined key/value pairs. The thing is only UPSTREAM_BUILD_NUMBER and UPSTREAM_BUILD_URL are actually worked out, and the others are just as is.


    In the downstream project console log when env is called from the shell script (and visible when the downstream project is in the queue by hovering over the job) they aren't passed through:


    what am I doing wrong. Do I need to use envinject plugin? I just want to pass the userid so I can take that and mail the person that started the overall job. 

    Thanks in advance,


    I switched to using JobExporter from the main job, set it to artifact the properties file and still pass the build number in a parameterized build of the downstream job. Then in it wget the correct file to its workspace and grab what I need.

  13. Unknown User (magjac)

    This plugin doesn't work for matrix jobs. I'd like to file a bug i JIRA, but the build-user-vars-plugin component doesn't exist. Can someone create it?

  14. Unknown User (godisone)

    Hey folks,

    Trying to download build-user-vars-plugin but can’t find it in available plugins in jenkins. Is it named something different? or any tip to download it.


  15. Unknown User (godisone)

    Hey folks,

    Trying to download build-user-vars-plugin but can’t find it in available plugins in jenkins. Is it named something different? or any tip to download it.


    1. Unknown User (tdwong)

      I was able to install it via Jenkins web UI.  From "Manage Jenkins" >> "Manage Plugins" >> choose "Available" >> type "user build" in the filter field".  The plug-in is actually showing as Jenkins user build vars plugin after installed.

  16. Unknown User (rsennat)

    This plugin is not working on matrix config projects. It would be good if this plugin supports that too.

    Even after enabling "Set jenkins user build variables" and trying to print in the execute shell command using "export BUILD_USER=$BUILD_USER"05:16:35 $ /bin/sh -xe /tmp/hudson1996225104865305122.sh
    05:16:35 + export BUILD_USER=
    05:16:35 + BUILD_USER=

  17. Unknown User (tdwong)

    This is really a great plug-in, especially for Jenkins newbie like me.

    I do have a feature request --- Is it possible to enhance this plug-in to retrieve the BUILD_USER_EMAIL value?

  18. Unknown User (vishalrekala)

    Will this work in Groovy?

    I would like to use in Execute Groovy Script????

  19. Unknown User (kerrhome)

    Is it BUILD_USER or BUILD_USER_NAME or both?

    1. Unknown User (gkonovalenko)

      Check plugin description for list of supported variables:


      Remember about variables expansion, i.e. in linux it will be $BUILD_USER but in windows - %BUILD_USER%

  20. Unknown User (masthanvalig)

    Hello Team,

    I have a scenario, like we have 100+ jobs in our Jenkins. The requirement is, the editable email notification plugin should send an mail with the detials of the Build Requestor.
    With Build user vars plugin we are able to acheive this , by selecting the option " set jenkins user variable" in Configure Jenkins Job page and including $Build_User in email content.
    As we have 100+ jobs is there any option to set this option at Manage Jenkins level.
    I have declared the $BUILD_USER in the Default Content at Manage Jenkins level. But we are getting the Build Requestor details only for the Jobs for which the option " set user jenkins variable" option is selected.
    Is there any option by which we can acheive this by doing something at Manage Jenkins level instead of configuring each and every jobAs we have 100+ jobs.

    Thanks for your help in advance.

    Masthan Vali

    1. Unknown User (gkonovalenko)

      Hi Masthan,

      very good question, worth raising a feature request. This needs s code update and won't be as fast as you would like to have it.

      there also were questions like "why this is not part of Jenkins". Probably this will become default Jenkin's feature at some point of time :)

      as workaround, I would suggest you find jobs folder on the file system and update all jobs' configs by adding tag enabling "set user jenkins variable" option.

      1. Unknown User (masthanvalig)

        Hello Gavrill konovalenko,

        Thankyou very much for your quick respose and work around.
        Jenkins users would be excited to see this feature as default one.
        Wishing Success to the team.

        Masthan Vali

      2. Unknown User (masthanvalig)

        Hi Gavriil,

        I have followed the work around provided by you. I have executed below line where I could do modification to the config.xml and the 'set user jenkins variable" got enabled.

        perl -i -pe 's/\<buildWrappers\/\>/\<buildWrappers\>\n\t\<org.jenkinsci.plugins.builduser.BuildUser plugin="build-user-vars-plugin@1.5"\/\>\n\t\<\/buildWrappers\>/g' ./config.xml

        But we need to do this to each and every job's config.xml. Could you please help me with a script which executes the above modification in each and every job's config.xml under /jenkins/jobs//config.xml

        1. Unknown User (gkonovalenko)

          Hi Masthan,

          here is something what will help you do replacement in multiple files: http://stackoverflow.com/questions/19995368/perl-find-and-replace-specific-string-in-mulitiple-text-file

          Have a fun :)

  21. Unknown User (stewartev)

    Is anyone using this plugin in conjunction with the Environment Dashboard plugin ( https://wiki.jenkins-ci.org/display/JENKINS/Environment+dashboard+plugin )?  I'm trying to use ${BUILD_USER_ID} as my build number for dashboard display but it doesn't get expanded (the dashboard shows literally ${BUILD_USER_ID}).  However in my shell build step,  "echo $BUILD_USER_ID" works as expected.

    1. Unknown User (sreekanthcs)

      Hello Stewart,

      I am also facing almost the same issue, "$BUILD_USER_ID" is what it prints and not the value.

      Rolling back to version 1.4 is working fine.

  22. Unknown User (kraxel)


    I want to use the Variables from this plugin in a groovy post-build. since it is not explicitely mentioned, can somebody confirm, that using the variables other than in a regular build step is not supported?

    If so, I really would like to vote for this feature in future releases.

    All recommendations I've found so far are workarounds in best case but in fact they're rather ugly tries to overcome this (potential) limitation.

    I'd really appreciate if there is a smart solution by extending this plugin.

    But perhaps I'm totally wrong and just not able to use it correctly? Then, I'm happy to learn how to do so.

    Thanks alot

  23. Unknown User (demogorgonx)

    I can't get the Build User Vars Plugin to work with the Pipeline Plugin (https://wiki.jenkins-ci.org/display/JENKINS/Pipeline+Plugin).

    I noticed that checking the "Set jenkins user build variables" box adds the following line to the config.xml of my Jenkins job:

    <org.jenkinsci.plugins.builduser.BuildUser plugin="build-user-vars-plugin@1.5"/>

    So I tried the following in my Pipeline script:

    import org.jenkinsci.plugins.builduser.BuildUser
    echo "${env.BUILD_USER}"

    But it prints out null.

  24. Unknown User (jjuel)

    I am not able to get this plugin to work. I am on Windows. I have selected the checkbox and added in the line:

    echo "Build started by: %BUILD_USER%"

    Then in my log it just prints out:

    Build started by: %BUILD_USER%

    And idea? I can give more information if needed. Thanks!

    1. Unknown User (demogorgonx)

      You could double check that you're running a "Windows batch command" as opposed to an "Execute shell" command. The % signs for varaibles would only work in the former.

      1. Unknown User (jjuel)

        Well it appears that we are using PowerShell. However, when I change it to $BUILD_USER I get a blank or null like it isn't being set. So I guess I am having a similar issue to yours above mine here.

  25. Unknown User (thalion)

    When using AD I'd expect the $BUILD_USER_EMAIL (for instance) to be populated from the AD and not manually set. Any solutions?

  26. Unknown User (johntiger1)

    Note that on the Jenkins plugin page I have to search for "

    " to install it

  27. Unknown User (roger_groom)

    I'm not having any luck getting this plugin to work. Jenkins 2.119 on Ubuntu.

    My build job has a bash script containing the following however each of BUILD_USER_FIRST_NAME and BUILD_USER_LAST_NAME are always returned empty. The user logged-in who is starting the build does have a first name and last name specified.


  28. Unknown User (hairbuilder)

    Make sure to enable the "Set jenkins user build variables" in your build environment for the Jenkins job you are working on.

  29. Unknown User (shadow00caster)

    I'm not able to get this to work either, I have the "Set jenkins user build variables" checked in my job and the variable just returns empty.  I am using a Powershell build step, other Jenkins env vars work such as $ENV:JOB_NAME work normally, but none of the ones from this plugin work properly.

    1. Unknown User (shadow00caster)

      I had to use $ENV:BUILD_USER for this to work, at least in my Powershell build step.

  30. Unknown User (opvissen)

    Doesn't work with Multi-branch pipelines (where you have a Jenkinsfile under source control).

    It looks like it's stopped by Sandbox security.

    It also doesn't work in a trusted global library.

    CORRECTION: It does work if you upgrade your pipeline plugin collection to the latest ones.