Skip to content
This repository has been archived by the owner on Dec 15, 2021. It is now read-only.

Commit

Permalink
Browse files Browse the repository at this point in the history
Merge pull request #104 from jglick/withEnv-JENKINS-26128
[JENKINS-26128] withEnv
  • Loading branch information
jglick committed Mar 30, 2015
2 parents 205f27b + e19ac36 commit 42805fe
Show file tree
Hide file tree
Showing 14 changed files with 485 additions and 45 deletions.
1 change: 1 addition & 0 deletions CHANGES.md
Expand Up @@ -4,6 +4,7 @@ Only noting significant user-visible or major API changes, not internal code cle

## 1.5 (upcoming)

* [JENKINS-26128](https://issues.jenkins-ci.org/browse/JENKINS-26128) Added `withEnv` step.
* Now based on Jenkins core 1.596.1.
* Avoid some possible name clashes with function names in scripts (`build` reported).
* [JENKINS-27531](https://issues.jenkins-ci.org/browse/JENKINS-27531): startup error in 1.597+ loading build records migrated from before 1.597.
Expand Down
17 changes: 14 additions & 3 deletions TUTORIAL.md
Expand Up @@ -211,17 +211,27 @@ node {
}
```

(Note: you cannot run the above script in the Groovy sandbox until Workflow 1.1 or later.)

Properties of this variable will be environment variables on the current node.
You can also override certain environment variables, and the overrides will be seen by subsequent `sh` steps (or anything else that pays attention to environment variables).
This is convenient because now we can run `mvn` without a fully-qualified path.

We will not use this style again, for reasons that will be explained later in more complex examples.
Setting a variable like `PATH` in this way is of course only safe if you are using a single slave for this build, so we will not do so below.
As an alternative you can use the `withEnv` step to set a variable within a scope:

```groovy
node {
git url: 'https://github.com/jglick/simple-maven-project-with-tests.git'
withEnv(["PATH+MAVEN=${tool 'M3'}/bin"]) {
sh 'mvn -B verify'
}
}
```

Some environment variables are defined by Jenkins by default, as for freestyle builds.
For example, `env.BUILD_TAG` can be used to get a tag like `jenkins-projname-1` from Groovy code, or `$BUILD_TAG` can be used from a `sh` script.

See the help in the _Snippet Generator_ for the `withEnv` step for more details on this topic.

## Build parameters

If you have configured your workflow to accept parameters when it is built (_Build with Parameters_), these will be accessible as Groovy variables of the same name.
Expand Down Expand Up @@ -563,6 +573,7 @@ env.PATH = "${mvnHome}/bin:${env.PATH}"
```

since environment variable overrides are currently limited to being global to a workflow run, not local to the current thread (and thus slave).
You could however use the `withEnv` step as noted above.

You may also have noticed that we are running `JUnitResultArchiver` several times, something that is not possible in a freestyle project.
The test results recorded in the build are cumulative.
Expand Down
@@ -0,0 +1,124 @@
/*
* The MIT License
*
* Copyright 2015 Jesse Glick.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/

package org.jenkinsci.plugins.workflow.steps;

import org.jenkinsci.plugins.workflow.BuildWatcher;
import org.jenkinsci.plugins.workflow.JenkinsRuleExt;
import org.jenkinsci.plugins.workflow.cps.CpsFlowDefinition;
import org.jenkinsci.plugins.workflow.job.WorkflowJob;
import org.jenkinsci.plugins.workflow.job.WorkflowRun;
import org.jenkinsci.plugins.workflow.test.steps.SemaphoreStep;
import org.junit.Test;
import org.junit.ClassRule;
import org.junit.Rule;
import org.junit.runners.model.Statement;
import org.jvnet.hudson.test.RestartableJenkinsRule;

public class EnvStepTest {

@ClassRule public static BuildWatcher buildWatcher = new BuildWatcher();
@Rule public RestartableJenkinsRule story = new RestartableJenkinsRule();

@Test public void overriding() {
story.addStep(new Statement() {
@Override public void evaluate() throws Throwable {
WorkflowJob p = story.j.jenkins.createProject(WorkflowJob.class, "p");
p.setDefinition(new CpsFlowDefinition(
"env.CUSTOM = 'initial'\n" +
"env.FOOPATH = '/opt/foos'\n" +
"env.NULLED = 'outside'\n" +
"node {\n" +
" withEnv(['CUSTOM=override', 'NOVEL=val', 'BUILD_TAG=custom', 'NULLED=', 'FOOPATH+BALL=/opt/ball']) {\n" +
" sh 'echo inside CUSTOM=$CUSTOM NOVEL=$NOVEL BUILD_TAG=$BUILD_TAG NULLED=$NULLED FOOPATH=$FOOPATH:'\n" +
" echo \"groovy NULLED=${env.NULLED}\"\n" +
" }\n" +
" sh 'echo outside CUSTOM=$CUSTOM NOVEL=$NOVEL NULLED=outside:'\n" +
"}"));
WorkflowRun b = story.j.assertBuildStatusSuccess(p.scheduleBuild2(0));
story.j.assertLogContains("inside CUSTOM=override NOVEL=val BUILD_TAG=custom NULLED= FOOPATH=/opt/ball:/opt/foos:", b);
story.j.assertLogContains("groovy NULLED=null", b);
story.j.assertLogContains("outside CUSTOM=initial NOVEL= NULLED=outside:", b);
}
});
}

@Test public void parallel() {
story.addStep(new Statement() {
@Override public void evaluate() throws Throwable {
WorkflowJob p = story.j.jenkins.createProject(WorkflowJob.class, "p");
p.setDefinition(new CpsFlowDefinition(
"parallel a: {\n" +
" node {withEnv(['TOOL=aloc']) {semaphore 'a'; sh 'echo TOOL=$TOOL'}}\n" +
"}, b: {\n" +
" node {withEnv(['TOOL=bloc']) {semaphore 'b'; sh 'echo TOOL=$TOOL'}}\n" +
"}"));
WorkflowRun b = p.scheduleBuild2(0).getStartCondition().get();
SemaphoreStep.waitForStart("a/1", b);
SemaphoreStep.waitForStart("b/1", b);
SemaphoreStep.success("a/1", null);
SemaphoreStep.success("b/1", null);
story.j.assertBuildStatusSuccess(JenkinsRuleExt.waitForCompletion(b));
story.j.assertLogContains("[a] TOOL=aloc", b);
story.j.assertLogContains("[b] TOOL=bloc", b);
}
});
}

@Test public void restarting() {
story.addStep(new Statement() {
@Override public void evaluate() throws Throwable {
WorkflowJob p = story.j.jenkins.createProject(WorkflowJob.class, "p");
p.setDefinition(new CpsFlowDefinition(
"def show(which) {\n" +
" echo \"groovy ${which} ${env.TESTVAR}:\"\n" +
" sh \"echo shell ${which} \\$TESTVAR:\"\n" +
"}\n" +
"node {\n" +
" withEnv(['TESTVAR=val']) {\n" +
" show 'before'\n" +
" semaphore 'restarting'\n" +
" show 'after'\n" +
" }\n" +
" show 'outside'\n" +
"}"));
WorkflowRun b = p.scheduleBuild2(0).getStartCondition().get();
SemaphoreStep.waitForStart("restarting/1", b);
}
});
story.addStep(new Statement() {
@Override public void evaluate() throws Throwable {
SemaphoreStep.success("restarting/1", null);
WorkflowRun b = story.j.assertBuildStatusSuccess(JenkinsRuleExt.waitForCompletion(story.j.jenkins.getItemByFullName("p", WorkflowJob.class).getLastBuild()));
story.j.assertLogContains("groovy before val:", b);
story.j.assertLogContains("shell before val:", b);
story.j.assertLogContains("groovy after val:", b);
story.j.assertLogContains("shell after val:", b);
story.j.assertLogContains("groovy outside null:", b);
story.j.assertLogContains("shell outside :", b);
}
});
}

}
@@ -0,0 +1,128 @@
/*
* The MIT License
*
* Copyright 2015 Jesse Glick.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/

package org.jenkinsci.plugins.workflow.steps;

import com.google.inject.Inject;
import hudson.EnvVars;
import hudson.Extension;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import net.sf.json.JSONObject;
import org.kohsuke.stapler.DataBoundConstructor;
import org.kohsuke.stapler.StaplerRequest;

public class EnvStep extends AbstractStepImpl {

/**
* Environment variable overrides.
* The format is {@code VAR=val}.
*/
private final List<String> overrides;

@DataBoundConstructor public EnvStep(List<String> overrides) {
for (String pair : overrides) {
if (pair.indexOf('=') == -1) {
throw new IllegalArgumentException(pair);
}
}
this.overrides = new ArrayList<String>(overrides);
}

public List<String> getOverrides() {
return overrides;
}

public static class Execution extends AbstractStepExecutionImpl {

private static final long serialVersionUID = 1;

@Inject(optional=true) private transient EnvStep step;

@Override public boolean start() throws Exception {
getContext().newBodyInvoker().
withContext(new ExpanderImpl(step.overrides)).
withCallback(BodyExecutionCallback.wrap(getContext())).
start();
return false;
}

@Override public void stop(Throwable cause) throws Exception {
// should be no need to do anything special (but verify in JENKINS-26148)
}

}

private static final class ExpanderImpl extends EnvironmentExpander {
private static final long serialVersionUID = 1;
private final Map<String,String> overrides;
private ExpanderImpl(List<String> overrides) {
this.overrides = new HashMap<String,String>();
for (String pair : overrides) {
int split = pair.indexOf('=');
assert split != -1;
this.overrides.put(pair.substring(0, split), pair.substring(split + 1));
}
}
@Override public void expand(EnvVars env) throws IOException, InterruptedException {
env.overrideAll(overrides);
}
}

@Extension public static class DescriptorImpl extends AbstractStepDescriptorImpl {

public DescriptorImpl() {
super(Execution.class);
}

@Override public String getFunctionName() {
return "withEnv";
}

@Override public String getDisplayName() {
return "Set environment variables";
}

@Override public boolean takesImplicitBlockArgument() {
return true;
}

@Override public Step newInstance(StaplerRequest req, JSONObject formData) throws FormException {
String overridesS = formData.getString("overrides");
List<String> overrides = new ArrayList<String>();
for (String line : overridesS.split("\r?\n")) {
line = line.trim();
if (!line.isEmpty()) {
overrides.add(line);
}
}
return new EnvStep(overrides);
}

}

}
@@ -0,0 +1,5 @@
package org.jenkinsci.plugins.workflow.steps.EnvStep
f = namespace(lib.FormTagLib)
f.entry(field: 'overrides', title: 'Environment variable overrides') {
f.textarea(value: instance == null ? '' : instance.overrides.join('\n'))
}
@@ -0,0 +1,6 @@
<div>
A list of environment variables to set, each in the form <code>VARIABLE=value</code>
or <code>VARIABLE=</code> to unset variables otherwise defined.
You may also use the syntax <code>PATH+WHATEVER=/something</code>
to prepend <code>/something</code> to <code>$PATH</code>.
</div>
@@ -0,0 +1,44 @@
<div>
Sets one or more environment variables within a block.
These are available to any external processes spawned within that scope.
For example:
<p><pre>
node {
withEnv(['MYTOOL_HOME=/usr/local/mytool']) {
sh '$MYTOOL_HOME/bin/start'
}
}
</pre>
<p>(Note that here we are using single quotes in Groovy, so the variable expansion is being done by the Bourne shell, not Jenkins.)
<p>From Groovy code inside the block, the value is also accessible as <code>env.VARNAME</code>.
You can write to this property rather than using the <code>withEnv</code> step,
though any changes are global to the workflow build so should not include node-specific content such as file paths:
<p><pre>
env.MYTOOL_VERSION = '1.33'
node {
sh '/usr/local/mytool-$MYTOOL_VERSION/bin/start'
}
</pre>
<p>A set of environment variables are made available to all Jenkins projects, including workflows.
The following is a general list of variables (by name) that are available;
see the notes below the list for Workflow-specific details.

<p>
<iframe src="${rootURL}/env-vars.html" width="100%"></iframe>
</p>

The following variables are currently unavailable inside a workflow script:
<ul>
<li><code>EXECUTOR_NUMBER</code></li>
<li><code>NODE_NAME</code></li>
<li><code>NODE_LABELS</code></li>
<li><code>WORKSPACE</code></li>
<li>SCM-specific variables such as <code>SVN_REVISION</code><li>
</ul>
As an example of loading variable values from Groovy:
<p><pre>
mail to: 'devops@acme.com',
subject: "Job '${env.JOB_NAME}' (${env.BUILD_NUMBER}) is waiting for input",
body: "Please go to ${env.BUILD_URL} and verify the build"
</pre>
</div>

0 comments on commit 42805fe

Please sign in to comment.