Development Guide

Guide for developers who want to contribute to gitlab-summary or build from source.

Prerequisites

Required

  • Visual Studio Code or Visual Studio 2022
  • GitHub account (for contributing)
  • GitLab Personal Access Token (for testing)

Getting the Source

Clone Repository 

  git clone https://github.com/garrardkitchen/gitlab-summary.git
cd gitlab-summary

Fork (for Contributing)

  1. Fork on GitHub: Click “Fork” button
  2. Clone your fork:
      git clone https://github.com/YOUR-USERNAME/gitlab-summary.git
cd gitlab-summary
  3. Add upstream:
      git remote add upstream https://github.com/garrardkitchen/gitlab-summary.git

Project Structure 

  gitlab-summary/
├── src/
│   ├── cli/                        # .NET CLI Application
│   │   ├── GitLabSummary/          # Main project
│   │   │   ├── Commands/           # CLI command handlers
│   │   │   │   ├── PipelinesCommand.cs
│   │   │   │   ├── ServeCommand.cs
│   │   │   │   ├── TokenCommand.cs
│   │   │   │   └── UrlCommand.cs
│   │   │   ├── Models/             # Data models
│   │   │   │   ├── GitLabModels.cs
│   │   │   │   └── Settings.cs
│   │   │   ├── Services/           # Business logic
│   │   │   │   ├── GitLabApiClient.cs
│   │   │   │   ├── PipelineAggregator.cs
│   │   │   │   ├── CredentialsService.cs
│   │   │   │   └── CopilotAnalysisService.cs
│   │   │   ├── Rendering/          # Console output formatters
│   │   │   └── Configuration/      # App configuration
│   │   └── GitLabSummary.Tests/    # Unit tests
│   └── dashboard/                  # Vue 3 Dashboard
│       └── src/
│           ├── composables/        # Vue composables
│           │   ├── usePipelineStream.ts
│           │   ├── useCopilotAnalysis.ts
│           │   └── useFormatters.ts
│           ├── components/         # Vue components
│           │   ├── PipelineDetailDialog.vue
│           │   ├── JobLogDialog.vue
│           │   └── GroupSelector.vue
│           ├── pages/              # Route pages
│           │   ├── OverviewPage.vue
│           │   ├── ProjectsPage.vue
│           │   └── ContributorsPage.vue
│           └── types/              # TypeScript type definitions
├── docs/                           # Documentation (this site)
├── .github/workflows/              # CI/CD workflows
├── CHANGELOG.md
├── README.md
└── RELEASING.md

Building from Source

CLI Application 

  cd src/cli
dotnet restore
dotnet build

# Run
dotnet run --project GitLabSummary -- --version

Dashboard 

  cd src/dashboard
npm install
npm run build

# Output in: dist/

Development Workflow

Backend Development (CLI)

Start Server 

  cd src/cli
dotnet run --project GitLabSummary -- serve --group YOUR-GROUP

Server runs on: http://localhost:5100

Make Changes

  1. Edit files in GitLabSummary/
  2. Save (hot reload with dotnet watch)
  3. Test changes

Run Tests 

  cd src/cli
dotnet test

Frontend Development (Dashboard)

Terminal 1: Backend Server 

  cd src/cli
dotnet run --project GitLabSummary -- serve --group YOUR-GROUP

Terminal 2: Vue Dev Server 

  cd src/dashboard
npm run dev

Dev server runs on: http://localhost:3000
Proxies API requests to: http://localhost:5100

Features:

  • Hot Module Replacement (HMR)
  • Instant updates on file changes
  • Vue DevTools integration

Make Changes

  1. Edit .vue or .ts files
  2. Save
  3. Browser auto-reloads

Linting 

  npm run lint        # Check
npm run lint:fix    # Fix

Testing

Backend Tests 

  cd src/cli
dotnet test

# With coverage
dotnet test --collect:"XPlat Code Coverage"

Frontend Tests 

  cd src/dashboard
npm run test

Manual Testing

Test CLI Commands:

  # Token management
dotnet run --project GitLabSummary -- token set --url https://gitlab.com
dotnet run --project GitLabSummary -- token show

# Pipeline query
dotnet run --project GitLabSummary -- pipelines --group YOUR-GROUP --since 1h

# Dashboard
dotnet run --project GitLabSummary -- serve --group YOUR-GROUP --open

Test Dashboard Features:

  • Navigate all pages
  • Test AI analysis (if Copilot configured)
  • Test group switching
  • Test time period changes
  • Test pipeline drill-down

Code Style

C# (.NET)

Follow Microsoft Conventions:

Use dotnet format:

  cd src/cli
dotnet format

