Upstream and Downstream Jobs

Learn the concepts, dependency chaining methods, status thresholds, and script steps required to sequence and link multiple automated jobs into a modular CI/CD flow.

What are Upstream and Downstream Jobs?

Complex CI/CD pipelines are rarely monolithic. To ensure clean separation of concerns, workflows are split into smaller, modular projects that trigger one another. The relationship between these chained tasks is defined by relative sequencing positions known as **Upstream** and **Downstream** positions.

Simple Definition: An Upstream Job is a primary task that triggers a subsequent run upon completion, while a Downstream Job is the secondary task that wakes up automatically once its parent finishes.

Core Dependency Mechanisms

Jenkins evaluates cross-project linkages using three functional integration models:

The `build` Step Directive: An explicit statement within a declarative pipeline stage that allows the master server to programmatically invoke a downstream target job.
Condition Threshold Filters: Settings that prevent downstream activation if anomalies arise, ensuring subsequent jobs run only on approved states (e.g., `SUCCESS`, `UNSTABLE`, or `FAILURE`).
Decoupled Modularity: Decoupled pipelines that run fast compile actions first as an upstream pass, offloading long-running test suites or deployment tasks to downstream worker routines.

Key Concepts

Synchronous vs. Asynchronous Calls

Understanding that setting `wait: true` locks the upstream pipeline until the downstream runner completes, whereas setting `wait: false` triggers it asynchronously, freeing the parent run immediately.

Downstream Parameter Inheritance

Learning to use the `parameters` block alongside the `build` step to securely forward dynamic metadata values (such as git commit hashes or build IDs) to downstream execution scripts.

Practical Jenkins Example

The following declarative pipeline snippet demonstrates how an upstream compilation job invokes a secondary downstream test automation suite with parameter hand-offs:

pipeline {
    agent any

























    stages {
        stage('Execute Core Compilation') {
            steps {
                echo 'Running primary upstream source compilation routine...'
                sh 'echo "Artifact packaged successfully."'
            }
        }
        stage('Trigger Automated Downstream Validation') {
            steps {
                echo 'Invoking dependent downstream quality gate test pipeline...'
                
                // Triggers a separate job named "App-Component-Regression-Tests"
                // Dispatches execution asynchronously without blocking the parent run
                build(
                    job: 'App-Component-Regression-Tests', 
                    wait: false,
                    parameters: [
                        string(name: 'UPSTREAM_BUILD_NO', value: env.BUILD_NUMBER)
                    ]
                )
            }
        }
    }
}

Practice Exercise: Build a Two-Tier Chained Pipeline Sequence

Step-by-Step Task Sequence:

Create a new Pipeline item named exactly: App-Component-Regression-Tests, add a single `echo` step inside it, and save it to act as your target mock job.
Open or create a primary test pipeline workspace, copy-paste the template code blocks provided in the practical example section above into the text area, and click Save.
Launch your parent pipeline by selecting the **Build Now** menu trigger link on the left-hand navigation sidebar column.
Open the current build's **Console Output** screen to trace the line where the `build` directive successfully executes.
Return to the main Jenkins portal home screen to verify that your downstream job has queued and launched itself automatically.

Summary

You have completed the Upstream and Downstream Jobs lesson. Continue through the syllabus to learn how to monitor execution logs and inspect error outputs in Build History and Console Output.

← Previous: Artifacts and Build Outputs Next: Build History and Console Output →