koji-habitude is an object management tool for Koji build systems. It provides a declarative approach to managing koji objects through YAML templates and data files.
This project is an offshoot of koji-box, fulfilling the need for populating a boxed koji instance with a bunch of tags and targets. However it is being written such that it can be used with any koji deployment, in the hopes that it may bring joy into the lives of those trying to keep project packagers happy.
Key Features:
- Define koji objects (tags, external repos, users, targets, hosts, groups, channels, permissions, build types, archive types) in YAML
- Use Jinja2 templates for dynamic configuration generation
- Automatically resolve dependencies between objects (tag inheritance)
- Apply changes in the correct order through tiered execution
- Validate configurations offline before deployment
koji-habitude provides a comprehensive CLI built with Click for managing Koji objects. The CLI includes:
- Primary commands:
apply,compare,expand,fetch,dump,list-templates,diff, andedit - Template subcommands: Work with individual templates using
template show,template expand,template compare,template diff,template apply
For detailed CLI documentation with all options, examples, and use cases, see the Command-Line Interface documentation in the full documentation.
YAML files can be single or multi-document, processed in-order. Each document
has a type key indicating the document type. Core types include template,
tag, target, user, group, host, channel, permission,
content-generator, build-type, archive-type, and external-repo.
Templates define new types based on their name.
Templates use Jinja2 for dynamic content
generation, allowing you to create reusable patterns for koji objects. When
processing data files, objects with type matching a template name trigger
template expansion, creating final koji objects through recursive processing.
For complete YAML format documentation and detailed examples, see the YAML Format Specification in the full documentation.
koji-habitude supports all core Koji object types with fully implemented Pydantic models: tags, external repos, users, targets, hosts, groups, channels, permissions, content generators, build types, and archive types.
The system automatically detects dependencies between objects (e.g., tag inheritance) and provides intelligent resolution through tiered execution, ensuring objects are processed in the correct order. The architecture includes:
- Template System: Jinja2-based template expansion with recursive processing
- Dependency Resolution: Automatic detection and tiered execution ordering
- Remote Models: Complete set of remote object models for fetching and comparing
- State Synchronization: State machine-driven processor with multicall integration
- Change Tracking: Detailed tracking of all modifications with explanations
- Dry-Run Support: Preview changes without applying them
- Bidirectional: Fetch remote state to YAML, or dump remote objects by pattern
Data Flow: YAML files → Template expansion → Dependency resolution → Tiered processing → Koji hub
Requirements:
Installation:
pip install -e .Author: Christopher O'Brien obriencj@gmail.com
Original Git Repository: https://github.com/obriencj/koji-habitude
Documentation: https://obriencj.github.io/koji-habitude
AI Assistance: This project was developed with assistance from Claude (Claude 3.5 and 4.5 Sonnet) via Cursor IDE.
License: GNU General Public License v3 or later. See https://www.gnu.org/licenses/ for details.