zosbuilder/GITHUB_ACTIONS.md

# GitHub Actions Integration

## Rootless Container Setup

### Prerequisites

GitHub Actions runners need proper subuid/subgid configuration for rootless containers:

```yaml
name: Build Zero OS Initramfs

on:
  push:
    branches: [ main, development ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
    
    - name: Setup rootless containers
      run: |
        # Configure subuid/subgid for runner user
        echo "runner:100000:65536" | sudo tee -a /etc/subuid
        echo "runner:100000:65536" | sudo tee -a /etc/subgid
        
        # Install container runtime
        sudo apt-get update
        sudo apt-get install -y podman
        
        # Verify rootless setup
        podman system info
    
    - name: Install build dependencies
      run: |
        sudo apt-get install -y \
          build-essential \
          rustc \
          cargo \
          upx-ucl \
          binutils \
          git \
          wget \
          qemu-system-x86 \
          cloud-hypervisor
    
    - name: Setup Rust musl target
      run: |
        rustup target add x86_64-unknown-linux-musl
        sudo apt-get install -y musl-tools
    
    - name: Build initramfs
      run: |
        chmod +x scripts/build.sh
        ./scripts/build.sh
    
    - name: Test with QEMU
      run: |
        chmod +x scripts/test.sh
        ./scripts/test.sh --qemu
    
    - name: Upload artifacts
      uses: actions/upload-artifact@v4
      with:
        name: zero-os-initramfs
        path: |
          dist/vmlinuz.efi
          dist/initramfs.cpio.xz
        retention-days: 30
    
    - name: Create release
      if: github.ref == 'refs/heads/main'
      uses: softprops/action-gh-release@v1
      with:
        tag_name: v${{ github.run_number }}
        files: |
          dist/vmlinuz.efi
          dist/initramfs.cpio.xz
```

## Container Caching Strategy

### Builder Container Reuse

```yaml
    - name: Cache builder container
      uses: actions/cache@v4
      with:
        path: ~/.local/share/containers
        key: ${{ runner.os }}-containers-${{ hashFiles('Dockerfile') }}
        restore-keys: |
          ${{ runner.os }}-containers-
    
    - name: Build or reuse container
      run: |
        if ! podman image exists zero-os-builder:latest; then
          podman build -t zero-os-builder:latest .
        fi
```

### Component Source Caching

```yaml
    - name: Cache Rust components
      uses: actions/cache@v4
      with:
        path: |
          components/
          ~/.cargo/registry
          ~/.cargo/git
        key: ${{ runner.os }}-rust-${{ hashFiles('config/sources.conf') }}
        restore-keys: |
          ${{ runner.os }}-rust-
```

## Security Considerations

### Rootless Execution Benefits

1. **No privileged access required**
2. **User namespace isolation**
3. **Reduced attack surface**
4. **Compatible with GitHub Actions security model**

### Container Security

```bash
# Use minimal Alpine base
FROM alpine:3.22

# Create non-root user
RUN adduser -D -s /bin/sh builder

# Install only required packages
RUN apk add --no-cache \
    build-base \
    rust \
    cargo \
    upx \
    git \
    wget

# Switch to non-root user
USER builder
WORKDIR /home/builder
```

## Parallel Builds

### Matrix Strategy for Testing

```yaml
strategy:
  matrix:
    test_runner: [qemu, cloud-hypervisor]
    optimization: [size, speed]

steps:
- name: Build with optimization
  run: |
    export OPTIMIZATION_TARGET="${{ matrix.optimization }}"
    ./scripts/build.sh
    
- name: Test with runner
  run: |
    ./scripts/test.sh --runner ${{ matrix.test_runner }}
```

## Environment Variables

### Build Configuration

```yaml
env:
  ALPINE_VERSION: "3.22"
  KERNEL_VERSION: "6.8.8" 
  RUST_TARGET: "x86_64-unknown-linux-musl"
  OPTIMIZATION_LEVEL: "max"
  CONTAINER_REGISTRY: "ghcr.io"
```

### Secrets Management

```yaml
    - name: Login to container registry
      uses: docker/login-action@v3
      with:
        registry: ghcr.io
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}
```

## Troubleshooting

### Common Issues

1. **Subuid/subgid not configured**
   ```bash
   # Solution: Configure in setup step
   echo "runner:100000:65536" | sudo tee -a /etc/subuid
   ```

2. **Container runtime not accessible**
   ```bash
   # Solution: Use rootless podman
   sudo apt-get install -y podman
   ```

3. **Rust musl target missing**
   ```bash
   # Solution: Add target and tools
   rustup target add x86_64-unknown-linux-musl
   sudo apt-get install -y musl-tools
   ```

4. **UPX compression fails**
   ```bash
   # Solution: Check UPX version compatibility
   upx --version
   upx --best --force binary || echo "UPX failed, continuing"
   ```

## Performance Optimization

### Build Time Reduction

1. **Container layer caching**
2. **Rust dependency caching**
3. **Parallel component builds**
4. **Incremental compilation**

### Resource Usage

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    
    steps:
    - name: Configure build resources
      run: |
        # Limit parallel jobs based on available cores
        export MAKEFLAGS="-j$(nproc)"
        export CARGO_BUILD_JOBS="$(nproc)"