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

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:

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:

# On your GitLab server
gitlab-runner list

Register a new runner (if needed):

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

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)

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:

[![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

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

Step 2: Encode Keystore

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:

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:

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):

[[runners]]
  [runners.docker]
    memory = "4g"
    memory_swap = "4g"

Restart runner:

gitlab-runner restart

Gradle Wrapper Not Executable

Issue: Permission denied: ./gradlew

Solution: Already fixed in pipeline with:

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:

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:

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

Merge Request Pipelines

Automatic builds on MRs (already configured):

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

# 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

# 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! ✨