How game-ci/unity-builder works
Main Components
• GitHub Action Integration: Represented by files like action.yml, the GitHub workflows under the .github/workflows directory, and various GitHub templates. This is the entry point of the action, defining how the action is triggered and used in CI pipelines.
• Build Engine / Unity Builder Core: This includes the logic implemented in the src directory (for example, index.ts and the underlying model files). These files coordinate reading inputs, executing build steps, handling versioning, caching, and performing the build for Unity projects.
• Platform-Specific Build Handlers: Notice the distinct directories under dist/platforms (mac, ubuntu, windows) that include platform-specific scripts. Represent these as separate build handler components that encapsulate the commands and scripts for each target environment.
• Cloud Runner and Providers: A large portion of the src/model/cloud-runner directory indicates support for running builds in cloud environments (with providers for AWS, Docker, Kubernetes, etc.). These components abstract away execution in various environments and provide integrations (error handling, logging, caching, hooks) that are crucial in a CI context.
• Input Readers & Validation: The src/model/input-readers directory shows components that parse configuration (like action-yaml, git-repo, and GitHub CLI readers). Additionally, validation and error handling modules (under src/model/error) help ensure the build is executed correctly.
• Testing & Integrity Components: There are tests (both unit and integration) spread across src/model/ directory and a separate test-project folder representing sample Unity projects. Incorporate these elements to acknowledge quality assurance processes.
• Distribution & Packaging: The dist folder, including its built projects and bundled scripts (index.js, sourcemap files, etc.), represents the output that is distributed as the action.
Relationships and Interactions
• The GitHub Action (triggered via GitHub Workflows) passes inputs to the Unity Builder core.
• The Unity Builder core (in the src/ folder) parses inputs through the input readers, applies validation, and sets up parameters (build parameters, versioning, caching).
• It then delegates execution to platform-specific build handlers in the dist/platforms directory.
• The cloud-runner modules provide abstraction layers for executing these builds remotely (via AWS, Docker, Kubernetes, or local providers) and report results/logs back.
• Errors are handled through a dedicated error handling module, and hooks (pre- and post-build) are executed as defined under the game-ci/command-hooks and container-hooks directories.
• Testing components validate the logic both internally (unit tests in src) and externally using the provided test-project sample.
Architectural Patterns & Design Principles
• Modular design: The project is organized into distinct modules for input parsing, cloud-runner abstraction, platform-specific operations, and error handling.
• Separation of concerns: There is a clear split between configuration (action.yml, GitHub workflows), business logic (src folder), platform-specific scripts (dist/platforms), and testing (src/tests and test-project).
• Extensibility and Provider Abstraction: Through its providers (AWS, Docker, Kubernetes, local, etc.) and workflow composition modules, the project is designed to easily extend and plug-in additional build environments.
• CI/CD Orientation: With integrated GitHub workflows and automated build/test scripts, the architecture strongly reflects continuous integration principles.
Relevant Technologies, Frameworks & Libraries
• GitHub Actions & Workflows
• Node.js/TypeScript (files in the src directory indicate a TypeScript build system)
• Unity engine integration (building Unity project assets)
• CI tooling and cloud orchestration utilities (AWS CloudFormation, Docker, Kubernetes)
• Testing frameworks (Jest, as visible from jest.config.js and test files)