Skip to content

How to set up a new repository

This guide shows you how to set up a new repository for building custom images based on blue-build/template, which provides a minimal example configuration along with GitHub Actions to build your image and a netinstall ISO of it. Updates to BlueBuild in your repository will be handled by the Pull and Dependabot apps, which are set up in the template.

Automatic setup using the web interface

The automatic setup will apply some default configuration based on your preferences. This approach currently requires running a podman command locally, so make sure you have the program installed before proceeding.

The current web interface is a placeholder and will be rewritten. No new features will be added for the time being, but bugs will be fixed if reported. The GitHub repository is blue-build/images-website.

  1. Open https://ublue-images-demo.netlify.app/.
  2. Press “Pick or create an image”.
  3. Pick your preferred desktop environment and whether you want Nvidia drivers.
  4. On the next screen, press “Continue to creating your own”.
  5. Choose a name and description for your image. These details can be changed later.
  6. Log in with GitHub. The GitHub API will be used to create a new repository for you and modify it contents.
  7. Press “Create repo”. A log box will pop up below the button. It might say “repo creation failed” while succeeding, this is a harmless known issue.
  8. Scroll down to the container signing step and follow instructions, then press “Submit”. Setting up container signing is important for security, and builds will fail without a proper signing setup.
  9. You’re done! You can now open config/recipe.yml and start customizing! The reference section of the documentation is your friend here.
  10. Once the first image is built, make it public by following the steps [here]. You wont be able to rebase to your image without doing this.

Manual setup with git and cosign

The manual setup is useful if the other methods aren’t working correctly or if you want to learn what they do. This approach requires git and either cosign or skopeo, so make sure the necessary programs are installed before proceeding.

  1. Open blue-build/template.
  2. Press “Use this template” and create a new repository.
  3. Set up container signing, then come back to this guide.
  4. Change the name: in config/recipe.yml and commit your changes. You can also apply some initial customizations here.
  5. Open the Actions tab of your repository and make sure GitHub Actions are enabled.
  6. Change all references to blue-build/template in the README.md to the details of your repository or custom image and commit your changes. You should also change the title and the short description below it so that people stumbling on your repository know what they are looking at.
  7. You’re done! You can now open config/recipe.yml and start customizing! The reference section of the documentation is your friend here.
  8. Once the first image is built, make it public by following the steps here. You wont be able to rebase to your image without doing this.