SilverDROID/GITLAB_CICD_SETUP.md

# GitLab CI/CD Setup for SilverDROID

Complete guide for setting up automated Android builds on your GitLab CE instance.

---

## 🎯 Overview

This CI/CD pipeline automatically:
- ✅ Builds Debug and Release APKs
- ✅ Runs lint checks and unit tests
- ✅ Generates Android App Bundles (AAB)
- ✅ Stores build artifacts
- ✅ Creates deployment environments
- ✅ Sends build notifications

---

## 📋 Prerequisites

### 1. GitLab CE Instance
**URL:** https://gitlab.silverlabs.uk
**Access Token:** `glpat-wqUcD7mg53F1mgM-N-PdiW86MQp1OjEH.01.0w074ox93`

### 2. GitLab Runner
You need at least one GitLab Runner configured with:
- Docker executor
- Sufficient resources (4GB RAM, 20GB disk)

---

## 🚀 Quick Setup

### Step 1: Initialize Git Repository

```bash
cd /mnt/c/Production/Source/SilverLABS/SilverDROID

# Initialize git (if not already)
git init

# Add remote
git remote add origin https://gitlab.silverlabs.uk/SilverLABS/silverdroid.git

# Add all files
git add .

# Commit
git commit -m "Initial commit - SilverDROID Dark Side Admin"

# Push to GitLab
git push -u origin main
```

### Step 2: Create GitLab Project

**Via GitLab Web UI:**
1. Go to https://gitlab.silverlabs.uk
2. Click "New Project"
3. Choose "Create blank project"
4. Project name: `silverdroid`
5. Namespace: `SilverLABS`
6. Visibility: `Private`
7. Click "Create project"

**Or via API:**
```bash
curl --request POST "https://gitlab.silverlabs.uk/api/v4/projects" \
  --header "PRIVATE-TOKEN: glpat-wqUcD7mg53F1mgM-N-PdiW86MQp1OjEH.01.0w074ox93" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "SilverDROID",
    "path": "silverdroid",
    "namespace_id": <SilverLABS_group_id>,
    "visibility": "private",
    "description": "Android PWA/WASM Launcher - Dark Side Admin"
  }'
```

### Step 3: Configure GitLab Runner

**Check existing runners:**
```bash
# On your GitLab server
gitlab-runner list
```

**Register a new runner (if needed):**
```bash
gitlab-runner register \
  --url https://gitlab.silverlabs.uk \
  --registration-token <PROJECT_REGISTRATION_TOKEN> \
  --executor docker \
  --docker-image mingc/android-build-box:latest \
  --description "Android Build Runner" \
  --tag-list "android,docker" \
  --docker-privileged=false \
  --docker-volumes "/cache"
```

---

## 🏗️ Pipeline Architecture

### Stages

```yaml
stages:
  - prepare      # Download dependencies
  - test         # Lint, unit tests, security scan
  - build        # Build APKs and AAB
  - deploy       # Deploy artifacts, notifications
```

### Jobs Overview

| Job | Stage | Trigger | Output |
|-----|-------|---------|--------|
| `prepare:dependencies` | prepare | All branches | Cached Gradle deps |
| `lint` | test | All branches | Lint reports |
| `unit_tests` | test | All branches | Test results |
| `security:scan` | test | main/develop | Security report |
| `build:debug` | build | All branches | app-debug.apk |
| `build:release` | build | main/tags | app-release.apk |
| `build:bundle` | build | main/tags | app-release.aab |
| `deploy:staging` | deploy | develop | Staging deployment |
| `deploy:production` | deploy | tags | Production (manual) |
| `apk:info` | deploy | main/develop | Build metadata |
| `notify:*` | deploy | main | Notifications |

---

## 🔧 Configuration

### Pipeline Variables

Set these in GitLab: **Settings → CI/CD → Variables**

#### Required Variables
None! Pipeline works out of the box.

#### Optional Variables (for signed APKs)

```yaml
KEYSTORE_FILE         # Base64 encoded keystore
KEYSTORE_PASSWORD     # Keystore password
KEY_ALIAS             # Key alias
KEY_PASSWORD          # Key password
```

