# GitLab CI/CD Complete Stack

> Self-hosted GitLab with integrated CI/CD runners, container registry, and monitoring

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: gitlab, gitlab-runner, registry, prometheus, grafana
- Tags: gitlab, ci-cd, git, registry, runners, devops
- Source: https://docker.recipes/devops/gitlab-cicd-complete

## Overview

GitLab is a complete DevOps platform that originated in 2011 as a self-hosted Git repository manager and evolved into a comprehensive solution covering the entire software development lifecycle. Unlike distributed DevOps toolchains requiring integration between multiple vendors, GitLab provides source code management, CI/CD pipelines, container registry, issue tracking, security scanning, and monitoring in a unified platform. This makes it particularly valuable for organizations seeking to reduce tool sprawl and streamline their development workflow. This stack combines GitLab's core platform with dedicated GitLab Runners for CI/CD execution, MinIO for S3-compatible artifact storage, and built-in Prometheus and Grafana integration for comprehensive monitoring. The multiple runner configuration provides concurrent job execution and fault tolerance, while MinIO handles large artifact storage requirements that would otherwise burden GitLab's main storage. This architecture creates a production-grade CI/CD environment capable of handling enterprise workloads with proper resource allocation and monitoring visibility. Development teams, DevOps engineers, and organizations transitioning from hosted solutions like GitHub Actions or Jenkins will find this stack provides enterprise-level capabilities with complete data sovereignty. The integrated monitoring through Prometheus and Grafana offers insights into both GitLab performance and CI/CD pipeline metrics, making it ideal for teams that need visibility into their development infrastructure performance and want to optimize build times and resource utilization.

## Features

- Complete DevOps platform with integrated Git repositories, issue tracking, merge requests, and wiki documentation
- Built-in CI/CD pipelines with YAML configuration supporting complex workflows, parallel jobs, and deployment strategies
- Integrated Docker container registry for storing and managing application images with vulnerability scanning
- Multiple GitLab Runner instances providing concurrent job execution and high availability for CI/CD workloads
- MinIO S3-compatible storage backend for GitLab artifacts, uploads, and Git LFS objects
- Built-in Prometheus monitoring with GitLab-specific metrics and performance insights
- Integrated Grafana dashboards for visualizing GitLab performance, runner utilization, and pipeline metrics
- Auto DevOps capabilities with automatic CI/CD pipeline generation based on detected project types

## Use cases

- Enterprise software development teams needing complete DevOps platform with on-premises data control
- Organizations migrating from Jenkins or GitHub Actions seeking integrated CI/CD with better pipeline visualization
- Development teams requiring private container registry alongside their source code and CI/CD infrastructure
- Companies building microservices architectures needing coordinated multi-project CI/CD with shared runners
- DevOps teams implementing GitOps workflows with integrated monitoring and alerting capabilities
- Educational institutions teaching DevOps practices with a complete, self-contained development platform
- Startups and small companies wanting enterprise-grade DevOps tools without SaaS subscription costs

## Prerequisites

- Minimum 8GB RAM recommended for GitLab, with additional 2GB for runners and monitoring components
- Docker and Docker Compose installed with at least 50GB available disk space for repositories and artifacts
- Ports 80, 443, 22, 5050, 9000, and 9001 available for GitLab, registry, and MinIO access
- Understanding of Git workflows, CI/CD concepts, and Docker containerization principles
- Basic knowledge of YAML for GitLab CI pipeline configuration and Docker Compose management
- Familiarity with Prometheus metrics and Grafana dashboard concepts for monitoring setup

## docker-compose.yml

```yaml
services:
  gitlab:
    image: gitlab/gitlab-ee:latest
    container_name: gitlab
    restart: unless-stopped
    hostname: gitlab.local
    ports:
      - "${HTTP_PORT:-80}:80"
      - "${HTTPS_PORT:-443}:443"
      - "${SSH_PORT:-22}:22"
    volumes:
      - gitlab_config:/etc/gitlab
      - gitlab_logs:/var/log/gitlab
      - gitlab_data:/var/opt/gitlab
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://${GITLAB_HOST:-localhost}'
        gitlab_rails['gitlab_shell_ssh_port'] = ${SSH_PORT:-22}
        registry_external_url 'http://${REGISTRY_HOST:-registry.localhost}:5050'
        prometheus_monitoring['enable'] = true
        grafana['enable'] = true
    shm_size: '256m'

  gitlab-runner:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner
    restart: unless-stopped
    volumes:
      - ./runner-config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      - gitlab

  gitlab-runner-2:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner-2
    restart: unless-stopped
    volumes:
      - ./runner-config-2:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      - gitlab

  minio:
    image: minio/minio:latest
    container_name: gitlab-minio
    restart: unless-stopped
    ports:
      - "${MINIO_PORT:-9000}:9000"
      - "${MINIO_CONSOLE:-9001}:9001"
    environment:
      - MINIO_ROOT_USER=${MINIO_USER:-minioadmin}
      - MINIO_ROOT_PASSWORD=${MINIO_PASSWORD:-minioadmin}
    volumes:
      - minio_data:/data
    command: server /data --console-address ":9001"

volumes:
  gitlab_config:
  gitlab_logs:
  gitlab_data:
  minio_data:
```

## .env

```bash
# GitLab Complete Stack
HTTP_PORT=80
HTTPS_PORT=443
SSH_PORT=22
MINIO_PORT=9000
MINIO_CONSOLE=9001

# GitLab
GITLAB_HOST=gitlab.localhost
REGISTRY_HOST=registry.localhost

# MinIO for artifacts storage
MINIO_USER=minioadmin
MINIO_PASSWORD=minioadmin
```

## Usage notes

- GitLab at http://localhost (first boot takes 5-10 minutes)
- Initial root password in: docker exec gitlab cat /etc/gitlab/initial_root_password
- Register runners: docker exec gitlab-runner gitlab-runner register
- Container registry at port 5050
- MinIO provides S3-compatible artifact storage
- Configure GitLab to use MinIO for artifacts, uploads, LFS

## Troubleshooting

- GitLab 502 error on startup: Wait 10-15 minutes for complete initialization, check docker logs gitlab for 'GitLab Workhorse started' message
- Runners failing to connect: Verify runner registration token from GitLab admin area and ensure Docker socket permissions allow runner containers to spawn jobs
- Container registry push failures: Check that external registry URL matches your domain configuration and port 5050 is accessible from client machines
- MinIO connection errors in GitLab: Verify MINIO_ROOT_USER and MINIO_ROOT_PASSWORD match GitLab's object storage configuration in omnibus settings
- High memory usage and OOM kills: Increase shared memory size beyond 256m and allocate at least 8GB system RAM for GitLab container
- Prometheus metrics not appearing: Ensure prometheus_monitoring['enable'] = true in GitLab configuration and restart container to apply omnibus changes

