OPSI Packaging Pipeline
Relevant source files
The following files were used as context for generating this wiki page:
The OPSI Packaging Pipeline automates the lifecycle of OPSI software packages by discovering upstream Windows application releases, downloading installers, and bundling them into .opsi archives. This system enables private software repositories to maintain current versions without requiring client machines to have internet access.
The pipeline executes within a Dockerized environment, utilizing the official opsi-cli for package creation and metadata generation. It consists of three primary stages: Source Resolution, Package Generation, and Repository Management.
Sources: README.md:12-23, builder/builder/main.py:18-30
Pipeline Architecture
The pipeline follows a structured flow from discovery to publication. It uses a file-based lock (builder.lock) to ensure only one builder process modifies the repository at a time.
The diagram shows the sequential stages of the automated build cycle, from initial discovery to final repository cleanup.
Sources: builder/builder/main.py:126-155, builder/builder/opsi.py:90-110
Key Components
1. Source Resolution
The resolve function identifies the latest software version and its download URL based on the catalog/packages.yaml definition. It supports various adapters including GitHub Releases, Microsoft Update APIs, and WinGet manifests.
| Adapter Type | Functionality |
|---|---|
github_release | Queries GitHub REST API for tags and assets matching regex. |
winget_manifest | Parses Microsoft's WinGet manifests for stable machine-scope installers. |
mozilla | Monitors Mozilla's JSON version feeds. |
direct_url | Uses regex patterns to extract versions from vendor pages. |
Sources: builder/builder/sources/adapters.py:64-160, README.md:88-105
2. Package Generation (opsi.py)
The generate() function creates the directory structure required by OPSI, specifically the CLIENT_DATA and OPSI folders.
- Template Rendering: Uses Jinja2 to render
control.toml,setup.opsiscript, anduninstall.opsiscript. - Script Injection: Copies standard PowerShell helpers (
runtime.ps1,install.ps1,uninstall.ps1) into the package. - Metadata: Generates a
config.jsoncontaining detection logic and aprovenance.jsonfor tracking the installer's origin.
Sources: builder/builder/opsi.py:20-75
3. Archive Building and Validation
The build() function executes the opsi-cli package make command. After creation, the pipeline performs a "round-trip" validation by extracting the package and verifying:
- The
control.tomlmetadata matches the source. - The bundled installer remains byte-identical to the original download.
- The package MD5 sidecar is correct.
Sources: builder/builder/opsi.py:88-125
4. Repository Management (repository.py)
Once built, archives are moved atomically to the repository/ directory. The pipeline then regenerates the repository metadata files (packages.json, etc.) in a temporary directory before replacing the live versions to prevent in-flight corruption.
Sources: builder/builder/repository.py:34-66
Data Flow for Package Creation
This sequence illustrates the interaction between the builder logic, the OPSI command-line tools, and the final storage location.
Sources: builder/builder/main.py:100-115, builder/builder/opsi.py:88-95
Repackaging System
The pipeline includes a specialized repackage.py module for offline updates. If only the OPSI deployment logic changes (and not the vendor software), this module extracts an existing archive and rebuilds it with a new revision number. This process skips network calls and upstream checks, relying on recorded provenance data.
Sources: builder/builder/repackage.py:40-80
Security and Integrity
The pipeline enforces strict security measures:
- Checksum Verification: Downloads must match vendor-published SHA256 hashes.
- Host Allowlists: Redirects are restricted to verified official hostnames defined in the catalog.
- Provenance: Every package includes a
provenance.jsondocumenting the download URL, timestamp, and signature status.
Sources: builder/builder/main.py:43-52, README.md:135-145
The OPSI Packaging Pipeline ensures that OPSI-managed environments receive verified, packaged updates automatically, reducing manual administrative overhead while maintaining deployment integrity.