Skip to content

ADR-0008: CI/CD Platform Selection - GitHub Actions with Self-Hosted Runners

Status

ACCEPTED

Date: 2025-07-06

Changelog

Date Revision Description Author
2025-07-06 1.0 Initial version souperk

Context

As part of the Loryth project's Release 0.1 roadmap focusing on Core Infrastructure Setup, we need to select a CI/CD platform that meets our requirements for automation, reliability, and scalability. Our current manual deployment process lacks consistency and is becoming unsustainable as the project grows.

After thorough consideration, we've refined our requirements to prioritize:

  • Minimal infrastructure management overhead
  • Cost-effectiveness for a small development team (currently one developer)
  • Minimal maintenance requirements ("set and forget")
  • Familiarity and industry adoption
  • Support for containerized builds and deployments
  • Ability to run on affordable infrastructure (development machine or small VPS)
  • Alignment with the project's self-hosting philosophy
  • Scalability for future growth

Decision

We will implement GitHub Actions with self-hosted runners as our CI/CD platform with the following specifications:

  1. Implementation Approach:

    • GitHub-hosted platform with self-hosted runners deployed on our infrastructure
    • Configuration as code with all CI/CD pipelines defined in .github/workflows/*.yml files
    • Self-hosted runners are installed on the developer machine initially, with an option to move to VPS later

  2. Infrastructure Configuration:

    • Simple Docker-based runner setup without complex infrastructure requirements
    • Environment-specific configurations managed through GitHub environments
    • Secrets managed using GitHub's built-in secrets management

  3. Monitoring Strategy:

    • Use GitHub's built-in monitoring for CI/CD pipeline execution
    • Implement lightweight application monitoring using free tiers of monitoring services
    • Defer complex monitoring (Prometheus/Grafana) until the project scale justifies it

  4. Integration Points:

    • Native integration with our GitHub repositories
    • GitHub Container Registry for storing build artifacts
    • GitHub notifications for workflow status updates

Consequences

Positive

  • Minimal Setup: GitHub Actions provides immediate functionality with minimal setup
  • Familiar Syntax: Industry-standard YAML workflow syntax is well-documented and widely understood
  • Container-Native: Excellent support for Docker-based workflows aligns with our containerization strategy
  • Extensive Marketplace: Rich ecosystem of pre-built actions for common tasks
  • Self-Hosted Control: Using our own runners gives us control over execution environment
  • Cost Control: Self-hosted runners allow unlimited build minutes without cloud usage charges
  • Minimal Infrastructure: No need for complex infrastructure or database management

Negative

  • GitHub Dependency: Some reliance on GitHub's platform, though with self-hosting flexibility
  • Runner Maintenance: Self-hosted runners require basic maintenance and updates
  • Resource Requirements: Runners consume resources on host machine during builds
  • Security Considerations: Runner security requires proper configuration and isolation

Neutral

  • Migration Effort: Transitioning from manual deployments will require initial setup time regardless of chosen solution
  • Scaling Consideration: Future scaling may require additional runner configuration
  • GitHub API Limits: May need to consider API rate limits for very high-frequency operations

Alternatives Considered

  1. Woodpecker CI

    • Description: Open-source, lightweight CI/CD system with GitHub Actions compatibility
    • Pros:
      • Open-source and self-hostable
      • Familiar workflow syntax
      • Container-native approach
      • Resource efficient
    • Cons:
      • Requires infrastructure management (database, server)
      • Additional maintenance overhead
      • Smaller community than mainstream options
      • Needs Terraform setup for proper infrastructure management
    • Why not chosen: Infrastructure management complexity exceeds current project needs

  2. Sourcehut (sr.ht)

    • Description: Ethical, independent CI/CD and collaboration platform
    • Pros:
      • Privacy-focused and independent from large corporations
      • Clean, efficient design
      • Pay-what-you-want model
      • Email-based workflows
    • Cons:
      • Different workflow paradigm requires adjustment
      • Smaller ecosystem of integrations
      • Less polished UI compared to mainstream options
    • Why not chosen: Additional migration effort and learning curve not justified for current team size

  3. Jenkins

    • Description: Traditional, highly customizable CI/CD server with extensive plugin ecosystem
    • Pros:
      • Mature ecosystem with extensive plugin support
      • Large community and widespread adoption
      • Highly flexible and customizable
    • Cons:
      • Heavier resource requirements
      • More complex maintenance and upgrades
      • Significant technical debt in core architecture
    • Why not chosen: Excessive complexity for our current needs and higher maintenance overhead

  4. GitLab CI

    • Description: Integrated CI/CD as part of GitLab platform
    • Pros:
      • Robust and mature platform
      • Strong security features
      • Good scaling capabilities
    • Cons:
      • Would require migration to GitLab
      • Higher resource requirements for self-hosting
      • Less flexibility when using only CI component
    • Why not chosen: Would require complete platform migration from GitHub

References