GitLab CI/CD Guide for OpenRoads MUD

This document explains the Continuous Integration and Continuous Deployment (CI/CD) pipeline for the OpenRoads MUD project.

Pipeline Overview

The GitLab CI/CD pipeline consists of five main stages:

1. Build - Compile the server binary and cross-platform releases

2. Test - Run unit tests and code quality checks

3. Integration - Run end-to-end tests and system verification

4. Deploy - Deploy to staging/production environments

5. Release - Create automated releases with cross-platform binaries

Pipeline Stages

🏗️ Build Stage

Job: build

• Compiles the OpenRoads server binary

• Uses Go 1.21 Alpine image

• Caches Go modules for faster builds

• Produces openroads binary artifact

• Runs on: merge requests, main, develop branches

Job: build_binaries

• Builds cross-platform release binaries

• Supports Linux AMD64, Windows AMD64, macOS AMD64, Linux ARM64

• Uses optimized build flags (-ldflags="-s -w")

• Only runs on tags and main branch

• Produces release-ready binaries

Artifacts:

• openroads binary (expires in 1 hour)

• Cross-platform binaries (expires in 1 week)

🧪 Test Stage

Job: unit_tests

• Runs unit tests for all packages (./lib/..., ./config/..., ./routines/...)

• Generates coverage reports

• Produces JUnit XML reports for GitLab integration

• Timeout: 5 minutes

Artifacts:

• report.xml - JUnit test results

• coverage.html - Coverage report

Job: code_quality

• Runs gofmt for code formatting

• Runs go vet for static analysis

• Runs staticcheck for advanced static analysis

• Runs goimports for import formatting

• Allows failure (non-blocking)

Artifacts:

• gofmt-report.txt

• goimports-report.txt

Job: security_scan (Manual)

• Runs gosec security scanner

• Generates security report

• Manual trigger only

• Allows failure

Artifacts:

• gosec-report.json

🔗 Integration Stage

Job: e2e_simple

• Runs simple end-to-end tests

• Tests core functionality:

  • Server connection & RLogin protocol

  • Static NPC spawning

  • Enemy spawning system

  • Multiple client connections

  • Server stability

• Timeout: 10 minutes

• Required for merge

Job: e2e_comprehensive (Manual)

• Runs comprehensive end-to-end tests

• Tests advanced features:

  • Player creation & authentication

  • Game commands and interactions

  • Combat system

  • Inventory management

• Manual trigger only

• Allows failure

• Timeout: 15 minutes

Job: static_npc_verification

• Verifies static NPC system functionality

• Ensures NPCs like Oria, Hanrod, Wenzel are properly placed

• Required for merge

Job: combat_system_verification

• Verifies combat system components

• Tests combat mechanics and equipment

• Required for merge

Job: enemy_spawning_verification

• Verifies enemy spawning system

• Tests spawn timing, max instances, room validation

• Required for merge

🚀 Deploy Stage

Job: deploy_staging (Manual)

• Deploys to staging environment

• Manual trigger only

• Runs only on main branch

• Prepares binary for deployment

Environment:

• Name: staging

• URL: http://staging.openroads.mud

🚀 Release Stage

Job: release_job

• Creates GitLab releases automatically when tags are pushed

• Links to cross-platform binaries from build_binaries job

• Uses GitLab's native release functionality

• Generates release notes from tag message

• Only runs when tags are created

Release Assets:

• openroads-linux-amd64 - Linux 64-bit binary

• openroads-windows-amd64.exe - Windows 64-bit executable

• openroads-darwin-amd64 - macOS 64-bit binary

• openroads-linux-arm64 - Linux ARM64 binary

Running Tests Locally

Prerequisites

# Install required tools
go install github.com/jstemmer/go-junit-report@latest
go install honnef.co/go/tools/cmd/staticcheck@latest
go install golang.org/x/tools/cmd/goimports@latest

Run All Tests

# Setup CI environment
./scripts/ci-setup.sh

# Run unit tests
go test -v ./lib/... ./config/... ./routines/...

# Run simple E2E tests
./run_simple_e2e.sh

# Run comprehensive E2E tests (optional)
./run_e2e_test.sh

# Generate test reports
./scripts/generate-test-reports.sh

Run Specific Test Suites

# Unit tests only
go test -v ./lib/...

# Simple E2E tests only
cd tests && go test -v -run TestSimpleE2E

