# GitLab CI/CD Setup for Federation Manager

This document explains how to set up and use the GitLab CI/CD pipeline for the Federation Manager project.

## Overview

The CI/CD pipeline includes a single stage with two different build jobs:
1. **Build (MR Validation)** - Builds Docker images for merge requests without pushing to registry
2. **Build and Push** - Builds Docker images and pushes them to the GitLab Container Registry for main branches

## Prerequisites

### GitLab Configuration

1. **Container Registry**: Ensure GitLab Container Registry is enabled for your project
2. **CI/CD Variables**: Configure the following variables in GitLab (Settings > CI/CD > Variables):

   | Variable | Description | Required |
   |----------|-------------|----------|
   | `CI_REGISTRY` | GitLab Container Registry URL | Auto-provided |
   | `CI_REGISTRY_USER` | Registry username | Auto-provided |
   | `CI_REGISTRY_PASSWORD` | Registry password | Auto-provided |

### Repository Setup

1. Ensure your GitLab project has a Container Registry enabled
2. The pipeline uses the project's Container Registry by default
3. Docker images will be tagged with commit SHA and 'latest'

## Pipeline Stages

### Build Stage

The build stage contains two different jobs depending on the trigger:

#### MR Build (build-mr)
- **Trigger**: On merge requests
- **Actions**:
  - Builds Docker image for validation
  - Tags with local name: `federation-manager:$CI_COMMIT_SHORT_SHA`
  - **Does NOT push to registry** (validation only)
  - No registry authentication required

#### Build and Push (build-and-push)
- **Trigger**: On main, develop branches, and tags
- **Actions**:
  - Builds Docker image
  - Tags with commit SHA and 'latest'
  - Pushes to GitLab Container Registry
  - Requires registry authentication

## Docker Image Information

### Image Naming Convention

#### Registry Images (build-and-push job)
- Registry: `$CI_REGISTRY_IMAGE/federation-manager`
- Tags:
  - `latest` - Latest build from main/develop branches
  - `$CI_COMMIT_SHORT_SHA` - Specific commit hash

#### Local Images (build-mr job)
- Local name: `federation-manager:$CI_COMMIT_SHORT_SHA`
- **Note**: These images are built locally for validation only and are NOT pushed to the registry

### Base Image
- Python 3.12 official image
- Includes system dependencies: bash, build-essential, git, wget, iptables, etc.
- Exposes port 8989
- Runs with Gunicorn (4 workers)

## Usage

### Triggering Builds

1. **Automatic triggers**:
   - **MR Build**: Create or update merge requests (builds for validation only)
   - **Build and Push**: Push to main or develop branches, create tags

2. **Manual triggers**:
   - Go to CI/CD > Pipelines in GitLab
   - Click "Run Pipeline"
   - Select branch/tag

### Build Types

#### Merge Request Validation
- **Purpose**: Validate that Docker builds work correctly before merging
- **Benefit**: Early feedback without affecting registry or consuming unnecessary resources
- **Output**: Local Docker image (not stored in registry)
- **Time**: Faster execution (no registry operations)

#### Production Builds
- **Purpose**: Create deployable images for main branches and releases
- **Output**: Images pushed to GitLab Container Registry
- **Accessibility**: Available for deployment and distribution

### Accessing Docker Images

**Note**: Only images from the `build-and-push` job are available in the registry. MR validation builds are local only.

1. **Pull from registry** (production images only):
   ```bash
   docker login registry.gitlab.com
   docker pull $CI_REGISTRY_IMAGE/federation-manager:latest
   ```

2. **Use in docker-compose**:
   ```yaml
   services:
     federation-manager:
       image: registry.gitlab.com/your-group/federation-manager/federation-manager:latest
   ```

### Monitoring Pipeline

- **Pipeline status**: GitLab project > CI/CD > Pipelines
- **Job logs**: Click on individual jobs to view logs
- **Coverage reports**: Available in merge request widgets
- **Container registry**: GitLab project > Packages & Registries > Container Registry

## Troubleshooting

### Common Issues

1. **Docker build fails**:
   - Check Dockerfile syntax
   - Verify all required files are present
   - Check .dockerignore doesn't exclude necessary files

2. **Registry push fails**:
   - Verify Container Registry is enabled
   - Check CI/CD variables are set correctly
   - Ensure sufficient permissions

3. **Build fails**:
   - Check Dockerfile syntax and build context
   - Verify all required files are present and not excluded by .dockerignore
   - Check Python 3.12 compatibility in requirements.txt
   - Ensure base image availability