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
DocsGeneratoris invoked for a .NET solution - THEN DocFX SHALL extract XML comments from source and produce a static HTML site
Scenario: Python doc generation
- WHEN
DocsGeneratoris 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
GrpcClientGeneratoris 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
GrpcClientGeneratoris 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
GrpcClientGeneratoris 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.ymltheme 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.envis 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.shis 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=trueand a remotehost:port, andVIRTUFIN_API_KEYis 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