Key Conventions:

  • PascalCase for public members
  • camelCase for private fields
  • _ prefix for private fields
  • async suffix for async methods
  • XML documentation for public APIs

Example:

  public class GitLabApiClient
{
    private readonly HttpClient _httpClient;
    
    /// <summary>
    /// Gets pipelines for the specified group.
    /// </summary>
    public async Task<IEnumerable<Pipeline>> GetPipelinesAsync(string groupId)
    {
        // Implementation
    }
}

TypeScript/Vue

Follow Vue Style Guide:

Use ESLint and Prettier:

  cd src/dashboard
npm run lint
npm run format

Key Conventions:

  • PascalCase for components: PipelineDetailDialog.vue
  • camelCase for functions/variables
  • kebab-case for events: @update-status
  • Composition API with <script setup>
  • TypeScript for type safety

Example:

  <script setup lang="ts">
import { ref, computed } from 'vue'
import type { Pipeline } from '@/types'

const props = defineProps<{
  pipeline: Pipeline
}>()

const emit = defineEmits<{
  close: []
  refresh: []
}>()

const isOpen = ref(false)
</script>

Making Changes

Create Feature Branch 

  git checkout -b feature/your-feature-name

Branch naming:

  • feature/add-export-csv — New features
  • fix/pipeline-sorting — Bug fixes
  • docs/api-reference — Documentation
  • refactor/api-client — Code refactoring

Make Commits

Commit Message Format:

  type: brief description

Longer explanation if needed.

Fixes #123

Types:

  • feat: — New feature
  • fix: — Bug fix
  • docs: — Documentation
  • refactor: — Code restructuring
  • test: — Test changes
  • chore: — Build/tooling

Examples:

  git commit -m "feat: add CSV export for pipelines

Adds new --export flag to pipelines command that outputs
results in CSV format for import into spreadsheets.

Fixes #123"
  
  git commit -m "fix: resolve SSE disconnection issue

Dashboard now properly reconnects when connection drops.
Includes exponential backoff retry logic."

Run Tests 

  # Backend
cd src/cli && dotnet test

# Frontend
cd src/dashboard && npm run test && npm run lint

# Build dashboard
npm run build

Push and Create PR 

  git push origin feature/your-feature-name

On GitHub:

  1. Click “Create Pull Request”
  2. Fill in description:
    • What changed
    • Why it changed
    • How to test
    • Screenshots (if UI changes)
  3. Link related issues
  4. Request review

Debugging

Backend Debugging (VS Code)

launch.json:

  {
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Core Launch (console)",
      "type": "coreclr",
      "request": "launch",
      "program": "${workspaceFolder}/src/cli/GitLabSummary/bin/Debug/net10.0/GitLabSummary.dll",
      "args": ["serve", "--group", "YOUR-GROUP"],
      "cwd": "${workspaceFolder}/src/cli/GitLabSummary",
      "stopAtEntry": false,
      "console": "internalConsole"
    }
  ]
}

Usage:

  1. Set breakpoints in C# code
  2. Press F5
  3. Debug normally

Frontend Debugging

Browser DevTools:

  F12 → Sources tab
Set breakpoints in TypeScript files

Vue DevTools:

  1. Install extension: https://devtools.vuejs.org
  2. Open Vue tab in DevTools
  3. Inspect component state, events, performance

Release Process

See RELEASING.md for complete release process.

Summary:

  1. Update version in .csproj
  2. Update CHANGELOG.md
  3. Create git tag
  4. Push tag
  5. GitHub Actions builds and publishes
  6. NuGet package published
  7. Executables created
  8. GitHub Release created

CI/CD

GitHub Actions Workflows

.github/workflows/build-test.yml:

  • Runs on every push/PR
  • Builds CLI and dashboard
  • Runs tests
  • Reports results

.github/workflows/release.yml:

  • Runs on tag push (vX.Y.Z)
  • Builds all platform executables
  • Publishes to NuGet
  • Creates GitHub Release

Local CI Simulation 

  # Install act (GitHub Actions locally)
brew install act  # macOS
# or from: https://github.com/nektos/act

# Run workflow locally
cd gitlab-summary
act -j build

Documentation

Adding Documentation

Documentation lives in docs/learn/content/:

  cd docs/learn/content/docs
# Create new page
echo "---
title: \"New Feature\"
description: \"Description\"
weight: 10
---

# New Feature

Content here..." > new-feature.md

Build Documentation Locally 

  cd docs/learn
hugo server -D

Open: http://localhost:1313

Getting Help

Questions

Review Process

  • All PRs require review
  • CI must pass
  • Tests must pass
  • Code style must be followed

See Also