### Branches Strategy

- **`main`** - Production builds (Release APK)
- **`develop`** - Staging builds (Debug APK)
- **`feature/*`** - Feature branches (Debug APK only)
- **`tags`** - Release tags (Signed Release + AAB)

---

## 📦 Build Artifacts

### Artifact Storage

All artifacts are stored in GitLab and accessible via:

```
Project → CI/CD → Pipelines → [Pipeline] → Jobs → [Job] → Browse
```

### Download URLs

**Debug APK:**
```
https://gitlab.silverlabs.uk/SilverLABS/silverdroid/-/jobs/artifacts/main/raw/app/build/outputs/apk/debug/app-debug.apk?job=build:debug
```

**Release APK:**
```
https://gitlab.silverlabs.uk/SilverLABS/silverdroid/-/jobs/artifacts/main/raw/app/build/outputs/apk/release/app-release-unsigned.apk?job=build:release
```

### Retention

- Debug APKs: 30 days
- Release APKs: 90 days
- Test reports: 7 days
- AAB bundles: 90 days

---

## 🎨 Pipeline Badges

Add to your README.md:

```markdown
[![Pipeline Status](https://gitlab.silverlabs.uk/SilverLABS/silverdroid/badges/main/pipeline.svg)](https://gitlab.silverlabs.uk/SilverLABS/silverdroid/-/commits/main)

[![Coverage](https://gitlab.silverlabs.uk/SilverLABS/silverdroid/badges/main/coverage.svg)](https://gitlab.silverlabs.uk/SilverLABS/silverdroid/-/commits/main)
```

---

## 🔐 Signing Release APKs

### Step 1: Create Keystore

```bash
keytool -genkey -v -keystore silverdroid.keystore \
  -alias silverdroid -keyalg RSA -keysize 2048 -validity 10000
```

### Step 2: Encode Keystore

```bash
base64 -w 0 silverdroid.keystore > keystore.base64
```

### Step 3: Add to GitLab Variables

1. Go to **Settings → CI/CD → Variables**
2. Add these variables (all marked as "Protected" and "Masked"):

```
KEYSTORE_FILE         = <contents of keystore.base64>
KEYSTORE_PASSWORD     = <your keystore password>
KEY_ALIAS             = silverdroid
KEY_PASSWORD          = <your key password>
```

### Step 4: Update .gitlab-ci.yml

Add signing configuration to `build:release`:

```yaml
build:release:
  stage: build
  before_script:
    - echo $KEYSTORE_FILE | base64 -d > silverdroid.keystore
    - export KEYSTORE_FILE=silverdroid.keystore
  script:
    - ./gradlew assembleRelease \
        -Pandroid.injected.signing.store.file=$KEYSTORE_FILE \
        -Pandroid.injected.signing.store.password=$KEYSTORE_PASSWORD \
        -Pandroid.injected.signing.key.alias=$KEY_ALIAS \
        -Pandroid.injected.signing.key.password=$KEY_PASSWORD
  after_script:
    - rm -f silverdroid.keystore
```

---

## 🔄 TeamCity Integration

Trigger TeamCity builds from GitLab:

### Add to .gitlab-ci.yml:

```yaml
trigger:teamcity:
  stage: deploy
  script:
    - |
      curl -X POST "https://cis1.silverlabs.uk/app/rest/buildQueue" \
        -H "Authorization: Bearer eyJ0eXAiOiAiVENWMiJ9.eWxqS3hnMTNlS0Ezb0hMX0tuSHhkUDJ2eFUw.Y2M1NzRiMzQtNTE2Yy00MjMyLWE5MmEtZTg5OGVjYWNiMjc1" \
        -H "Content-Type: application/xml" \
        -d "<build><buildType id='SilverDROID_Build'/></build>"
  only:
    - main
```

---

## 📊 Monitoring

### Pipeline Status

View pipeline status:
```
https://gitlab.silverlabs.uk/SilverLABS/silverdroid/-/pipelines
```

### Job Logs

Access detailed logs:
```
Project → CI/CD → Jobs → [Select Job]
```

### Build Duration

