Contributing

Pull requests

Changes to this project should be proposed as pull requests on Github at:
https://github.com/lxc/incus-os

Proposed changes will then go through code review there and be merged in the main branch.

Code of Conduct

When contributing, you must adhere to the Code of Conduct, which is available at:
https://github.com/lxc/incus-os/blob/main/CODE_OF_CONDUCT.md

Policy on the use of Large Language Models (LLMs) and AI tooling

For issue reporting

We do NOT allow direct filing of issues by LLMs.

We REQUIRE a human being to go through our issue reporting form on Github and accurately describe their issue and provide all needed information.

The more concise and to the point the issue is, the more likely it is to be understood, tracked down and resolved quickly.

Long winded AI written essays can easily look overwhelming and cause our maintainers and other contributors to just entirely skip the issue to focus their energy on something else.

We also don’t benefit from AI generated root cause analysis or proposed fixes in those issues. If you yourself understand the code base well enough to go through that content and suggested fix, then turn it into a pull request and submit it yourself. Otherwise, please limit your report to describing the issue at hand and we’ll take it from there.

For contributions

We REQUIRE all contributions to IncusOS to be submitted by human beings who can assert full copyright ownership of their contribution or have been allowed by their employer to contribute. This is what the DCO (see below) requires of all contributors.

AI tools can sometimes be beneficial, particularly when it comes to finding patterns among a large data set (entire code base), performing tedious repetitive changes or large refactoring/re-organization.

While we now tolerate the use of such tools, they must abide by our instructions (AGENTS.md) and their operators cannot override those instructions.

We expect everyone contributing to IncusOS to fully own their contribution, be able to reason about it, be able to explain why things were done a particular way and act as the full owner of that code. AI tools are treated the same as traditional tooling like sed, awk or coccinelle.

For the purpose of this project, AI tools CANNOT be treated as author, co-author or be credited in any way that would suggest any ownership over the contribution.

The contributor should have done all the thinking, planning and understanding of the changes needed to resolve an issue or implement a new feature prior to using automated tooling to perform the grunt work.

Unguided use of those tools or the inability to prove understanding of the code contributed will result in a loss of trust in that contributor by project maintainers which can then lead to exclusion from any further contribution to the project.

It’s also worth pointing out that while those tools are good at implementing the more boring/repetitive/grunt work. We’ve generally found that you only really understand the project and its structure by having done such work yourself a few times.

For anyone with write access to the repository

Anyone with write access to this repository must ensure to NEVER run an AI agent or similar tool on a system which holds repository credentials (SSH key, GPG key, web browser cookies, …).

Any use of AI tooling should be done inside of a clean virtual machine/container that itself cannot directly push to or alter this repository in any way.

The safest approach is to SSH into that environment and then extract the changes using git format-patch, then review and apply them to your actual tree, tweak them as needed, sign them off and then push and open the pull request.

Any potential credential compromise or loss of control should be immediately reported to security@linuxcontainers.org.

Developer Certificate of Origin

To improve tracking of contributions to this project we use the DCO 1.1 and use a “sign-off” procedure for all changes going into the branch.

The sign-off is a simple line at the end of the explanation for the commit which certifies that you wrote it or otherwise have the right to pass it on as an open-source contribution.

Developer Certificate of Origin Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 660 York Street, Suite 102, San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Developer’s Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

An example of a valid sign-off line is:

Signed-off-by: Random J Developer <random@developer.org>

Use your real name and a valid e-mail address. Sorry, no pseudonyms or anonymous contributions are allowed.

We also require each commit be individually signed-off by their author, even when part of a larger set. You may find git commit -s useful.

Building locally

You can build IncusOS locally. Only users specifically interested in the development and testing of new IncusOS features should need to do this.

We currently only support building IncusOS in a Debian 13 environment, though other Debian releases and Debian derivatives like Ubuntu may work as well.

Begin by ensuring that the required build dependencies are installed:

sudo apt install devscripts golang-any libnbd-dev mkosi

