EnvInject Plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID envinject Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
1.89
Oct 13, 2013
1.445
maven-plugin (version:1.445)
ivy (version:1.21, optional)
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Gregory Boissinot (id: gbois)
Usage Installations 2013-Apr 6452
2013-May 7037
2013-Jun 7679
2013-Jul 8400
2013-Aug 8918
2013-Sep 9464
2013-Oct 10365
2013-Nov 10780
2013-Dec 11073
2014-Jan 12104
2014-Feb 12837
2014-Mar 13796

This plugin makes it possible to have an isolated environment for your jobs.

Features

  • Removes inherited environment variables by the Jenkins Java process
  • Injects environment variables at node (master/slave) startup
  • Executes a setup script before or/and after a SCM checkout for a run
  • Injects environment variables before or/and after a SCM checkout for a run
  • Injects environment variables as a build step for a run
  • Injects password values for a run
  • Exports environment variables at the end of the build in order to to know the set of environment variables used for each build

Some use cases

  • To remove inherited environment variables (PATH, ANT_HOME, ...) at node level (master/slave), available by default for a job run.
  • To inject variables in the first step of the job (before the SCM checkout)
  • To inject variables based on user parameter values
  • To execute an initialization script before a SCM checkout.
  • To execute an initialization script after a SCM checkout
  • To inject variables as a build step obtained from a file filled in by a previous build step
  • To know environment variables used for a build
  • To inject build cause as environment variable for a build
  • To inject environment variables from the evaluation of a Groovy script
  • To export environment variables as a metadata in your binary repository

Build Causes

This plugin also exposes the cause of the current build as an environment variable. A build can be triggered by multiple causes at the same time e.g. an SCM Change could have occurred at the same time as a user triggers the build manually.

The build cause is exposed as a coma separated list:

BUILD_CAUSE=USERIDCAUSE, SCMTRIGGER, UPSTREAMTRIGGER 

In addition, each cause is exposed as a single envvariable too:

BUILD_CAUSE_USERIDCAUSE=true
BUILD_CAUSE_SCMTRIGGER=true
BUILD_CAUSE_UPSTREAMTRIGGER=true

Configuration

At node (master and slaves) level

At job level

Set up a clean environment

Inject variables after a SCM checkout

Inject variables as a build step

Variables Traceability

Each build captures environment variables and stores them in an environment file called 'injectedEnvVars.txt' located in
$JENKINS_HOME/jobs/<your_job>/builds/<your_build>.

For an old build, you can display injected environment variables through the right UI menu on the build page.

You can also get build environment variables by the following HTTP GET URL: <jenkins_url>/job/<job_name>/<build_number>/injectedEnvVars/export
XML, JSON and TXT format are supported.
For example:

  • curl -X GET H"Accept:text/plain" <jenkins_url>/job/<job_name>//lastBuild/injectedEnvVars/export
  • curl -X GET H"Accept:application/xml" <jenkins_url>/job/<job_name>//18/injectedEnvVars/export
  • curl -X GET H"Accept:application/json" <jenkins_url>/job/<job_name>//18/injectedEnvVars/export

Examples

Append to PATH on Windows

Gerrit Trigger plugin with parameterized Build branch name

  • Check "This build is parameterized"
    • Name: GERRIT_BRANCH
    • Default Value: master
  • Check "Prepare an environment for the run"
    • Evaluated Groovy script:
      if (!binding.variables.containsKey('GERRIT_REFSPEC')) {
          return [GERRIT_REFSPEC: "refs/heads/$GERRIT_BRANCH"]
      }
      

Additional features provided by other plugins

Shared Objects plugin contributes to Envinject plugin that enables you to populate shared objects as environment variables.

Extensibility with other plugins

EnvInject captures build environment variables populated by plugins providing environment variables through Jenkins extension points (such as BuildWrappers, EnvironmentContributions and so on).
Environment variables injected by the EnvInject plugin are available in Jenkins triggers (for example in all XTrigger plugin typologies, injected environment variable can be used).
Injected environment variables with the EnvInject plugin are captured by the BuildContext capture plugin.

Comparison with other plugins

This plugin is an alternative to Setenv Plugin and Envfile Plugin plugins
Note 1: The EnvInject plugin automatically migrates the Jobs configuration from these plugins. The setenv and/or the envfile plugins can be deleted from your plugin list.
Note 2: Master and slave are managed.

