pipeline, agent, stages, and steps

Scenario: A misplaced directive prevents parsing before any useful stage starts.

Pipeline example

pipeline { agent none; stages { stage('Test') { agent any; steps { sh './test.sh' } } } }

Declarative syntax is a model

The required pipeline block contains an agent policy and stages; each stage normally contains steps or a supported nested parallel or matrix structure. Directives are not arbitrary Groovy statements, and placement is part of the grammar. A stage can own agent, when, options, environment, input, tools, and post behavior. Validation can reject a misplaced directive before an executor is allocated or any external side effect begins.

Agent any allocates one workspace for the whole Pipeline. Agent none avoids holding an executor during orchestration and lets stages select appropriate nodes, but files do not follow between workspaces. Transfer small intra-run outputs with stash and unstash; publish durable packages externally. A container agent changes execution tools while the controller still interprets Pipeline structure and schedules the underlying node.

Keep the graph truthful

Use stage names for user-visible delivery boundaries and executable actions inside steps. A small script block is reasonable for logic Declarative cannot express, but large imperative regions hide agent use, conditions, and stages from validation and visualization. Stable dimensions belong in matrix or explicit parallel stages instead of dynamically generated Groovy whenever possible.

Run the Declarative linter and exercise failure paths, not only successful parsing. Force compilation failure, test failure, timeout, skipped condition, and aborted input; then verify post conditions, reports, cleanup, and final result. The best Jenkinsfile lets a reviewer identify executor allocation, privileged boundaries, gates, and evidence without mentally executing a general-purpose Groovy program.

Goal: Practice the concrete behavior in jenkins-declarative-rescue. Learn sections have no Jenkins terminal; the Jenkins lab opens the real shared service in a new full-screen tab inside your private folder.