Skip to content

Commit 8553d32

Browse files
hanthorhanthor
committed
docs: Add build pipeline guide and remove openQA integration from the stable release workflow.
1 parent 3a9f5ca commit 8553d32

File tree

3 files changed

+115
-94
lines changed

3 files changed

+115
-94
lines changed

‎.github/workflows/release-stable.yml‎

Lines changed: 0 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -93,50 +93,10 @@ jobs:
9393
aws-region: us-east-1
9494

9595
- name: Upload to S3
96-
9796
run: |
98-
9997
aws s3 cp output/qcow2/disk.qcow2 s3://${{ secrets.S3_BUCKET }}/tunaos-${{ github.ref_name }}.qcow2
100-
10198
echo "IMAGE_URL=https://${{ secrets.S3_BUCKET }}.s3.amazonaws.com/tunaos-${{ github.ref_name }}.qcow2" >> $GITHUB_ENV
10299
103-
104-
- name: Setup openQA CLI
105-
106-
run: |
107-
108-
sudo apt-get update && sudo apt-get install -y jq
109-
110-
# Installing openQA client (example, might need specific repo or container)
111-
112-
# For now, assuming we can run it via container or it's available.
113-
114-
# Let's use a container for the CLI to be safe.
115-
116-
echo "alias openqa-cli='podman run --rm \
117-
118-
-e OPENQA_API_KEY=${{ secrets.OPENQA_API_KEY }} \
119-
120-
-e OPENQA_API_SECRET=${{ secrets.OPENQA_API_SECRET }} \
121-
122-
-e OPENQA_HOST=${{ secrets.OPENQA_HOST }} \
123-
124-
registry.opensuse.org/devel/openqa/containers/openqa_client:latest openqa-cli'" >> ~/.bashrc
125-
126-
source ~/.bashrc
127-
128-
129-
130-
- name: Run openQA Test
131-
132-
run: |
133-
134-
# Source bashrc to get the alias
135-
136-
source ~/.bashrc
137-
138-
./scripts/openqa-trigger.sh "${{ env.IMAGE_URL }}" "${{ github.ref_name }}"
139-
140100
- name: Promote to Stable
141101
if: success()
142102
run: |

