# Local GitLab E2E Environment

> **Platform note:** This guide is written primarily for **Windows** (PowerShell + Docker Desktop). All helper scripts under `scripts/` are `*.ps1`. The underlying stack is cross-platform (`docker-compose.e2e.yml` + Go integration tests); Linux/macOS users can follow [Non-Windows (manual)](#non-windows-manual) below.

Local GitLab EE via Docker for real API integration tests — no GitLab.com or corporate instance required.

> **Version:** `gitlab/gitlab-ee:18.8.10-ee.0` + `gitlab/gitlab-runner:v18.8.0` (aligned with corporate GitLab 18.8.x). EE runs in **trial mode** without a license — sufficient for gitlab-cli API E2E. Major upgrades (e.g. 17→18): **recreate volumes** (`docker compose down -v` or `e2e-down.ps1 -RemoveVolumes`); do not reuse old CE data.

See also [CONTRIBUTING.md](../CONTRIBUTING.md).

**Quick start (Windows):**

```powershell
.\scripts\e2e-up.ps1 -Wait
go test -tags=integration ./e2e/...
```

---

## Prerequisites

- **Docker Desktop** (Windows/macOS) or **Docker Engine** (Linux)
- Recommended: ≥ 8 GB RAM, ≥ 10 GB disk
- First boot: about **5–15 minutes**

---

## Windows: Install Docker (optional D: drive)

Default **GUI installer** puts Docker on `C:`. To install on **D:**, use **elevated PowerShell** + installer CLI:

```powershell
# Option A: repo script (downloads installer to %TEMP%)
# Run from repository root
.\scripts\install-docker-d.ps1 -InstallDir D:\Docker\Docker -WslDataDir D:\Docker\wsl

# Option B: when you already have DockerDesktopInstaller.exe
Start-Process -Wait -FilePath "D:\Downloads\Docker Desktop Installer.exe" -ArgumentList @(
  "install", "--accept-license",
  "--installation-dir=D:\Docker\Docker",
  "--wsl-default-data-root=D:\Docker\wsl",
  "--windows-containers-default-data-root=D:\Docker\containers"
)
```

After install:

1. Open **Docker Desktop** and wait until the engine is *Running*
2. **Settings → Resources → Advanced** — confirm **Disk image location** is on D: (some versions require a manual change)
3. If WSL data is still on C:, adjust `%UserProfile%\.wslconfig` or migrate distros (optional)

`winget` usually **cannot** choose install path; use the CLI options above for D:.

### GitLab data on D: only (Docker on C: is fine)

```powershell
.\scripts\e2e-up.ps1 -DataRoot D:\gitlab-cli-e2e -Wait
```

GitLab config/logs/data land under `D:\gitlab-cli-e2e\{config,logs,data}`.

---

## Start (Windows)

```powershell
cd gitlab-cli
.\scripts\e2e-up.ps1
# Recommended: wait for ready + PAT + register gitlab-runner (pipeline/job tests)
.\scripts\e2e-up.ps1 -Wait
# Or register runner separately (Docker must mount /var/run/docker.sock)
.\scripts\e2e-runner-register.ps1
```

### CI Runner (avoid pipeline/job SKIP)

Local GitLab has no runner by default. Compose includes **`gitlab-cli-e2e-runner`** ( **shell** executor: jobs run inside the runner container, clone via `clone_url=http://gitlab:8929`, works with Windows Docker Desktop).

**If the GitLab data volume was recreated** (`e2e-up` with a new volume), runner tokens are invalid — re-register:

```powershell
.\scripts\e2e-runner-register.ps1 -Force
```

The register script clears config and re-registers when `verify` fails; `e2e-wait.ps1` also attempts registration at the end.

```powershell
.\scripts\e2e-wait.ps1           # auto-calls e2e-runner-register.ps1 at the end
.\scripts\e2e-runner-register.ps1
docker logs -f gitlab-cli-e2e-runner
```

| Item | Value |
|------|--------|
| Web UI | http://localhost:8929 |
| User | `root` |
| Default password | `Xk9#mQ7vL2pRn4W8!` (override with `-RootPassword`; avoid common words like `Gitlab` — policy may reject) |
| Web login fails | `.\scripts\e2e-reset-password.ps1` |

---

## Wait for ready / obtain PAT (Windows)

```powershell
.\scripts\e2e-wait.ps1
```

On success, writes to `scripts/e2e.local.env` (gitignored):

```env
GITLAB_CLI_HOST=http://localhost:8929
GITLAB_CLI_TOKEN=glpat-...
```

You can also create a PAT in the UI (scope: **api**).

---

## Verify CLI (Windows)

```powershell
$env:GITLAB_CLI_HOST = "http://localhost:8929"
$env:GITLAB_CLI_TOKEN = "<PAT>"
gitlab-cli doctor --compact
gitlab-cli project list --limit 5 --compact
```

Acceptance report: [E2E-ACCEPTANCE-REPORT.md](./E2E-ACCEPTANCE-REPORT.md).

---

## Test strategy

| Type | Command | Notes |
|------|---------|--------|
| Unit | `go test ./...` | `cmd/*_test.go` uses httptest mocks; **all 85 leaf commands** covered; `TestUnit_EveryLeafCommandHasTest` guards gaps |
| Integration | `go test -tags=integration ./e2e/...` | Real local GitLab; **one run per leaf command**; bootstrap seeds a project |

---

## Integration tests (real GitLab API, Windows)

```powershell
# GitLab up + PAT in scripts/e2e.local.env
.\scripts\e2e-wait.ps1
.\scripts\e2e-test.ps1

# Or one step: wait + test (first bootstrap + CI wait ~5–15 min)
.\scripts\e2e-test.ps1 -Wait
```

Manual:

```powershell
go test -tags=integration -v -count=1 -timeout=20m ./e2e/...
```

- Writes use `--dry-run` by default; reads hit the real API.
- `pipeline` / `job` cases **Skip** if CI is not ready (no failure).
- No manual signup: use `root` + PAT from `e2e-wait`.

---

## Stop (Windows)

```powershell
.\scripts\e2e-down.ps1          # keep volumes — faster next start
.\scripts\e2e-down.ps1 -Volumes # wipe data — full reset
```

---

## Non-Windows (manual)

There are **no bash wrappers** yet. Equivalent flow:

```bash
# From repo root
docker compose -f docker-compose.e2e.yml up -d

# Wait until http://localhost:8929 responds, then create a root PAT (api scope) in the UI
export GITLAB_CLI_HOST=http://localhost:8929
export GITLAB_CLI_TOKEN=glpat-...

gitlab-cli doctor --compact
go test -tags=integration -v -count=1 -timeout=20m ./e2e/...
```

Runner registration on Linux/macOS: inspect `scripts/e2e-runner-register.ps1` and register a runner against the compose network, or accept pipeline/job **Skip** in integration tests.

Contributions welcome: `scripts/e2e-up.sh` / `e2e-wait.sh` parity with the PowerShell scripts.

---

## CI

GitHub Actions can use `services: gitlab` or this compose file. GitLab containers need memory and long startup — CI typically runs a **smoke subset** (`doctor`, `auth status`, `project list`) only. Full 85-command E2E is intended for **local** runs (documented above for Windows).