# GitLab CI Setup & Validation
This document describes how to run and validate the GitLab CI pipeline for elektromail,
including Docker integration tests, multi-platform image publishing, and crates.io publishing.
## 1) Prerequisites
- The repository root has `.gitlab-ci.yml` that includes `.gitlab/gitlab-ci.yml`.
- GitLab Container Registry is enabled for the project.
- A Docker-capable runner is available (see below).
## 2) Runner Requirements
The pipeline uses Docker-in-Docker (DinD) and multi-arch buildx. The runner must allow:
- Docker executor (or a Kubernetes executor with DinD enabled)
- Privileged mode (required for `tonistiigi/binfmt` and buildx multi-arch)
If you use a self-managed runner, set `privileged = true` in the runner config.
## 3) Required CI Variables
Set these in **Project → Settings → CI/CD → Variables**:
- `CRATES_IO_TOKEN` (masked, protected if you only publish from tags)
GitLab automatically provides these for registry publishing:
- `CI_REGISTRY`, `CI_REGISTRY_USER`, `CI_REGISTRY_PASSWORD`
## 4) Pipeline Triggers
- **Merge Request or default branch** runs:
- `test` (fmt, clippy, tests)
- `test:docker` (container integration test)
- security jobs (deny, sbom, etc.)
- `docker:build` on default branch (pushes latest + branch tags)
- **Tag release** `vX.Y.Z`:
- `docker:build` publishes multi-platform images with `vX.Y.Z` and `latest`
- `publish:crates` is **manual** on tag (requires click in GitLab UI)
## 5) Validation Checklist (Step-by-Step)
1. Push a branch or open a Merge Request.
2. Go to **CI/CD → Pipelines** and open the latest pipeline.
3. Verify these jobs succeed:
- `test`
- `test:docker`
4. Check `test:docker` logs for:
- `docker build -t elektromail:ci .`
- `cargo test docker_procedere_smoke`
- `ELEKTROMAIL_DOCKER_HOST=docker` (required for DinD connectivity)
5. Merge to default branch (or push directly).
6. Verify `docker:build` completes on default branch.
7. Confirm images appear in **Deploy → Container Registry**:
- `latest`
- `<branch>`
- `<short SHA>`
8. Create a tag `vX.Y.Z` and push:
- `docker:build` should publish `vX.Y.Z`
- `publish:crates` appears as manual
9. Trigger `publish:crates` from the job UI.
10. Confirm the crate appears on crates.io with the tag version.
## 6) Troubleshooting
- **buildx fails or binfmt missing**: runner likely not privileged.
- **docker:build can’t push**: check registry credentials and project registry settings.
- **container_scanning can’t find image**: ensure `docker:build` ran and pushed the image tag used by `CS_IMAGE`.
- **publish:crates fails**: verify `CRATES_IO_TOKEN` and `Cargo.toml` version.