Skip to main content
What are sequential stages? Sequential stages allow you to run multiple stages in order inside each branch of a parallel pipeline. Introduced for Jenkins Declarative Pipelines around 2018, this feature combines the benefits of parallel execution (for coverage across platforms or configs) with explicit, visible sequences inside each branch — so you can see exactly which step is running or failed without digging through logs.
A webpage from the Jenkins site titled "Running Multiple Stages in a Parallel Branch," with explanatory text. The page includes a flowchart diagram showing pipeline stages arranged in parallel branches with sequential stages.
Why use sequential stages?
  • Better visibility: the Jenkins UI shows each nested stage, making it clear which step is running or failing inside a parallel branch.
  • Ordered work: tasks that must run in sequence (like install → test → package) can be expressed cleanly within each parallel branch.
  • Isolation of flow: a failure in one stage only affects the remaining inner stages of that branch; other parallel branches continue.
Example: Node.js branch that first installs dependencies, then runs tests To run a sequence inside a parallel branch you nest a stages block inside that branch’s stage. The following Declarative Pipeline snippet demonstrates this pattern:
Key point: a stage may contain a stages block, and those inner stage declarations execute sequentially inside that branch while sibling branches run in parallel. Common failure modes and debugging tips
  1. npm cache / permission problems (EACCES) If agents have a root-owned global npm cache or restricted filesystem permissions, npm install may fail with EACCES errors (attempting to create directories under root-owned locations). Example excerpt:
Workarounds:
  • Use an agent-writable cache directory (example in the snippet above): npm install --no-audit --cache .
  • Or ensure the agent user owns the global cache: sudo chown -R $(id -u):$(id -g) ~/.npm on the agent (if you control it).
  • Alternatively, run builds inside containers or ephemeral workspaces where cache and ownership are predictable.
  1. ENOTEMPTY / rename errors (workspace state) Even after switching cache directories, npm may fail with ENOTEMPTY when renaming subfolders in node_modules. That indicates leftover files or race conditions in the workspace rather than a Jenkins pipeline bug:
Mitigations:
  • Clean the workspace between runs (deleteDir() in a Declarative post step or use the Workspace Cleanup plugin).
  • Use isolated build containers or workspaces per job/branch to avoid leftover node_modules interference.
  • Consider caching strategies that store prebuilt artifacts instead of node_modules where feasible.
When using nested stages inside a parallel branch:
  • Put the inner stages block directly inside the branch’s stage.
  • Each inner stage runs in order; if one fails, following stages in that branch are skipped.
  • Other parallel branches are unaffected and continue to run concurrently.
Summary table — behavior and recommendations Best practices and recommendations
  • Prefer containerized or ephemeral agents for reproducible Node builds.
  • Use --cache . or explicitly configured cache directories to avoid global cache ownership issues.
  • Clean workspaces or use new workspaces for each build to avoid ENOTEMPTY and rename races.
  • Use stage-level options { retry(n) } for transient failures, especially around networked installs.
Further reading and references In short:
  • Sequential stages inside parallel branches give you ordered steps per branch with clear UI visibility.
  • Define them by nesting a stages block inside a branch stage.
  • Fix npm cache/permission issues by using a writable cache path or fixing ownership; resolve workspace errors by cleaning or isolating builds.
  • Remember: a failed inner stage prevents subsequent inner stages from running in that branch, but does not stop other parallel branches.

Watch Video