Local CI Scripts Guide

Overview

The GridBuilding project uses local CI scripts instead of cloud-based CI/CD. This gives developers full control over their testing and validation environment without dependency on external services.

Quick Start

1
2
3
4
5
6
7

# Run complete CI pipeline
./scripts/ci-all.sh

# Run individual steps
./scripts/ci-build.sh     # Build only
./scripts/ci-test.sh      # Tests only  
./scripts/ci-quality.sh   # Quality checks only

Scripts

ci-all.sh - Complete CI Pipeline

Orchestrates all CI checks in the proper order:

1. Build
2. Test
3. Code Quality

Usage:

1

./scripts/ci-all.sh

Output:

• Color-coded progress indicators
• Step-by-step execution status
• Total duration and summary
• Exits with error code 1 if any step fails

ci-build.sh - Build Automation

Restores dependencies and builds the entire solution.

Usage:

1
2
3
4
5

# Default: Release configuration
./scripts/ci-build.sh

# Specify configuration
CONFIGURATION=Debug ./scripts/ci-build.sh

Features:

• Automatic dependency restoration
• Configurable build configuration
• Clear error reporting
• Fast feedback on compilation errors

ci-test.sh - Test Automation

Runs all Core tests with optional code coverage collection.

Usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# With code coverage (default)
./scripts/ci-test.sh

# With code coverage + report generation (opt-in)
GENERATE_COVERAGE_REPORT=true ./scripts/ci-test.sh

# Without code coverage
COVERAGE=false ./scripts/ci-test.sh

# With Godot tests (requires GODOT_BIN)
GODOT_BIN=/path/to/godot ./scripts/ci-test.sh

Features:

• Runs all Core unit tests (xUnit)
• Optional code coverage collection
• Godot test support (when GODOT_BIN is set)
• Detailed test output
• Coverage file locations reported

Environment Variables:

• CONFIGURATION - Build configuration (default: Release)
• COVERAGE - Enable coverage collection (default: true)
• GENERATE_COVERAGE_REPORT - If true, attempts to generate a local HTML/text report (default: false)
• GODOT_BIN - Path to Godot executable (optional)
• CI_ALL_BUILD_DONE - If true, ci-test.sh will pass --no-build to dotnet test (used by ci-all.sh to avoid redundant rebuilding)

Coverage Gates (Production-Readiness):

• GATE_MODE - Coverage gate mode: pr, rc, or prod (default: pr).
• CS_COVERAGE_GATE - If true, enforce the C# coverage gate using the generated coverage.opencover.xml (default: true).
• GDUNIT_51 - If true, run the 5.1 GDScript test suite via GodotToolkit.TestOrchestrator (default: false).
• REACHABILITY_GATE - If true, run reachability coverage (coverage-only) and validate against the committed baseline (default: true, only evaluated when GDUNIT_51=true).

Integrity Gates:

• ci-test.sh validates csproj integrity and fails if any project attempts to hide tests via <Compile Remove="Tests/**" ...>.

ci-quality.sh - Code Quality Checks

Performs comprehensive code quality and security checks.

Usage:

1

./scripts/ci-quality.sh

Checks Performed:

1. Project structure validation
2. Build warning detection
3. Vulnerable package scanning
4. Outdated package detection
5. Code formatting verification (if dotnet-format installed)

Features:

• Project validation using validate-projects.sh
• Security vulnerability detection
• Warning and error counting
• Informational checks for outdated packages
• Optional code formatting verification

Exit Codes:

• 0 - All checks passed
• 1 - Critical errors found
• 0 (with warnings) - Passed with warnings

Environment Variables

All scripts support the following environment variables:

Additional variables used by coverage/integrity gates are described in the ci-test.sh section.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Debug build
CONFIGURATION=Debug ./scripts/ci-build.sh

# Test without coverage
COVERAGE=false ./scripts/ci-test.sh

# Test with Godot
GODOT_BIN=/usr/local/bin/godot ./scripts/ci-test.sh

# All together
CONFIGURATION=Debug COVERAGE=true GODOT_BIN=/usr/local/bin/godot ./scripts/ci-all.sh

Integration

Pre-commit Hook

Add a pre-commit hook to run CI checks:

1
2
3

# .git/hooks/pre-commit
#!/bin/bash
./scripts/ci-all.sh

IDE Integration

VS Code

Add tasks to .vscode/tasks.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "CI: Full Pipeline",
      "type": "shell",
      "command": "./scripts/ci-all.sh",
      "group": "test"
    },
    {
      "label": "CI: Build",
      "type": "shell",
      "command": "./scripts/ci-build.sh",
      "group": "build"
    },
    {
      "label": "CI: Test",
      "type": "shell",
      "command": "./scripts/ci-test.sh",
      "group": "test"
    }
  ]
}

JetBrains Rider

Add external tools via Settings → Tools → External Tools

CI/CD Integration

For automated build systems (Jenkins, GitLab CI, etc.):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Example GitLab CI
test:
  script:
    - ./scripts/ci-all.sh

# Example Jenkins
stage('CI') {
  steps {
    sh './scripts/ci-all.sh'
  }
}

Troubleshooting

Build Fails

Issue: Build fails with dependency errors

Solution: Clean and restore

1
2

dotnet clean
./scripts/ci-build.sh

Tests Fail

Issue: Tests fail unexpectedly

Solution: Run with detailed output

1

dotnet test cs/Tests/Core/GridBuilding.Core.Tests.csproj --logger "console;verbosity=detailed"

Coverage Not Working

Issue: Coverage files not generated

Solution: Ensure coverlet is installed

1

dotnet add package coverlet.collector

Godot Tests Skip

Issue: Godot tests always skipped

Solution: Set GODOT_BIN environment variable

1
2

export GODOT_BIN=/path/to/godot
./scripts/ci-test.sh

Quality Checks Fail

Issue: validate-projects.sh fails

Solution: Check for forbidden patterns

1

grep -r "Compile Remove.*Tests" --include="*.csproj"

Permission Denied

Issue: Scripts won’t execute

Solution: Make scripts executable

1

chmod +x scripts/ci-*.sh

Best Practices

Daily Development

1
2
3
4
5

# Quick feedback during development
./scripts/ci-build.sh && ./scripts/ci-test.sh

# Before committing
./scripts/ci-all.sh

Before Pull Request

1
2
3
4
5

# Full validation
COVERAGE=true ./scripts/ci-all.sh

# Check for uncommitted changes
git status

Release Preparation

1
2

# Full check with Godot tests
CONFIGURATION=Release GODOT_BIN=/path/to/godot ./scripts/ci-all.sh

Advantages of Local CI

1. No External Dependencies: Runs completely offline
2. Faster Feedback: No queue times or network delays
3. Full Control: Configure and customize as needed
4. Consistent Environment: Same results locally and in CI
5. Easy Debugging: Direct access to logs and state
6. Cost Effective: No CI/CD service costs

Future Enhancements

Potential improvements to consider:

• Parallel test execution
• Incremental builds
• Test result caching
• Docker containerization
• Performance benchmarking
• Automated changelog generation

Related Documentation

• GitHub SWE Setup Guide - Complete setup and usage
• Production Roadmap - Production timeline
• Test Isolation Workflow - Test development

Last Updated: December 8, 2024
Maintained By: Development Team
Status: Active

For questions or issues with CI scripts, please open a GitHub issue.