Skip to content

CI/CD Tooling

Purpose

Shared CI/CD tooling and developer utilities for the Virtufin ecosystem (the common repo), including multi-language documentation generation, gRPC client stub generation and publishing, reusable GitHub Actions workflows, per-repo versioning, and a local gRPC UI launcher.

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, package publishing, doc generation, integration tests and linting SHALL be provided as reusable GitHub Actions workflows. Deployment is not one of them: clusters are deployed from their own Ansible repos.

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: Docs workflow

  • WHEN a downstream project calls docs-common.yaml
  • THEN its MkDocs site SHALL be built on the shared mkdocs-base.yml theme and assets and published to its docs site

Requirement: Centralized Versioning

Each versioned repo's versions.env file SHALL define its API_VERSION and LIBRARY_VERSION. 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

common SHALL provide scripts/run_grpcui_local.sh, which launches gRPC UI against a gateway for debugging. It is the only local development script; services run locally through deploy-local or docker-compose.

Scenario: Local gateway

  • WHEN run_grpcui_local.sh is run without arguments
  • THEN it SHALL open gRPC UI in plaintext on localhost:5002 (HOST, PORT), bound to loopback only

Scenario: Remote gateway with a key

  • WHEN it is run with TLS=true and a remote host:port, and VIRTUFIN_API_KEY is set
  • THEN it SHALL send the key as x-api-key, and it SHALL refuse to send the key in cleartext to a non-loopback host