Known incompatibilities

  • with the MaskPasswords plugin.
    MaskPasswords plugin is able to mask password elements. However, technically,this plugin provides its own class.
    And we don't want to have a hard dependency from the EnvInject plugin to any other plugin. Therefore, Envinject can't retrieve information from the maskpassword plugin.
    However, EnvInject provides all MaskPasswords features.
  • with Tool Environment Plugin
    EnvInject can't use exported environment variables provided by the Tool Environment plugin.
    Instead, we suggest to use the SharedObjects Plugin. It covers Tool Env plugin features and provides a good integration with EnvInject.

Known limitations

  • Properties values can't end with backslashes in the properties content section
    (interpreted as content with multiple lines)
  • As into regular shell scripts, you are not able to use "." character for environment variable names
  • Only previous environment variables are available for polling
    Some plugins provide polling mechanisms (such as SCM plugins, XTrigger plugins, ...) and you want to use injected environment variables in form fields of these plugins. Unfortunately, injected environment variables are processed only at build time therefore after the build is scheduled. Therefore, we can't access environment variables configured within the job. However, previous injected environment variables (from the previous build) are retrievable (implemented for example in the XTtrigger plugins). For the otehr plugins, authors are free to add the envinject-lib library dependency in their plugins in order to provide the ability to use environment variables given the EnvInject plugin.

Jenkins core compatibility

This plugin requires Jenkins 1.444+

TODO LIST (Enhancement)

  • Priority Critical: Add tests (unit tests and integration tests)
  • Priority Important: Provide an abstraction layer for manipulating easier the environment variables
    • Provide a custom lifecycle during the job flow
    • Sort these variables
    • Break down into categories, etc

Note: Any contributions are welcome.
Feel free to fork the source code and provide a pull request

Changelog

1.88

* Fix issue #16316 - Changes to global variables not honored
* Log both source and resolved unreachable properties file paths
* Fix issue #14144 - use a WorkspaceListener to avoid injecting a temporary

1.87

* Actually load script from master

1.86

* Fix reopen issue #13348 - EnvInject overriding WORKSPACE variable

1.85

* Retain line break characters in property values.

1.84

* Add logger to Groovy script evaluation

1.83

* Fix reopen issue #16316 - Global variables not updated

1.82

* Fix issue #16566 - poll SCM not work after upgrade the EnvInject Plugin to 1.81
* Fix issue #16575 - SEVERE: Failed to record SCM polling - java.lang.NullPointerException - EnvInject Plugin
* Update to envinject-lib 1.15

1.81

* Fix issue #16239 - NPE in getRootDir
** Update to envinject-lib 1.14
* Remove Injected from Labels
* Fix issue #16380 - Starting with >1.73 global environment variables overrule build specific parameter variables
* Fix issue #16372 -Password parameter is malformed

1.80

* Fix issue #16233 - EnvInject plugin using a cached value for ${WORKSPACE}

1.79

* Fix issue #16316 - Global variables not updated
* Fix issue #16399 - SCM documentation is incorrect

1.78

* Fix issue #16219 regression from issue #14437 - Version 1.77 injects all environment variables into ANT command line (-D)

1.77

* Fix issue #14437 - envinject fails to "really" set/override build parameters

1.76

* Fix issue #16016 - Global passwords are visible for matrix configuration builds

1.75

* Add currentJob and currentBuild variables for Groovy scripts

1.74

* Correct spelling of Password from Passowrd ( merged from pull request)

1.73

* Fix issue #15658 - EnvInject Undefines Jenkins Global properties referencing WORKSPACE variable
* Fix issue #15664 - Help text for EnvInject plugin is wrong

1.72

* Fix issue #15146 - EnvJect unsets empty string properties returned in maps

1.71

* Support for new job types
* Replace "white-list" strategy for supported job types by use of BuildableItemWithBuildWrappers interface to access the job's buildWrapper list.

1.70

* Fix issue #15071 - Editing the description of Jobs throws an Error 500 message
* Update to envinject-lib 1.13

1.69

* Fix issue #14930 - Can't overload/update PYTHONPATH

1.68

* Fix issue #14897 - ConfigFileProvider variable is not seen by EnvInject
* Require Jenkins 1.444+

1.67

* Fix issue #14761 - Backslash broken on Properties Content injection
* Fix issue #14768 - Backslash is escaped from injected $WORKSPACE property on slave node

1.66

* Fix issue #14686 - Fail evaluating Groovy script before job run

1.65

* Add feature - Mask job password parameter value

1.64

* Fix issue #14645 - Executing external job results in an ClassCastException (ExternalRun cannot be cast to AbstractBuild)

1.63

* Fix reponed issue #14371 - NullPointerException in EnvInjectBuilderContributionAction.buildEnvVars during SCM poll
* Fix issue #14459 - Failed to record SCM polling with envinject plugin