# Static NPC verification
cd tests && go test -v -run TestStaticNPCVerification

# Combat system verification
cd tests && go test -v -run TestCombatSystem

# Enemy spawning verification
cd tests && go test -v -run TestEnemySpawning

Creating Releases

Automated Release Process

OpenRoads MUD uses an automated release process that creates cross-platform binaries and GitLab releases when tags are pushed.

Using the Release Script

# Use the automated release creation script
./dev_tools/create-release.sh

The script will:

1. Validate the current git state

2. Prompt for version and release notes

3. Run tests to ensure quality

4. Create and push the git tag

5. Trigger the automated release pipeline

Manual Release Process

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

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

Release Pipeline Workflow

1. Tag Detection: Pipeline detects new tag

2. Cross-platform Build: build_binaries job creates binaries for:

   • Linux AMD64

   • Windows AMD64

   • macOS AMD64

   • Linux ARM64

3. Release Creation: release_job creates GitLab release with:

   • Release notes from tag message

   • Links to all platform binaries

   • Automatic asset organization

Version Naming Convention

Use semantic versioning for releases:

• v1.0.0 - Major release

• v1.1.0 - Minor release with new features

• v1.0.1 - Patch release with bug fixes

• v1.0.0-beta.1 - Pre-release versions

CI Environment Variables

The pipeline uses these environment variables:

• GO_VERSION: Go version to use (default: 1.21)

• BINARY_NAME: Name of the compiled binary (default: openroads)

• TEST_TIMEOUT: Timeout for tests (default: 5m)

• CI: Set to "true" in CI environment

• CI_COMMIT_SHA: Git commit hash

• CI_COMMIT_REF_NAME: Git branch name

Artifacts and Reports

Test Reports

• Location: test-reports/ directory

• JUnit XML: For GitLab test result integration

• Coverage HTML: Visual coverage reports

• Test Output: Raw test output for debugging

Build Artifacts

• Binary: openroads executable

• Reports: Various analysis and test reports

• Logs: CI execution logs

Pipeline Configuration

Cache Strategy

• Go modules cached in .cache/go-mod/

• Build cache in .cache/go-build/

• Speeds up subsequent builds

Timeout Settings

• Unit tests: 5 minutes

• Simple E2E: 10 minutes

• Comprehensive E2E: 15 minutes

• Build: Default (10 minutes)

Failure Handling

• Blocking failures: Build, unit tests, simple E2E tests

• Non-blocking failures: Code quality, security scan, comprehensive E2E

• Manual jobs: Comprehensive E2E, security scan, deployment

Merge Request Requirements

For a merge request to be accepted, the following must pass:

✅ Required (Blocking):

• Build successful

• Unit tests pass

• Simple E2E tests pass

• Static NPC verification pass

• Combat system verification pass

• Enemy spawning verification pass

⚠️ Optional (Non-blocking):

• Code quality checks

• Security scan

• Comprehensive E2E tests

Troubleshooting

Common Issues

Build Failures

# Check Go version compatibility
go version

# Clean and rebuild
go clean -cache
go mod tidy
go build .

Test Failures

# Run tests locally first
./run_simple_e2e.sh

# Check for port conflicts
netstat -tulpn | grep 2025

# Clean up any hanging processes
pkill -f openroads

CI Environment Issues

# Verify CI setup
./scripts/ci-setup.sh

# Check required files
ls -la world/enemies.json world/formatted_rooms.json config/config.ini

Getting Help

1. Check the CI logs in GitLab

2. Run tests locally to reproduce issues

3. Review the test output in artifacts

4. Check the troubleshooting section above

5. Create an issue using the bug report template

Best Practices

For Developers

1. Run tests locally before pushing

2. Keep commits small and focused

3. Write tests for new features

4. Update documentation when needed

5. Use descriptive commit messages

For CI/CD

1. Keep pipelines fast - optimize for quick feedback

2. Fail fast - catch issues early in the pipeline

3. Provide clear feedback - good error messages and logs

4. Cache dependencies - speed up builds

5. Monitor pipeline performance - track build times and success rates

Monitoring and Metrics

The CI/CD pipeline provides these metrics:

• Build success rate

• Test pass rate

• Pipeline duration

• Test coverage percentage

• Security scan results

These metrics help maintain code quality and identify areas for improvement.