Manual Operations and Dry Runs
Relevant source files
The following files were used as context for generating this wiki page:
Manual operations and dry runs provide administrators with controlled methods to interact with the repo-builder outside of its standard six-hour automated cycle. These operations allow for targeted package builds, safety checks, and emergency rebuilds without altering the production repository state or committing to permanent changes.
A dry run simulates the discovery and build process by fetching release metadata and published checksums to report proposed changes. It avoids creating installers, OPSI packages, file locks, or persistent state modifications. Manual operations use specific CLI arguments to trigger immediate builds for single products or force the reconstruction of existing archives when packaging logic changes.
Sources: README.md:12-19, README.md:129-133, builder/builder/main.py:151-155
Dry Run Functionality
The dry run mode validates catalog configurations and upstream connectivity without modifying the repository. It identifies new versions, verifies if host allowlists match upstream redirects, and reports what actions the builder would take during a normal cycle.
Execution Logic
When you trigger a dry run, the system:
- Loads the catalog and validates product definitions.
- Resolves upstream metadata to identify the latest available versions.
- Compares identified versions against the current repository inventory and state.
- Outputs a summary of "Updated" (would build), "Unchanged", and "Failed" items to the console.
Sources: builder/builder/main.py:46-51, builder/builder/main.py:100-104, README.md:131-133
Simulation Flow
The following diagram illustrates the restricted logic path taken during a dry run compared to a standard execution.
The dry run terminates before any filesystem writes occur in the repository, state, or work directories.
Sources: builder/builder/main.py:100-108, tests/test_workflow.py:228-234
Manual Build Operations
Manual operations allow you to bypass the UPDATE_INTERVAL_SECONDS timer. You can run the builder for a specific product or force a full cycle immediately.
Execution Commands
Use the following commands via Docker Compose to perform manual tasks:
| Operation | Command | Result |
|---|---|---|
| Single Product | docker compose run --rm repo-builder --once --product <id> | Builds only the specified product. |
| One-time Run | docker compose run --rm repo-builder --once | Executes one full cycle for all enabled products and exits. |
| Force Rebuild | docker compose run --rm repo-builder --once --force <id> | Rebuilds the package even if the version already exists. |
| Force All | docker compose run --rm repo-builder --once --force-all | Rebuilds every product in the catalog. |
Sources: README.md:129-133, builder/builder/main.py:180-186, agents.md:65-67
Locking and Serialization
Manual runs respect the global builder lock. If a scheduled background cycle is active, the manual run will fail to acquire the lock and exit to prevent repository corruption.
Force Operations and Checksum Guards
The --force flag triggers a rebuild of OPSI archives, but it does not bypass security guards regarding installer integrity.
Forced Rebuild Logic
- Re-packaging: The builder downloads the installer and regenerates the OPSI scripts and
control.toml. - Checksum Verification: The builder compares the newly downloaded installer against the historical SHA256 stored in
state/packages.jsonorprovenance.json. - Safety Failure: If the upstream installer hash has changed for a version the builder already knows, the operation fails even with
--force. This prevents silent replacement of installers.
Sources: README.md:195-207, builder/builder/main.py:84-95
Overriding Checksum Guards
If a vendor has legitimately updated an installer at the same URL/version, you must explicitly permit the change using an environment variable during the manual run:
docker compose run --rm -e ALLOW_CHANGED_CHECKSUM=true repo-builder --once --product <id> --force <id>
Sources: README.md:208-212, builder/builder/main.py:85-86
Summary of Operation Arguments
The builder/builder/main.py entry point supports the following arguments for manual control:
| Argument | Type | Description |
|---|---|---|
--once | Flag | Run one cycle and exit immediately. |
--dry-run | Flag | Simulate actions without writing to disk or locking. |
--product | String | Limit operation to a specific opsi_product_id. |
--force | Append | Specify products to rebuild regardless of existing archives. |
--force-all | Flag | Rebuild all products in the catalog. |
Sources: builder/builder/main.py:180-186
Manual operations are essential for testing new catalog entries. Administrators should perform a product dry run followed by a manual build and Windows client acceptance test before allowing a package to be managed by the automated schedule.
Sources: agents.md:46-51, README.md:73-77