1.62

* Fix issue #14371 - NullPointerException in EnvInjectBuilderContributionAction.buildEnvVars during SCM poll

1.61

* Fix issue #14367 - Global & node level self-referencing variables should work

1.60

* Fix issue #14290 - Support for Ivy project type

1.59

* Fix issue #14271 - EnvInject claims global env vars are unresolved on slave

1.58

* Fix issue #14284 - Single backslashes are droped or used as escape char

1.57

* Fix issue #14232 - EnvInject not handling properties file with logical lines

1.56

* Load environment variables from the node (therefore, you are able to redefine classic variables such as the PATH variable at node level)
* Upgrade to envinject-lib 1.8

1.55

* Technical release: Merge pull request - Make EnvInjectPluginAction implements EnvironmentContributingAction

1.54

* A few minor changes to keep jdk5 compatibility

1.53

* Fix regression on backward compatibility

1.52

* Remove env variables presence in build serialization file

1.51

* Add a complement to fix issue #12423 - Password masked by Mask Passwords are visible when using envinject plugin (no display environment variables when the job is running)

1.50

* Update to envinject-lib 1.7 (Enable to external plugin to retrieve envVars)

1.49

* Merge pull request - use UnsupportedOperationException instead of UnsupportedMediaException
* Merge pull request - added Japanese localization

1.48

* Fix issue #12878 - manage old data fails with RuntimeException: Failed to serialize hudson.model.Actionable#actions for class hudson.model.FreeStyleBuild

1.47

* Fix issue #13566 - EnvInject is messing around with my TEMP variable when username contains a dollar sign (windows)
* Update to envinject-lib 1.5

1.46

* Fix interaction with multijob plugin

1.45

* Add /export/txt, /export/xml and /export/json for the exportation

1.44

* Fix EnvInject Password process

1.43

* Fix reopened issue #12108 - EnvInject failure using multi-configuration jobs

1.42

* Fix issue #13183 - SCM variables resolution

1.41

* Fix issue #13157 - EnvInject cannot inject variables whose contents contain a dollar sign ($)

1.40

* Fix issue #13167 - Cannot use EnvInject in a Maven 2 Jenkins project

1.39

* Fix issue #13155 - Parameters are not working in EnvInject plugin 1.38

1.38

* Fix issue #13119 - Add feature: Set an environment variable based on value of user passed parameter

1.37

* Fix issue #13085 - Environment Variable Injection doesn't work when project run on slave node that sets the same variable

1.36

* Fix issue #13041 - PATH variable is being injected from master on multiconfiguration jobs

1.35

* Fix issue #13022 - EnvInject 1.33 doesn''t seem to work with Jenkins 1.454

1.34

* Change Environment contributors resolution

1.33

* Move global passwords injection to the 'Prepare job environment' section
* Add 'Inject job passwords'

1.32

* Fix issue #12944 - Env Inject Plugin doesn't substitute ${WORKSPACE} variable at all when used in 'Preparing an environment for the job'
* Fix issue #12963 - EnvInject plugin causes job to use JAVA_HOME instead of configured JDK

1.31

* Fix issue #12936 - EnvInject Plugin 1.30 does not display all properties on job config page

1.30

* Fix issue #12905 - PATH variable is not injected

1.29

* Fix issue #12876 - Version 1.20 and later removed all comments and new-lines
* Add test to issue #12841 - EnvInject Plugin 1.26 does not substitute ${WORKSPACE} correctly

1.28

* Fix reponed issue #12108 - EnvInject failure using multi-configuration jobs
* Fix issue #12841 - EnvInject Plugin 1.26 does not substitute ${WORKSPACE} correctly

1.27

* Add a build context to EnvInjectContributor

1.26

* Fix issue #12704 - WORKSPACE variable for concurrent builds are not defined properly.

1.25

* Fix issue #12809 - Injecting from file removes backslashes on ${WORKSPACE}

1.24

* Add the ability to inject password values
* Fix issue #12423 - Password masked by Mask Passwords are visible when using envinject plugin

1.23

* Fix issue #12788 - Missing variables when executing EnvInject script

1.22

* Fix NullPointerException for a setenv or a envfile migration

1.21

* Fix issue #12746 - envinject strips off "\" each time config page is opened

1.20

* Move properties content serialization to a Map (avoid carriage return issues)
* Fix usage of build variables for the 'Prepare environment jobs'
* Fix Injected environment vars when EnvInject is not configured

1.19

* Fix reopened issue #12423 - Password masked by Mask Passwords are visible when using envinject plugin

1.18

