docs: add cosign and cleanup other info
This commit is contained in:
Benjamin Sherman
parent
78a2e68421
commit
efef8cbaa4
2 changed files with 56 additions and 18 deletions
3
.github/workflows/build.yml
vendored
3
.github/workflows/build.yml
vendored
|
|
@ -144,8 +144,7 @@ jobs:
|
|||
#- name: Sign container image
|
||||
# if: github.event_name != 'pull_request'
|
||||
# run: |
|
||||
# cosign sign -y --key env://COSIGN_PRIVATE_KEY ${{ steps.registry_case.outputs.lowercase }}/$
|
||||
{{ steps.build_image.outputs.image }}@${TAGS}
|
||||
# cosign sign -y --key env://COSIGN_PRIVATE_KEY ${{ steps.registry_case.outputs.lowercase }}/${{ steps.build_image.outputs.image }}@${TAGS}
|
||||
# env:
|
||||
# TAGS: ${{ steps.push.outputs.digest }}
|
||||
# COSIGN_EXPERIMENTAL: false
|
||||
|
|
|
|||
71
README.md
71
README.md
|
|
@ -1,43 +1,82 @@
|
|||
# ublue-custom-start
|
||||
# ublue-custom-template
|
||||
|
||||
# Purpose
|
||||
|
||||
This repository is meant to be used as a template to build your own custom Universal Blue Image. This example base template is what the Universal Blue Project uses for all of our new and existing downstream projects (Bazzite, Bluefin, and Ucore). This template includes a Containerfile and 2 Github workflows (one for building the container and one for building an installation ISO from the container file) that will work immediately out of the box as soon as you enable the workflow in your repository.
|
||||
This repository is meant to be a template for building your own custom Universal Blue image. This template is the recommended way to make customizations to any image published by the Universal Blue Project:
|
||||
- [Aurora](https://getaurora.dev/)
|
||||
- [Bazzite](https://bazzite.gg/)
|
||||
- [Bluefin](https://projectbluefin.io/)
|
||||
- [uCore](https://projectucore.io/)
|
||||
- [main](https://github.com/ublue-os/main/)
|
||||
- [hwe](https://github.com/ublue-os/hwe/)
|
||||
|
||||
This template includes a Containerfile and a Github workflow for building the container image. As soon as the workflow is enabled in your repository, it will build the container image and push it to the Github Container Registry.
|
||||
|
||||
# Prerequisites
|
||||
|
||||
Working knowledge in the following topics:
|
||||
|
||||
- Containers
|
||||
- Resources:
|
||||
- https://www.youtube.com/watch?v=SnSH8Ht3MIc
|
||||
- https://www.mankier.com/5/Containerfile
|
||||
- https://www.youtube.com/watch?v=SnSH8Ht3MIc
|
||||
- https://www.mankier.com/5/Containerfile
|
||||
- rpm-ostree
|
||||
- Resources:
|
||||
- https://coreos.github.io/rpm-ostree/
|
||||
- https://coreos.github.io/rpm-ostree/container/
|
||||
- Fedora Silverblue (and other Fedora Atomic variants)
|
||||
- Resources:
|
||||
- https://docs.fedoraproject.org/en-US/fedora-silverblue/
|
||||
- https://docs.fedoraproject.org/en-US/fedora-silverblue/
|
||||
- Github Workflows
|
||||
- Resources:
|
||||
- https://docs.github.com/en/actions/using-workflows
|
||||
- https://docs.github.com/en/actions/using-workflows
|
||||
|
||||
# How to Use
|
||||
|
||||
## Template
|
||||
|
||||
Since this is a template repository, you can select `Use this Template` and create a new repository from it. To enable the workflows, you will need to go the actions tab of the new repository and enable the workflows.
|
||||
Select `Use this Template` and create a new repository from it. To enable the workflows, you will need to go the `Actions` tab of the new repository and click to enable workflows.
|
||||
|
||||
## Containerfile
|
||||
|
||||
This is the main file used to customize the base image you are using. There are several examples of how to add layered rpm-ostree packages
|
||||
This file defines the operations used to customize the selected image. It contains examples of possible modifications, including how to:
|
||||
- change the upstream from which the custom image is derived
|
||||
- add additional RPM packages
|
||||
- add binaries as a layer from other images
|
||||
- modify system files (like /etc/systemd/system.conf)
|
||||
|
||||
## Workflows
|
||||
|
||||
### build.yml
|
||||
|
||||
This workflow creates your custom OCI container and publishes it to Github Container Registry.
|
||||
This workflow creates your custom OCI image and publishes it to the Github Container Registry (GHCR).
|
||||
|
||||
### build_iso.yml
|
||||
#### Container Signing
|
||||
|
||||
This workflow creates an ISO and uploads it as a Github Artifact. (For examples on how to upload to a cloud registry, feel free to review Bazzite or Bluefin's workflow for uploading to R2.)
|
||||
Container signing is important for end-user security and is enabled on all Universal Blue images. It is recommended you set this up, and by default the image builds *will fail* if you don't.
|
||||
|
||||
This provides users a method of verifying the image.
|
||||
|
||||
1. Install the [cosign CLI tool](https://edu.chainguard.dev/open-source/sigstore/cosign/how-to-install-cosign/#installing-cosign-with-the-cosign-binary)
|
||||
|
||||
2. Run inside your repo folder:
|
||||
|
||||
```bash
|
||||
cosign generate-key-pair
|
||||
```
|
||||
|
||||
|
||||
- Do NOT put in a password when it asks you to, just press enter. The signing key will be used in GitHub Actions and will not work if it is encrypted.
|
||||
|
||||
> [!WARNING]
|
||||
> Be careful to *never* accidentally commit `cosign.key` into your git repo.
|
||||
|
||||
3. Add the private key to GitHub
|
||||
|
||||
- This can also be done manually. Go to your repository settings, under Secrets and Variables -> Actions
|
||||
|
||||
Add a new secret and name it `SIGNING_SECRET`, then paste the contents of `cosign.key` into the secret and save it. Make sure it's the .key file and not the .pub file. Once done, it should look like this:
|
||||
|
||||
|
||||
- (CLI instructions) If you have the `github-cli` installed, run:
|
||||
|
||||
```bash
|
||||
gh secret set SIGNING_SECRET < cosign.key
|
||||
```
|
||||
|
||||
4. Commit the `cosign.pub` file into your git repository
|
||||
|
|
|
|||
Loading…
Reference in a new issue