Konfusion

Konflux Fusion. CLI for implementing CI tasks. No confusion.

Design

See DESIGN.md.

Development

Start by installing make and uv. E.g.:

sudo dnf install make uv

Virtual environment

Set up a virtual env, install konfusion and all the dependencies necessary for development:

make .venv
source .venv/bin/activate

Play with konfusion:

konfusion --help
konfusion --version
konfusion apply-tags --tags v1 v1.0 --to-image quay.io/my-org/my-image:latest

Static checks

• pyright for type-checking¹
  • We may switch to ty when it's production-ready.
• ruff for linting and formatting

For the best development experience, integrate your editor with the pyright/pylance and ruff LSP servers.

If you don't have these tools integrated with your editor, run them manually:

# check for issues and incorrect formatting
make check
# apply correct formatting
make format
# autofix some issues
make autofix

Tests

We use pytest for all our tests, including doctests.

To run tests locally, use:

make test

Or run pytest directly to make use of its full power:

source .venv/bin/activate
pytest --stepwise -vvv

Integration tests

Pre-requisites:

• podman
• openssl

Run integration tests with:

make integration-test

Or directly using pytest (just copy the command from the Makefile).

konfusion-test-utils

Integration tests deploy an instance of the Zot container registry (a small, OCI-compliant registry implementation). The tests also set up TLS for the registry by generating a custom CA certificate and using it to sign Zot's server certificate.

This makes working with the registry a little tricky, which is why we have a separate konfusion-test-utils package and CLI to make testing easier.

Run the registry for local testing:

source .venv/bin/activate
konfusion-test-utils run-zot-registry
# see the output for further instructions

Run commands in the konfusion container image in a way that makes interacting with the registry straightworward:

konfusion-test-utils run-konfusion-container -- \
  skopeo copy docker://busybox:latest docker://localhost:5000/busybox:latest

konfusion-test-utils run-konfusion-container -- \
  konfusion apply-tags --to-image localhost:5000/busybox:latest --tags test

By default, run-konfusion-container will rebuild the Konfusion container image every time. To use an existing image instead:

podman build -t localhost/konfusion:latest .
export TEST_KONFUSION_CONTAINER_IMAGE=localhost/konfusion:latest

konfusion-test-utils run-konfusion-container -- \
  skopeo copy docker://busybox:latest docker://localhost:5000/busybox:latest

Tips and tricks

Registry reuse

By default, when you run integration tests, they clean up registry storage, run a registry instance for the tests and then stop the instance again.

If you would like to inspect the state of the registry after the tests, run konfusion-test-utils run-zot-registry and log in to the UI (find the URL and the credentials in the output of this command).

Before running tests again, stop the registry (podman kill konfusion-zot-registry) so that the tests can use a clean instance.

If you keep the registry running, tests will reuse your instance without cleaning the storage. This can be useful if you'd like to do some manual setup while working on tests, for example. But always make sure the tests work when starting from a clean storage before you submit a pull request.

Dependency management

The primary package manager for this project is uv. Add a new dependency using:

uv add {dependency}

# if the dependency is for development/testing
uv add --group dev {dependency}

Konfusion builds its container image hermetically in Konflux, which requires extra lockfiles on top of the primary uv.lock.

Whenever uv.lock changes, re-generate requirements[-build].txt:

make requirements.txt
make requirements-build.txt

If you need to install a new package in the Containerfile using dnf, first add it to rpms.in.yaml and then re-generate rpms.lock.yaml:

make rpms.lock.yaml

Footnotes

1. You may be more familiar with mypy for type-checking Python code. But if you use something like VSCode, Vim or Emacs with a Python LSP server, there's a good chance you use pyright (in case of VSCode - pylance, based on pyright). To better align with your editor experience, we use pyright for type-checking. ↩