* Fix issue #12691 - Property variable not set if using a property file

1.17

* Fix migration from the setenv and envfile plugin

1.16

* Fix external EnvInjectContribution section display
* Fix text typo

1.15 (technical release)

* Refactoring + fix wrong commit

1.14

* Fix issue #12416 - Environment is not injected for each configuration in a multi-configuration project

1.13

* Add the extension point EnvInject Job Property Contributor to enable other plugins to contribute to this plugin for the prepare job step

1.12

* Fix issue #12423 - Password masked by Mask Passwords are visible when using envinject plugin

1.11

* Update to envinject-lib 1.2

1.10

* Update to envinject-lib 1.1
* Fix bug on the build end

1.9

* Export reuse code to a dedicated library: envinject-lib 1.0
* Fix typo

1.8

* Switch properties section and scripts section for the prepare step

1.7

* Fix issue #12293 - Incorrect inserting environment variables on linux slave

1.6

* Recording EnvVars contributing by other plugins at the end of the build

1.5

* Fix issue #12252 - envinject does not fail the build after Environment Script Content fails

1.4

* Fix portability in the history build.xml file (using the build reference instead of the absolute path of the EnvInjected file)
* Add the ability to load a properties file at node startup (at master and/or at slave startup)

1.3

* Move 'Triggered Build Cause' to Jenkins build variables option
* Add an export option to export environment variables to TXT, XML or JSON

1.2

* Fix NullPointerException when master has 0 executors

1.1

* Fix issue #12108 - EnvInject failure using multi-configuration jobs
* Fix issue #12084 -Variables resolved alphabetically rather than order found in content/file. ${WORKSPACE} not always getting resolved as result
* Accept script parameters to script path sections

1.0

* Fix issue #12027 - ${WORKSPACE} variable doesn't use my specific workspace directory anymore in a build step
* Make it stable for production

0.26

* Enhance display log
* Refactoring for fixing properties variables propagation

0.25

* Fix issue #11763 - Can not set some 'special' variable names the first time
* Technical Refactoring

0.24

* Make it extensible by an another plugin.

0.23

* Fixed issue #11595 - Some env variables can not be used to inject, for example $NODE_NAME

0.22

* Add the ability for the 'prepare environment' feature to load the properties file and the script file from the master node even if the build runs on a slave node.

0.21

* Add global properties and node properties process

0.20

* Fix issue #11439 - Can't add "environment inject" to pre-scm-buildstep plugin.

0.19

* Fix issue #11181 -Variables failing to be set if referencing previous variable

0.18

* Fix issue #11067 - Pre-SCM and Post-SCM environment scripts do not use Pre-SCM and Post-SCM properties

0.17

* Fix issue #11066 - Property Variables "Randomly" Not Working/Getting Unset

0.16

* Fix issue #11063 - Multiple "Inject Environment Variables" Build Steps All Show Same Content

0.15

* Backslashes in file path for windows platform are managed
* Added feature 'unset variable' when the variable is unresolved

0.14

* Integrate domi pull request (add trigger causes as environment variables)
* Fix issue #10980 - EnvInject to optinally trim trailing spaces

0.13.1

* Improve reporting errors

0.13

* Fix issue #10919 - Variables are shared between jobs

0.12

* Fixed issue #10916 - Properties not injected and build marked as failed

0.11.1 (technical release)

* Remove unused maven dependency

0.11

* Fix issue #10894 - Inject environment variables with property file not working

0.10

* Add the ability to unset system variable at node level
* Add an option to 'Keep Jenkins system variables'
* Fix issue #10845 and issue #10877 - master/slave sync / Job variables/parameters are missing
* Complete the fix to issue #10847

0.9

* Fix partially issue #10847 and issue #10845 - Enivronment is not separated
* The ability to 'Keep system variables' has been removed. The feature will be restored later (and moved at slave/node level (not at job level).

0.8

* Fixed variables restauration for Maven jobs

0.7

* Fixed variables propagation between typologies
* Fixed variables restore for all typologies

0.6

* Add a 'Keep Jenkins Build variables' option
* Add 'EnvInject' as prefix for plugin log messages
* Sort the EnvInject variables table

0.5

* Remove advanced sections

0.4

* Add a build wrapper
* Fix serialization fiels for JobProperty
* Add a migration procedure for setenv and envfile plugins

0.3

* Add variables resolution in elements

0.2.1

* Fix environment script content process

0.2

* Can inject environment variables as a build step.

0.1

* Initial version

Labels

Edit
plugin-buildwrapper plugin-buildwrapper Delete
plugin-builder plugin-builder Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment