Skip to content

Contributing and Development Build Automation and Wiki Management

Jump to bottom
github-actions[bot] edited this page Aug 3, 2026 · 3 revisions

Build Automation and Wiki Management

Referenced Files in This Document

Update Summary

Changes Made

  • Enhanced GitHub Actions workflow for wiki synchronization to include scripts/build-wiki.mjs in path filters
  • Improved automatic rebuild triggers when wiki build logic is modified
  • Updated development workflow reliability by eliminating manual intervention requirements
  • Enhanced documentation to reflect improved CI/CD pipeline automation
  • Updated for version 4.8.0-rc.2 release preparation including routine maintenance updates

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Enhanced Wiki Management Features
  7. GitHub Actions Workflow Enhancements
  8. Dependency Analysis
  9. Performance Considerations
  10. Troubleshooting Guide
  11. Conclusion

Introduction

This document explains the build automation and wiki management capabilities of the project. It focuses on how documentation is processed, embedded into the application, and synchronized to GitHub Wiki, as well as how containerization, UI builds, and Helm chart versioning are automated. The goal is to provide a clear understanding for contributors who need to modify or extend these workflows.

Updated Enhanced with improved GitHub Actions workflow automation that automatically triggers wiki rebuilds when build logic changes, eliminating manual intervention requirements. Updated for version 4.8.0-rc.2 release preparation with routine maintenance improvements.

Project Structure

Build and wiki-related assets are primarily located under:

  • scripts: Node.js and shell utilities for building docs, embedding content, syncing wiki, and managing Helm versions
  • .github/workflows: CI orchestration that invokes the scripts above with enhanced path filtering
  • Root configuration files: package.json, vite.config.ts, tsconfig.json, Dockerfile, compose.yaml define build tooling and containerization
graph TB
subgraph "Build & Docs"
PKG["package.json"]
VITE["vite.config.ts"]
TSCFG["tsconfig.json"]
DOCKER["Dockerfile"]
COMPOSE["compose.yaml"]
end
subgraph "Enhanced Scripts"
BUILDWIKI["scripts/build-wiki.mjs<br/>(Enhanced Path Filtering)"]
SYNCWIKI["scripts/sync-wiki.sh"]
SETUPPERMS["scripts/setup-github-wiki-permissions.sh"]
BUILDEMBEDSLUG["scripts/build-embed-docs-slug-meta.ts"]
BUILDEMBED["scripts/build-embed-docs.ts"]
BUILDVITEENV["scripts/build-vite-ui-env-define.ts"]
HELMBUMP["scripts/helm-bump-version.mjs"]
HELMSYNC["scripts/helm-sync-app-version.mjs"]
CIPARALLEL["scripts/ci-parallel-checks.mjs"]
CISUMMARY["scripts/ci-github-step-summary.mjs"]
EMBEDDOCS["Embedded Resources<br/>Generator"]
end
subgraph "CI/CD Pipeline"
GHA["GitHub Actions<br/>(Enhanced Path Filters)"]
AUTOBUILD["Automatic Rebuild Trigger"]
end
PKG --> BUILDWIKI
PKG --> BUILDEMBEDSLUG
PKG --> BUILDEMBED
PKG --> BUILDVITEENV
PKG --> HELMBUMP
PKG --> HELMSYNC
VITE --> BUILDVITEENV
DOCKER --> BUILDEMBED
COMPOSE --> BUILDEMBED
BUILDWIKI --> SYNCWIKI
BUILDWIKI --> EMBEDDOCS
SYNCWIKI --> SETUPPERMS
CIPARALLEL --> BUILDEMBED
CIPARALLEL --> BUILDWIKI
CISUMMARY --> CIPARALLEL
EMBEDDOCS --> BUILDWIKI
GHA --> AUTOBUILD
AUTOBUILD --> BUILDWIKI
Loading

Diagram sources

Section sources

Core Components

  • Documentation embedding pipeline: Converts markdown-based docs into structured metadata and embeddable resources consumed by the application at runtime.
  • Enhanced Wiki synchronization: Builds and pushes documentation to GitHub Wiki using configured permissions and tokens, with improved automated resource handling and automatic rebuild triggers.
  • UI environment generation: Produces build-time constants for the UI based on environment variables.
  • Helm versioning helpers: Automates bumping and synchronizing Helm chart versions with application versions.
  • CI orchestration: Runs checks in parallel and generates step summaries for better visibility.
  • New Embedded resource generator: Provides advanced capabilities for processing and synchronizing embedded documentation resources.
  • Enhanced GitHub Actions workflow: Includes scripts/build-wiki.mjs in path filters for automatic rebuilds when wiki build logic is modified.

