Beginner8 min readLesson 3 of 5

Pipelines as code: reading a Jenkinsfile

A Jenkinsfile describes the pipeline in a file stored with the code. A declarative pipeline names the agent to run on, a list of stages each containing steps, and a post section that runs at the end. Conditions, approvals and credentials are all part of the same file.

A complete declarative pipeline

Jenkinsfile

pipeline {
  agent { label 'linux' }
  environment {
    APP = 'payroll'
  }
  stages {
    stage('Build') {
      steps { sh './build.sh' }
    }
    stage('Test') {
      steps {
        sh './run-tests.sh'
        junit 'reports/*.xml'
      }
    }
    stage('Package') {
      steps {
        sh './package.sh ${BUILD_NUMBER}'
        archiveArtifacts artifacts: 'dist/*.tar.gz', fingerprint: true
      }
    }
    stage('Deploy to test') {
      when { branch 'main' }
      steps { sh './deploy.sh test' }
    }
  }
  post {
    failure { echo "Build ${env.BUILD_NUMBER} failed" }
    always  { cleanWs() }
  }
}

Reading it block by block

What each part meansWhat it means

pipeline { }

Everything lives inside this block. It marks the file as a declarative pipeline.

agent { label 'linux' }

Run on an agent labelled linux. agent any means any available agent.

environment { }

Variables available to every step.

stages / stage('Build')

The named phases. Each one appears as a column in the Jenkins stage view.

steps { sh '...' }

The actual work. sh runs a shell command and fails the stage if it exits non-zero.

junit / archiveArtifacts

Record test results, and keep the built files with the build.

when { branch 'main' }

Run this stage only on main, so feature branches build and test but do not deploy.

post { failure / always }

Runs after the stages: on failure, on success, or always, for example to tidy up.

Approvals and secrets

An input step pauses the pipeline until a person approves, which is a common gate in front of production: input message: 'Deploy release 1.4.2 to production?'. A credential is brought in by ID, for example environment { DEPLOY_KEY = credentials('prod-deploy-key') }. Its value is available to the steps and is masked in the console.

Declarative and scripted

There are two syntaxes. Declarative, which starts with pipeline {, is structured and easy to read, and it is what Jenkins recommends. Scripted, which starts with node {, is plain Groovy code: more flexible, but harder for others to follow. You will mostly write and read declarative pipelines.

TRY IT YOURSELF

Which step in a Jenkinsfile runs a shell command such as ./build.sh?

Show a hint

Two letters.

Show the solution

sh, as in sh './build.sh'.

Examples are for learning. Run commands and jobs only on a system you are authorised to use, such as a training or test system, and never on production without approval.

Common mistakes

Deploying from every branch

Without a when { branch 'main' } condition, any experimental branch could deploy. Gate deployment stages.

Leaving out the post section

Without post, nobody hears about failures and workspaces fill the disk. Notify on failure and clean up always.

Writing secrets inline

A password typed into the Jenkinsfile lives in Git history for ever. Use credentials() and an ID.

What you will see at work

Because the Jenkinsfile is in Git, a pipeline change goes through a pull request, just like code.
The stage names become the column titles in Jenkins' stage view, so choose names people understand at a glance.
Many teams keep shared pipeline code in a Jenkins shared library, so dozens of repositories reuse the same tested stages.

Key terms

Jenkinsfile

Check your understanding.
Take this lesson's quiz and save your progress. Free.

Take the lesson quiz

← Jenkins: controller, agents, jobs and plugins Packaging binaries: artifacts, versions and repositories →