GhostlyHavens CI/CD Setup

This repository uses Forgejo Actions for continuous integration and deployment.

Workflow Overview

The CI/CD pipeline (build-and-deploy.yml) performs the following:

1. Build Windows (x64): Compiles the game for Windows with .NET 10 on your custom runner
2. Build Linux (x64): Compiles the game for Linux with .NET 10 on your custom runner
3. Deploy to itch.io: Automatically pushes builds when you create a version tag (e.g., v1.0.0)

Infrastructure

Custom Forgejo Runner

This workflow uses your custom dotnet-10 runner which has:

• ? .NET 10 SDK pre-installed
• ? Linux environment (likely Debian/Ubuntu based)
• ? Build tools (zip, curl, etc.)

Benefits:

• No need to install .NET on every build
• Faster build times (no SDK download)
• Consistent build environment

Setup Instructions

1. Configure Forgejo Secrets

Go to your repository settings ? Secrets and add the following:

Secret Name	Description	How to Get
BUTLER_API_KEY	itch.io API key for Butler CLI	Get from itch.io
ITCH_USER	Your itch.io username	Your itch.io account username
ITCH_GAME	Your game's itch.io project name	The URL slug (e.g., ghostlyhavens from user.itch.io/ghostlyhavens)

2. Create Your itch.io Project

1. Go to itch.io/game/new
2. Set up your game page
3. Note the project URL slug for the ITCH_GAME secret

3. Trigger Builds

Automatic Builds

• On Push to Main: Builds artifacts but doesn't deploy
• On Pull Request: Runs build tests only
• On Version Tag: Builds and deploys to itch.io

Manual Builds

You can manually trigger the workflow from the Forgejo Actions tab.

4. Deploying a Release

To deploy a new version to itch.io:

# Tag the current commit with a version
git tag v1.0.0

# Push the tag to trigger deployment
git push origin v1.0.0

The workflow will:

1. Build Windows and Linux versions
2. Upload to itch.io as separate channels (windows-x64 and linux-x64)
3. Create a GitHub/Forgejo release with downloadable artifacts

Build Artifacts

Build artifacts are stored for 7 days and can be downloaded from the Actions page:

• GhostlyHavens-Windows-x64.zip - Windows build
• GhostlyHavens-Linux-x64.zip - Linux build

Customization

Change .NET Version

Edit the workflow file and update:

env:
  DOTNET_VERSION: '10.0.x'

Add macOS Build

Add a new job to the workflow:

build-macos:
  name: Build macOS (ARM64)
  runs-on: macos-latest
  steps:
    # Similar to Linux build but with -r osx-arm64

Change Build Configuration

Modify the dotnet publish command parameters:

• -c Release ? Build configuration
• -r win-x64 ? Runtime identifier
• --self-contained true ? Include .NET runtime
• -p:PublishSingleFile=false ? Single executable (may have issues with MonoGame)

Troubleshooting

Build Fails with "Project not found"

• Check that PROJECT_NAME and SOLUTION_FILE in the workflow match your actual file names

Butler Upload Fails

• Verify your BUTLER_API_KEY is correct
• Ensure ITCH_USER and ITCH_GAME match your itch.io project
• Check that the itch.io project exists and is accessible

MonoGame Content Not Included

• Ensure Content files are set to "Copy to Output Directory" in your .csproj
• Check that Content/ directory is included in the publish output

Local Testing

Test the build locally before pushing:

# Windows
dotnet publish ghostlyhavens.game/ghostlyhavens.game.csproj -c Release -r win-x64 --self-contained true -o ./test-build/windows

# Linux
dotnet publish ghostlyhavens.game/ghostlyhavens.game.csproj -c Release -r linux-x64 --self-contained true -o ./test-build/linux

Resources

• Forgejo Actions Documentation
• Butler (itch.io CLI) Documentation
• .NET Publishing Documentation
• MonoGame Deployment Guide