Updated Enhanced core components with improved GitHub Actions workflow automation and automatic rebuild capabilities.

Section sources

Architecture Overview

The build system integrates multiple stages with enhanced GitHub Actions workflow automation:

  • Source docs (markdown) are transformed into metadata and embedded artifacts.
  • Enhanced Wiki pipeline processes embedded resources with improved automation and automatic rebuild triggers.
  • UI build injects environment-specific constants.
  • Container images include prebuilt assets.
  • Helm charts are versioned consistently with app releases.
  • Enhanced CI orchestrates steps with intelligent path filtering and reports results.
sequenceDiagram
participant Dev as "Developer"
participant GHA as "GitHub Actions<br/>(Enhanced)"
participant NPM as "npm Scripts"
participant Embed as "build-embed-docs.ts"
participant Slug as "build-embed-docs-slug-meta.ts"
participant WikiEnh as "Enhanced build-wiki.mjs"
participant Vite as "vite.config.ts"
participant EnvDef as "build-vite-ui-env-define.ts"
participant Docker as "Dockerfile"
participant Compose as "compose.yaml"
participant HelmBump as "helm-bump-version.mjs"
participant HelmSync as "helm-sync-app-version.mjs"
participant Wiki as "GitHub Wiki"
participant EmbedRes as "Embedded Resources"
Dev->>GHA : Push code changes
GHA->>NPM : Check path filters
Note over GHA,NPM : Auto-trigger if scripts/build-wiki.mjs changed
GHA->>Embed : Generate embedded docs
GHA->>Slug : Generate slug metadata
GHA->>WikiEnh : Execute enhanced wiki build
GHA->>EnvDef : Define UI env constants
GHA->>Vite : Build UI bundle
GHA->>Docker : Build container image
GHA->>Compose : Orchestrate local services
GHA->>HelmBump : Bump chart version
GHA->>HelmSync : Sync app version in chart
WikiEnh->>EmbedRes : Process embedded resources
WikiEnh->>Wiki : Synchronize with enhanced capabilities
Wiki-->>Dev : Updated wiki pages with embedded resources
Loading

Diagram sources

Detailed Component Analysis

Documentation Embedding Pipeline

Purpose: Transform source documentation into structured data and embeddable resources used by the application.

Key responsibilities:

  • Parse markdown documents and extract metadata
  • Compute slugs and canonical identifiers
  • Emit artifacts consumed by the server and UI
  • Integrate with UI build to expose environment-specific settings
flowchart TD
Start(["Start"]) --> ReadDocs["Read source docs"]
ReadDocs --> ParseMeta["Extract metadata"]
ParseMeta --> ComputeSlugs["Compute slugs and IDs"]
ComputeSlugs --> EmitArtifacts["Emit embedded artifacts"]
EmitArtifacts --> InjectEnv["Inject UI env constants"]
InjectEnv --> End(["Done"])
Loading

Diagram sources

Section sources

Enhanced Wiki Synchronization Workflow

Purpose: Build documentation and synchronize it to GitHub Wiki with improved automated resource handling and automatic rebuild triggers.

Updated Enhanced workflow now includes advanced embedded resource processing, improved synchronization capabilities, and automatic rebuild triggers when build logic changes.

Workflow overview:

  • Prepare wiki repository and credentials
  • Enhanced Process embedded resources with improved automation
  • Build wiki content using the enhanced build script
  • Push updates to GitHub Wiki with better error handling
  • New Automatic trigger detection for build logic modifications
sequenceDiagram
participant User as "User/CI"
participant GHA as "GitHub Actions"
participant BuildWiki as "Enhanced build-wiki.mjs"
participant EmbedRes as "Embedded Resource Processor"
participant Sync as "sync-wiki.sh"
participant Perms as "setup-github-wiki-permissions.sh"
participant GH as "GitHub API"
User->>GHA : Push code changes
GHA->>BuildWiki : Check path filters
Note over GHA,BuildWiki : Auto-trigger if build-wiki.mjs modified
GHA->>BuildWiki : Execute enhanced wiki build
BuildWiki->>Perms : Configure permissions
BuildWiki->>EmbedRes : Process embedded resources
EmbedRes-->>BuildWiki : Enhanced resource artifacts
BuildWiki->>Sync : Sync content with embedded resources
Sync->>GH : Push wiki updates with enhanced capabilities
GH-->>User : Success/Failure with detailed feedback
Loading

