Stage block structure in Jenkins - Commands & Configuration

Introduction

When you want to organize your Jenkins pipeline into clear steps, you use stage blocks. Each stage represents a part of your process, like building or testing, making it easier to see progress and find problems.

When you want to separate your pipeline into logical steps for clarity.

When you need to run different tasks like build, test, and deploy in order.

When you want Jenkins to show progress visually in the pipeline view.

When you want to add conditions or parallel tasks inside specific stages.

When you want to easily identify which part of the pipeline failed.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                echo 'Building the application'
            }
        }
        stage('Test') {
            steps {
                echo 'Running tests'
            }
        }
        stage('Deploy') {
            steps {
                echo 'Deploying the application'
            }
        }
    }
}

This Jenkinsfile defines a pipeline with three stages: Build, Test, and Deploy.

The pipeline block is the main container.

The agent any means Jenkins can run this pipeline on any available agent.

The stages block holds multiple stage blocks, each representing a step in the process.

Inside each stage, the steps block contains the commands to run.

Commands

Check that Jenkins job builder is installed and accessible before running pipelines.

Terminal

jenkins-jobs --version

Expected Output

1.0.0

Start the Jenkins pipeline named 'example-pipeline' which uses the Jenkinsfile with stage blocks.

Terminal

jenkins-cli build example-pipeline

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] stage

[Pipeline] { (Build)

Building the application

[Pipeline] }

[Pipeline] stage

[Pipeline] { (Test)

Running tests

[Pipeline] }

[Pipeline] stage

[Pipeline] { (Deploy)

Deploying the application

[Pipeline] }

[Pipeline] End of Pipeline

View the console output of the running or completed pipeline to see the output of each stage.

Terminal

jenkins-cli console example-pipeline

Expected Output

Building the application

Running tests

Deploying the application

Key Concept

If you remember nothing else from this pattern, remember: stage blocks divide your pipeline into clear, named steps that show progress and organize tasks.

Common Mistakes

Not wrapping steps inside a stage block

Jenkins will fail to run the pipeline or stages won't show up in the UI.

Always put commands inside a stage block within the stages section.

Missing the steps block inside a stage

Jenkins expects steps to be inside the steps block; otherwise, it throws syntax errors.

Wrap all commands inside a steps block inside each stage.

Using stages outside the pipeline block

The pipeline block is the root; stages must be inside it or Jenkins will reject the file.

Always place stages inside the pipeline block.

Summary

Stage blocks organize Jenkins pipelines into named steps for clarity and progress tracking.

Each stage must have a steps block containing the commands to run.

Stages go inside the stages block, which is inside the pipeline block.