gh-ryanbreen-breenix-breenix-ci/skills/breenix-github-workflow-authoring/references/breenix-ci-patterns.md

Breenix CI/CD Patterns Reference

Core Requirements

Rust Toolchain

• Nightly version: nightly-2025-06-24 (pinned for consistency)
• Components: rust-src, llvm-tools-preview
• Optional: clippy for code quality checks
• Target: x86_64-unknown-none for kernel builds

System Dependencies

sudo apt-get update
sudo apt-get install -y \
  qemu-system-x86 \
  qemu-utils \
  ovmf \
  mtools \
  dosfstools \
  xorriso \
  nasm \
  lld

Build Tools

• llvm-tools: Add to PATH: $(rustc --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/bin
• ld.lld: Required for linking userspace binaries

Breenix-Specific Build Patterns

Userspace Binary Building

Must be done before kernel tests that execute userspace code:

export PATH="$PATH:$(rustc --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/bin"
cd userspace/tests
./build.sh

Kernel Build with Testing Features

cargo run --release --features testing --bin qemu-uefi -- -serial stdio -display none

Using xtask for Tests

Breenix uses the xtask pattern for complex test workflows:

cargo run -p xtask -- ring3-smoke
cargo run -p xtask -- ring3-enosys

Timeout Strategies

Typical Timeouts

• Code quality checks: 10-15 minutes
• Build + simple tests: 20 minutes
• Full integration tests: 45 minutes
• CI environment: Add 2-3x overhead for slower runners

QEMU Execution Timeouts

• Local: 30 seconds for smoke tests
• CI: 60 seconds (logs are verbose, builds are slower)
• File creation: 30s local, 300s (5 min) CI

Caching Strategies

Cargo Cache

- uses: actions/cache@v4
  with:
    path: |
      ~/.cargo/registry
      ~/.cargo/git
      target
    key: cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}

Benefits

• Reduces build time from ~10 minutes to ~2 minutes
• Especially important for dependency-heavy builds
• Invalidates on Cargo.lock changes

Test Execution Patterns

Serial Output to File

- name: Run test
  run: cargo run -p xtask -- ring3-smoke

Internally, xtask uses:

-serial file:target/xtask_ring3_smoke_output.txt

Log Artifact Upload

- name: Upload logs
  if: always()  # Run even on failure
  uses: actions/upload-artifact@v4
  with:
    name: breenix-logs
    path: |
      logs/*.log
      target/xtask_ring3_smoke_output.txt
    if-no-files-found: ignore
    retention-days: 7

Success Detection Patterns

Looking for Signals in Output

// Check for userspace execution evidence
if contents.contains("USERSPACE OUTPUT: Hello from userspace") ||
   (contents.contains("Context switch: from_userspace=true, CS=0x33") &&
    contents.contains("restore_userspace_thread_context: Restoring thread"))

Common Success Signals

• USERSPACE OUTPUT: Hello from userspace
• 🎯 KERNEL_POST_TESTS_COMPLETE 🎯
• Context switch: from_userspace=true, CS=0x33
• ✅ SUCCESS: Userspace syscall completed

Common Failure Patterns

• DOUBLE FAULT - Page table or stack issues
• PAGE FAULT - Memory mapping problems
• Timeout - Test hung or infinite loop
• Build errors - Missing dependencies or wrong toolchain

Workflow Triggers

Current Patterns

# Run on all branches
on:
  push:
    branches: [ "**" ]
  pull_request:

# Run only manually (for expensive tests)
on:
  workflow_dispatch:

# Run on specific paths
on:
  push:
    paths:
      - 'kernel/**'
      - '.github/workflows/code-quality.yml'

Environment Variables

Useful Vars

env:
  RUST_BACKTRACE: full
  CARGO_UNSTABLE_BINDEPS: true  # For build dependencies
  CI: true  # Detection for different timeouts

Common Workflow Structure

name: Test Name
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-22.04
    timeout-minutes: 20

    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: nightly-2025-06-24
          override: true
          target: x86_64-unknown-none
          components: rust-src, llvm-tools-preview

      - name: Cache cargo
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: cargo-${{ runner.os }}-${{ hashFiles('**/Cargo.lock') }}

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y qemu-system-x86 ovmf nasm

      - name: Build userspace tests
        run: |
          export PATH="$PATH:$(rustc --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/bin"
          cd userspace/tests
          ./build.sh

      - name: Run test
        run: cargo run -p xtask -- ring3-smoke

      - name: Upload logs
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-logs
          path: |
            logs/*.log
            target/xtask_*_output.txt
          retention-days: 7

Debugging Failed CI

Step 1: Check Logs

Download artifacts from the Actions run, look for:

• Compilation errors (wrong Rust version, missing components)
• Missing system dependencies (QEMU, OVMF, etc.)
• Timeout vs actual kernel panic

Step 2: Reproduce Locally

# Use exact same commands as CI
cargo run -p xtask -- ring3-smoke

Step 3: Common Fixes

• Rust version mismatch: Update toolchain specification
• Missing QEMU: Add to system dependencies
• Timeout: Increase timeout or optimize test
• Userspace not built: Add userspace build step before kernel test
• Cache corruption: Clear cache or change cache key