Jenkins Pipeline Environment Variables: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(29 intermediate revisions by the same user not shown)
Line 4: Line 4:
=Overview=
=Overview=


Jenkins Pipeline exposes environment variables via the global variable <code>env</code>, which is available from anywhere in the [[Jenkins_Concepts#Jenkinsfile|Jenkinsfile]].
A Jenkins [[Jenkins_Concepts#Pipeline|pipeline]] exposes environment variables via the [[Jenkins_Concepts#Pipeline_Global_Variables|global variable]] <code>env</code>, which is available from anywhere in the [[Jenkins_Concepts#Jenkinsfile|Jenkinsfile]]. Please note that <code>env</code> is not directly available from Groovy layer code invoked from Jenkinsfile, the reference to the pipeline must be passed along and must be used to refer to the <code>env</code> global variable:
<syntaxhighlight lang='text'>
String imageVersion = buildInfo.rpmVersion != null ? buildInfo.rpmVersion : env.PREBUILT_IMAGE_TAG
[...]
hudson.remoting.ProxyException: groovy.lang.MissingPropertyException: No such property: env for class: playground.jenkins.steps.TestSomethingStep
</syntaxhighlight>
Any variable set this way are global to the Pipeline build. For variables with node-specific content (such as file paths), you should use instead use <tt>[[Jenkins_Pipeline_Syntax#withEnv|withEnv()]]</tt> step, to bind the variable only with a <tt>[[Jenkins_Pipeline_Syntax#node|node]]</tt> block.
 
The full list of environment variables accessible from within a Jenkins pipeline is documented at http&#58;//<jenkins-instance-url>/pipeline-syntax/globals#env.
 
=Programming Model=
 
==Accessing Environment Variables==
 
<syntaxhighlight lang='groovy'>
echo "Running ${env.BUILD_ID} on ${env.JENKINS_URL}"
</syntaxhighlight>
 
==Setting Environment Variables==


The full environment variables accessible from within Jenkins Pipeline is documented at http&#58;//<jenkins-instance-url>/pipeline-syntax/globals#env.
Setting an environment variable within a Jenkins Pipeline is accomplished differently depending on whether declarative or scripted pipeline is used.
 
===Declarative Pipeline===
 
Declarative pipeline supports an [[Jenkins_Pipeline_Syntax#environment|environment]] directive. An <code>environment</code> directive used in the top-level pipeline block will apply to all steps within the pipeline. An environment directive defined within a stage will only apply the given environment variables to steps within the stage.
 
<syntaxhighlight lang='groovy'>
pipeline {
    agent any
    environment {
        CC = 'clang'
    }
    stages {
        stage('Example') {
            environment {
                DEBUG_FLAGS = '-g'
            }
            steps {
                sh 'printenv'
            }
        }
    }
}
</syntaxhighlight>
 
===Scripted Pipeline===
 
Scripted pipeline must use the [[Jenkins_Pipeline_Syntax#withEnv|withEnv]] step.
 
===Setting Environment Variables Dynamically===
{{External|https://jenkins.io/doc/book/pipeline/jenkinsfile/#setting-environment-variables-dynamically}}


=Environment Variables=
=Environment Variables=
{{External|https://www.jenkins.io/doc/pipeline/tour/environment/}}
{{External|https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#using-environment-variables}}
Environment variables can be set globally or per stage. Setting environment variable per stage means they will only apply to the stage in which they were defined.
==Jenkins Pipeline Environment Variables==
The Jenkins Pipeline exposes its environment variable via the global variable "env", which is available from anywhere in the Jenkinsfile".
The full list is available at ${YOUR_JENKINS_URL}/pipeline-syntax/globals#env


==BUILD_ID==
==BUILD_ID==


The current build ID, identical to [[#BUILD_NUMBER|BUILD_NUMBER]].
The current build ID, identical to [[#BUILD_NUMBER|BUILD_NUMBER]]. Available both on master and on nodes.
<syntaxhighlight lang='text'>
153
</syntaxhighlight>


==BUILD_NUMBER==
==BUILD_NUMBER==


The current build number, such as "153". Same as [[#BUILD_ID|BUILD_ID]].
The current build number, such as "153". Same as [[#BUILD_ID|BUILD_ID]]. Available both on master and on nodes.
<syntaxhighlight lang='text'>
153
</syntaxhighlight>


==BUILD_TAG==
==BUILD_TAG==


Contains job name, branch name, build number:
Contains job (pipeline) name and build number. Available both on master and on nodes.
<syntaxhighlight lang="text">
jenkins-${env.JOB_NAME}-${env.BUILD_NUMBER}
</syntaxhighlight>
<syntaxhighlight lang="text">
<syntaxhighlight lang="text">
jenkins-${JOB_NAME}-${BUILD_NUMBER}
jenkins-my-pipeline-153
</syntaxhighlight>
</syntaxhighlight>


==BUILD_URL==
==BUILD_URL==


The URL where the results of this build can be found. Example: http&#58;//<jenkins-instance-url>/jenkins/job/MyJobName/17/
The URL where the results of this build can be found. Available both on master and on nodes. Example:  
<syntaxhighlight lang='text'>
https://<jenkins-instance-url>/job/${env.JOB_NAME}/-${env.BUILD_NUMBER}/
https://playground.io/cloud/job/my-pipeline/153/
</syntaxhighlight>
For <jenkins-instance-url>, see [[#JENKINS_URL|JENKINS_URL]] below.
 
==EXECUTOR_NUMBER==
 
The unique number that identifies the current executor among executors of the same machine performing this build. This is the number shown in the "build executor status", except that the number starts from 0, not 1. Not available on master.
 
==JAVA_HOME==
If your job is configured to use a specific JDK, this variable is set to the JAVA_HOME of the specified JDK. When this variable is set, PATH is also updated to include the bin subdirectory of JAVA_HOME. Not available on master.
 
==JENKINS_URL==
Full URL of Jenkins, such as https&#58;//example.com:port/<jenkins-instance-name>/. It is only available if Jenkins URL set in "System Configuration".


==JOB_NAME==
==JOB_NAME==
Name of the project (pipeline) of this build.
==JOB_BASE_NAME==
==JOB_BASE_NAME==
==NODE_NAME==
The name of the node the current build is running on. Set to 'master' for master node. Example on node:
<syntaxhighlight lang='text'>
</syntaxhighlight>
==WORKSPACE==
The absolute path of the workspace. Not available on master.

Latest revision as of 02:59, 8 May 2021

Internal

Overview

A Jenkins pipeline exposes environment variables via the global variable env, which is available from anywhere in the Jenkinsfile. Please note that env is not directly available from Groovy layer code invoked from Jenkinsfile, the reference to the pipeline must be passed along and must be used to refer to the env global variable:

String imageVersion = buildInfo.rpmVersion != null ? buildInfo.rpmVersion : env.PREBUILT_IMAGE_TAG
[...]
hudson.remoting.ProxyException: groovy.lang.MissingPropertyException: No such property: env for class: playground.jenkins.steps.TestSomethingStep

Any variable set this way are global to the Pipeline build. For variables with node-specific content (such as file paths), you should use instead use withEnv() step, to bind the variable only with a node block.

The full list of environment variables accessible from within a Jenkins pipeline is documented at http://<jenkins-instance-url>/pipeline-syntax/globals#env.

Programming Model

Accessing Environment Variables

echo "Running ${env.BUILD_ID} on ${env.JENKINS_URL}"

Setting Environment Variables

Setting an environment variable within a Jenkins Pipeline is accomplished differently depending on whether declarative or scripted pipeline is used.

Declarative Pipeline

Declarative pipeline supports an environment directive. An environment directive used in the top-level pipeline block will apply to all steps within the pipeline. An environment directive defined within a stage will only apply the given environment variables to steps within the stage.

pipeline {
    agent any
    environment { 
        CC = 'clang'
    }
    stages {
        stage('Example') {
            environment { 
                DEBUG_FLAGS = '-g'
            }
            steps {
                sh 'printenv'
            }
        }
    }
}

Scripted Pipeline

Scripted pipeline must use the withEnv step.

Setting Environment Variables Dynamically

https://jenkins.io/doc/book/pipeline/jenkinsfile/#setting-environment-variables-dynamically

Environment Variables

https://www.jenkins.io/doc/pipeline/tour/environment/
https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#using-environment-variables

Environment variables can be set globally or per stage. Setting environment variable per stage means they will only apply to the stage in which they were defined.

Jenkins Pipeline Environment Variables

The Jenkins Pipeline exposes its environment variable via the global variable "env", which is available from anywhere in the Jenkinsfile".

The full list is available at ${YOUR_JENKINS_URL}/pipeline-syntax/globals#env

BUILD_ID

The current build ID, identical to BUILD_NUMBER. Available both on master and on nodes.

153

BUILD_NUMBER

The current build number, such as "153". Same as BUILD_ID. Available both on master and on nodes.

153

BUILD_TAG

Contains job (pipeline) name and build number. Available both on master and on nodes.

jenkins-${env.JOB_NAME}-${env.BUILD_NUMBER}
jenkins-my-pipeline-153

BUILD_URL

The URL where the results of this build can be found. Available both on master and on nodes. Example:

https://<jenkins-instance-url>/job/${env.JOB_NAME}/-${env.BUILD_NUMBER}/
https://playground.io/cloud/job/my-pipeline/153/

For <jenkins-instance-url>, see JENKINS_URL below.

EXECUTOR_NUMBER

The unique number that identifies the current executor among executors of the same machine performing this build. This is the number shown in the "build executor status", except that the number starts from 0, not 1. Not available on master.

JAVA_HOME

If your job is configured to use a specific JDK, this variable is set to the JAVA_HOME of the specified JDK. When this variable is set, PATH is also updated to include the bin subdirectory of JAVA_HOME. Not available on master.

JENKINS_URL

Full URL of Jenkins, such as https://example.com:port/<jenkins-instance-name>/. It is only available if Jenkins URL set in "System Configuration".

JOB_NAME

Name of the project (pipeline) of this build.

JOB_BASE_NAME

NODE_NAME

The name of the node the current build is running on. Set to 'master' for master node. Example on node:

WORKSPACE

The absolute path of the workspace. Not available on master.