Integrating Endevor CAST with SonarQube:
Integrating a SonarQube code-quality gate into Endevor Package CAST actions offers a seamless and efficient way to enforce code quality standards for software managed by Endevor. This approach embeds scanning and validation directly into the existing pipeline, which streamlines the enforcement process.
Endevor packages, which group inventory items for approvals and promotions through the pipeline, are subject to a CAST action to determine their suitability for execution. This CAST action includes a series of built-in validations on the package content. If any of these internal validations fail, the package CAST fails.
The package CAST phase offers an ideal window to embed SonarQube analysis as a supplementary validation gate. By incorporating this check during the CAST process, you establish a timely and automated quality control point. This validation scans COBOL elements, for example, within the package along with their associated input components, which are identified via Automated Configuration Manager (ACM) lookups. If the SonarQube analysis detects issues, the package CAST can be blocked and the specific discrepancies will be logged. A successful CAST is only possible once all errors identified by SonarQube have been rectified.
To align Endevor CAST with SonarQube, review the following implementation strategies to determine the most effective workflow for your environment:
1. Scope of Scanning (What to Scan):
-
Element Types: Specify which types of Endevor elements to scan. SonarQube supports various elements, including COBOL, C++, and JCL.
2. Enforcing or Offering the Scan (When to Scan):
-
Optional Scan (Developer Choice): Allow development teams to indicate which packages require a scan, perhaps by noting it in the Package notes.
-
Mandatory Scan (Required):
-
Require a SonarQube scan for all packages, or only for packages containing certain element types, before allowing the package to proceed to the next step in the life cycle.
-
Consider whether to allow developers to override this requirement.
3. Workflow Integration (How to Handle Results):
-
Wait for Analysis: Determine if the process should wait for the SonarQube analysis to complete before proceeding.
-
Update Endevor: Decide whether to incorporate the SonarQube analysis results back into Endevor.
4. Developer Overrides for SonarQube Analysis actions:
Because SonarQube operates as a server-side application external to the mainframe—running on platforms such as Linux, Windows, or within Docker containers—analyzing Endevor Package content requires transferring packaged elements and their associated input components from the mainframe environment to the SonarQube server.
While various methods exist for artifact transmission and remote command execution, this specific implementation recommends XCOM (as described in the linked documentation).
XCOM supports seamless, high-speed, and secure data transfer across a wide variety of systems (mainframe, Windows, Linux, AIX, AS/400, cloud storage, etc.). It uses advanced data compression and record packing techniques, offering significantly higher performance (up to 98% improvements, check out the blog here) compared to FTP. XCOM excels with large batch files, in a reliable, auditable, managed way.
XCOM components of this solution are found in the XCOM folder on GitHub. However, this design allows for easy substitution with equivalent components that utilize your transmission tool—or tools—of choice. You have the option to use separate tools for transfers and remote executions.
This solution leverages Endevor exit software, using the "Rexx Exit" found on the Broadcom Product Scripts GitHub, which is automatically triggered when an Endevor package CAST starts. This software orchestrates the entire process. It utilizes a REXX driver (also on GitHub) and the Table Tool to manage activities. These components work together to:
-
Collect a list of COBOL members and input components for transfer.
-
Execute the transfers.
-
Initiate the SonarQube analysis via a Python driver on Linux
-
Wait for the analysis outcomes.
-
Update the package CAST status based on the results.
The User ID under which the CAST and SonarQube analysis is executed is configurable, offering two options:
-
The analysis runs under the User ID of the individual who last CAST or Approved the package.
-
The analysis runs under the Endevor Alternate ID, a choice that may necessitate fewer accompanying security controls.
_____________________________________________________________________________________________________________________________
High-level flow
Endevor CAST & SonarQube Integration
The Process An Endevor package defines actions for specific elements. When an authorized user "CASTs" a package to begin validation, the following automated workflow occurs:
-
Execution Check (Foreground vs. Batch): A pre-configured COBOL exit triggers a REXX subroutine. To prevent the SonarQube analysis from locking the user's terminal, TSO Foreground CASTs are automatically resubmitted as batch JCL. CASTs initiated via Zowe or Explorer proceed immediately as they are already in batch mode.
-
Data Gathering: The REXX program uses Endevor APIs to compile package dependencies into a TableTool table, allowing for easy site-specific configurations.
The Two-Job Workflow The integration coordinates two distinct jobs: the CAST Job (Endevor actions) and the SonarQube Job (Analysis).
-
Step 1: Identification & Handoff The CAST Job lists all COBOL and Copybook components, submits the SonarQube Job, and pauses execution to wait for results.
-
Step 2: Transfer & Analysis The SonarQube Job transfers code to the server and triggers the analysis. It updates specific datasets after every step (Transfer, Analyze, Result Generation) to signal its progress to the waiting CAST Job.
-
Step 3: Completion Once analysis results are transferred back to the mainframe, the SonarQube Job terminates. The CAST Job retrieves these results and updates the final Package CAST status.
_____________________________________________________________________________________________________________________________
Implementation Choices
The configuration of this solution is designed for inherent flexibility, allowing you to tailor the SonarQube analysis workflow to your site's specific requirements:
-
Execution Modes (Mandatory, Default, or On-Demand): You can configure the SonarQube trigger through several enforcement strategies:
-
Enforcing a mandatory analysis where all package CAST actions must successfully pass the quality gate.
-
Establishing a default-on policy where scans run automatically unless specifically bypassed via the package Notes.
-
Implementing an on-demand model where analysis is skipped by default, but can be requested through package Notes entries.
-
Analysis Synchronization: Similarly, you can define whether the Endevor CAST process should wait for analysis results or proceed independently:
-
Allow the CAST to complete normally without synchronizing with SonarQube results; in this mode, analysis findings do not impact the CAST outcome.
-
Require the CAST to wait for the analysis to finish, ensuring that any quality gate failures automatically result in a failed package CAST.
As you implement this solution, you can establish default values and custom trigger strings within the @SITE.rex program. This flexibility allows you to define the specific text patterns developers use in the package Notes to signal their analysis preferences. Once configured, these recognized terms can be entered anywhere within the Notes section, as demonstrated in the following examples:
_____________________________________________________________________________________________________________________________
Retention of the Analysis Reports
Whether your configuration waits for the SonarQube analysis, or allows the package to CAST without waiting, you can place the results into Endevor. Member SONR#ADD? Uses the package name as the element name, making the SonarQube results easy to find - even after the package is Committed.
What you’ll need
-
Endevor Package Exit enabled for CAST (configured in your exits table). See content on GitHUb.
-
XCOM (or equivalent) connectivity between z/OS and your Linux SonarQube runner host.
-
SonarQube (Server) + SonarQube Scanner CLI installed on the Linux host.
-
Python 3 on Linux to orchestrate scanning and formatting results.
-
A service account and token for SonarQube (project-level or global).
-
A results contract (simple JSON or CSV) that the exit can parse reliably.
_____________________________________________________________________________________________________________________________
Implementation blueprint
1) Endevor: package exit responsibilities
Your exit does three things:
-
Collect impacted components:
Use the package content list to enumerate COBOL sources and their dependencies (copybooks, includes). Endevor already knows impacts—leverage that.
-
Launch the XCOM job (3 steps):
Submit a JCL that:
-
S1 SEND: ships the enumerated datasets/members to Linux (preserving directory structure if you can).
-
S2 RUN: invokes the Linux Python driver.
-
S3 RECEIVE: pulls the results file back to a known dataset (e.g., HLQ.SQ.RESULTS(&PKGID)).
-
Parse results + decide:
-
Read the results dataset, extract status and key metrics (e.g., vulnerabilities, code smells, coverage, quality gate state).
-
Fail CAST if the quality gate = FAIL (or if metrics breach thresholds). Otherwise return success.
Tip: Keep the exit stateless and put all environment-specific values (Linux host, ports, token DSN, project key template) in a PARMLIB member.
_____________________________________________________________________________________________________________________________
2) XCOM job: the three-step pattern
This section focuses on the activities of your transmission-tool members. Although we refer to them generally as the XCOM job steps for simplicity, note that their names may vary depending on the specific transmission tool you utilize.
The SONARMDL.skl member, available on GitHub, serves as the model for the Job that handles file transmissions and the remote execution of the SonarQube analysis. The process is orchestrated using Table Tool, which substitutes variables such as &AltIDAcctCode, &ReportingPFX, and &METHOD with actual values before the job is submitted and monitored.
//&Jobname JOB &AltIDAcctCode,
// &Userid,REGION=0M,NOTIFY=&Userid,MSGCLASS=X,CLASS=A,
- - - - - - - - - - - - - - - - 20 Line(s) not Displayed
//REPORT1 EXEC PGM=IKJEFT1B, <- Report that job started SONARMDL
- - - - - - - - - - - - - - - - 25 Line(s) not Displayed
//REPORT DD DSN=&ReportingPFX.#1,
- - - - - - - - - - - - - - - - 65 Line(s) not Displayed
// INCLUDE MEMBER=&METHOD.#RUN <- Exec the Transmission
- - - - - - - - - - - - - - - - 5 Line(s) not Displayed
//REPORT2B EXEC PGM=IKJEFT1B, <- Report Transmit FAILED SONARMDL
- - - - - - - - - - - - - - - - 20 Line(s) not Displayed
//REPORT DD DSN=&ReportingPFX.#2,
- - - - - - - - - - - - - - - - 5 Line(s) not Displayed
//REPORT2A EXEC PGM=IKJEFT1B, <- Report Transmit is done SONARMDL
- - - - - - - - - - - - - - - - 20 Line(s) not Displayed
//REPORT DD DSN=&ReportingPFX.#2,
- - - - - - - - - - - - - - - - 7 Line(s) not Displayed
// INCLUDE MEMBER=&METHOD.#JOB <- Exec Sonar Analysis
- - - - - - - - - - - - - - - - 8 Line(s) not Displayed
//REPORT3 EXEC PGM=IKJEFT1B, <- Report SonarQube is done SONARMDL
- - - - - - - - - - - - - - - - 20 Line(s) not Displayed
//REPORT DD DSN=&ReportingPFX.#3,
- - - - - - - - - - - - - - - - 6 Line(s) not Displayed
// INCLUDE MEMBER=&METHOD.#RCV <- Receive Results
- - - - - - - - - - - - - - - - 14 Line(s) not Displayed
The INCLUDE MEMBER JCL statements utilize the variable &METHOD to dynamically specify the names of the members to be included. For instance, in our example, &METHOD is set to "XCOM", to include XCOM* members.
Interspersed in the JCL are REPORTn steps which are vital for efficient process management. These steps relay feedback to the Endevor CAST package job, which waits for the results, thereby controlling the overall elapsed time. The calculated wait duration for subsequent steps is based on the early results from these reporting steps.
Swapping XCOM: We found XCOM easy to use with superior performance. Also, XCOM is a Broadcom supported product, so any questions you have can be quickly answered by the support team.
However, you can replace the XCOM with other tools that support send → run → return operations. .
_____________________________________________________________________________________________________________________________
3) The Python driver on Linux
Keep it small and deterministic:
Responsibilities
-
Load runtime config (project key, token, source path, output path).
-
Execute sonar-scanner with required properties (sonar.projectKey, sonar.sources, sonar.host.url, sonar.login or token env).
-
Poll the SonarQube CE task until it completes (read the ceTaskId from scanner output or .report-task.txt).
-
Fetch quality gate and metrics via SonarQube Web API.
-
Write a normalized results file (JSON/CSV) for z/OS.
-
Delete the staged source directory (/opt/sonar/work/${PKGID}) to avoid residue.
Code sketch:
GitHub Link to the Code
CAST failure output example :