Skip to content

CI/CD Tooling

Purpose

Shared CI/CD tooling and developer utilities for the Virtufin ecosystem, including multi-language documentation generation, gRPC client stub generation and publishing, reusable GitHub Actions workflows, centralized versioning, and local development utilities.

Requirements

Requirement: Multi-Language Documentation Generation

The tooling SHALL generate API documentation for C# (via DocFX), Python (via pdoc), and TypeScript (via TypeDoc) from a single configuration. Generated docs SHALL include git metadata.

Scenario: C# doc generation

  • WHEN DocsGenerator is invoked for a .NET solution
  • THEN DocFX SHALL extract XML comments from source and produce a static HTML site

Scenario: Python doc generation

  • WHEN DocsGenerator is invoked for a Python package
  • THEN pdoc SHALL produce HTML documentation from docstrings

Scenario: Git commit badge

  • WHEN docs are generated
  • THEN each page SHALL include the git commit SHA and branch in a navigation badge

Requirement: gRPC Client Generation and Publishing

The tooling SHALL generate and publish gRPC client stubs for Python, TypeScript, and .NET from Protobuf definitions. Publishing SHALL use Gitea package registries.

Scenario: Python client publish

  • WHEN GrpcClientGenerator is invoked for a Python target
  • THEN grpc_tools.protoc SHALL generate stubs, a wheel SHALL be built via uv, and the wheel SHALL be published to the Gitea PyPI registry

Scenario: TypeScript client publish

  • WHEN GrpcClientGenerator is invoked for a TypeScript target
  • THEN buf SHALL generate ES stubs, an npm package SHALL be built, and it SHALL be published to the Gitea npm registry

Scenario: .NET client publish

  • WHEN GrpcClientGenerator is invoked for a .NET target
  • THEN dotnet pack SHALL create a NuGet package from the client project, and it SHALL be pushed to the Gitea NuGet registry

Requirement: Reusable CI/CD Workflows

Common CI/CD workflows for Docker builds, Helm deployments, package publishing, doc generation, and linting SHALL be provided as reusable GitHub Actions workflows.

Scenario: Docker build workflow

  • WHEN a downstream project calls the Docker build workflow
  • THEN a multi-architecture Docker image SHALL be built and pushed to the Harbor registry

Scenario: Helm deploy workflow

  • WHEN a downstream project calls the deploy workflow
  • THEN the Helm chart SHALL be installed or upgraded in the target Kubernetes namespace

Requirement: Centralized Versioning

A single versions.env file SHALL define API_VERSION and LIBRARY_VERSION for all downstream projects. The tooling SHALL read this file to tag packages and Docker images.

Scenario: Version propagation

  • WHEN versions.env is updated to a new library version
  • THEN all generated packages, Docker images, and documentation SHALL carry the new version

Requirement: DocFX Custom Templates

Shared DocFX templates SHALL provide consistent branding with Bootstrap 5, dark/light theme support, search, and breadcrumbs.

Scenario: Template application

  • WHEN a project uses the custom DocFX templates
  • THEN its generated docs SHALL have the shared Virtufin visual identity

Requirement: Local Development Utilities

Scripts SHALL be provided for running Dapr applications locally, launching gRPC UI for debugging, and listing gRPC services via reflection.

Scenario: Local Dapr run

  • WHEN run_dapr_app is called with an app ID and port
  • THEN the Dapr sidecar SHALL start, the app SHALL be launched, and health checks SHALL gate readiness before declaring success