Basic Structure of a Jenkinsfile

What is Jenkins:

Jenkins is an open-source tool, popular among DevOps practitioners. Jenkins helps to create and manage CI (Continuous Integration)/CD (Continuous Delivery) pipelines to orchestrate entire software delivery pipeline.

What is a Jenkinsfile:

A Jenkinsfile holds the script to define a pipeline. Entire workflow can be written in a Jenkinsfile, which eventually helps Jenkins tool to automatically manage and execute jobs based on the repository branches. Sometime a Jenkinsfile is referred as "Pipeline-As-Code" or a "Scripted Pipeline".

While a Jenkins file commonly have "Jenkinsfile" in the name, but you can name your Jenkinsfile anything you want. The file needs to be present in the root directory of your code-base / repository.

Where / How to use a Jenkinsfile:

While creating a pipeline in Jenkins tool, first you have to provide the path of your code-repo. Then select the mode "by Jenkinsfile" then pass the Jenkinsfile name in the Script Path.

What is the extension of Jenkinsfile:

Nothing. Jenkinsfile does not need an extension.

See this example. Jenkinsfile can be opened / edited with a text editor.

Basic structure of a Jenkinsfile:

A Jenkinsfile starts with pipeline{} . Common attributes used in a Jenkinsfile are environment, tools, parameters, stages & post. Let's go through the Jenkinsfile for better understanding.

//start of the Jenkinsfile

pipeline {
    
    // Agent Any means : this pipeline can be used for any Jenkins 

agent
    agent any


    environemnt {

        // environment attribute holds the environemnt variables which can be used in all the stages.

        NEW_BUILD_VERSION = '1.2.345'
    }


    tools{
        //Mention the tools to be used in your build. 
        //Tools needs to pre-configured in Jenkins in "Global Tool Configuaraitons". 
        //this is Not a mandatory attribute.

        maven
    }


    parameters { 
        //parameters attribute allows users to pass on some parameters before the build starts.
        //select Build with Parameters in Jenkins tool.
        //format : <variable type> (<name of variable>, <default value>, <description>)  

        //to have a text box for user to pass of the version number 
        string(name: 'VERSION', defaultValue: '', description: 'Version to deploy')

        //to have an listbox
        choice(name: 'VERSION', choices: ['1.0.0', '1.1.0', '1.2.1'], description: 'Select version to depoloy') 

        //to have a checkbox
        booleanParam(name: 'executeTest', defaultValue: true, description: 'executeTest') 
    }


    //Scripts to be used for every stages of a pipeline
    stages {
        
        //define the stages one by one. a pipelinbe can have as many as stages you want.

        stage("build") { 
            //When Expression : is used to execute steps based on some logic.
            when {
                expression {
                    // execute below mentioned steps only when a Branch Name is 'dev' and if there was any code change in this branch 

                    BRANCH_NAME == 'DEVELOPMENT' || BRANCH_NAME == 'MASTER' && CODE_CHANGES == true

                }
            }


            //steps will have all the scripts needed for the deployment e.g. npm code

            steps { 
                sh 'npm install'
                sh 'npm build'
                echo 'I am building my application.'
            }
        }
        stage("test") {
            when {
                expression {
                    params.executeTests
                }
            }
            steps {
                //using an environmental variable in the script. Note the use of "$" and "{}"

                echo "Now Building the version ${NEW_BUILD_VERSION}" 
                echo 'Now testing the new application...' 
            }
        }
        stage("deploy") {
            steps {
                echo 'deplying the application...' 
                echo "Now deploying the applicaiton version ${params.VERSION}"
                }
            }


    }


    //Post Expression : execute some logics after all of the stages are executed.
    //Can be used to email build results to the developers.

    post {
        
        always {
            // execute logics after execution, build status does not matter.
        }
        success {
            // execute logics after execution, only after a SUCCESSFUL build. 
        }
        failure {
            // execute logics after execution, only after a build FAILS. 
        }
    }
}         

Stages defined in the Jenkinsfile will appear in the pipeline like below. In our code we have defined 3 stages : build, test, deploy.

stage("build") { }        

Whatever you will write inside echo command can be seen in the log under that specific stage. Below example is from the build stage.

echo 'I am building my application.'        

Parameterized build helps the developer to pass on some parameters to the script before the build starts. e.g. a list of build versions can be passed as a dropdown list.

choice(name: 'VERSION', choices: ['1.0.0', '1.1.0', '1.2.1'], description: 'Select version to depoloy')