Implement macOS Build and Release Pipeline

[stphung]

Overview

Continuum needs a professional macOS build and release pipeline to distribute the game to Mac users. This includes automated builds, code signing, notarization, and deployment through GitHub Releases.

Current State

• Development builds run locally via Godot editor
• No automated build pipeline for distribution
• Missing macOS-specific optimizations and packaging
• No code signing or notarization for security compliance
• Manual export process without CI/CD integration

Requirements

Core Build System Integration

SCons Build System Enhancement

• Extend existing SCons build system with macOS export targets
• Add scons build-mac-dev and scons build-mac-release commands
• Integrate with existing validation and testing pipeline
• Support for different macOS architectures (Intel x64, Apple Silicon arm64)

Godot Export Configuration

• Configure macOS export template with optimized settings
• Set up proper bundle identifier and app metadata
• Configure icon and launch screen assets
• Optimize for macOS performance characteristics

Code Signing and Security

Apple Developer Integration

• Apple Developer account setup and certificate management
• Code signing certificate integration in CI/CD
• Automatic notarization through Apple's notary service
• Gatekeeper compliance verification

Security Best Practices

• Hardened runtime configuration
• Entitlements configuration for required permissions
• Bundle verification and integrity checks
• App sandbox compatibility (if applicable)

Release Automation

GitHub Actions CI/CD Integration

• Automated builds triggered by version tags
• Multi-architecture builds (x64 + arm64 universal binary)
• Automated testing on macOS runners before release
• Integration with existing CI/CD workflow

GitHub Releases Integration

• Automatic release creation for version tags
• Asset upload automation (DMG, ZIP packages)
• Release notes generation from commit history
• Semantic versioning compliance

Distribution Packaging

macOS Package Formats

• DMG disk image creation with custom background/layout
• ZIP archive for direct download
• App bundle verification and testing
• Installation instructions and documentation

Package Optimization

• Asset compression and optimization for distribution
• Unused asset removal for release builds
• Bundle size optimization
• Launch time optimization

Technical Implementation

SCons Build System Extension

New Build Targets

# site_scons/macos_build.py
def build_macos_release(env):
    """Build optimized macOS release with code signing"""
    return env.GodotExport(
        platform='macos',
        export_preset='macOS Release',
        output_path='builds/macOS/Continuum.app',
        sign=True,
        notarize=True
    )

def build_macos_dev(env):
    """Build development macOS version"""
    return env.GodotExport(
        platform='macos',
        export_preset='macOS Debug',
        output_path='builds/macOS/Continuum-dev.app'
    )

Integration with Existing System

# New SCons commands to add
scons build-mac-release    # Build signed, notarized release
scons build-mac-dev        # Build development version  
scons package-mac          # Create DMG/ZIP packages
scons validate-mac         # Test macOS build integrity

GitHub Actions Workflow

Automated Build Pipeline

# .github/workflows/macos-release.yml
name: macOS Release Build

on:
  push:
    tags: ['v*']
  
jobs:
  build-macos:
    runs-on: macos-latest
    steps:
      - name: Build and Sign
        run: scons build-mac-release
      - name: Notarize
        env:
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
        run: scons notarize-mac
      - name: Create Release
        uses: actions/create-release@v1
        with:
          files: builds/macOS/*

Code Signing Configuration

Certificate Management

# Secure certificate storage in GitHub Secrets
APPLE_CERTIFICATE_P12: Base64 encoded certificate
APPLE_CERTIFICATE_PASSWORD: Certificate password
APPLE_ID: Apple ID for notarization
APPLE_PASSWORD: App-specific password
APPLE_TEAM_ID: Developer team identifier

Entitlements Configuration

<!-- Continuum.entitlements -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.cs.allow-jit</key>
    <true/>
    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
    <true/>
</dict>
</plist>

Distribution Package Creation

DMG Creation Script

# scripts/create_dmg.sh
create-dmg \
  --volname "Continuum" \
  --volicon "assets/icon.icns" \
  --window-pos 200 120 \
  --window-size 600 300 \
  --icon-size 100 \
  --icon "Continuum.app" 175 120 \
  --hide-extension "Continuum.app" \
  --app-drop-link 425 120 \
  "Continuum-${VERSION}.dmg" \
  "builds/macOS/"

Integration Points

Existing Systems

• SCons Build System: Extend with macOS-specific targets
• Testing Pipeline: Run macOS tests before release builds
• Asset Pipeline: Optimize assets for macOS distribution
• CI/CD Workflow: Integrate with existing GitHub Actions

New Dependencies

• Godot macOS export templates
• Apple Developer certificates
• DMG creation tools (create-dmg)
• Notarization tools (xcrun altool or xcrun notarytool)

Testing Strategy

Build Verification

• Test builds on different macOS versions (macOS 11+)
• Verify both Intel and Apple Silicon compatibility
• Test installation process on fresh systems
• Validate code signature and notarization status

Quality Assurance

• Run full test suite on macOS builds
• Performance testing on different Mac hardware
• Graphics and audio system validation
• Input system testing (keyboard, trackpad, mouse)

Security Validation

• Gatekeeper compatibility verification
• Malware scanning and security analysis
• App sandbox compatibility (if enabled)
• Privacy permissions validation

Release Process

Version Tagging

# Create release tag
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# Triggers automated build and release

Release Validation

• Download and test release artifacts
• Verify installation on clean macOS systems
• Test core gameplay functionality
• Validate release notes and documentation

Success Criteria

1. Automation: Complete hands-off build and release process
2. Security: Properly signed and notarized macOS applications
3. Compatibility: Works on macOS 11+ across Intel and Apple Silicon
4. Quality: Release builds pass all tests and quality checks
5. Distribution: Professional DMG packages ready for distribution
6. Integration: Seamlessly integrates with existing SCons build system

Implementation Phases

Phase 1: Basic Build Pipeline (High Priority)

• SCons macOS build targets
• Basic GitHub Actions integration
• Manual code signing process

Phase 2: Automated Security (Medium Priority)

• Automated code signing in CI/CD
• Notarization integration
• Release artifact validation

Phase 3: Distribution Polish (Low Priority)

• Professional DMG creation
• Advanced packaging options
• App Store preparation (future)

Dependencies

• Apple Developer Program membership ($99/year)
• macOS GitHub Actions runners
• Godot macOS export templates
• DMG creation tools and dependencies

---

This build pipeline will enable professional distribution of Continuum on macOS with security compliance and automated quality assurance.