How to Use Stages and Steps in a Jenkins Pipeline

By Daniel Zoghalchali·Latchkey

In Jenkins, a stage is a named phase shown on the pipeline graph, and steps are the actual commands run inside it.

Each stage groups a unit of work and appears as a column in the Stage View. Inside, steps holds the sh, echo, or plugin calls that execute.

Stages with steps

Three stages render as three columns; the steps inside each do the work.

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Install') {
      steps {
        sh 'npm ci'
      }
    }
    stage('Lint') {
      steps {
        sh 'npm run lint'
      }
    }
    stage('Test') {
      steps {
        echo 'Running tests'
        sh 'npm test'
      }
    }
  }
}

Gotchas

A stage must contain exactly one of steps, parallel, matrix, or nested stages.
Stage names show in the UI; keep them short and descriptive.
A failing step fails its stage and, by default, stops the pipeline.

Verify it actually works

Validate the pipeline definition against the running controller before committing. Jenkins parses declarative pipelines strictly, and a syntax error surfaces as a failed build rather than a clear parse message.

Terminal

# validate a Jenkinsfile against the live controller
curl -X POST -F "jenkinsfile=<Jenkinsfile" \
  https://your-jenkins/pipeline-model-converter/validate

# replay a build with modified script to test a change without committing
# Build page -> Replay -> edit -> Run

Agent and workspace assumptions that break in CI

An agent label that matches no online agent leaves the build queued indefinitely rather than failing.
Workspaces are reused between builds by default, so stale files from a previous run can mask or cause failures. Use cleanWs() or a fresh workspace when correctness matters.
Tools resolved from the controller PATH are not necessarily on the agent PATH. Declare them in a tools block or install them in the pipeline.
Credentials bound with withCredentials are masked in logs but still visible to any process you launch; avoid passing them as command-line arguments.

Key takeaways

stage names a phase; steps runs the commands.
Each stage holds one of steps, parallel, matrix, or nested stages.
A failed step fails the stage and halts the pipeline by default.

Frequently asked questions

How do I use Stages and Steps in a Jenkins Pipeline?

Each stage groups a unit of work and appears as a column in the Stage View. Inside, steps holds the sh, echo, or plugin calls that execute.

Stages with steps?