Ensure GitHub Pages Deployment Updates During Release Process

[stphung]

Overview

The current release process creates tagged releases with downloadable assets but may not properly update the GitHub Pages deployment to reflect the latest release version. We need to ensure that when releases are created, the web build deployed to GitHub Pages is also updated to match the released version.

Current State Analysis

✅ Working Release Pipeline

• Integrated Workflow: Single CI/CD handles building, versioning, and releasing
• Automatic Versioning: Patch increments (v1.1.1 → v1.1.2) based on commits
• Multi-Platform Builds: Linux, Windows, Android, Web built in parallel
• Release Creation: Automated GitHub releases with downloadable archives

✅ Working GitHub Pages Deployment

• Web Export: Godot web build deployed to GitHub Pages
• Main Branch Deployment: Updates on every push to main
• Live URL: Available at https://stphung.github.io/continuum/

❓ Potential Issue: Version Synchronization

Current Web Deployment Trigger:

# From .github/workflows/ci-cd.yml
- name: Deploy to GitHub Pages
  uses: actions/deploy-pages@v4
  if: github.ref == 'refs/heads/main'  # Only deploys on main branch pushes

Release Process Trigger:

# Auto-version runs after successful builds
auto-version:
  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
  needs: [export-linux, export-windows, export-web, export-android]

# Release creation uses the new tag
create-release:
  if: (startsWith(github.ref, 'refs/tags/v')) || (needs.auto-version.outputs.new_tag != '')

Potential Gap:

• GitHub Pages deploys during initial main branch push
• Auto-versioning creates new tag and release
• Risk: Pages deployment may not reflect the final tagged version

Investigation Required

Timing Analysis

• Workflow Sequence: Verify Pages deployment happens before or after auto-versioning
• Asset Consistency: Confirm web build in release archive matches Pages deployment
• Version Display: Check if deployed web app shows correct version information
• Cache Behavior: Verify Pages deployment caches are properly invalidated

Current Workflow Flow

Push to Main → [Build All Platforms] → [Deploy to Pages] → [Auto-Version] → [Create Release]
                                   ↑
                            This timing may be the issue

Desired Workflow Flow

Push to Main → [Build All Platforms] → [Auto-Version] → [Deploy Latest to Pages] → [Create Release]
                                                     ↑
                                          Deploy versioned build to Pages

Requirements

Core Synchronization

Version-Aware Pages Deployment

• GitHub Pages should deploy the exact same web build included in releases
• Pages deployment should happen after auto-versioning (if version changed)
• Web app should display current version information
• Pages cache should be invalidated when new versions are deployed

Consistent User Experience

• Web app at https://stphung.github.io/continuum/ matches latest release
• Download links and version info are synchronized
• Users get the same experience whether playing online or downloading

Release Process Integration

• Pages deployment integrated into release workflow
• Clear indication when Pages has been updated with new version
• Rollback capability if deployment issues occur

Advanced Features

Version Information Display

• Web app shows current version in UI
• Build timestamp and commit information
• Link to corresponding GitHub release
• Clear indication of latest features

Deployment Verification

• Automated testing of Pages deployment
• Verification that web app loads and functions correctly
• Performance validation for web build
• Cross-browser compatibility checks

Technical Implementation

Option 1: Sequential Deployment (RECOMMENDED)

Modify CI/CD Workflow Order:

jobs:
  # ... existing build jobs ...

  auto-version:
    # ... existing auto-version job ...

  deploy-pages:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-22.04
    if: github.ref == 'refs/heads/main'
    needs: [export-web, auto-version]  # Wait for versioning
    permissions:
      contents: read
      pages: write
      id-token: write
    steps:
      - name: Download Web Build
        uses: actions/download-artifact@v4
        with:
          name: web
          path: ./web-build

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload to GitHub Pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./web-build

      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4

  create-release:
    needs: [export-linux, export-windows, export-web, export-android, auto-version, deploy-pages]
    # ... existing release job ...

Option 2: Conditional Deployment

Deploy Only When Version Changes:

