If you are new to Jenkins Pipeline, the Blue Ocean UI helps youset up your Pipeline project, andautomatically creates and writes your Pipeline (i.e. theJenkinsfile) for youthrough the graphical Pipeline editor.

As part of setting up your Pipeline project in Blue Ocean, Jenkins configures asecure and appropriately authenticated connection to your project’s sourcecontrol repository. Therefore, any changes you make to theJenkinsfile viaBlue Ocean’s Pipeline editor are automatically saved and committed to sourcecontrol.

Read more about Blue Ocean in theBlue Ocean chapter andGetting started with Blue Ocean page.

AJenkinsfile created using the classic UI is stored by Jenkins itself (withinthe Jenkins home directory).

To create a basic Pipeline through the Jenkins classic UI:

1. If required, ensure you are logged in to Jenkins.

2. From the Jenkins Dashboard, selectNew Item.

   

3. In theEnter an item name field, specify the name for your new Pipelineproject.
   Caution: Jenkins uses this item name to create directories on disk. It isrecommended to avoid using spaces in item names, since doing so may uncoverbugs in scripts that do not properly handle spaces in directory paths.

4. Scroll down and clickPipeline, then clickOK at the end of the page toopen the Pipeline configuration page (whoseGeneral tab is selected).

   

5. Click thePipeline tab in the side panel of the page to scroll down to thePipeline section.
   Note: If instead you are defining yourJenkinsfile in source control,follow the instructions inIn SCM below.

6. In thePipeline section, ensure that theDefinition field indicates thePipeline script option.

7. Enter your Pipeline code into theScript text area.
   For instance, copy the following Declarative example Pipeline code (below theJenkinsfile ( …​ ) heading) or its Scripted version equivalent and pastethis into theScript text area. (The Declarative example below is usedthroughout the remainder of this procedure.)

   Jenkinsfile (Declarative Pipeline)

   pipeline {    agent any(1)    stages {        stage('Stage 1') {            steps {                echo'Hello world!'(2)            }        }    }}

   Toggle Scripted Pipeline(Advanced)

   Jenkinsfile (Scripted Pipeline)

   node {(3)    stage('Stage 1') {        echo'Hello World'(2)    }}

   1	agent instructs Jenkins to allocate an executor (on any availableagent/node in the Jenkins environment) and workspace for the entire Pipeline.
   2	echo writes simple string in the console output.
   3	node effectively does the same asagent (above). Note: You can also select from cannedScripted Pipeline examples from thetry sample Pipeline option at the top right of theScript text area. Beaware that there are no canned Declarative Pipeline examples available from thisfield.

8. ClickSave to open the Pipeline project/item view page.

9. On this page, clickBuild Now on the left to run the Pipeline.

   

10. UnderBuild History on the left, click#1 to access the details for thisparticular Pipeline run.

