APT Package Build Automator

A small Python tool that validates Debian package metadata, builds fixture packages, runs lint checks, detects dependency conflicts, and writes CI-friendly reports.

This project has two deliberately different execution modes:

• Mock mode is deterministic and works on Windows, WSL, and GitHub Actions without Debian tools.
• Native mode is the Linux/WSL path. It generates a minimal Debian source tree from the fixture metadata, then invokes dpkg-buildpackage and lintian installed on the system.

The mock repository contains 60 package descriptions so the pipeline can demonstrate repeatable repository-scale validation without downloading untrusted code.

Why this project exists

Debian package automation is a useful systems problem: source metadata, build tools, dependency constraints, lint policy, reports, and CI all have to agree. This project is intentionally small enough to read, but structured like a real validation pipeline.

WSL quick start

In Ubuntu on WSL:

sudo apt update
sudo apt install -y build-essential debhelper devscripts dpkg-dev lintian python3-venv
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'

Check the environment:

apt-build doctor
apt-build --toolchain native doctor

Run the deterministic pipeline first:

apt-build --toolchain mock run-all --report report.json

Run one native Debian build:

apt-build --toolchain native build pkg-01

Native builds execute package tooling and should be run in an isolated WSL distribution or VM. The fixture data is local and uses no network download.

Commands

apt-build fetch <package>                 Copy package metadata into the work area
apt-build build <package>                 Build and lint one package
apt-build check-deps                      Print dependency conflicts
apt-build doctor                          Report paths and selected toolchain
apt-build run-all [--package NAME]        Validate the repository and write JSON

Global options must appear before the subcommand:

apt-build --repo-dir fixtures/mock-repo --work-dir .apt-build --toolchain mock run-all --report report.json

Exit codes are useful in scripts:

• 0: validation completed without package failures or dependency conflicts.
• 1: validation completed and found a package failure or dependency conflict.
• 2: invalid command or configuration.
• 3: selected native tools are unavailable or an operational command failed.

Project layout

src/apt_builder/
  cli.py           Argument parsing and exit-code handling
  config.py        Repository, work directory, and toolchain settings
  fetch.py         Package discovery and local source copying
  build.py         Package-level orchestration
  toolchain.py     Small toolchain contract and error type
  toolchains.py    Mock adapter and native Debian adapter
  deps.py          Dependency requirement parsing and conflict detection
  lintian.py       Deterministic lint checks for mock packages
  report.py        Versioned JSON reports and status classification
  orchestrator.py Repository-wide execution
fixtures/          60 safe JSON package descriptions with .yml names
tests/              Unit and CLI tests
web/                Static report dashboard

The data flow is:

package metadata -> fetch -> selected toolchain build -> lint -> JSON report
                                      \
                                       dependency conflict scan -> summary

Tests and CI

python -m pytest -q
python -m apt_builder --toolchain mock run-all --report report.json

The main GitHub Actions workflow tests Python and mock mode on Ubuntu 20.04, 22.04, and 24.04. The native workflow installs Debian tools on Ubuntu 24.04 and performs a real smoke build. Reports are uploaded as workflow artifacts.

Limitations and honest trade-offs

• The fixture repository is synthetic; it is not an Ubuntu archive mirror.
• Native mode creates minimal source packages from metadata instead of fetching arbitrary upstream source.
• Dependency conflict detection handles the simple version operators used by the fixtures, not the complete Debian version language.
• lintian output is recorded, but this tool does not replace Debian's package policy or archive review process.

Further reading

Contributions and security guidance are in CONTRIBUTING.md and SECURITY.md.