LanMountainDesktop/.github/WORKFLOWS_GUIDE.md

GitHub CI/CD Workflow Setup Guide

Overview

This document describes the CI/CD workflows configured for LanMountainDesktop. These workflows are designed to maintain code quality, automate testing, and streamline the release process.

Workflows

1. Build & Test (build.yml)

Trigger: Every push/PR to main branches, or manual dispatch

What it does:

• Builds both LanMountainDesktop and RecommendationBackend in Debug and Release modes
• Runs unit tests (if available)
• Uploads build artifacts for inspection
• Runs on Windows (windows-latest)

Branch Coverage: main, master, dev, develop

2. Code Quality (code-quality.yml)

Trigger: Pull requests and pushes to main branches, or manual dispatch

What it does:

• Builds projects with analysis
• Checks code formatting using dotnet format
• (Optional) Can integrate with Qodana for professional code analysis

Branch Coverage: main, master, dev, develop

Optional: Qodana Integration Uncomment the Qodana step in the workflow and add your token as a secret:

# In GitHub > Settings > Secrets > Actions
QODANA_TOKEN=your_token_here
QODANA_ENDPOINT=https://qodana.cloud

3. Release & Publish (release.yml)

Trigger: Push git tags (v1.0.0, release-1.0.0), or manual workflow dispatch

What it does:

• Builds for Windows (x64, x86) - self-contained executables
• Builds for Linux (x64) - tar.gz packages
• Builds for macOS (x64, arm64) - universal support
• Publishes optimized release builds for all platforms
• Generates GitHub Release with all platform artifacts
• Supports pre-release versions

Supported Platforms:

Platform	Architectures	Output Format	Status
Windows	x64, x86	.zip	✅ Full support
Linux	x64	.tar.gz	✅ Full support
macOS	x64, arm64 (Apple Silicon)	.tar.gz	✅ Full support

Build Scripts:

• Windows: Uses PowerShell (LanMountainDesktop\scripts\package.ps1)
• Linux/macOS: Uses Bash (scripts/build.sh)

Usage:

Create a full release for all platforms:

git tag v1.0.0
git push origin v1.0.0
# Automatically triggers Windows + Linux + macOS builds

Manual trigger with selective platforms: Go to GitHub > Actions > Release & Publish > Run workflow

• Specify version: 1.0.0
• Toggle build targets as needed:
  • ✅ Build Windows (x64/x86)
  • ✅ Build Linux (x64)
  • ✅ Build macOS (x64/arm64)
• Check pre-release option if needed

4. Issue Management (issue-management.yml)

Trigger: Daily at 1:30 AM UTC, or manual dispatch

What it does:

• Automatically marks inactive issues as "stale"
• Closes old stale issues/PRs after grace period
• Issues with need-more-info or waiting-for-response labels
• Grace period: 14 days to stale, 7 days before close
• PR grace period: 21 days to stale, 14 days before close

Repository Secrets & Configuration

To enable all workflows, configure these GitHub secrets:

Required

None - the workflows use default GitHub token

Optional (for enhanced features)

1. Qodana Integration
   • Go to GitHub Settings > Secrets > Actions
   • Add QODANA_TOKEN from https://qodana.cloud

Local Development Setup

To align with CI workflows, set up your local environment:

# Install .NET 10 SDK
# https://dotnet.microsoft.com/download/dotnet/10.0

# Restore dependencies
dotnet restore

# Build (like CI does)
dotnet build LanMountainDesktop/LanMountainDesktop.csproj
dotnet build LanMountainDesktop.RecommendationBackend/LanMountainDesktop.RecommendationBackend.csproj

# Format code locally (required by CI)
dotnet format

# Run tests
dotnet test LanMountainDesktop/LanMountainDesktop.csproj
dotnet test LanMountainDesktop.RecommendationBackend/LanMountainDesktop.RecommendationBackend.csproj

# Alternative: Use local build scripts (Linux/macOS)
./scripts/build.sh --rid linux-x64 --version 1.0.0
./scripts/build.sh --rid osx-x64 --version 1.0.0

# Or on Windows with the PowerShell script
./LanMountainDesktop/scripts/package.ps1 -RuntimeIdentifier win-x64 -Version 1.0.0

Cross-Platform Build Scripts

Linux / macOS:

# Make script executable first
chmod +x scripts/build.sh

# Build for Linux
./scripts/build.sh --rid linux-x64 --version 1.0.0

# Build for macOS x64
./scripts/build.sh --rid osx-x64 --version 1.0.0

# Build for macOS ARM64 (Apple Silicon)
./scripts/build.sh --rid osx-arm64 --version 1.0.0

# Full help
./scripts/build.sh --help

Windows:

# Using PowerShell script
.\LanMountainDesktop\scripts\package.ps1 -RuntimeIdentifier win-x64 -Version 1.0.0

# Or use dotnet directly
dotnet publish LanMountainDesktop/LanMountainDesktop.csproj `
    -c Release -r win-x64 -o ./publish/win-x64 `
    -p:PublishSingleFile=true --self-contained

Pull Request Process

1. Create a branch from dev or develop

   git checkout -b feature/your-feature
   

2. Make your changes and test locally

   dotnet build
   dotnet format  # Important!
   dotnet test
   

3. Push and create a PR

   • The PR template will guide you
   • Fill out all required sections
   • Link related issues

4. Checks will run automatically:

   • CI builds in Debug & Release
   • Code quality checks
   • Code formatting validation

5. Review and merge

   • Address any feedback
   • Wait for all checks to pass
   • Merge to dev or main as appropriate

Release Process

For Stable Releases

# On main branch
git tag v1.0.0
git push origin v1.0.0
# GitHub Actions will automatically create the release

For Pre-releases

1. Go to Actions tab
2. Select "Release & Publish" workflow
3. Click "Run workflow"
4. Enter version (e.g., 1.0.0-beta)
5. Check "Mark as pre-release"
6. Click "Run workflow"

Monitoring

Status Badge

Add to your README.md:

![Build Status](https://github.com/YOUR_ORG/LanMountainDesktop/workflows/Build%20&%20Test/badge.svg)

Check Workflow Status

• GitHub > Actions tab
• View workflow runs and logs
• See build artifacts

Troubleshooting

Build Failures

1. Check the workflow logs in GitHub Actions
2. Try building locally with same .NET version
3. Ensure all submodules are initialized: git clone --recursive

PR Checks Not Running

• Ensure branch is up-to-date with main
• Review branch protection rules in Settings
• Check if workflows are enabled in Actions

Release Creation Failed

• Verify tag format (v*.* or release-.)
• Check that csproj files are in correct format
• Review workflow output for specific errors

Future Enhancements

Consider adding:

• Test coverage reporting
• Performance benchmarking
• Automated versioning (CalVer/SemVer)
• Multi-platform builds (Linux, macOS)
• Installer generation (.exe, .msi)
• Automated changelog generation
• Docker images for backend

References

• GitHub Actions Documentation
• ClassIsland CI/CD Setup (reference project)
• .NET Build & Deploy
• Avalonia Desktop Deployment