GitHub Integration

Relevant source files

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

• src/services/versions/v1/index.ts
• src/services/stats/v1/index.ts
• src/lib/github-errors.ts
• README.md
• test/mocks/github-releases.ts
• test/utils/test-types.ts

The GitHub Integration system serves as the primary data acquisition layer for the FOSSBilling API Worker. It is responsible for fetching, processing, and caching release information from the official FOSSBilling repository. This integration enables the API to provide real-time update notifications, changelog generation, and historical release statistics to FOSSBilling instances worldwide.

The system utilizes both the GitHub REST API for general release metadata and the GitHub GraphQL API for efficient batch retrieval of configuration files (specifically composer.json). By combining these interfaces with a robust caching strategy using Cloudflare KV, the integration minimizes external API dependency and ensures high availability even during GitHub service interruptions.

Sources: README.md:1-15, src/services/versions/v1/index.ts:1-20

Architecture and Data Flow

The integration logic is primarily housed within the Versions Service, which acts as the data provider for other modules like the Stats Service. The flow involves authenticating with a GitHub Personal Access Token, fetching release lists, and resolving dependencies for each version.

Integration Workflow

The following diagram illustrates the sequence of operations when the API retrieves release data:

Data Acquisition Methods

GitHub REST API

The system uses the REST API to fetch the primary list of releases. It targets the endpoint https://api.github.com/repos/FOSSBilling/FOSSBilling/releases.

Key logic includes:

• Asset Filtering: The integration specifically looks for FOSSBilling.zip or FOSSBilling-{tag}.zip to verify a valid distribution exists.
• Semantic Versioning: Only releases with valid semver tags are processed using the semver library.
• Pagination: Requests are limited to the 100 most recent releases per fetch.

Sources: src/services/versions/v1/index.ts:18-22, src/services/versions/v1/index.ts:117-125, src/services/versions/v1/index.ts:210-220

GitHub GraphQL API

To avoid the "N+1" request problem where each release would require a separate REST call to fetch its composer.json, the system employs a batch GraphQL query.

// Example of the batch query structure used
const query = `{ repository(owner: "${REPO_OWNER}", name: "${REPO_NAME}") {
  r0: object(expression: "0.6.0:composer.json") { ... on Blob { text } }
  r1: object(expression: "0.5.0:composer.json") { ... on Blob { text } }
} }`;

This query retrieves the raw text of composer.json for all new releases in a single HTTP request, which is then parsed to extract the minimum_php_version.

Sources: src/services/versions/v1/index.ts:430-465, test/utils/mock-helpers.ts:37-55

Error Handling and Resilience

The github-errors.ts module provides a specialized classification system for GitHub-specific failures. This allows the API to differentiate between user-fixable errors (like Auth) and transient infrastructure issues.

Error Classification Table

Error Class	HTTP Status	Priority	Description
AuthError	401	CRITICAL	Invalid or expired GITHUB_TOKEN.
RateLimitError	403	CRITICAL	GitHub API rate limits exceeded.
NetworkError	N/A	HIGH	Connection timeouts or DNS failures.
NotFoundError	404	MEDIUM	Repository or release resource not found.
ValidationError	N/A	LOW	Unexpected JSON structure or missing fields.

Sources: src/lib/github-errors.ts:1-80, test/lib/github-errors.test.ts:10-50

Graceful Degradation (Stale-While-Revalidate)

If a GitHub API request fails, the system attempts to serve "stale" data from the KV cache if available. The response includes a stale: true flag to inform the client that the data may be outdated.

Sources: src/services/versions/v1/index.ts:330-360, test/services/versions/v1/errors.test.ts:135-155

Configuration and Environment

The integration requires specific environment variables and storage bindings to function within the Cloudflare Workers environment.

Variable/Binding	Type	Description
GITHUB_TOKEN	Secret	GitHub Personal Access Token (classic) with public repo read access.
CACHE_KV	KV Namespace	Stores processed GitHub release data (Key: gh-fossbilling-releases).
AUTH_KV	KV Namespace	Stores the UPDATE_TOKEN for manual cache refresh.

Sources: README.md:40-55, src/services/versions/v1/index.ts:15-30

Release Data Structure

The processed data extracted from GitHub is mapped into a standardized ReleaseDetails interface used throughout the application.

Field	Source from GitHub	Description
version	release.name or tag_name	The display version string.
released_on	release.published_at	ISO 8601 timestamp of publication.
minimum_php_version	composer.json -> require.php	Minimum PHP version required by the release.
download_url	asset.browser_download_url	Direct link to the FOSSBilling.zip file.
size_bytes	asset.size	Size of the release archive in bytes.
changelog	release.body	Markdown release notes from GitHub.

Sources: src/services/versions/v1/index.ts:285-300, test/utils/test-types.ts:75-85

Summary

The GitHub Integration is a robust, multi-tiered system designed for efficiency and reliability. By utilizing a combination of REST and GraphQL APIs, it minimizes overhead, while its specialized error handling and KV-based caching ensure that the FOSSBilling ecosystem remains operational even during external service disruptions.