Diagram sources

Section sources

UI Environment Definition

Purpose: Generate build-time constants for the UI based on environment variables.

Integration points:

  • Invoked during UI build
  • Consumed by Vite configuration
  • Ensures consistent behavior across environments
flowchart TD
A["Environment Variables"] --> B["build-vite-ui-env-define.ts"]
B --> C["Generated Constants File"]
C --> D["vite.config.ts"]
D --> E["UI Bundle"]
Loading

Diagram sources

Section sources

Helm Versioning Helpers

Purpose: Keep Helm chart versions aligned with application versions and automate bumping.

Tasks:

  • Bump chart version
  • Sync app version within chart values/templates
flowchart TD
Start(["Start"]) --> Bump["helm-bump-version.mjs"]
Bump --> SyncVer["helm-sync-app-version.mjs"]
SyncVer --> Commit["Commit changes"]
Commit --> End(["Done"])
Loading

Diagram sources

Section sources

CI Orchestration and Summaries

Purpose: Parallelize checks and produce actionable summaries.

Highlights:

  • Run multiple checks concurrently
  • Aggregate results and generate step summaries
  • Integrate with GitHub Actions reporting
  • Enhanced Intelligent path filtering for automatic rebuild triggers
sequenceDiagram
participant CI as "CI Runner"
participant ParChecks as "ci-parallel-checks.mjs"
participant Summary as "ci-github-step-summary.mjs"
participant GH as "GitHub Actions"
CI->>ParChecks : Execute parallel checks
ParChecks-->>Summary : Results
Summary->>GH : Post step summary
GH-->>CI : Display summary
Loading

Diagram sources

Section sources

Enhanced Wiki Management Features

Advanced Embedded Resource Processing

The enhanced build-wiki.mjs script now provides sophisticated capabilities for processing and synchronizing embedded documentation resources. This includes improved handling of complex document structures, better error recovery, and enhanced performance for large documentation sets.

Key enhancements:

  • Improved resource validation: Enhanced validation of embedded resources before synchronization
  • Better error handling: More robust error recovery and detailed logging for failed operations
  • Performance optimization: Optimized processing pipeline for large documentation repositories
  • Advanced conflict resolution: Better handling of concurrent modifications and merge conflicts

Enhanced Synchronization Capabilities

The wiki synchronization process has been significantly improved with better support for:

  • Incremental updates to reduce synchronization time
  • Better retry mechanisms for network failures
  • Enhanced logging and debugging capabilities
  • Improved support for large file uploads and batch operations

Integration with Embedded Resources

The enhanced system provides seamless integration between the main documentation and embedded resources:

  • Automatic detection and processing of embedded resource dependencies
  • Coordinated updates between main docs and embedded content
  • Better version consistency across all documentation components

Section sources

GitHub Actions Workflow Enhancements

Automatic Rebuild Triggers

The GitHub Actions workflow has been enhanced to include scripts/build-wiki.mjs in path filters, ensuring automatic rebuilds when wiki build logic is modified. This improvement eliminates the need for manual intervention and improves development workflow reliability.

Key improvements:

  • Intelligent path filtering: Automatically detects changes to wiki build logic
  • Automatic trigger activation: Rebuilds wiki content without manual intervention
  • Enhanced development workflow: Reduces friction in documentation updates
  • Improved reliability: Ensures wiki stays synchronized with build logic changes

Workflow Optimization Benefits

The enhanced workflow provides several benefits for developers and maintainers:

  • Reduced manual overhead: No need to manually trigger wiki rebuilds after build script changes
  • Faster iteration: Immediate wiki updates when build logic is modified
  • Better developer experience: Seamless integration between code changes and documentation updates
  • Improved reliability: Consistent wiki state aligned with build system changes
