Description
1. Problem Statement
Currently, Hephaestus relies exclusively on GitHub for repository data and synchronization, which prevents its usage in educational or organizational contexts where GitHub is not allowed or desired (e.g., the Technical University of Munich’s legal constraints). By not supporting GitLab, Hephaestus loses potential adoption in many academic and enterprise scenarios that prefer or require alternative hosting providers.
2. Requirements
2.1 User Stories
- Story 1: As an administrator, I want to configure GitLab as a valid Git hosting provider so that developers can use their GitLab repositories within Hephaestus.
- Story 2: As a developer, I want to link my GitLab projects (instead of GitHub) so that I can monitor my pull requests (merge requests) and see my contributions in the Hephaestus leaderboard.
- Story 3: As an educator, I want to adopt Hephaestus in a GitLab-only environment so that I can integrate it seamlessly into my university’s existing infrastructure
2.2 Terminology / Glossary
(to be created during initial sprints)
| Term | Definition |
|---|---|
| Term1 | [Definition of Term1] |
| Term2 | [Definition of Term2] |
| Term3 | [Definition of Term3] |
2.3 Analysis Object Model (AOM)
UML Class Diagram:
Key Elements:
-
GitHostingProvider: Must handle GitLab-specific data (API URLs, OAuth tokens).
-
Repository / PullRequest / Issue: Should handle GitLab’s “Merge Request” concept.
2.4 Dynamic Model (Optional)
Dynamic Model:
2.5 UI Mockups & Prototyping
Low-Fidelity Mockups:
(To be created during initial sprints)
High-Fidelity Prototypes (Optional):
(To be defined upon refinement of low-fidelity mockups)
2.6 Quality Attributes & External Constraints
- Quality Attributes:
- Interoperability: Must consistently handle GitLab’s concepts (merge requests) alongside GitHub (pull requests).
- Security: OAuth token handling must follow best practices (e.g., no plain-text storage).
- External Constraints:
- University or organizational policies requiring GitLab usage.
- GitLab’s own rate limits and API usage constraints.
3. Architecture
3.1 Design Goals
- Goal 1: Seamless authentication with GitLab (OAuth).
- Goal 2: Minimize code duplication by abstracting differences between GitHub and GitLab.
- Goal 3: Provide consistent user experience across multiple hosting providers.
3.2 Subsystem Decomposition
Subsystems Overview:
- Provider Abstraction: Existing GitHostingProviderEntity logic.
- GitLab Connector: For OAuth handling, rate limit management, and Merge Request fetching.
- Hephaestus Core: Leaderboard logic, user data, workspace management
3.3 Hardware–Software Mapping
Deployment Model:
- Node 1 (Server): Extended to handle GitLab APIs
- Node 2 (DB): Stores GitLab tokens, merge requests, etc.
- Node 3(GitLab): External hosting service for code
3.4 Data Management
Persistent Data:
- GitLab user tokens and repository metadata
- Merge Request entities stored similarly to PullRequest
Strategy Rationale:
- Leverage the same relational DB for consistent entity relationships
3.5 Access Control
User Roles:
- Admin
- Educator
- Developer
Mechanisms:
- GitLab OAuth: Validate user tokens, ensuring correct scope.
3.6 Boundary Conditions
- Initialization: Register GitLab as a provider (endpoint, OAuth client).
- Termination: Revoke GitLab tokens if user or workspace is removed
- Failure Handling: Graceful fallback if GitLab API is unreachable or rate-limited.
4. Progress Log & Additional Notes
Progress Log:
- April 15, 2025 – Epic created and requirements defined.
Additional Notes:
- This epic excludes workspace isolation tasks (covered in the “Multi-Workspace Support” epic) but references the same abstract architecture for repositories and pull/merge requests.