‎docs/build-pipeline.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# TunaOS Build Pipeline Guide
2+
3+
This document provides a comprehensive overview of the CI/CD pipeline for TunaOS. The pipeline is designed to be automated, robust, and secure, moving images through a defined promotion strategy from `next` to `testing` to `stable`.
4+
5+
## 🏗️ Architecture Overview
6+
7+
The pipeline consists of three main stages, corresponding to the three channels:
8+
9+
1. **Next (`:next`)**: The bleeding edge. Built frequently (on push to main or schedule).
10+
2. **Testing (`:testing`)**: The candidate for release. Promoted weekly after passing automated QA.
11+
3. **Stable (`:stable`)**: The official release. Promoted from testing via Git tags.
12+
13+
### Concepts
14+
15+
- **Variants**: Different OS bases.
16+
- `albacore` (AlmaLinux)
17+
- `yellowfin` (AlmaLinux Kitten)
18+
- **Flavors**: Different package sets.
19+
- `base`: Minimal OS.
20+
- `dx`: Developer Experience (includes dev tools).
21+
- `gdx`: Graphical Developer Experience (includes desktop environment).
22+
23+
---
24+
25+
## 🔄 Workflows
26+
27+
### 1. Build Next Image (`build-next.yml`)
28+
29+
This is the primary build workflow.
30+
31+
- **Triggers**:
32+
- Push to `main`.
33+
- Schedule (Daily).
34+
- Manual `workflow_dispatch`.
35+
- **Process**:
36+
1. **Matrix Generation**: Dynamically generates a build matrix for all Variant/Flavor combinations.
37+
2. **Build**: Uses `reusable-build-image.yml` to build the container images.
38+
3. **Push**: Pushes images to GHCR with the `:next` tag.
39+
- **Key Features**:
40+
- **Chaining**: Builds `base` first, then uses it as the base for `dx`, and `dx` for `gdx`.
41+
42+
### 2. Pull Request Checks (`reusable-build-image.yml`)
43+
44+
When a Pull Request is opened, the build workflow runs in a special mode.
45+
46+
- **Triggers**: Pull Request events.
47+
- **Process**:
48+
1. Builds the image from the PR code.
49+
2. **Image Diff**: Pulls the current `:next` image and compares it with the PR image.
50+
3. **Reporting**: Posts a comment on the PR detailing:
51+
- Added/Removed/Upgraded RPM packages.
52+
- File changes in `/usr` and `/etc`.
53+
54+
### 3. Promote to Testing (`promote-to-testing.yml`)
55+
56+
This workflow manages the promotion from `next` to `testing`.
57+
58+
- **Triggers**:
59+
- Schedule (Weekly, e.g., Mondays).
60+
- Manual `workflow_dispatch`.
61+
- **Process**:
62+
1. **Candidate Selection**: Identifies the latest successful `build-next` run.
63+
2. **QA & Verification**:
64+
- **SBOM**: Generates a Software Bill of Materials using `syft`.
65+
- **QEMU Boot Test**: Builds a QCOW2 disk image from the container and boots it in QEMU to verify system integrity.
66+
3. **Manual Gate**: Pauses for approval in the `manual-approval` Environment.
67+
4. **Promotion**: Upon approval, retags the specific image digest to `:testing`.
68+
5. **Summary**: Outputs a summary of promoted images.
69+
70+
### 4. Release Stable (`release-stable.yml`)
71+
72+
This workflow handles the final release.
73+
74+
- **Triggers**:
75+
- Push of a tag matching `*-YYYYMMDD.x` (e.g., `albacore-20251126.0`).
76+
- **Process**:
77+
1. **Validation**: Parses the tag to identify the Variant/Flavor.
78+
2. **Artifact Generation**: Builds a QCOW2 disk image from the `:testing` image.
79+
3. **Upload**: Uploads the QCOW2 to S3.
80+
4. **Promotion**: Retags the `:testing` image to `:stable` and the versioned tag (e.g., `:20251126.0`).
81+
82+
---
83+
84+
## 🛠️ Scripts & Tools
85+
86+
The pipeline relies on several helper scripts in the `scripts/` directory:
87+
88+
- **`diff-images.sh`**: Compares two container images and outputs a Markdown report of RPM and file differences. Used in PR checks.
89+
- **`build-bootc-diskimage.sh`**: A wrapper around `bootc-image-builder` to generate disk images (QCOW2, ISO, etc.) from container images. Requires privileged mode.
90+
- **`qemu-test.sh`**: Boots a QCOW2 image in QEMU and waits for the SSH port to become active, verifying the image is bootable.
91+
92+
---
93+
94+
## 📖 How-To Guides
95+
96+
### How to Manually Trigger a Build
97+
1. Go to **Actions** tab in GitHub.
98+
2. Select **Build Next Image**.
99+
3. Click **Run workflow**.
100+
4. Optionally select specific Variants or Flavors.
101+
102+
### How to Approve a Promotion
103+
1. When `promote-to-testing` runs, it will pause at the "Promote to Testing" job.
104+
2. Click **Review deployments**.
105+
3. Check the **Promotion Candidate** summary in the workflow run.
106+
4. Click **Approve and deploy**.
107+
108+
### How to Cut a Stable Release
109+
1. Ensure the `:testing` image is the one you want to release.
110+
2. Create and push a git tag:
111+
```bash
112+
git tag albacore-20251126.0
113+
git push origin albacore-20251126.0
114+
```
115+
3. The `release-stable` workflow will trigger automatically.

‎scripts/openqa-trigger.sh‎

Lines changed: 0 additions & 54 deletions
This file was deleted.

0 commit comments

Comments
 (0)