Average pipeline duration: ~5-8 minutes
- prepare: ~1 min
- test: ~2 min
- build: ~3-5 min
- deploy: ~30 sec

---

## 🐛 Troubleshooting

### Pipeline Fails on First Run

**Issue:** Gradle dependencies download timeout

**Solution:**
1. Increase job timeout: Settings → CI/CD → General pipelines → Timeout
2. Set to 30 minutes for first run
3. Subsequent runs use cache (~5 min)

### Runner Out of Memory

**Issue:** Build fails with "Out of memory" error

**Solution:**
Edit runner config (`/etc/gitlab-runner/config.toml`):
```toml
[[runners]]
  [runners.docker]
    memory = "4g"
    memory_swap = "4g"
```

Restart runner:
```bash
gitlab-runner restart
```

### Gradle Wrapper Not Executable

**Issue:** `Permission denied: ./gradlew`

**Solution:**
Already fixed in pipeline with:
```yaml
before_script:
  - chmod +x ./gradlew
```

### Artifacts Not Appearing

**Issue:** Can't find APK after build

**Solution:**
1. Check job artifacts tab
2. Verify artifact expiration hasn't passed
3. Check `paths:` in `.gitlab-ci.yml`

---

## 🔔 Notifications

### Slack/Mattermost Integration

Update notification jobs in `.gitlab-ci.yml`:

```yaml
notify:success:
  script:
    - |
      curl -X POST "YOUR_WEBHOOK_URL" \
        -H "Content-Type: application/json" \
        -d "{
          \"text\": \"✅ Build #${CI_PIPELINE_ID} succeeded\",
          \"username\": \"GitLab CI\",
          \"icon_emoji\": \":white_check_mark:\"
        }"
```

### Email Notifications

Configure in GitLab:
1. Settings → Integrations → Pipelines emails
2. Add recipient emails
3. Check events to notify

---

## 📈 Advanced Features

### Parallel Builds

Build multiple variants simultaneously:

```yaml
build:variants:
  stage: build
  parallel:
    matrix:
      - VARIANT: [debug, release]
  script:
    - ./gradlew assemble${VARIANT}
```

### Merge Request Pipelines

Automatic builds on MRs (already configured):
```yaml
only:
  - merge_requests
```

### Scheduled Pipelines

Nightly builds:
1. CI/CD → Schedules → New schedule
2. Cron: `0 2 * * *` (2 AM daily)
3. Target branch: `develop`
4. Variables: `BUILD_TYPE=nightly`

---

## 📝 Testing the Pipeline

### Trigger a Build

```bash
# Make a change
echo "# Test" >> README.md

# Commit and push
git add README.md
git commit -m "Test CI/CD pipeline"
git push origin main
```

### Monitor Progress

```bash
# View pipeline status
curl "https://gitlab.silverlabs.uk/api/v4/projects/SilverLABS%2Fsilverdroid/pipelines?per_page=1" \
  --header "PRIVATE-TOKEN: glpat-wqUcD7mg53F1mgM-N-PdiW86MQp1OjEH.01.0w074ox93"
```

---

## ✅ Checklist

- [ ] GitLab project created
- [ ] Repository pushed to GitLab
- [ ] Runner registered and active
- [ ] Pipeline executed successfully
- [ ] Artifacts generated and downloadable
- [ ] (Optional) Signing configured
- [ ] (Optional) Notifications configured
- [ ] (Optional) TeamCity integration added

---

## 📞 Support

### Resources
- **GitLab Docs:** https://docs.gitlab.com/ee/ci/
- **Docker Image:** https://github.com/mingchen/docker-android-build-box
- **Pipeline File:** `.gitlab-ci.yml` (in project root)

### SilverLABS Infrastructure
- **GitLab:** https://gitlab.silverlabs.uk
- **TeamCity:** https://cis1.silverlabs.uk
- **Token:** (See ~/.claude/CLAUDE.md)

---

## 🎉 You're All Set!

Your Android CI/CD pipeline is ready to:
- Automatically build APKs on every push
- Run tests and quality checks
- Store artifacts for download
- Deploy to staging/production

Push your code and watch the magic happen! ✨