ADR-005: GitHub as Code Repository
Status: Accepted
Date: 2025-06-23
Authors: Piotr Brzozowski
Reviewers: Piotr Brzozowski
GitHub is adopted as the primary platform for version control, issue tracking, project management, and community engagement for the Entirius project. This provides industry-standard development workflows, comprehensive collaboration features, and optimal visibility for open-source development.
All Entirius repositories must use “master” as the name for the main git branch to maintain consistency across the project ecosystem.
# Clone repository
git clone https://github.com/entirius/repository-name.git
# Create feature branch from master
git checkout master
git checkout -b feature/feature-name
# Commit with conventional format
git commit -m "feat: add user authentication system"
# Create pull request to master
gh pr create --title "Feature: User Authentication" --body "Description" --base master
# Review and merge
gh pr review --approve
gh pr merge --squash
- Issues: Bug tracking with templates and labels
- Projects: Kanban boards for sprint planning
- Discussions: Community Q&A and announcements
- Actions: Automated CI/CD workflows
- Security: Dependabot and CodeQL scanning
- Releases: Version management with changelogs
Entirius requires a robust version control and code management platform to support the development of both backend and frontend components. The platform must facilitate:
- Source code version control and collaboration
- Bug tracking and issue management
- Project management and workflow coordination
- CI/CD pipeline integration
- Community engagement and contributions
- Code review processes
- Release management
- Integration with development tools and services
Key considerations:
- Open-source project requiring public visibility (ADR-004)
- Modular monolith architecture with multiple components (ADR-001)
- Django backend and Next.js frontend requiring coordinated development
- Small development team with plans for community contributions
- Need for professional project management features
- Integration with documentation and deployment workflows
- Description: Use GitHub as the primary platform for version control, issue tracking, and project management
- Pros:
- Industry standard for open-source projects
- Excellent community engagement features
- Integrated CI/CD with GitHub Actions
- Advanced project management tools (Projects, Issues, Discussions)
- Comprehensive bug tracking with GitHub Issues
- Issue templates and automated workflows
- Strong integration ecosystem
- Built-in security features (Dependabot, CodeQL)
- Free for open-source projects
- Excellent documentation hosting (GitHub Pages)
- Native Git integration with advanced features
- Cons:
- Microsoft-owned platform (vendor lock-in)
- Limited customization compared to self-hosted solutions
- Pricing can be expensive for private repos at scale
- Some features require paid plans
- Impact on system: Seamless integration with modern development workflows
- Description: Use GitLab for version control and integrated DevOps platform
- Pros:
- Complete DevOps platform in one tool
- Excellent CI/CD capabilities
- Can be self-hosted for complete control
- Integrated project management
- Strong security features
- Good open-source offering
- Cons:
- Less community adoption than GitHub
- Steeper learning curve for team
- Self-hosted option requires infrastructure management
- Smaller ecosystem of integrations
- Less visibility for open-source projects
- Impact on system: More control but potentially reduced community engagement
- Description: Use Atlassian Bitbucket for version control with Jira integration
- Pros:
- Excellent integration with Atlassian tools (Jira, Confluence)
- Good CI/CD with Bitbucket Pipelines
- Competitive pricing for small teams
- Strong enterprise features
- Cons:
- Less popular for open-source projects
- Smaller community and ecosystem
- Limited free tier features
- Less visibility than GitHub for recruitment
- Fewer integrations with third-party tools
- Impact on system: Good for enterprise but limits open-source community growth
- Description: Self-host lightweight Git service like Gitea or Forgejo
- Pros:
- Complete control over infrastructure and data
- No vendor lock-in
- Lightweight and fast
- Cost-effective for private repositories
- Open-source solutions available
- Cons:
- Requires infrastructure management and maintenance
- Limited community features compared to GitHub
- Smaller ecosystem of integrations
- No built-in advanced security features
- Reduced visibility for open-source project
- Additional operational overhead
- Impact on system: Maximum control but increased operational complexity
Chosen option: GitHub
Key decision factors:
- Community visibility: GitHub is the de facto standard for open-source projects, maximizing project discoverability and adoption
- Developer familiarity: Most developers are familiar with GitHub workflows, reducing onboarding time and increasing contribution likelihood
- Integrated ecosystem: Seamless integration with development tools, CI/CD pipelines, documentation hosting, and third-party services
- Project management: Advanced features like GitHub Projects, Issues, Discussions, and automation support comprehensive project coordination
- Risk analysis: Minimal technical risk with mature platform, excellent uptime, and established industry standard
- Business impact: Free for open-source projects with professional features that support community growth and collaboration
- Compatibility: Excellent integration with chosen technology stack (Django, Next.js, CI/CD tools)
- Branch naming consistency: Standardizing on “master” as the main branch name ensures consistency across all Entirius repositories and simplifies automation workflows