When building locally, during the initial build various development Secure Boot certificates will be generated so the resulting build artifacts can be properly signed. This should be a transparent process, and only needs to be done once. If for some reason your development Secure Boot certificates get messed up, you can regenerate them by running:

rm -rf ./certs/ ./incus-osd/certs/files/
make generate-test-certs

From the root of the IncusOS repository, a new build can be created by running:

make

By default, the build will produce a raw image in the mkosi.output/ directory, suitable for writing to a USB stick. It is also possible to build an ISO image if you need to boot from a (virtual) CD-ROM device:

make build-iso

Testing

The recommended way to test IncusOS is running it within an Incus virtual machine. It is also possible to test IncusOS on a physical machine, but debugging and introspecting into the system state will be greatly restricted.

Note

When testing IncusOS in an Incus virtual machine, the following assumptions are made:

  • Incus is configured to run on the local machine; remote Incus servers aren’t supported

  • The Incus client has full administrative access (most commonly, your user is part of the incus-admin group)

  • The default incusbr0 network bridge exists, and will be used by the virtual machines for their network connectivity.

To support local development builds of IncusOS, a Python-based HTTP server will be started as needed to provide a very simple private images server. This local images server operates in the same way as the public Linux Containers images server; the virtual machine’s images provider will be automatically configured to check locally for any available updates.

To test a locally built raw image in an Incus virtual machine, run:

make test

To test the update process, build a new image and update to it with:

make
make test-update

A new build can also be published locally by running:

make publish-local-update

Extending the cli package

IncusOS provides a cli package which is imported by Incus, Migration Manager and Operations Center to provide an end-user command line interface to IncusOS.

When adding a new command or making some other change, it’s easy to test the changes by building a local client binary. Assuming you already have the IncusOS repository cloned in your home directory, clone the Incus repository and create a symlink to the IncusOS cli package at the root:

git clone https://github.com/lxc/incus
cd incus/
ln -s ~/incus-os/incus-osd/cli/ .

Then, update the import path of cmd/incus/admin_os.go from github.com/lxc/incus-os/incus-osd/cli to github.com/lxc/incus/v7/cli.

Finally, build the local Incus client:

go build ./cmd/incus/

You can now test your new command or other changes: ./incus admin os ...

Debugging

Note

Running commands or opening a shell on an IncusOS server is only possible when run as an Incus virtual machine and requires fully enabling incus-agent support. Be aware that this will cause the system to report a degraded security state via the API and an on-screen message. This is because running arbitrary commands within the virtual machine can make changes outside of the control of IncusOS.

To fully enable incus-agent support in the virtual machine, run the following command and then restart the virtual machine.

incus config set <vm> systemd.credential.fully-enable-incus-agent=true

When IncusOS is run in an Incus virtual machine, it is possible to exec into the running system to facilitate debugging of the system:

incus exec test-incus-os bash

You can also easily side-load a custom incus-osd binary into the virtual machine. Execution from the root disk isn’t allowed, so a memory file system is required:

incus exec test-incus-os -- mkdir -p /root/dev/
incus exec test-incus-os -- mount -t tmpfs tmpfs /root/dev/

Once that’s in place, you can build the new binary:

cd ./incus-osd/
go build ./cmd/incus-osd/

And finally put it in place and have the system run it:

incus exec test-incus-os -- umount -l /usr/local/bin/incus-osd || true
incus exec test-incus-os -- rm -f /root/dev/incus-osd
incus file push ./incus-osd test-incus-os/root/dev/
incus exec test-incus-os -- mount -o bind /root/dev/incus-osd /usr/local/bin/incus-osd
incus exec test-incus-os -- pkill -9 incus-osd

Those last two steps can be repeated every time you want to build and run a new binary. The first step must be run every time the system is restarted.

When debugging, it’s a good idea to install the debug application which contains a variety of useful tools, including a basic text editor (nano).

incus exec test-incus-os bash
curl --unix-socket /run/incus-os/unix.socket socket/1.0/applications -X POST -d '{"name": "debug"}'