flowchart TD
CodeChange["Code Change to scripts/build-wiki.mjs"] --> PathFilter["GitHub Actions Path Filter"]
PathFilter --> AutoTrigger["Automatic Workflow Trigger"]
AutoTrigger --> BuildProcess["Execute Build Process"]
BuildProcess --> WikiRebuild["Rebuild Wiki Content"]
WikiRebuild --> Publish["Publish Updated Wiki"]
Publish --> Developer["Developer Notification"]
style CodeChange fill:#e1f5fe
style AutoTrigger fill:#f3e5f5
style WikiRebuild fill:#e8f5e8
style Publish fill:#fff3e0
Loading

Diagram sources

Section sources

Dependency Analysis

Build scripts depend on:

  • Node.js runtime and npm packages defined in package.json
  • TypeScript compilation via tsconfig.json
  • Vite for UI bundling
  • Shell utilities for wiki operations
  • Docker and Compose for containerization
  • Enhanced Additional dependencies for improved wiki management and embedded resource processing
  • New GitHub Actions workflow dependencies for path filtering and automatic triggers
graph LR
PKG["package.json"] --> NODE["Node.js Runtime"]
TSCFG["tsconfig.json"] --> TS["TypeScript Compiler"]
VITE["vite.config.ts"] --> VITEPKG["Vite"]
DOCKER["Dockerfile"] --> DOCKRUN["Docker Engine"]
COMPOSE["compose.yaml"] --> COMPRUN["Compose"]
SCRIPTS["scripts/*"] --> NODE
SCRIPTS --> SHELL["Shell Utilities"]
ENHANCED["Enhanced Wiki Features"] --> NODE
ENHANCED --> WEBLIBS["Web Libraries"]
ENHANCED --> FILESYS["File System APIs"]
WORKFLOW["GitHub Actions Workflow"] --> PATHFILTER["Path Filtering"]
WORKFLOW --> AUTOTRIGGER["Auto Triggers"]
PATHFILTER --> SCRIPTS
AUTOTRIGGER --> WORKFLOW
Loading

Diagram sources

Section sources

Performance Considerations

  • Parallelize independent tasks to reduce total build time.
  • Cache intermediate artifacts (e.g., generated metadata) to avoid redundant work.
  • Limit concurrency when interacting with external APIs (e.g., GitHub Wiki) to respect rate limits.
  • Use incremental builds where possible to speed up iterative development.
  • Enhanced Leverage improved caching mechanisms in the enhanced wiki synchronization process.
  • Enhanced Utilize optimized resource processing pipelines for better performance with large documentation sets.
  • New Benefit from automatic rebuild triggers that only activate when necessary, reducing unnecessary CI runs.

Troubleshooting Guide

Common issues and resolutions:

  • Authentication failures when syncing wiki: Ensure proper token configuration and permissions setup before running wiki sync.
  • Missing environment variables during UI build: Verify that environment definitions are generated and available to Vite.
  • Helm version mismatches: Confirm that Helm versioning helpers are executed prior to packaging or releasing.
  • CI timeouts or partial runs: Review parallel check logs and adjust concurrency settings if necessary.
  • Enhanced Embedded resource processing errors: Check enhanced logging output for detailed error information and resource validation failures.
  • Enhanced Wiki synchronization timeouts: Monitor enhanced retry mechanisms and consider adjusting timeout configurations for large documentation sets.
  • New GitHub Actions path filter issues: Verify that scripts/build-wiki.mjs is properly included in path filters for automatic triggers.
  • New Manual intervention still required: Check GitHub Actions workflow configuration to ensure automatic rebuild triggers are functioning correctly.

Updated Added troubleshooting guidance for enhanced wiki management features and GitHub Actions workflow improvements.

Section sources

Conclusion

The project's build automation integrates documentation processing, UI environment definition, containerization, Helm versioning, and CI orchestration with significantly enhanced wiki management capabilities. The improved build-wiki.mjs script provides advanced automated documentation generation and synchronization capabilities for embedded resources, while the enhanced GitHub Actions workflow ensures automatic rebuilds when wiki build logic is modified. This eliminates manual intervention requirements and improves development workflow reliability. By following the documented workflows and leveraging the provided scripts, contributors can reliably build, test, and publish both application artifacts and documentation with enhanced reliability, performance, and automation.

Updated Enhanced conclusion reflecting the improved wiki management capabilities, embedded resource handling, and GitHub Actions workflow automation that eliminates manual intervention requirements. Updated for version 4.8.0-rc.2 release preparation with routine maintenance improvements.

KAIROS MCP

Clone this wiki locally