deploy-pages:
  name: Deploy to GitHub Pages
  if: |
    github.ref == 'refs/heads/main' && 
    (needs.auto-version.outputs.new_tag != '' || github.event_name == 'release')
  needs: [export-web, auto-version]

Option 3: Dual Deployment Strategy

Immediate + Release Deployment:

# Keep existing immediate deployment for development
deploy-pages-dev:
  name: Deploy to Pages (Development)
  if: github.ref == 'refs/heads/main' && needs.auto-version.outputs.new_tag == ''

# Add release deployment for tagged versions  
deploy-pages-release:
  name: Deploy to Pages (Release)
  if: needs.auto-version.outputs.new_tag != ''
  needs: [export-web, auto-version]

Investigation Tasks

Phase 1: Current State Analysis (HIGH PRIORITY)

• Monitor Release Workflow: Track next release creation and Pages deployment timing
• Version Verification: Check if current Pages deployment matches latest release
• Asset Comparison: Compare web build in release archive vs Pages deployment
• User Experience Audit: Verify consistency between online and downloadable versions

Phase 2: Implementation Planning (MEDIUM PRIORITY)

• Workflow Modification: Choose optimal deployment strategy
• Version Display: Add version information to web app UI
• Testing Strategy: Plan validation of Pages deployment integration
• Rollback Planning: Design recovery process for failed deployments

Phase 3: Enhanced Integration (LOW PRIORITY)

• Deployment Verification: Automated testing of Pages updates
• Performance Monitoring: Track Pages deployment performance
• User Analytics: Monitor web app usage and version adoption
• Documentation: Update release process documentation

Success Criteria

Phase 1 Success

• Timing Verification: Understand current Pages deployment timing relative to releases
• Version Consistency: Confirm Pages deployment matches release archives
• Issue Identification: Clear understanding of any synchronization gaps
• Impact Assessment: Determine if changes are needed

Phase 2 Success

• Synchronized Deployment: Pages updates automatically with new releases
• Version Display: Web app shows current version information
• Consistent Experience: Online and downloadable versions match
• Reliable Process: Deployment integration works without manual intervention

Long-term Success

• Automated Validation: Deployment verification and testing
• Performance Optimization: Fast, reliable Pages deployment
• User Experience: Seamless experience across all access methods
• Maintenance: Sustainable, well-documented process

Risk Assessment

Low Risk

• Current Functionality: Existing Pages deployment and releases work independently
• Gradual Implementation: Can test and validate changes incrementally
• Rollback Capability: Easy to revert workflow changes if issues occur

Medium Risk

• Deployment Timing: Changes might affect release creation timing
• Cache Issues: Pages cache might not properly invalidate with new deployments
• User Experience: Brief inconsistency during deployment transitions

Mitigation Strategies

• Thorough Testing: Validate workflow changes on non-production branches
• Monitoring: Track deployment success and timing
• User Communication: Clear documentation of any temporary inconsistencies
• Fallback Plan: Maintain ability to manually deploy Pages if automated process fails

Dependencies

Internal Dependencies

• Working Release Pipeline: Current auto-versioning and release creation
• GitHub Pages Setup: Existing Pages deployment configuration
• Web Build Quality: Stable, deployable web exports from Godot

External Dependencies

• GitHub Actions: Pages deployment actions and permissions
• GitHub Pages Service: Reliable Pages hosting and deployment
• Godot Web Export: Stable web build generation

Expected Benefits

User Experience

• ✅ Consistent Versions: Online play matches downloadable releases
• ✅ Latest Features: Web app always has newest functionality
• ✅ Clear Information: Version display helps users understand what they're playing
• ✅ Reliable Access: Guaranteed deployment of working versions

Development Workflow

• ✅ Automated Process: No manual Pages deployment required
• ✅ Quality Assurance: Pages deployment tied to successful release process
• ✅ Version Control: Clear tracking of what version is deployed where
• ✅ Professional Standards: Coordinated release process across all platforms

---

Priority: Medium (quality of life improvement)
Complexity: Low-Medium (workflow configuration changes)
Impact: Ensures consistent user experience across web and download platforms

Next Steps: Start with Phase 1 investigation to understand current timing and identify any existing gaps.