Jenkins Shared Library: PO/PM Overview

A walkthrough of the Jenkins Shared Library for Product Owners and Project Managers, showing the migration path from static Jenkins file templates to a centrally-managed shared library, and explaining how OIS scanning (Open Image Scanning) is coming back via scan hub. Less technical depth than the technical deep-dive; focused on adoption timeline, responsibility handoff, and compliance implications.

Jenkins Shared Library Recording

TL;DR

The Jenkins Shared Library replaces per-project static Jenkins files. Instead of regenerating a Jenkins file on every build and committing it to your repo, you just call the library — library updates apply to all projects automatically.

Adoption is opt-in via a jenkinsSharedLib: true flag in your tiles configuration (tiles 1.5.0+). If you don’t set it, your builds keep using the old static Jenkins file templates.

Three migration steps: (1) update to tiles 1.5.0, (2) set the jenkinsSharedLib property, (3) run file-gen:init-jenkins-yaml to generate a jenkins.yaml at the repository root (a moduleDir field names your service module). Then reconfigure the Jenkins job to point at Jenkinsfile instead of Jenkinsfile.sandbox.

OIS scans (Open Image Scanning) replace the old Fortify / 4-to-5 scans and are coming back via scan hub. Enabling the shared library is how you wire it in — set enableOISScan: true in jenkins.yaml.

What It Is and Why It Exists

The Old System

ci-file-generator (Maven plugin) downloaded Jenkins file templates from the CKM deployment templates repo and replaced placeholder variables with values from metadata.yaml. Every change — to templates or to your project — required a regenerate-and-commit cycle for every repo affected. Two Jenkins files per project: Jenkinsfile.sandbox and Jenkinsfile (for SQL/prod).

The New System

One Jenkins file per project that just loads the shared library and calls a function. The library lives in a central Git repo. When the library is updated, all projects pick it up on their next build — no per-project commits required.

This removes the administrative burden of managing templates across many repos and eliminates the synchronization problem where template changes don’t propagate until someone explicitly regenerates and commits.

Key Technical Details

The Generated Jenkinsfile

Running file-gen:init-jenkins-yaml produces:

  • A jenkins.yaml config file (project-specific settings)

  • A new Jenkinsfile that is a thin wrapper:

    • Loads the shared library (+ scan hub / codeQL library annotation)

    • Detects which environment it’s running in (sandbox vs SQL)

    • Configures credentials accordingly

    • Calls buildServiceProject()

  • The old Jenkinsfile.sandbox is deleted automatically when you set the flag

This means one Jenkins file now handles sandbox, SQL, and prod. Environment-specific behavior (different DTR credential IDs per env) is handled by the library’s runtime logic.

jenkins.yaml Fields

The init command reads metadata.yaml’s build section and tries to auto-populate jenkins.yaml. Notable fields:

  • buildTool — set from detected Maven plugin (e.g., maven, jib)

  • imageTool — set from detected image plugin (e.g., jib)

  • deployNamespace — which Kubernetes namespace to deploy to by default; overridable for teams that deploy to non-default namespaces

  • enableOISScan: true — opt-in for OIS / scan hub integration (commented out by default)

  • jiraComponent — optional; only needed if your Jira component differs from the artifact ID; required for OIS scan linkage

Tiles Version Requirement

Must be on tiles 1.5.0 to use the shared library. Earlier versions default to the old static Jenkins file generation. The jenkinsSharedLib: true property in your tiles config activates the new path; without it, nothing changes.

File Generator Tooling

The Maven plugin prefix is shortened from ci-file-generator: to file-gen:. The init command is file-gen:init-jenkins-yaml. Must be run from the service module (the one that references tiles), not the root.

Fortify Scans Sunset

Fortify scans were previously opt-in via enableFortify in metadata.yaml. That flag is now disabled by default in the shared library; you don’t need to explicitly turn it off.

OIS Scanning: The Replacement

OIS scans (Open Image Scanning) replace Fortify scans. Previously required a separate manual process through another team. Now wired into the pipeline via scan hub. Required for CPM and VEO services.

The shared library Jenkins file already includes the scan hub library annotation — you just need to set enableOISScan: true in jenkins.yaml when you’re ready.

How to Adopt

  1. Update to tiles 1.5.0 in your service module pom.xml

  2. Set jenkinsSharedLib: true in your tiles configuration

  3. cd into your service module, then run file-gen:init-jenkins-yaml (replaces old ci-file-generator:initialize)

  4. Review and update the generated jenkins.yaml (project-specific fields like deployNamespace, enable OIS if applicable)

  5. In the Jenkins multi-branch config, change the Jenkinsfile name from Jenkinsfile.sandbox → Jenkinsfile

  6. Build and validate; Jenkinsfile.sandbox will be auto-deleted by the init command

For teams with non-standard deploy namespaces (e.g., deploying to sqla or a contract-specific namespace), set deployNamespace in jenkins.yaml — this replaces the separate branch in the old deployment templates.

Q&A Highlights

Is This Mandatory?

No, but required to get OIS scanning. Without jenkinsSharedLib: true the old behavior is unchanged.

Only One Jenkins File from Now On?

Yes. The new Jenkinsfile handles sandbox and SQL/prod logic internally. Jenkinsfile.sandbox is gone.

What About Custom Jenkins Files?

Your results will vary. Test first. For genuinely non-standard commands, the library’s build-commands.groovy can be extended rather than adding project-specific customizations. The DevOps team is working on documenting all properties and use cases on the Apothesource docs site.

Separate Deploy Namespaces

For teams deploying to separate namespaces (e.g., Thomas Brothers deploying to sqla): deployNamespace in jenkins.yaml handles it. Manual deploys still select the namespace explicitly, same as before.

Can I See a Preview of the Generated Jenkinsfile?

No offline preview — execution is runtime, on Jenkins. Best approach: check out the shared library repo and read the source (build-service-project.groovy).

Bug Fixes and Project Commits

If there’s a bug in the library logic, the library is fixed centrally; you just rebuild on Jenkins. No project commits needed for library-side fixes. This is one of the key benefits of the centralized approach.

Documentation

The DevOps team is publishing documentation with all properties, defaults, and usage examples on the Apothesource docs site. A Jenkins Shared Library migration guide will be available.

Compliance and OIS Scanning

OIS scans are required for CPM and VEO services as part of compliance efforts. The shared library gates OIS scanning behind the enableOISScan: true flag in jenkins.yaml. Once enabled, scans run automatically on every build without additional manual steps.

This represents a shift from the previous model where OIS scans required manual coordination with a separate team. The integration into the standard pipeline makes scanning a routine part of the build process.

Why This is in the Knowledge Base

The Jenkins Shared Library is the current standard CI/CD build mechanism for all Apothesource services. As a PO/PM, understanding what jenkins.yaml controls, how library updates propagate, and how OIS scans wire in is baseline context for service delivery, compliance, and platform alignment. The adoption timeline (opt-in with tiles 1.5.0+) affects sprint planning for services moving to the new system. The OIS scanning requirement for CPM/VEO services is a compliance / audit-trail consideration that affects scope and story pointing for those services.