Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 40 ยท Pipeline as Code

Pipeline Basics and the Jenkinsfile

Learn Jenkins Pipeline: what a Jenkinsfile is, declarative versus scripted syntax, and how pipeline, agent, stages and steps fit together in a first working pipeline.

A Pipeline is a Jenkins job whose steps are written as code instead of clicked together in forms. The code lives in a text file named Jenkinsfile, stored in the root of your repository next to the source it builds. Because it is a normal file, it gets all the benefits of normal code: you can review it in a pull request, see its history in Git, copy it, branch it and roll it back.

That is the single biggest reason most teams use Pipeline instead of the freestyle jobs from Your First Job: Freestyle Projects. In this lesson you learn the two Pipeline syntaxes, the four words that appear in almost every Jenkinsfile (pipeline, agent, stages, steps), and how Jenkins turns the file into a run. The real thing needs a Jenkins server, so Jenkinsfiles here are read-only, and the runnable example is a stand-in: a tiny parser and runner written in JavaScript that understands a small subset of the syntax.

Anatomy of a declarative pipeline

pipeline The outer block around everything.
agent Where the work runs.
stages Ordered phases like Build and Test.
steps The commands inside a stage.

pipeline > agent + stages > stage > steps

1 / 2

Why Pipeline is better than freestyle

  • Pipeline as code. The build definition is versioned with the project. A branch that changes how the app is built also changes its Jenkinsfile.
  • Durable. A pipeline can survive a controller restart and carry on.
  • Rich flow. Stages, parallel branches, conditions, retries, timeouts and approval prompts are built in.
  • Visible. Jenkins can draw each stage as a box and show which one failed.
  • Reusable. Common pieces can move into shared libraries (see Shared Libraries).

Your first Jenkinsfile

Here is a complete, valid declarative pipeline. This is real Jenkins syntax, shown read-only:

GROOVY
pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                echo 'Compiling the project'
                sh 'make build'
            }
        }
        stage('Test') {
            steps {
                echo 'Running the tests'
                sh 'make test'
            }
        }
    }

    post {
        always {
            echo 'Pipeline finished'
        }
        failure {
            echo 'Something went wrong'
        }
    }
}

Read it from the outside in.

  • pipeline { ... } is required in declarative syntax. Everything lives inside it.
  • agent any says: run on any available agent. You can ask for a specific one with agent { label 'linux' }, or run in a container, which we do in Docker Agents and Building Images.
  • stages { ... } holds one or more stage('Name') { ... } blocks. They run in order, and a failing stage stops the ones after it. The names appear in the stage view.
  • steps { ... } inside a stage holds the commands to run. Here echo prints a message and sh runs a shell command (on Windows agents you use bat).
  • post { ... } declares what happens after the stages finish, depending on the outcome: always, success, failure and more. See Conditions and Post Actions.

Groovy strings in single quotes ('text') are plain text. Double quotes ("text ${var}") allow variable interpolation. Use single quotes unless you need that.

Where the Jenkinsfile lives and how a job uses it

To use the file, you create a job of type Pipeline and tell it where the code is:

  • Pipeline script from SCM: Jenkins checks out your repository and reads Jenkinsfile from it. This is the normal approach.
  • Pipeline script (inline): you paste the code into the job. Fine for experiments, but you lose the benefits of versioning.

Even better is a Multibranch Pipeline, which finds every branch and pull request that contains a Jenkinsfile and creates a job for each. See Multibranch Pipelines and Pull Requests. When Jenkins runs a pipeline from SCM, it checks out the code for the Jenkinsfile first (a "lightweight checkout"), and the first line of the log tells you which commit it used.

Declarative versus scripted

Jenkins has two syntaxes for Pipeline, both written in a Groovy-based language:

Declarative starts with pipeline { } and uses a fixed set of sections (agent, stages, post, environment, options and so on). It is stricter, which makes it easier to read, easier to check and easier for the interface to visualise. It reports mistakes before the run starts.

Scripted starts with node { } and is ordinary Groovy code: variables, loops, try/catch. It is more flexible and easier to get wrong.

GROOVY
// Scripted: the same idea
node {
    stage('Build') {
        echo 'Compiling the project'
        sh 'make build'
    }
    stage('Test') {
        echo 'Running the tests'
        sh 'make test'
    }
}

For new work, start with declarative. When you need a bit of programming (a loop, a computed value), put a script { } block inside a step; the language details come in Scripted Pipeline and Groovy for Jenkins.

Jenkinsfiles are Groovy, but you do not need to know Groovy to begin. Declarative pipelines mostly look like configuration with commands in quotes.

A stand-in declarative runner

Jenkins' real parser is part of the Pipeline plugins. The stand-in below is a toy written in JavaScript so you can watch the structure turn into a run. It reads the same shape of text (a pipeline, stages, stage('...'), steps, echo/sh, and a post section) by matching braces, then runs the stages in order. The sh command does not start a shell; it looks up a pretend result in a table. Try changing the Jenkinsfile text, for example by making make test fail.

JS A stand-in declarative pipeline runner

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The first run goes through three stages and ends with SUCCESS. After you break make test, the second run stops in the Test stage, never reaches Package, and the failure post block runs as well as always. Those are the same rules the real engine follows, even though its parser is far more complete.

Reading a Pipeline run

In the real UI, a pipeline run shows each stage as a column in the stage view, coloured by result, with the time it took. Click a stage to see only its log. If a stage is red, its log is the first place to look; scroll for the first failing step, as in the console tips from A Tour of the Jenkins Interface.

Common first-pipeline mistakes

  • Missing steps. Each stage needs a steps block (or a nested stages/parallel).
  • Mixing quotes. echo 'Build ${BUILD_NUMBER}' prints the text literally; use double quotes to interpolate.
  • Using sh on Windows agents. Use bat there, or powershell.
  • Everything in one giant stage. Use stages so failures are easy to locate.
  • Forgetting to commit the Jenkinsfile. Jenkins reads the committed file, not your local edit.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does a typical Jenkinsfile live?

    Keeping the Jenkinsfile in source control gives you review, history and per-branch build definitions.
  2. 2. Which block must wrap a whole declarative pipeline?

    Declarative syntax starts with pipeline { }. Scripted pipelines start with node { }.
  3. 3. A stage in the middle of the pipeline fails. What happens to later stages?

    By default a failed stage stops the stages after it. Post conditions such as always and failure still run.
  4. 4. Which is the best choice for a new pipeline when you need an occasional loop or computed value?

    Declarative keeps the structure readable and checkable, and script { } gives you Groovy for the small parts that need it.

Summary

  • A Pipeline job runs code from a Jenkinsfile, ideally stored in your repository and read from SCM.
  • Declarative syntax (pipeline, agent, stages, stage, steps, post) is structured and the best start; scripted syntax (node) is plain Groovy.
  • Stages run in order; a failure stops later stages, while post conditions still run.
  • The runnable example here is a toy runner. Real Jenkinsfiles run only on a Jenkins server.

Next, explore every section in Declarative Pipeline Syntax in Depth.