11. ClickConsole Output to see the full output from the Pipeline run. Thefollowing output shows a successful run of your Pipeline.

    

    Notes:

    • You can also access the console output directly from the Dashboard by clickingthe colored globe to the left of the build number (e.g.#1).

    • Defining a Pipeline through the classic UI is convenient for testing Pipelinecode snippets, or for handling simple Pipelines or Pipelines that do notrequire source code to be checked out/cloned from a repository. As mentionedabove, unlikeJenkinsfiles you define through Blue Ocean(above) or in source control(below),Jenkinsfiles entered intotheScript text area of Pipeline projects are stored by Jenkins itself,within the Jenkins home directory. Therefore, for greater control andflexibility over your Pipeline, particularly for projects in source controlthat are likely to gain complexity, it is recommended that you useBlue Ocean orsource control to define yourJenkinsfile.

Complex Pipelines are difficult to write and maintain within theclassic UI’sScript text area of the Pipelineconfiguration page.

To make this easier, your Pipeline’sJenkinsfile can be written in a texteditor or integrated development environment (IDE) and committed to sourcecontrol^[3] (optionally with the application code that Jenkinswill build). Jenkins can then check out yourJenkinsfile from source controlas part of your Pipeline project’s build process and then proceed to executeyour Pipeline.

To configure your Pipeline project to use aJenkinsfile from source control:

1. Follow the procedure above for defining your Pipelinethrough the classic UI until you reach step 5(accessing thePipeline section on the Pipeline configuration page).

2. From theDefinition field, choose thePipeline script from SCM option.

3. From theSCM field, choose the type of source control system of therepository containing yourJenkinsfile.

4. Complete the fields specific to your repository’s source control system.
   Tip: If you are uncertain of what value to specify for a given field, clickits? icon to the right for more information.

5. In theScript Path field, specify the location (and name) of yourJenkinsfile. This location is the one that Jenkins checks out/clones therepository containing yourJenkinsfile, which should match that of therepository’s file structure. The default value of this field assumes that yourJenkinsfile is named "Jenkinsfile" and is located at the root of therepository.

When you update the designated repository, a new build is triggered, as long asthe Pipeline is configured with an SCM polling trigger.

The built-in "Snippet Generator" utility is helpful for creating bits ofcode for individual steps, discovering new steps provided by plugins, orexperimenting with different parameters for a particular step.

The Snippet Generator is dynamically populated with a list of the stepsavailable to the Jenkins controller. The number of steps available is dependenton the plugins installed which explicitly expose steps for use in Pipeline.

To generate a step snippet with the Snippet Generator:

1. Navigate to thePipeline Syntax link (referenced above) from a configured Pipeline, or at${YOUR_JENKINS_URL}/pipeline-syntax.

2. Select the desired step in theSample Step dropdown menu

3. Use the dynamically populated area below theSample Step dropdown to configure the selected step.

4. ClickGenerate Pipeline Script to create a snippet of Pipeline which can becopied and pasted into a Pipeline.

To access additional information and/or documentation about the step selected,click on the help icon (indicated by the red arrow in the image above).

In addition to the Snippet Generator, which only surfaces steps, Pipeline alsoprovides a built-in "Global Variable Reference." Like the Snippet Generator,it is also dynamically populated by plugins. Unlike the Snippet Generatorhowever, the Global Variable Reference only contains documentation forvariables provided by Pipeline or plugins, which are available forPipelines.

The variables provided by default in Pipeline are:

env

Exposes environment variables, for example:env.PATH orenv.BUILD_ID. Consult the built-in global variable reference at${YOUR_JENKINS_URL}/pipeline-syntax/globals#envfor a complete, and up to date, list of environment variablesavailable in Pipeline.

params

Exposes all parameters defined for the Pipeline as a read-onlyMap,for example:params.MY_PARAM_NAME.

currentBuild

May be used to discover information about the currently executing Pipeline,with properties such ascurrentBuild.result,currentBuild.displayName,etc. Consult the built-in global variable reference at${YOUR_JENKINS_URL}/pipeline-syntax/globalsfor a complete, and up to date, list of properties available oncurrentBuild.

This video reviews using thecurrentBuild variable in Jenkins Pipeline.

While the Snippet Generator helps with generating steps for a ScriptedPipeline or for thesteps block in astage in a Declarative Pipeline, itdoes not cover thesections anddirectives used to define a Declarative Pipeline.The "Declarative Directive Generator" utility helps with that.Similar to theSnippet Generator, the Directive Generator allows youto choose a Declarative directive, configure it in a form, and generate theconfiguration for that directive, which you can then use in your Declarative Pipeline.

To generate a Declarative directive using the Declarative Directive Generator:

1. Navigate to thePipeline Syntax link (referenced above) from a configured Pipeline,and then click on theDeclarative Directive Generator link in the sidepanel,or go directly to${YOUR_JENKINS_URL}/directive-generator.

2. Select the desired directive in the dropdown menu

3. Use the dynamically populated area below the dropdown to configure the selected directive.

4. ClickGenerate Directive to create the directive’s configuration to copyinto your Pipeline.

The Directive Generator can generate configuration for nested directives,such as conditions inside awhen directive, but it cannot generate Pipeline steps.For the contents of directives which contain steps,such assteps inside astage or conditions likealways orfailure insidepost,the Directive Generator adds a placeholder comment instead.You will still need to add steps to your Pipeline by hand.

• Pipeline Steps Reference,encompassing all steps provided by plugins distributed in the Jenkins UpdateCenter.

• Pipeline Examples, acommunity-curated collection of copyable Pipeline examples.