GitHub Actions Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• scripts/generate-assets.ts
• package.json
• export.config.json
• cubic.yaml
• scripts/types.ts
• scripts/svgo.config.ts

The GitHub Actions workflow automates the optimization, generation, and distribution of FOSSBilling branding assets. It processes source SVG files to produce production-ready vector and raster graphics, favicons, and metadata. The system ensures brand consistency by validating source inputs and providing automated previews for review.

Sources: README.md:92-94, scripts/generate-assets.ts:11-17

Workflow Architecture and Triggers

The project utilizes GitHub Actions for continuous integration and deployment. The primary workflow, named build-and-publish-assets.yml, executes based on specific repository events to maintain the asset pipeline.

Execution Triggers

The workflow activates under three primary conditions:

• Pull Requests: Validates changes and generates a downloadable artifact for inspection.
• Pushes to main: Generates assets and publishes them to production storage.
• Manual Runs: Allows developers to trigger builds for specific branches with an optional publish flag.

Sources: README.md:92-97

AI Code Review Workflow

The repository integrates with Cubic for automated code reviews. This workflow monitors pull requests to provide technical feedback and auto-approval for low-risk changes.

Configuration	Setting	Description
reviews.enabled	true	Enables AI-driven code reviews for incoming PRs.
reviews.sensitivity	high	Sets a strict threshold for identifying potential issues.
auto_approve	low_risk_only	Restricts auto-approvals to minimal impact changes.
ignore.head_branches	renovate/*, dependabot/*	Excludes automated dependency updates from AI review.

Sources: cubic.yaml:12-32

Asset Generation Pipeline

The core logic of the workflow resides in the npm run generate command, which executes the scripts/generate-assets.ts utility. This script transforms source files into distributed formats.

The diagram shows the sequential steps from workflow initiation to final asset publication.
Sources: README.md:78-90, package.json:5-7, scripts/generate-assets.ts:11-17

Validation and Optimization

The workflow enforces strict rules for source SVGs to ensure cross-platform compatibility:

1. Text Outlining: Rejects SVGs containing <text> elements; all lettering must be converted to paths.
2. Viewport Integrity: Validates the presence of a viewBox and ensures optimization does not alter dimensions.
3. SVG Optimization: Applies a conservative svgo configuration to remove metadata, comments, and editor data without altering path coordinates.

Sources: scripts/generate-assets.ts:89-100, scripts/svgo.config.ts:6-18

Output Transformation Logic

The script processes variants defined in export.config.json to create a standard set of outputs.

Output Category	Processing Logic	Targeted Files
Optimized SVGs	Removes unnecessary XML overhead via SVGO.	assets/**/*.svg
PNG Icons	Renders vectors at 2x resolution before downsampling for sharpness.	dist/**/icon/*.png
Favicons	Combines 16px, 32px, and 48px PNG frames into a single ICO file.	favicon.ico
Preview	Generates a reference sheet with branding on multiple backgrounds.	preview.png

Sources: scripts/generate-assets.ts:50-65, scripts/generate-assets.ts:133-157, scripts/create-preview.ts:12-25

Data Structures and Manifests

The workflow produces an AssetManifest to track all generated files. This manifest acts as a registry for downstream consumers or the web preview.

Manifest Schema

The manifest.json file records the exact time of export and a list of all asset objects.

export interface Asset {
  path: string;
  variant: string | null;
  type: 'icon' | 'logo' | 'favicon' | 'apple-touch-icon' | 'preview';
  format: string;
  width?: number;
  height?: number;
  sizes?: number[];
  variants?: string[];
}

Sources: scripts/types.ts:8-17

Deployment and Artifacts

Upon successful generation, the workflow manages two types of distribution:

1. GitHub Artifacts: A ZIP file named fossbilling-branding is uploaded to the workflow run. It contains the dist/ and assets/ content along with the manifest.json.
2. Cloudflare R2: On pushes to main, the workflow synchronizes the generated files to Cloudflare R2 storage for public consumption at branding.fossbilling.org.

Sources: README.md:92-99, scripts/generate-assets.ts:161-163

The workflow also performs cleanup by identifying and removing obsolete files in the assets/ and dist/ directories that no longer match the current export.config.json definitions.

Sources: scripts/generate-assets.ts:173-193