5.4 Jenkins Declarative Pipeline Integration

How to execute CertiQA test suites inside Jenkins declarative pipelines.

The Shell Step, and When You Need More Than That

The declarative pipeline below is the fastest path from zero to a working gate: a plain sh step invoking the same certiqa-run.sh script documented in 5.1, inside a stage Jenkins already knows how to fail the build on.

pipeline {
    agent any
    environment {
        CERTIQA_TOKEN = credentials('certiqa-api-token')
        CERTIQA_API_URL = 'https://api.certiqa.app'
        CERTIQA_PROJECT_ID = 'PROJ-100'
        CERTIQA_SUITE_ID = 'SUITE-200'
    }
    stages {
        stage('E2E Quality Gate') {
            steps {
                sh './certiqa-run.sh'
            }
            post {
                always {
                    junit 'certiqa-junit.xml'
                    archiveArtifacts artifacts: 'certiqa-junit.xml', allowEmptyArchive: true
                }
            }
        }
    }
}

credentials(‘certiqa-api-token’) pulls the token out of Jenkins’ own Credentials Store (Manage Jenkins → Credentials) rather than a plaintext environment variable in the Jenkinsfile itself – Jenkins automatically masks any string matching that credential’s value out of the console log, the same protection GitHub Actions secrets give you. The post { always { … } } block is what keeps the JUnit report and any captured evidence even when the stage fails: without always, a post { success { … } } (or no post block at all) silently drops the exact run you most need to inspect.

Reading a Failed Stage in Blue Ocean

The junit post-build step does double duty: it fails the stage if any element is present in the report (so Jenkins’ own pass/fail state matches CertiQA’s), and it populates the Test Result Trend graph on the job’s summary page, letting you see flakiness or regressions accumulate across builds rather than reading one Jenkinsfile console log at a time. In Blue Ocean specifically, a failed E2E Quality Gate stage shows a red node in the pipeline visualization – click it to jump straight to the failing test’s console output instead of scrolling the full raw log.

Targeted Reruns with CERTIQA_CASE_IDS

In large enterprise suites spanning hundreds of multi-turn scenarios, re-running the entire suite when one case fails is wasteful. CertiQA’s runner script supports targeted re-execution via the CERTIQA_CASE_IDS environment variable. Jenkins pipelines can capture failing case IDs from the first pass and immediately retry only the failed cases, or accept an input parameter for manual triage.

# Re-run only specific failed test cases by ID
export CERTIQA_CASE_IDS="tc-checkout-flow,tc-refund-mcp"
./certiqa-run.sh

Agentless Jenkins Gate (No Node.js or Docker)

If your Jenkins agents have neither Node.js nor Docker, certiqa-run.sh still works: it needs only a POSIX shell, curl and jq. It starts the run with POST /api/v1/projects/{projectId}/hooks/trigger, polls GET /api/v1/runs/{runId}/report?format=summary until the run finishes, downloads the JUnit report, and exits with the codes in 5.1. Run it on any agent that can reach your CertiQA API over HTTPS; the tests themselves execute on CertiQA’s runners or your own runner fleet.

stage('E2E Quality Gate (agentless)') {
    steps {
        // Needs only sh, curl and jq on the agent; CERTIQA_* variables as in the pipeline above
        sh './certiqa-run.sh'
    }
    post {
        always { junit allowEmptyResults: true, testResults: 'certiqa-junit.xml' }
    }
}

Timeouts and Infrastructure Errors Need Explicit Handling

• Exactly like the GitHub Actions and GitLab examples, a bare sh step treats every non-zero exit the same. Exit code 2 means the run timed out and exit code 3 means an infrastructure or auth problem, so retry those rather than treating them as regressions. Do not remap 2 to 0, which would turn an unfinished run green. Quarantined failures do not fail the gate, so they need no special handling.

• 🐧 CLI Runner & Headless Execution — The exit-code contract this Jenkinsfile depends on, and the BYOC option for internal Jenkins agents.
• 🐙 GitHub Actions Quality Gate Workflow — The equivalent gate on GitHub Actions, including how GitHub redacts secrets from logs.