How does a Jenkins declarative pipeline work and what are its stages?

Think of a Jenkins declarative pipeline like an assembly line in a factory. Each station on the assembly line performs a specific task in a fixed order: first the raw materials are inspected, then they are shaped, then painted, then tested, and finally packaged for shipping. Similarly, a declarative pipeline defines a series of stages that code must pass through before it reaches production. Just as the factory floor manager sets the rules for how the assembly line operates, the pipeline block sets the rules for how code flows through the CI/CD process.

A declarative pipeline is defined in a Jenkinsfile placed at the root of your repository. The top-level pipeline block contains an agent directive that specifies where the pipeline runs, followed by a stages block that holds one or more individual stage blocks. Each stage contains a steps block where the actual work happens, such as compiling code, running tests, building Docker images, or deploying to environments. Additional sections like environment, options, triggers, and post provide configuration for variables, build settings, automatic triggers, and post-build actions respectively.

Internally, when Jenkins encounters a Jenkinsfile, the pipeline engine parses the declarative syntax and converts it into an internal execution graph. Each stage becomes a node in this graph, and Jenkins orchestrates the execution by allocating workspace directories, managing environment variables, and coordinating with agents. The pipeline engine uses a durable execution model backed by the FlowNode storage system, which means that if Jenkins restarts mid-build, it can resume the pipeline from where it left off. Stage boundaries serve as checkpoints in this durable execution model, and each stage transition is persisted to disk before proceeding.

In production environments, declarative pipelines are typically configured with multiple stages reflecting the software delivery lifecycle: checkout, build, unit test, integration test, security scan, staging deployment, acceptance test, and production deployment. Teams often use the when directive to conditionally execute stages based on branch names, enabling different behaviors for feature branches versus the main branch. The post section is critical for production pipelines, as it defines cleanup actions, notification steps, and artifact archival that must happen regardless of whether the pipeline succeeds or fails. Input steps can be inserted between stages to require manual approval before production deployments.

A common gotcha with declarative pipelines is confusing the scope of environment variables and credentials. Variables defined in the top-level environment block are available to all stages, but variables defined within a stage are scoped only to that stage. Another frequent mistake is placing resource-intensive operations outside of stages, which can cause them to run on the Jenkins controller node instead of an agent, potentially destabilizing the entire Jenkins instance. Teams should also be aware that declarative pipelines have a strict structure that cannot be violated, and attempting to use scripted pipeline syntax inside a declarative pipeline requires wrapping it in a script block, which should be used sparingly to maintain readability.