Jenkins-pipeline Jenkinsfile说明

一. 简介：

Jenkinsfile 是一个文本文件，通常保存在项目的源代码仓库中，用于定义 Jenkins Pipeline 的行为。使用 Jenkinsfile 可以使 CI/CD 流程版本化，并且易于共享和审核。

二. 关于jenkinsfile：

jenkins的pipeline目前支持两种语法： Declarative（在Pipeline 2.5中引入）和Scripted Pipeline。两者都支持建立连续输送Pipeline。两者都可以用于在Web UI或者a中定义一个流水线Jenkinsfile。

从检索的资料来看，Declarative Pipeline 是后续Open Blue Ocean所支持的类型。相对而言，Declarative Pipeline比较简单，Declarative Pipeline中，也是可以内嵌Scripted Pipeline代码的。

为与BlueOcean脚本编辑器兼容，通常建议使用Declarative Pipeline的方式进行编写,从jenkins社区的动向来看，很明显这种语法结构也会是未来的趋势。

https://stackoverflow.com/questions/43484979/jenkins-scripted-pipeline-or-declarative-pipeline

http://jenkins-ci.361315.n4.nabble.com/Declarative-pipelines-vs-scripted-td4891792.html

a). declarative pipeline方式:

pipeline {
    agent any                     #没有agent指令，声明Pipeline无效，不能做任何工作
    stages {                      
        stage('Build') {          
            steps {               
                echo 'Building..'
            }
        }
        .................
    }
} 

b). scripts pipeline方式：
node {                          #没有node Pipeline不能做任何工作
    stage('Build') {
        echo 'Building....'
    }
    .................
    }
}

二. pipeline流程：

一个标准的pipeline项目，应当包含最基本的构建、测试、部署三个阶段(对应3个stage)。

a). 构建(build):

通常情况下，一个jenkins项目中的task是从构建(build)开始的。在pipeline中，这个阶段是编译源码打包的过程。Jenkinsfile不是为了替换现有的编译工具(如GNU/Make,Maven,Gradle,etc,but等)。而是作为一个结合项目的开发生命周期的多个阶段（建设，测试，部署等）一起的联合胶水。如通过sh下的make指令：

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                sh 'make' 
                archiveArtifacts artifacts: '**/target/*.jar', fingerprint: true 
            }
        }
    }
}

#sh： 调用make命令，只有在命令返回零退出代码时才会继续。任何非零退出代码为失败状态
#archiveArtifacts：捕获包含匹配（**/target/*.jar)的文件，并将它们保存到Jenkins主文件以供以后检索（只能用于基本报告和文件归档）。

b). 测试(test):

运行自动化测试是任何成功的连续传送过程的重要组成部分。因此，Jenkins有许多插件提供的测试记录，报告和可视化设备。当有测试失败时，Jenkins可以在Web UI中记录报告和可视化的故障。下面的示例使用junit由JUnit plugin.提供的

steps：

pipeline {
    agent any

    stages {
        stage('Test') {
            steps {
                /* `make check` returns non-zero on test failures,
                * using `true` to allow the Pipeline to continue nonetheless
                */
                sh 'make check || true' 
                junit '**/target/*.xml' 
            }
        }
    }
}
 
#sh || true ： 确保sh能够返回正确退出代码，从而使该junit步骤有机会捕获和处理测试报告。
#junit :   捕获并关联与匹配（**/target/*.xml) 的JUnit XML文件

c). 部署(deploy):

部署环节相对来说可能比较麻烦。不同的team(公司环境下，规范化的重要性就凸显了)可能会有不同的方式。通常情况下，进入部署阶段，意味着构建和测试阶段是成功了的，否则，应该控制jenkins退出。

pipeline {
    agent any

    stages {
        stage('Deploy') {
            when {
              expression {
                currentBuild.result == null || currentBuild.result == 'SUCCESS' 
              }
            }
            steps {
                sh 'make publish'
            }
        }
    }
}
 
#currentBuild.result变量允许Pipeline确定是否有任何测试失败。在这种情况下，值将是UNSTABLE的

d). 变量引用：

Pipeline使用与Groovy相同的规则, 进行变量引用。

1 . 自带全局变量：

jenkins会通过自身或插件，自动定义一些全局变量env(可以通过自己安装的jenkins查看: http://localhost:8080/job/jobname/pipeline-syntax/globals)，可以用于整个构建环境的任何步骤。引用方式如;

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                echo "Running ${env.BUILD_ID} on ${env.JENKINS_URL}"
            }
        }
    }
}

自定义环境变量：

Declarative Pipeline支持environment变量设置指令，scripts pipeline不支持，需要通过withEnv步骤(可参考官网)：

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

# environment: 在pipeline块中使用的environment会在Pipeline中的所有步骤中生效。
# 在一个stage中定义environment，只会在当前的stage中生效

e). 参数：

Declarative Pipeline支持开箱即用的参数，允许Pipeline在运行时通过parameters指令接受用户指定的参数。使用script Pipeline配置参数是通过properties步骤完成的，可以在代码段生成器中找到(说明参考官网)。如果使用"使用构建参数"选项来配置Pipeline以接受参数，那么这些参数可作为params 变量的成员访问(如：定义一个名为"Greeting"的String参数已经在配置中 Jenkinsfile，它可以通过${params.Greeting}以下方式访问)。

pipeline {
    agent any
    parameters {
        string(name: 'Greeting', defaultValue: 'Hello', description: 'How should I greet the world?')
    }
    stages {
        stage('Example') {
            steps {
                echo "${params.Greeting} World!"
            }
        }
    }
}

pipeline状态处理（运行结束时的操作）;

在一个项目运行时，声明不同的"post conditions" (目前支持：always, unstable, success, failure, 和changed ),根据不同的处理状态，做不同的操作。

pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                sh 'make check'
            }
        }
    }
    post {
        always {
            junit '**/target/*.xml'
        }
        failure {
            mail to: team@example.com, subject: 'The Pipeline failed :('
        }
    }
}

#always：无论Pipeline运行的完成状态如何。
#changed：当前Pipeline运行的状态与先前完成的Pipeline的状态不同时。
#failure：当前Pipeline处于"失败"状态时。
#success：当前Pipeline具有"成功"状态时
#unstable：当前Pipeline具有"不稳定"状态，如由测试失败，代码违例等引起。
#aborted：当前Pipeline处于"中止"状态时，通常是由于Pipeline被手动中止。

f). 使用多个代理(agent)：

通常情况下，一个pipeline工作中，选择在同一个agent/node中执行。但也有一些特殊的情况。如在不同的系统环境下，进行test验证。我们可以通过label进行打标签，在jenkins中指定不同的agent执行相应的工作：

pipeline {
    agent none
    stages {
        stage('Build') {
            agent any
            steps {
                checkout scm
                sh 'make'
                stash includes: '**/target/*.jar', name: 'app' 
            }
        }
        stage('Test on Linux') {
            agent { 
                label 'linux'
            }
            steps {
                unstash 'app' 
                sh 'make check'
            }
            post {
                always {
                    junit '**/target/*.xml'
                }
            }
        }
        stage('Test on Windows') {
            agent {
                label 'windows'
            }
            steps {
                unstash 'app'
                bat 'make check' 
            }
            post {
                always {
                    junit '**/target/*.xml'
                }
            }
        }
    }
}