Contributor and AI Agent Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
This document establishes the standards and procedures for contributors and AI agents interacting with the auto-opsi-repo codebase. It outlines the development workflow, architectural requirements for adding software packages, and the technical constraints governing the repository builder.
The project provides an automatic private OPSI 4.3 software repository. It discovers upstream Windows releases, packages them into .opsi archives, and serves them via Nginx. Contributors must adhere to specific code style rules and testing requirements to ensure the stability of the automated build cycles.
Sources: agents.md:6-12, README.md:10-18
Development Workflow and Standards
Code Style and Linting
The project enforces specific Python standards to maintain consistency. You must use Python 3.13 as the target version. The repository utilizes the Ruff linter with a defined set of rules.
Sources: agents.md:20-24, pyproject.toml:1-6
- Line Length: Maximum 100 characters.
- Lint Rules: E4, E7, E9, F, I, UP, B.
- Python Version: 3.13.
Branching and Pull Requests
You must follow a structured contribution process for all changes:
- Create a new branch from
mainfor every feature or bug fix. - Commit changes with descriptive messages.
- Push the branch and initiate a Pull Request (PR).
- Address review feedback and rebase the branch if necessary.
Sources: agents.md:27-31
Testing Requirements
Unit tests focus on mocking network calls to validate internal logic. You must run tests before submitting changes.
Sources: agents.md:15-18, agents.md:52-59
# Environment setup and test execution
python3 -m venv .venv
.venv/bin/pip install -r builder/requirements.txt pytest
.venv/bin/python -m pytest -q
Sources: agents.md:15-18
Package Management Guidelines
Adding New Packages
When adding a software package, you must modify catalog/packages.yaml. The system requires a unique lowercase OPSI product ID (maximum 32 characters) and a specific architecture (x64).
Sources: agents.md:36-41, README.md:153-157
The following flowchart illustrates the mandatory steps for package inclusion:
Sources: agents.md:36-41, README.md:175-180
Catalog Configuration Structure
Every package entry must include source adapters, installer arguments, and detection methods.
Sources: catalog/packages.yaml:1-20, README.md:158-174
| Field | Requirement | Description |
|---|---|---|
opsi_product_id | Unique, max 32 chars | The internal OPSI identifier. |
source.type | Supported adapter | e.g., github_release, direct_url, winget_manifest. |
source.allowed_hosts | List of hostnames | Strict allowlist for download redirects. |
installer.type | exe, msi, or zip | The format of the vendor installer. |
detection.method | registry, msi, file_version | Method to verify successful installation. |
| Sources: README.md:158-174, README.md:185-208 |
Architectural Logic and Constraints
The Build Cycle
The repo-builder operates on a configurable interval (default 6 hours). It follows a specific sequence to ensure repository integrity, using a file lock to prevent concurrent writes.
Sources: builder/builder/main.py:167-185, README.md:20-22
Security and Validation Guards
- Checksum Verification: A changed installer hash for a known version causes a failure. You must not bypass this unless
ALLOW_CHANGED_CHECKSUMis explicitly enabled. - Host Validation: Every redirect URL is checked against the
allowed_hostslist defined in the catalog. - Atomic Operations: Metadata generation occurs outside the served directory and uses atomic renames to prevent corruption for active readers.
Sources: README.md:23-28, README.md:280-295, builder/builder/download.py
OPSI Packaging Logic
The builder generates OPSI scripts and control files based on Jinja templates and catalog overrides.
Sources: builder/builder/opsi.py:20-66
- Templates: Located in
builder/templates. - Overrides: Located in
catalog/overrides/<opsi_product_id>/. - Provenance: Every built package includes a
provenance.jsoninCLIENT_DATAcontaining the download timestamp, source URL, and original SHA256.
Sources: builder/builder/opsi.py:27-32, builder/builder/main.py:108-124
Summary
Contributors and AI agents must prioritize repository integrity by adhering to the strict validation logic of the builder. All new software definitions require thorough metadata configuration in the catalog and must pass both unit tests and dry runs before deployment. Broad distribution rights should be verified before setting redistribution status to allowed.
Sources: README.md:377-385, agents.md:52-59