Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: remove overall release plan document and add mobile app release process documentation

Browse Source
This commit is contained in:
Achintha Isuru
2026-03-06 15:26:08 -05:00
parent 6feeea920b
commit 37d8427df9
11 changed files with 818 additions and 2141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

363
docs/RELEASE/APK_SIGNING_IMPLEMENTATION_SUMMARY.md
View File

@@ -1,363 +0,0 @@
# APK Signing Implementation - Complete Summary
**Status**: ✅ Implementation Complete | 🟡 Secrets Configuration Pending
**Last Updated**: 2024
---
## 📋 What Was Implemented
### 1. GitHub Actions Workflow Updates
**File**: `.github/workflows/product-release.yml`
**New Steps Added**:
1. **🔐 Setup APK Signing** (before build)
- Detects app (worker/client) and environment (dev/stage/prod)
- Decodes keystore from GitHub Secrets
- Sets CodeMagic-compatible environment variables
- Configures `CI=true` for build.gradle.kts detection
- Gracefully handles missing secrets with warnings
2. **✅ Verify APK Signature** (after build)
- Verifies APK is properly signed using `jarsigner`
- Displays certificate details
- Shows signer information
- Provides helpful warnings if unsigned
**How It Works**:
```yaml
Setup Signing:
- Reads: ${{ secrets.WORKER_KEYSTORE_DEV_BASE64 }}
- Decodes to: /tmp/keystores/release.jks
- Sets env: CI=true, CM_KEYSTORE_PATH_STAFF=/tmp/keystores/release.jks
Build APK:
- Runs: make mobile-staff-build PLATFORM=apk MODE=release
- build.gradle.kts detects CI=true
- Uses environment variables for signing
Verify Signature:
- Checks with: jarsigner -verify app-release.apk
- Displays certificate info
```
### 2. Documentation Created
**Files Created**:
| File | Purpose | Lines |
|------|---------|-------|
| [docs/RELEASE/APK_SIGNING_SETUP.md](../../docs/RELEASE/APK_SIGNING_SETUP.md) | Complete setup guide | 300+ |
| [docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md](../../docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md) | Quick reference checklist | 120+ |
| [.github/scripts/setup-github-secrets.sh](../../.github/scripts/setup-github-secrets.sh) | Helper script | 200+ |
### 3. Scripts Created
**File**: `.github/scripts/setup-github-secrets.sh`
**Purpose**: Interactive helper to:
- Show which secrets are needed
- Generate base64 from existing keystores
- Display keytool information
- Provide copy-paste commands
**Usage**:
```bash
./.github/scripts/setup-github-secrets.sh
```
---
## 🔑 GitHub Secrets Required
**Total: 24 Secrets** (6 keystores × 4 properties each)
### Secret Naming Pattern:
```
{APP}_KEYSTORE_{ENV}_BASE64
{APP}_KEYSTORE_PASSWORD_{ENV}
{APP}_KEY_ALIAS_{ENV}
{APP}_KEY_PASSWORD_{ENV}
```
Where:
- `{APP}` = `WORKER` or `CLIENT`
- `{ENV}` = `DEV`, `STAGING`, or `PROD`
### Full List:
**Worker Mobile (12 secrets)**:
- `WORKER_KEYSTORE_DEV_BASE64`, `WORKER_KEYSTORE_PASSWORD_DEV`, `WORKER_KEY_ALIAS_DEV`, `WORKER_KEY_PASSWORD_DEV`
- `WORKER_KEYSTORE_STAGING_BASE64`, `WORKER_KEYSTORE_PASSWORD_STAGING`, `WORKER_KEY_ALIAS_STAGING`, `WORKER_KEY_PASSWORD_STAGING`
- `WORKER_KEYSTORE_PROD_BASE64`, `WORKER_KEYSTORE_PASSWORD_PROD`, `WORKER_KEY_ALIAS_PROD`, `WORKER_KEY_PASSWORD_PROD`
**Client Mobile (12 secrets)**:
- `CLIENT_KEYSTORE_DEV_BASE64`, `CLIENT_KEYSTORE_PASSWORD_DEV`, `CLIENT_KEY_ALIAS_DEV`, `CLIENT_KEY_PASSWORD_DEV`
- `CLIENT_KEYSTORE_STAGING_BASE64`, `CLIENT_KEYSTORE_PASSWORD_STAGING`, `CLIENT_KEY_ALIAS_STAGING`, `CLIENT_KEY_PASSWORD_STAGING`
- `CLIENT_KEYSTORE_PROD_BASE64`, `CLIENT_KEYSTORE_PASSWORD_PROD`, `CLIENT_KEY_ALIAS_PROD`, `CLIENT_KEY_PASSWORD_PROD`
---
## 🚀 How to Configure
### Step 1: Prepare Dev Keystores
Dev keystores are already in the repository:
- Worker: `apps/mobile/apps/staff/android/app/krow_with_us_staff_dev.jks`
- Client: `apps/mobile/apps/client/android/app/krow_with_us_client_dev.jks`
Generate base64:
```bash
# Worker Dev
base64 -i apps/mobile/apps/staff/android/app/krow_with_us_staff_dev.jks
# Client Dev
base64 -i apps/mobile/apps/client/android/app/krow_with_us_client_dev.jks
```
### Step 2: Retrieve Staging/Prod Keystores
**Option A**: From CodeMagic
1. Go to CodeMagic → Team Settings → Code signing identities
2. Download keystores: `krow_staff_staging.jks`, `krow_staff_prod.jks`, etc.
3. Generate base64 for each
**Option B**: From Secure Storage
1. Retrieve from your organization's key management system
2. Generate base64 for each
### Step 3: Add to GitHub
1. Go to: **Repository → Settings → Secrets and variables → Actions**
2. Click: **New repository secret**
3. Add all 24 secrets (use checklist: [GITHUB_SECRETS_CHECKLIST.md](../../docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md))
### Step 4: Test the Workflow
```bash
# Test with dev environment first
# Go to: Actions → Product Release → Run workflow
# Select:
# - App: worker-mobile-app
# - Environment: dev
# - Version type: patch
# - Create GitHub Release: true
```
**Expected Output**:
```
🔐 Setting up Android signing for worker-mobile-app in dev environment...
✅ Keystore decoded successfully
📦 Keystore size: 3.2K
✅ Signing environment configured for STAFF (dev environment)
🔑 Using key alias: krow_staff_dev
📱 Building Staff (Worker) APK...
✅ APK built successfully
🔍 Verifying APK signature...
✅ APK is properly signed!
📜 Certificate Details: [shows cert info]
```
---
## 🔒 Security Considerations
### ✅ Safe Practices
1. **Dev keystores in repo**: Acceptable for development
- Committed: `krow_with_us_staff_dev.jks`, `krow_with_us_client_dev.jks`
- Password: `krowwithus` (public knowledge)
2. **Staging/Prod keystores**: ONLY in GitHub Secrets
- Never commit to repository
- Encrypted at rest by GitHub
- Only accessible in workflow runs
3. **Keystore cleanup**: Workflow stores in `${{ runner.temp }}`
- Automatically deleted after job completes
- Not persisted in artifacts or logs
### ⚠️ Important Notes
1. **Same keystores as CodeMagic**: Use identical keystores to ensure app updates work
2. **Signature consistency**: Apps signed with different keystores cannot update each other
3. **Key rotation**: Document process for rotating production keys
4. **Backup keystores**: Keep secure backups - lost keystores = can't update app
---
## 🧪 Testing Checklist
Before using in production:
- [ ] Configure all 24 GitHub Secrets
- [ ] Run workflow with `dev` environment
- [ ] Download APK artifact
- [ ] Verify signature: `jarsigner -verify -verbose app.apk`
- [ ] Install APK on Android device
- [ ] Launch app and verify functionality
- [ ] Compare signature fingerprints with CodeMagic builds
- [ ] Test `stage` environment
- [ ] Test `prod` environment (after full validation)
---
## 📊 Architecture Overview
```
┌─────────────────────────────────────────────────────────────┐
│ GitHub Actions Workflow: product-release.yml │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. Validate & Create Release │
│ └─> Extract version from pubspec.yaml │
│ └─> Create Git tag │
│ └─> Create GitHub Release │
│ │
│ 2. Build Mobile Artifacts │
│ │ │
│ ├─> Setup Node.js + Firebase CLI │
│ ├─> Setup Java 17 │
│ ├─> Setup Flutter 3.24.5 │
│ ├─> Install Melos │
│ ├─> Install Dependencies │
│ │ │
│ ├─> 🔐 Setup APK Signing (NEW) │
│ │ ├─> Detect app (worker/client) │
│ │ ├─> Detect environment (dev/stage/prod) │
│ │ ├─> Read GitHub Secret: │
│ │ │ {APP}_KEYSTORE_{ENV}_BASE64 │
│ │ ├─> Decode base64 → .jks file │
│ │ ├─> Set environment variables: │
│ │ │ - CI=true │
│ │ │ - CM_KEYSTORE_PATH_STAFF=/tmp/keystore.jks │
│ │ │ - CM_KEYSTORE_PASSWORD_STAFF=*** │
│ │ │ - CM_KEY_ALIAS_STAFF=krow_staff_dev │
│ │ │ - CM_KEY_PASSWORD_STAFF=*** │
│ │ └─> ✅ Ready for signed build │
│ │ │
│ ├─> 🏗️ Build APK │
│ │ └─> make mobile-staff-build PLATFORM=apk │
│ │ └─> Flutter build detects CI=true │
│ │ └─> build.gradle.kts uses env vars │
│ │ └─> Signs APK with keystore │
│ │ │
│ ├─> ✅ Verify APK Signature (NEW) │
│ │ ├─> jarsigner -verify app-release.apk │
│ │ ├─> Show certificate details │
│ │ └─> Confirm signing successful │
│ │ │
│ ├─> 📤 Upload APK as Artifact │
│ │ └─> 30-day retention in GitHub Actions │
│ │ │
│ └─> 📦 Attach APK to GitHub Release │
│ └─> krow-withus-worker-mobile-dev-v0.1.0.apk │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Build Configuration: build.gradle.kts │
├─────────────────────────────────────────────────────────────┤
│ │
│ signingConfigs { │
│ create("release") { │
│ if (System.getenv()["CI"] == "true") { │
│ // ✅ GitHub Actions / CodeMagic │
│ storeFile = file( │
│ System.getenv()["CM_KEYSTORE_PATH_STAFF"] │
│ ) │
│ storePassword = │
│ System.getenv()["CM_KEYSTORE_PASSWORD_*"] │
│ keyAlias = │
│ System.getenv()["CM_KEY_ALIAS_*"] │
│ keyPassword = │
│ System.getenv()["CM_KEY_PASSWORD_*"] │
│ } else { │
│ // Local Development │
│ use key.properties file │
│ } │
│ } │
│ } │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## 📖 Documentation Index
1. **[APK_SIGNING_SETUP.md](../../docs/RELEASE/APK_SIGNING_SETUP.md)**
- Complete setup guide with all details
- Security best practices
- Troubleshooting guide
- Keystore management commands
2. **[GITHUB_SECRETS_CHECKLIST.md](../../docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md)**
- Quick reference for all 24 secrets
- Copy-paste checklist
- Dev environment values
3. **[setup-mobile-github-secrets.sh](../../.github/scripts/setup-mobile-github-secrets.sh)**
- Interactive helper script
- Shows existing keystores
- Generates base64 commands
- Displays keytool info
4. **[product-release.yml](../../.github/workflows/product-release.yml)**
- Updated workflow with signing
- Lines 198-294: Setup APK Signing
- Lines 330-364: Verify APK Signature
---
## ✅ Next Steps
### Immediate (Required for Signed APKs)
1. **Configure GitHub Secrets** (30 minutes)
- Start with dev environment (test first)
- Use helper script: `.github/scripts/setup-mobile-github-secrets.sh`
- Follow checklist: `docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md`
2. **Test Dev Signing** (15 minutes)
- Run workflow with dev environment
- Download APK and verify signature
- Install on device and test
3. **Configure Staging/Prod** (30 minutes)
- Retrieve keystores from CodeMagic/secure storage
- Add to GitHub Secrets
- Test each environment
### Future Enhancements (Optional)
- [ ] Add AAB (Android App Bundle) support for Play Store
- [ ] Implement iOS signing for IPA files
- [ ] Add automated Play Store upload
- [ ] Set up GitHub Environments with protection rules
- [ ] Add Slack notifications for releases
---
## 🆘 Support
If you encounter issues:
1. Check workflow logs for signing step output
2. Verify GitHub Secrets are configured correctly
3. Run helper script: `.github/scripts/setup-mobile-github-secrets.sh`
4. Review: `docs/RELEASE/APK_SIGNING_SETUP.md` → Troubleshooting section
**Common Issues**:
- "Keystore not found" → Secret not configured or wrong name
- "Wrong password" → Secret value doesn't match actual keystore
- APK unsigned → CI=true not set or build.gradle.kts issue
- App won't install over existing → Different keystore used
---
**Implementation Date**: 2024
**Implemented By**: GitHub Copilot (Claude Sonnet 4.5)
**Status**: ✅ Code Complete | 🟡 Awaiting Secrets Configuration

282
docs/RELEASE/APK_SIGNING_SETUP.md
View File

@@ -1,282 +0,0 @@
# APK Signing Setup for GitHub Actions
**For Worker Mobile & Client Mobile Apps**
---
## 📋 Overview
This document explains how to set up APK signing for automated builds in GitHub Actions. The same keystore files used in CodeMagic will be used here.
---
## 🔑 Understanding App Signing
### Why Sign APKs?
- **Required by Google Play**: All Android apps must be signed before distribution
- **App Identity**: The signature identifies your app across updates
- **Security**: Ensures the APK hasn't been tampered with
### Keystore Files
Each app and environment combination has its own keystore:
**Worker Mobile (Staff App):**
- `krow_staff_dev.jks` - Development builds
- `krow_staff_staging.jks` - Staging builds
- `krow_staff_prod.jks` - Production builds
**Client Mobile:**
- `krow_client_dev.jks` - Development builds
- `krow_client_staging.jks` - Staging builds
- `krow_client_prod.jks` - Production builds
### Current State
- ✅ **Dev keystores** are committed to the repository (in `apps/mobile/apps/*/android/app/`)
- ⚠️ **Staging/Prod keystores** are stored securely in CodeMagic (NOT in repo)
---
## 🔐 GitHub Secrets Setup
### Step 1: Export Keystores as Base64
For staging and production keystores (stored in CodeMagic), you'll need to:
```bash
# On your local machine with access to the keystore files:
# For Worker Mobile - Staging
base64 -i krow_staff_staging.jks -o krow_staff_staging.jks.base64
# For Worker Mobile - Production
base64 -i krow_staff_prod.jks -o krow_staff_prod.jks.base64
# For Client Mobile - Staging
base64 -i krow_client_staging.jks -o krow_client_staging.jks.base64
# For Client Mobile - Production
base64 -i krow_client_prod.jks -o krow_client_prod.jks.base64
```
### Step 2: Create GitHub Secrets
Go to: **GitHub Repository → Settings → Secrets and variables → Actions → New repository secret**
Create the following secrets:
#### Worker Mobile (Staff App) Secrets
| Secret Name | Value | Environment |
|-------------|-------|-------------|
| `WORKER_KEYSTORE_DEV_BASE64` | (base64 of dev keystore) | dev |
| `WORKER_KEYSTORE_STAGING_BASE64` | (base64 of staging keystore) | stage |
| `WORKER_KEYSTORE_PROD_BASE64` | (base64 of prod keystore) | prod |
| `WORKER_KEYSTORE_PASSWORD_DEV` | `krowwithus` | dev |
| `WORKER_KEYSTORE_PASSWORD_STAGING` | (actual staging password) | stage |
| `WORKER_KEYSTORE_PASSWORD_PROD` | (actual prod password) | prod |
| `WORKER_KEY_ALIAS_DEV` | `krow_staff_dev` | dev |
| `WORKER_KEY_ALIAS_STAGING` | (actual staging alias) | stage |
| `WORKER_KEY_ALIAS_PROD` | (actual prod alias) | prod |
| `WORKER_KEY_PASSWORD_DEV` | `krowwithus` | dev |
| `WORKER_KEY_PASSWORD_STAGING` | (actual staging key password) | stage |
| `WORKER_KEY_PASSWORD_PROD` | (actual prod key password) | prod |
#### Client Mobile Secrets
| Secret Name | Value | Environment |
|-------------|-------|-------------|
| `CLIENT_KEYSTORE_DEV_BASE64` | (base64 of dev keystore) | dev |
| `CLIENT_KEYSTORE_STAGING_BASE64` | (base64 of staging keystore) | stage |
| `CLIENT_KEYSTORE_PROD_BASE64` | (base64 of prod keystore) | prod |
| `CLIENT_KEYSTORE_PASSWORD_DEV` | `krowwithus` | dev |
| `CLIENT_KEYSTORE_PASSWORD_STAGING` | (actual staging password) | stage |
| `CLIENT_KEYSTORE_PASSWORD_PROD` | (actual prod password) | prod |
| `CLIENT_KEY_ALIAS_DEV` | `krow_client_dev` | dev |
| `CLIENT_KEY_ALIAS_STAGING` | (actual staging alias) | stage |
| `CLIENT_KEY_ALIAS_PROD` | (actual prod alias) | prod |
| `CLIENT_KEY_PASSWORD_DEV` | `krowwithus` | dev |
| `CLIENT_KEY_PASSWORD_STAGING` | (actual staging key password) | stage |
| `CLIENT_KEY_PASSWORD_PROD` | (actual prod key password) | prod |
---
## ⚙️ How It Works in GitHub Actions
### Build Configuration Detection
The `build.gradle.kts` files check for `CI=true` environment variable:
```kotlin
signingConfigs {
create("release") {
if (System.getenv()["CI"] == "true") {
// CI environment (CodeMagic or GitHub Actions)
storeFile = file(System.getenv()["CM_KEYSTORE_PATH_STAFF"] ?: "")
storePassword = System.getenv()["CM_KEYSTORE_PASSWORD_STAFF"]
keyAlias = System.getenv()["CM_KEY_ALIAS_STAFF"]
keyPassword = System.getenv()["CM_KEY_PASSWORD_STAFF"]
} else {
// Local development (uses key.properties)
keyAlias = keystoreProperties["keyAlias"] as String?
keyPassword = keystoreProperties["keyPassword"] as String?
storeFile = keystoreProperties["storeFile"]?.let { file(it) }
storePassword = keystoreProperties["storePassword"] as String?
}
}
}
```
### GitHub Actions Workflow Steps
1. **Decode Keystore**: Convert base64 secret back to `.jks` file
2. **Set Environment Variables**: Provide the same env vars CodeMagic uses
3. **Build APK**: Flutter build automatically uses the signing config
4. **Verify Signature**: Optionally verify the APK is signed correctly
---
## 🚀 Usage
### For Development Builds
Dev keystores are already in the repo, so GitHub Actions will automatically use them:
```bash
# No special setup needed for dev builds
# They use committed keystores: krow_with_us_staff_dev.jks
```
### For Staging/Production Builds
Once GitHub Secrets are configured (Step 2 above), the workflow will:
1. Detect the environment (dev/stage/prod)
2. Use the appropriate keystore secret
3. Decode it before building
4. Sign the APK automatically
---
## ✅ Verification
### Check APK Signature
After building, verify the APK is signed:
```bash
# Using keytool (part of Java JDK)
keytool -printcert -jarfile app-release.apk
# Expected output should show certificate info with your key alias
```
### Check Build Logs
In GitHub Actions, look for:
```
✅ Keystore decoded successfully
✅ APK signed with: krow_staff_prod
✅ APK built successfully: /path/to/app-release.apk
```
---
## 🔒 Security Best Practices
### DO:
- ✅ Store production keystores ONLY in GitHub Secrets (encrypted)
- ✅ Use different keystores for dev/staging/prod
- ✅ Rotate passwords periodically
- ✅ Limit access to repository secrets (use environment protection rules)
- ✅ Keep keystore files backed up securely offline
### DON'T:
- ❌ Never commit staging/production keystores to Git
- ❌ Never share keystore passwords in plain text
- ❌ Never use production keystores for development
- ❌ Never commit `.jks` files for staging/prod
---
## 📝 Keystore Management Commands
### Generate New Keystore
```bash
keytool -genkey -v \
-keystore krow_staff_prod.jks \
-alias krow_staff_prod \
-keyalg RSA \
-keysize 2048 \
-validity 10000 \
-storetype JKS
```
### View Keystore Info
```bash
keytool -list -v -keystore krow_staff_prod.jks
```
### Get SHA-1 and SHA-256 Fingerprints
```bash
keytool -list -v -keystore krow_staff_prod.jks -alias krow_staff_prod
```
These fingerprints are needed for:
- Firebase project configuration
- Google Maps API key restrictions
- Google Play Console app signing
---
## 🆘 Troubleshooting
### "keystore not found" Error
**Problem**: GitHub Actions can't find the decoded keystore
**Solution**: Check the decode step in the workflow creates the file in the correct location
### "wrong password" Error
**Problem**: Keystore password doesn't match
**Solution**: Verify the GitHub Secret value matches the actual keystore password
### APK Not Signed
**Problem**: APK builds but isn't signed
**Solution**: Ensure `CI=true` is set before building
### Certificate Mismatch
**Problem**: "App not installed" when updating
**Solution**: You're using a different keystore than previous builds. Use the same keystore for all versions.
---
## 📚 Related Documentation
- [Product Release Workflow](./MOBILE_RELEASE_PLAN.md)
- [Hotfix Process](./HOTFIX_PROCESS.md)
- [CodeMagic Configuration](/codemagic.yaml)
- [Android App Signing (Google Docs)](https://developer.android.com/studio/publish/app-signing)
---
## 🔄 Migration from CodeMagic
If you want to use GitHub Actions instead of CodeMagic:
1. Export all keystores from CodeMagic
2. Convert to base64 (as shown above)
3. Add to GitHub Secrets
4. Test with a dev build first
5. Verify signatures match previous releases
6. Deploy staging build for testing
7. Only then use for production
**Important**: Make sure the GitHub Actions builds produce the SAME signature as CodeMagic builds, otherwise app updates will fail!

115
docs/RELEASE/GITHUB_SECRETS_CHECKLIST.md
View File

@@ -1,115 +0,0 @@
# GitHub Secrets Checklist for APK Signing
**Quick reference for repository secret configuration**
📍 **Configure at**: Repository Settings → Secrets and variables → Actions
---
## ✅ Worker Mobile (Staff App) - 12 Secrets
### Dev Environment
- [ ] `WORKER_KEYSTORE_DEV_BASE64`
- [ ] `WORKER_KEYSTORE_PASSWORD_DEV`
- [ ] `WORKER_KEY_ALIAS_DEV`
- [ ] `WORKER_KEY_PASSWORD_DEV`
### Staging Environment
- [ ] `WORKER_KEYSTORE_STAGING_BASE64`
- [ ] `WORKER_KEYSTORE_PASSWORD_STAGING`
- [ ] `WORKER_KEY_ALIAS_STAGING`
- [ ] `WORKER_KEY_PASSWORD_STAGING`
### Production Environment
- [ ] `WORKER_KEYSTORE_PROD_BASE64`
- [ ] `WORKER_KEYSTORE_PASSWORD_PROD`
- [ ] `WORKER_KEY_ALIAS_PROD`
- [ ] `WORKER_KEY_PASSWORD_PROD`
---
## ✅ Client Mobile - 12 Secrets
### Dev Environment
- [ ] `CLIENT_KEYSTORE_DEV_BASE64`
- [ ] `CLIENT_KEYSTORE_PASSWORD_DEV`
- [ ] `CLIENT_KEY_ALIAS_DEV`
- [ ] `CLIENT_KEY_PASSWORD_DEV`
### Staging Environment
- [ ] `CLIENT_KEYSTORE_STAGING_BASE64`
- [ ] `CLIENT_KEYSTORE_PASSWORD_STAGING`
- [ ] `CLIENT_KEY_ALIAS_STAGING`
- [ ] `CLIENT_KEY_PASSWORD_STAGING`
### Production Environment
- [ ] `CLIENT_KEYSTORE_PROD_BASE64`
- [ ] `CLIENT_KEYSTORE_PASSWORD_PROD`
- [ ] `CLIENT_KEY_ALIAS_PROD`
- [ ] `CLIENT_KEY_PASSWORD_PROD`
---
## 📦 Total: 24 Secrets
**Status**: ⬜ Not Started | 🟡 In Progress | ✅ Complete
---
## 🔧 Quick Setup Commands
### Generate base64 for existing keystores:
```bash
# Worker Mobile Dev (already in repo)
base64 -i apps/mobile/apps/staff/android/app/krow_with_us_staff_dev.jks
# Client Mobile Dev (already in repo)
base64 -i apps/mobile/apps/client/android/app/krow_with_us_client_dev.jks
# For staging/prod keystores (retrieve from secure storage first):
base64 -i /path/to/krow_staff_staging.jks
base64 -i /path/to/krow_staff_prod.jks
base64 -i /path/to/krow_client_staging.jks
base64 -i /path/to/krow_client_prod.jks
```
### Or use the helper script:
```bash
.github/scripts/setup-mobile-github-secrets.sh
```
---
## 📋 Dev Environment Values (Public - Already in Repo)
**Worker Mobile:**
- Password: `krowwithus`
- Alias: `krow_staff_dev`
- Key Password: `krowwithus`
- Keystore: `apps/mobile/apps/staff/android/app/krow_with_us_staff_dev.jks`
**Client Mobile:**
- Password: `krowwithus`
- Alias: `krow_client_dev`
- Key Password: `krowwithus`
- Keystore: `apps/mobile/apps/client/android/app/krow_with_us_client_dev.jks`
---
## 🚨 Important Notes
1. **Staging/Production keystores** should NEVER be committed to the repository
2. Retrieve staging/prod keystores from:
- CodeMagic Team Settings → Code signing identities
- Or your organization's secure key management system
3. Keep keystore passwords in a password manager
4. Test with **dev environment first** before configuring staging/prod
---
## 📚 Related Documentation
- [Complete Setup Guide](./APK_SIGNING_SETUP.md)
- [Release Workflow](./MOBILE_RELEASE_PLAN.md)

343
docs/RELEASE/HOTFIX_PROCESS.md
View File

@@ -1,343 +0,0 @@
# Hotfix Process
**For Emergency Production Fixes**
---
## 🚨 When to Hotfix
Use hotfix when:
- ✅ Critical bug in production affecting users
- ✅ Data loss or security vulnerability
- ✅ Service unavailable or major feature broken
- ✅ Customer-blocking issue
**Don't use hotfix for:**
- ❌ Minor bugs (can wait for next release)
- ❌ Feature requests
- ❌ Nice-to-have improvements
- ❌ Styling issues
---
## 🔄 Hotfix Process
### Step 1: Assess & Declare Emergency
```
Issue: [Brief description]
Severity: CRITICAL / HIGH / MEDIUM
Product: [Staff Mobile / Client Mobile / Web / Backend]
Environment: Production
Impact: [How many users affected]
```
Once severity confirmed → Start hotfix immediately.
---
### Step 2: Create Hotfix Branch
```bash
# From production tag
git checkout -b hotfix/krow-withus-worker-mobile-v0.1.1 \
krow-withus-worker-mobile/prod-v0.1.0
# Verify you're on the right tag
git log -1 --oneline
```
**Format**: `hotfix/<product>-v<PATCH+1>`
---
### Step 3: Fix the Bug
```bash
# Make your fix
# Edit files, test locally
# Commit with clear message
git commit -m "fix: [issue description]
HOTFIX for production
Issue: [what happened]
Solution: [what was fixed]
Tested: [how was it tested locally]"
```
**Keep it minimal:**
- Only fix the specific bug
- Don't refactor or optimize
- Don't add new features
---
### Step 4: Update Version
Update PATCH version only (0.1.0 → 0.1.1):
**For Mobile** (`apps/mobile/apps/*/pubspec.yaml`):
```yaml
# Old
version: 0.1.0+5
# New
version: 0.1.1+6 # Only PATCH changed
```
**For Web** (`apps/web/package.json`):
```json
"version": "0.1.1"
```
**For Backend** (`backend/*/package.json`):
```json
"version": "0.1.1"
```
---
### Step 5: Update CHANGELOG
Add entry to **top** of appropriate CHANGELOG:
```markdown
| 2026-03-05 | 0.1.1 | HOTFIX: [Issue fixed] |
(previous entries below...)
```
---
### Step 6: Code Review (Expedited)
```bash
# Push hotfix branch
git push origin hotfix/krow-withus-worker-mobile-v0.1.1
# Create PR on GitHub with URGENT label
gh pr create --title "HOTFIX: [Issue description]" \
--body "**URGENT PRODUCTION FIX**
Issue: [What was broken]
Impact: [Users affected]
Solution: [What was fixed]
Testing: [Local verification]"
```
**Get approval within 15 minutes if possible.**
---
### Step 7: Merge to Main
```bash
# Review complete - merge
git checkout main
git pull origin main
git merge --ff-only hotfix/krow-withus-worker-mobile-v0.1.1
git push origin main
```
---
### Step 8: Create Production Tag
```bash
# Create tag from main
git tag -a krow-withus-worker-mobile/prod-v0.1.1 \
-m "HOTFIX: [Issue fixed]"
git push origin krow-withus-worker-mobile/prod-v0.1.1
```
---
### Step 9: Deploy to Production
```bash
# Follow your deployment procedure
# Higher priority than normal releases
./scripts/deploy-mobile-production.sh krow-withus-worker-mobile/prod-v0.1.1
```
**Deployment time**: Within 30 minutes of approval
---
### Step 10: Verify & Monitor
```bash
# Smoke tests
- App launches
- Core features work
- No new errors
# Monitor for 2 hours
- Watch error logs
- Check user reports
- Verify fix worked
```
---
### Step 11: Communicate
**Immediately after deployment:**
```markdown
🚨 PRODUCTION HOTFIX DEPLOYED
Product: Worker Mobile
Version: 0.1.1
Issue: [Fixed issue]
Impact: [Resolved for X users]
Status: ✅ Deployed & verified
No user action required.
Service restored to normal.
```
**24 hours later:**
```markdown
✅ HOTFIX STATUS UPDATE
Production hotfix v0.1.1 deployed 24 hours ago.
Zero errors reported post-deployment.
System stable.
Thank you for your patience!
```
---
## ⏱️ Timeline
```
T-0: Issue detected & reported
T+5min: Severity assessed, hotfix branch created
T+15: Fix implemented, code review started
T+30: Approved & merged, tag created
T+45: Deployed to production
T+60: Smoke tests pass, monitoring enabled
T+120: Declare emergency resolved, communicate
T+1day: Follow-up communication
```
**Total time: 2-4 hours from detection to resolution**
---
## 🚫 Common Mistakes to Avoid
❌ **Don't**:
- Skip code review (even in emergency)
- Add multiple unrelated fixes in one hotfix
- Forget to update version number
- Forget CHANGELOG entry
- Deploy without testing
- Forget to communicate with users
✅ **Do**:
- Keep hotfix minimal and focused
- Test every fix locally first
- Get at least one approval
- Update all version files
- Deploy immediately after approval
- Monitor actively for 2+ hours
---
## 📋 Hotfix Checklist
Copy for each emergency:
```
Hotfix: [Product] v[Old Version] → v[New Version]
□ Severity assessed & documented
□ Branch created from production tag
□ Bug fixed & tested locally
□ Version number updated (PATCH only)
□ CHANGELOG entry added
□ Commit message clear
□ Code review requested (marked URGENT)
□ Approval obtained
□ Merged to main
□ Production tag created
□ Tag pushed to remote
□ Deployed to production
□ Smoke tests passed
□ Error logs monitored (2+ hours)
□ Users notified
□ GitHub Release created
□ Incident documented
Total Time: ___ minutes
```
---
## 🔍 Post-Incident
After emergency is resolved:
1. **Document what happened**
- Root cause analysis
- Why it wasn't caught before
- What testing was missed
2. **Schedule postmortem** (within 24 hours)
- Review what went wrong
- Discuss prevention
- Update processes if needed
3. **Plan prevention**
- Add test coverage
- Update CI/CD checks
- Improve monitoring
4. **Communicate findings**
- Share with team
- Update documentation
- Prevent recurrence
---
## 📞 Emergency Contacts
When issue detected:
1. **Notify**:
- Release Engineer
- DevOps
- Product Owner
- Affected Team
2. **Communication Channel**:
- Slack: #emergency-releases
- Time-sensitive decisions on call
3. **Decision Maker**:
- Product Owner approves rollback vs hotfix
- Release Engineer executes
- DevOps monitors infrastructure
---
## 🔗 Related
- [OVERALL_RELEASE_PLAN.md](./OVERALL_RELEASE_PLAN.md) - Main release strategy
- [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) - Mobile-specific process
- [../../CHANGELOG.md](../../CHANGELOG.md) - Version history
---
**Last Updated**: 2026-03-05
**Severity Levels**:
- 🔴 CRITICAL: Service down, data loss, security (< 1 hour)
- 🟠 HIGH: Major feature broken, workaround available (< 4 hours)
- 🟡 MEDIUM: Minor feature affected (next release OK)

564
docs/RELEASE/MOBILE_RELEASE_PLAN.md
View File

@@ -1,564 +0,0 @@
# Mobile App Release Plan
**For Staff Mobile & Client Mobile Apps**
---
## 📱 Overview
This document covers release procedures for:
- **Staff Mobile App** (aka "Worker Mobile") - `krow-withus-worker-mobile`
- **Client Mobile App** - `krow-withus-client-mobile`
Both apps:
- Built with Flutter
- Distributed to iOS & Android app stores
- Maintain independent versions
- Have independent CHANGELOGs
- Share backend infrastructure
---
## 🏷️ Tag & Release Naming
### Tag Format
```
krow-withus-<app>-mobile/<environment>-v<major>.<minor>.<patch>
```
### Examples
**Staff Mobile (Worker Mobile)**
```
krow-withus-worker-mobile/dev-v0.1.0
krow-withus-worker-mobile/stage-v0.2.0
krow-withus-worker-mobile/prod-v1.0.0
krow-withus-worker-mobile/prod-v1.0.1-hotfix.1
```
**Client Mobile**
```
krow-withus-client-mobile/dev-v0.1.0
krow-withus-client-mobile/stage-v0.2.0
krow-withus-client-mobile/prod-v1.0.0
```
### GitHub Release Names
```
Krow With Us - Worker Mobile - DEV - v0.1.0
Krow With Us - Worker Mobile - STAGE - v0.2.0
Krow With Us - Worker Mobile - PROD - v1.0.0
Krow With Us - Client Mobile - DEV - v0.1.0
Krow With Us - Client Mobile - STAGE - v0.2.0
Krow With Us - Client Mobile - PROD - v1.0.0
```
---
## 📝 CHANGELOG Management
### Location
Each app has its own CHANGELOG in the `apps/mobile/` directory structure:
```
apps/mobile/
├── packages/
│ ├── features/
│ │ ├── staff/
│ │ │ ├── authentication/CHANGELOG.md
│ │ │ ├── home/CHANGELOG.md
│ │ │ ├── payments/CHANGELOG.md
│ │ │ ├── shifts/CHANGELOG.md
│ │ │ └── ... (other staff features)
│ │ └── client/
│ │ ├── dashboard/CHANGELOG.md
│ │ ├── orders/CHANGELOG.md
│ │ └── ... (other client features)
│ └── ... (other packages)
├── apps/
│ ├── staff_app/CHANGELOG.md ← Staff app root
│ └── client_app/CHANGELOG.md ← Client app root
└── CHANGELOG.md ← Consolidated (optional)
```
### App-Level CHANGELOG Format
**File**: `apps/mobile/apps/staff_app/CHANGELOG.md`
```markdown
# Staff Mobile App - Change Log
## [0.2.0] - 2026-03-15
### Added
- Feature X implementation
- Feature Y enhancement
- New UI component Z
### Fixed
- Bug fix for issue #123
- Crash when loading payments
### Changed
- Updated design system
- Improved performance
### Deprecated
- Removed old API endpoint
## [0.1.0] - 2026-03-01
### Added
- Initial release
- Authentication with phone & OTP
- Shift browsing and booking
- Clock in/out functionality
- Payment history view
```
### Consolidated CHANGELOG (Optional)
**File**: `apps/mobile/CHANGELOG.md` (at root of mobile folder)
High-level overview of both apps:
```markdown
# Krow Workforce - Mobile Apps - Change Log
## Staff Mobile v0.2.0 + Client Mobile v0.1.0 - 2026-03-15
### Staff Mobile v0.2.0
- Feature improvements
- Bug fixes
### Client Mobile v0.1.0
- Initial release
## Previous versions...
```
---
## 📝 Version Files
### Staff Mobile App
**Primary Version File**: `apps/mobile/apps/staff_app/pubspec.yaml`
```yaml
name: staff_app
description: "Krow With Us - Staff App"
# Version format: MAJOR.MINOR.PATCH+BUILD_NUMBER
version: 0.1.0+1
environment:
sdk: '>=3.10.0 <4.0.0'
flutter: '>=3.38.0 <4.0.0'
```
**Rules**:
- Update version before each release
- Bump build number (+1) every build
- SemVer only for version part (before +)
### Client Mobile App
**Primary Version File**: `apps/mobile/apps/client_app/pubspec.yaml`
```yaml
name: client_app
description: "Krow With Us - Client App"
version: 0.1.0+1
environment:
sdk: '>=3.10.0 <4.0.0'
flutter: '>=3.38.0 <4.0.0'
```
---
## 🚀 Release Workflow
### Step 1: Create Release Branch
```bash
cd /Users/achintha/Documents/GitHub/krow-workforce
# For Staff Mobile
git checkout -b release/staff-mobile-v0.2.0
# For Client Mobile
git checkout -b release/client-mobile-v0.2.0
```
---
### Step 2: Update Version Numbers
#### Staff Mobile Example (v0.1.0 → v0.2.0)
**File**: `apps/mobile/apps/staff_app/pubspec.yaml`
```yaml
# Old
version: 0.1.0+5
# New
version: 0.2.0+6
```
#### Client Mobile Example (v0.1.0 → v0.2.0)
**File**: `apps/mobile/apps/client_app/pubspec.yaml`
```yaml
# Old
version: 0.1.0+3
# New
version: 0.2.0+4
```
---
### Step 3: Update CHANGELOG
**File**: `apps/mobile/apps/staff_app/CHANGELOG.md`
Add entry at **top**:
```markdown
# Staff Mobile App - Change Log
## [0.2.0] - 2026-03-05
### Added
- New shift details page with profile gating
- Benefits overview section
- Auto-match functionality
### Fixed
- Payment history display bug
- Clock-in location verification
### Changed
- Updated design system components
- Improved shift booking flow
## [0.1.0] - 2026-02-15
...
```
---
### Step 4: Commit Changes
```bash
cd /Users/achintha/Documents/GitHub/krow-workforce
# Stage changes
git add apps/mobile/apps/staff_app/pubspec.yaml
git add apps/mobile/apps/staff_app/CHANGELOG.md
# Commit
git commit -m "chore(staff-mobile): bump version to 0.2.0
- Updated pubspec.yaml version: 0.1.0 → 0.2.0
- Updated build number: 5 → 6
- Updated CHANGELOG.md with v0.2.0 changes"
```
---
### Step 5: Create Pull Request
```bash
# Push release branch
git push origin release/staff-mobile-v0.2.0
# Create PR (GitHub CLI)
gh pr create \
--title "Release: Staff Mobile v0.2.0" \
--body "## Release: Staff Mobile v0.2.0
### Changes
- See CHANGELOG.md for full list
### Testing
- [ ] All tests passing
- [ ] Manual testing complete
- [ ] CodeMagic build successful
### Checklist
- [x] Version updated
- [x] CHANGELOG updated
- [x] Branch created from main
- [ ] Approved by team lead"
```
---
### Step 6: Merge to Main
Once PR is approved:
```bash
# Switch to main
git checkout main
git pull origin main
# Merge (fast-forward only)
git merge --ff-only release/staff-mobile-v0.2.0
# Push to remote
git push origin main
# Delete release branch
git push origin --delete release/staff-mobile-v0.2.0
```
---
### Step 7: Create Git Tag
```bash
# For DEV release
git tag -a krow-withus-worker-mobile/dev-v0.2.0 \
-m "Staff Mobile v0.2.0 - Dev Release
Features:
- Shift details improvements
- Benefits overview
- Auto-match functionality
Testing:
- All unit tests passing
- Manual QA on dev environment"
# For STAGE release
git tag -a krow-withus-worker-mobile/stage-v0.2.0 \
-m "Staff Mobile v0.2.0 - Stage Release"
# For PROD release
git tag -a krow-withus-worker-mobile/prod-v0.2.0 \
-m "Staff Mobile v0.2.0 - Production Release"
```
**Push tags**:
```bash
git push origin krow-withus-worker-mobile/dev-v0.2.0
git push origin krow-withus-worker-mobile/stage-v0.2.0
git push origin krow-withus-worker-mobile/prod-v0.2.0
```
---
### Step 8: Create GitHub Release
1. Go to: GitHub → Releases → Draft a new release
2. Fill in:
```
Tag version: krow-withus-worker-mobile/dev-v0.2.0
Release title:
Krow With Us - Worker Mobile - DEV - v0.2.0
Description:
## 🎯 What's New in v0.2.0
### ✨ Features
- Shift details page with profile completion gating
- Benefits overview with sick leave tracking
- Auto-match shift recommendations
### 🔧 Improvements
- Faster payment history loading
- Better shift booking UX
- Improved clock-in reliability
### 🐛 Bug Fixes
- Fixed payment display date issue
- Fixed location verification on iOS 15+
- Fixed crash when no shifts available
## 📦 Installation
**iOS**: Download via TestFlight (internal) or App Store
**Android**: Download via Play Store
## 🔗 Dependencies
Requires:
- Backend API v0.1.0+
- DataConnect schema v0.3.0+
## ⚠️ Known Issues
- Location permissions take 5-10 seconds on first install
- Workaround: Grant permissions in Settings app
## 📝 Notes for QA
- Test on actual device, not emulator
- Verify clock-in with GPS enabled
- Test all payment history edge cases
---
Release Date: 2026-03-05
Build Number: 6
```
3. **Optional**: Attach build artifacts (APK/AAB from CodeMagic)
4. **Click**: "Publish release"
---
## 🔄 Deployment Flow
### Dev Release → Staging
After dev is tested:
```bash
# Create stage tag from same commit
git tag -a krow-withus-worker-mobile/stage-v0.2.0 \
krow-withus-worker-mobile/dev-v0.2.0 \
-m "Staff Mobile v0.2.0 - Stage Release"
git push origin krow-withus-worker-mobile/stage-v0.2.0
# Deploy using CodeMagic or manual process
```
### Staging Release → Production
After QA approval:
```bash
# Create prod tag from same commit
git tag -a krow-withus-worker-mobile/prod-v0.2.0 \
krow-withus-worker-mobile/stage-v0.2.0 \
-m "Worker Mobile v0.2.0 - Production Release"
git push origin krow-withus-worker-mobile/prod-v0.2.0
# Deploy to production
```
---
## 📱 App Store Distribution
### iOS App Store
**Version Name**: Match pubspec.yaml version (0.2.0)
**Build Number**: Match pubspec.yaml build number (+6)
**Steps**:
1. Ensure TestFlight build passed
2. Submit to App Review
3. Apple reviews (3-5 days)
4. Release to users (can be phased)
### Google Play Store
**Version Name**: Match pubspec.yaml version (0.2.0)
**Version Code**: Match pubspec.yaml build number (6)
**Steps**:
1. Upload APK/AAB from CodeMagic
2. Fill in release notes (from CHANGELOG)
3. Submit for review
4. Google reviews (hours to 24h)
5. Release to users (can be phased, e.g., 10% then 100%)
---
## 🔧 Pre-Release Checklist
Before creating tags:
- [ ] All PRs merged to main
- [ ] Code review complete
- [ ] Tests passing (unit, widget, integration)
- [ ] No lint/analysis errors: `flutter analyze`
- [ ] Pubspec.yaml version updated
- [ ] Build number incremented
- [ ] CHANGELOG.md updated with date
- [ ] Screenshots prepared (fresh)
- [ ] Release notes drafted
- [ ] No hardcoded strings (use translations)
- [ ] No debug prints remaining
- [ ] Performance acceptable (app launch < 3 seconds)
- [ ] Screen lock/unlock works
- [ ] Deep links tested
- [ ] Notifications working
- [ ] GPS/location working
- [ ] Camera permissions working
- [ ] All user-facing text reviewed
---
## 🎯 Release Cadence
### Development Releases (dev)
- **Frequency**: Weekly
- **Day**: Monday 10:00 UTC
- **Process**: Quick, test in dev only
### Staging Releases (stage)
- **Frequency**: Bi-weekly (on sprint/feature completion)
- **Day**: Wednesday before production
- **Process**: Full QA testing, 1 week in staging
### Production Releases (prod)
- **Frequency**: Monthly (end of sprint)
- **Day**: Sunday/Monday morning (low traffic)
- **Process**: Full validation, market distribution
---
## 🔗 Related
- [OVERALL_RELEASE_PLAN.md](./OVERALL_RELEASE_PLAN.md) - General strategy
- [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) - Emergency procedures
- [../../CHANGELOG.md](../../CHANGELOG.md) - Root-level history
---
## 📞 Common Questions
**Q: What if I need to release just one app (not both)?**
A: Completely fine! Each app is independent. Release when ready.
**Q: Do I need to update the root CHANGELOG?**
A: Optional. If you do, keep it high-level and reference app-specific CHANGELOGs.
**Q: What about shared packages inside mobile/?**
A: If shared package updated, mention in both app CHANGELOGs.
**Q: How do I handle breaking changes?**
A: MAJOR version bump (0.x → 1.x) and clearly document in CHANGELOG.
**Q: Can I release dev and stage on different days?**
A: Yes, no fixed schedule for dev/stage. Prod should be consistent (Sundays).
---
**Last Updated**: 2026-03-05
**Owner**: Mobile Engineering Team
**Status**: Active

452
docs/RELEASE/OVERALL_RELEASE_PLAN.md
View File

@@ -1,452 +0,0 @@
# KROW Workforce - Overall Release Plan
**Document Version**: 1.0
**Created**: 2026-03-05
**Last Updated**: 2026-03-05
**Product Scope**: All products (Mobile, Web, Backend, Database)
---
## 📋 Overview
This document outlines the release strategy for KROW Workforce monorepo containing 5 products:
1. **Staff Mobile App** (Flutter - iOS/Android)
2. **Client Mobile App** (Flutter - iOS/Android)
3. **Web Dashboard** (React/Vite)
4. **Backend Services** (Node.js - Command API, Core API)
5. **Database** (Firebase Data Connect with PostgreSQL)
---
## 🔗 Versioning Strategy
### Semantic Versioning (SemVer)
All products use **Semantic Versioning 2.0.0**:
```
MAJOR.MINOR.PATCH-QUALIFIER
0.1.0
1.2.3-rc.1
```
- **MAJOR** (0→1): Breaking changes, major features
- **MINOR** (1→2): Backward-compatible new features
- **PATCH** (3→4): Bug fixes, minor improvements
- **QUALIFIER** (optional): `-rc.1`, `-beta.1`, `-hotfix.1`
### Version Independence
Each product maintains **independent versioning**:
- Products release on their own schedule
- No requirement to synchronize versions
- Can release major updates independently
---
## 🏷️ Git Tag Naming Convention
### Standard Format
```
<product>/<environment>-v<major>.<minor>.<patch>
```
### Products & Environments
| Product | Tag Prefix | Environments |
|---------|-----------|---------------|
| Staff Mobile | `krow-withus-worker-mobile` | dev, stage, prod |
| Client Mobile | `krow-withus-client-mobile` | dev, stage, prod |
| Web Dashboard | `web-dashboard` | dev, stage, prod |
| Command API | `command-api` | dev, stage, prod |
| Core API | `core-api` | dev, stage, prod |
| DataConnect | `dataconnect` | stage, prod |
### Environments
- **dev**: Development releases (daily/weekly), unstable
- **stage**: Staging releases (bi-weekly), pre-production testing
- **prod**: Production releases (monthly), stable, customer-facing
### Examples
```
krow-withus-worker-mobile/dev-v0.1.0
krow-withus-client-mobile/stage-v0.2.0
web-dashboard/prod-v1.0.0
command-api/dev-v0.2.1
core-api/prod-v0.1.0
```
---
## 📅 Release Cadence
### Development Releases (dev)
- **Frequency**: Weekly or as-needed
- **Scope**: Feature completions, bug fixes
- **Duration**: Not guaranteed stable
- **Deployment**: Dev environment only
- **Who**: Development team
### Staging Releases (stage)
- **Frequency**: Bi-weekly (typically mid/end of sprint)
- **Scope**: Sprint completion, feature milestones
- **Duration**: 1-2 weeks stability expected
- **Deployment**: Staging environment for QA
- **Who**: QA team validates
### Production Releases (prod)
- **Frequency**: Monthly or sprint-based
- **Scope**: Feature milestone completion, critical fixes
- **Duration**: 4+ weeks standard support
- **Deployment**: Production environment (customer-facing)
- **Who**: Product owner approves, DevOps deploys
---
## 🔄 Product Dependency & Deployment Order
### Critical Path (for synchronized releases)
Deploy in this order:
1. **DataConnect Schema** (if schema changed)
- Deploy schema changes first
- All APIs depend on schema availability
2. **Backend Services** (parallel OK)
- Command API
- Core API
- Both can deploy simultaneously
3. **Web Dashboard**
- Can deploy once backend ready
- Test API endpoints stable
4. **Mobile Apps** (parallel OK)
- Staff Mobile
- Client Mobile
- Both can deploy simultaneously, independent of web
### Independent Releases
Products **can release independently** if:
- No backend schema changes
- No breaking API changes
- No data migrations required
Example: Staff Mobile can release UI improvements without web/backend changes.
---
## 📝 CHANGELOG Management
### Location & Structure
Each major product maintains its own CHANGELOG:
```
apps/mobile/packages/features/staff/*/CHANGELOG.md
apps/mobile/packages/features/client/*/CHANGELOG.md
apps/web/CHANGELOG.md
backend/command-api/CHANGELOG.md
backend/core-api/CHANGELOG.md
CHANGELOG.md (root - high-level overview)
```
### Format
```markdown
| Date | Version | Change |
|------|---------|--------|
| 2026-03-05 | 0.1.0 | Initial release - [feature list] |
```
### What to Track
- Features added
- Bugs fixed
- Breaking changes (clearly marked ⚠️)
- Dependencies upgraded
- Migration steps (if applicable)
---
## ✅ Release Checklist
### Pre-Release (48 hours before)
- [ ] All PRs merged to main
- [ ] Code review complete
- [ ] All tests passing (unit, integration, E2E)
- [ ] No lint/type errors
- [ ] Mobile builds succeed (CodeMagic)
- [ ] Performance benchmarks acceptable
- [ ] Security scan completed
- [ ] CHANGELOG.md updated with all changes
- [ ] Documentation updated
- [ ] Team notified of pending release
### Release Day
- [ ] Update version numbers in all relevant files
- [ ] Update CHANGELOG with date
- [ ] Git commit: `git commit -m "chore: bump version to X.Y.Z"`
- [ ] Git push changes to main
- [ ] Create git tag: `git tag -a <product>/<env>-v<version> -m "Release message"`
- [ ] Push tags: `git push origin <tag-name>`
- [ ] Deploy to target environment
- [ ] Smoke tests pass
- [ ] Create GitHub Release page
- [ ] Notify stakeholders
### Post-Release (24 hours)
- [ ] Monitor error logs
- [ ] Verify all features work end-to-end
- [ ] Performance is acceptable
- [ ] No regressions reported
- [ ] Users updated if needed
- [ ] Document any issues
---
## 🔐 Protected Tags
### Branch Protection Rules
**Production tags require approval:**
- Tag pattern: `*/prod-v*`
- Require pull request review (1+ approval)
- Require status checks to pass
- Prevent force pushes
- Disable deletions
**Staging tags recommended:**
- Tag pattern: `*/stage-v*`
- Consider: Require at least 1 approval
- Status checks should pass
**Dev tags open:**
- Tag pattern: `*/dev-v*`
- No restrictions
- Allow fast iteration
---
## 🚨 Rollback Procedures
### For Production Issues
**If critical issue detected:**
1. **Identify** the product and issue
2. **Assess** impact and severity
3. **Decide** rollback vs hotfix
- Rollback: Undo entire release
- Hotfix: Fix and re-release (see HOTFIX_PROCESS.md)
4. **Execute** rollback:
```bash
# Revert commit
git revert <commit-hash> -m 1
git push origin main
# Or switch traffic back to previous version
# (depends on deployment infrastructure)
```
5. **Communicate** with users
6. **Plan** hotfix or next release
### Time Windows
- **Awareness**: 15-30 minutes (monitoring)
- **Decision**: 15-30 minutes (severity assessment)
- **Execution**: 15-60 minutes (rollback deployment)
- **Verification**: 30-60 minutes (smoke tests)
- **Communication**: Immediate + 24h updates
**Total**: 2-4 hours from detection to stable state
---
## 📊 Release Templates & Tools
### Git Commands
```bash
# Create tag
git tag -a krow-withus-worker-mobile/dev-v0.1.0 \
-m "Staff Mobile v0.1.0 - Feature X"
# Push tag
git push origin krow-withus-worker-mobile/dev-v0.1.0
# View tags for product
git tag -l "krow-withus-worker-mobile/*" --sort=-version:refname
# See what's in a tag
git show krow-withus-worker-mobile/dev-v0.1.0
# Delete tag (if mistake)
git tag -d krow-withus-worker-mobile/dev-v0.1.0
git push origin --delete krow-withus-worker-mobile/dev-v0.1.0
```
### GitHub Release Template
```markdown
# Krow With Us - Worker Mobile - DEV - v0.1.0
**Release Date**: [Date]
**Environment**: Development
## What's New
### ✨ Features
- Feature 1 description
- Feature 2 description
### 🔧 Improvements
- Improvement 1
- Improvement 2
### 🐛 Bug Fixes
- Bug fix 1
- Bug fix 2
## Dependencies
Requires:
- Backend API v0.1.0 or higher
- DataConnect schema v0.3.0 (if updated)
## Installation
[Download links & instructions]
## Known Issues
- Issue 1: [desc] (Workaround: ...)
## Support
contact: support@krow-workforce.com
```
---
## 🔄 Hotfix Releases
See [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) for emergency procedures.
Quick summary:
1. Branch from production tag
2. Fix the issue
3. Bump PATCH version only
4. Test and deploy immediately
5. Create hotfix tag
---
## 📱 Mobile-Specific Release Process
See [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) for detailed mobile app process including:
- Staff Mobile vs Client Mobile differences
- Build number management
- CodeMagic integration
- App store distribution
- CHANGELOG per app
---
## 🎯 Release Coordination
### Single Product Release
1. Update version files
2. Update CHANGELOG
3. Commit & push
4. Create tag
5. Deploy
6. Create GitHub Release
**Time**: 30-45 minutes (excluding testing)
### Multi-Product Release (e.g., v1.0.0)
**Pre-release phase** (1 week before):
- Code freeze announced
- QA testing begins
- No new features merged
**Release phase** (2-3 days):
- Staging release (all products)
- QA validation
- Product owner sign-off
**Production phase** (1 day):
- Deploy in dependency order
- Smoke tests each product
- Monitor 24 hours
- User communication
**Time**: 5-7 days total, 4 hours active deployment
---
## 📞 Roles & Responsibilities
| Role | Responsibility |
|------|-----------------|
| **Developer** | Keep code release-ready, update versions |
| **QA** | Test staging releases, validate prod |
| **Release Engineer** | Create tags, manage deployment, monitor |
| **Product Owner** | Approve releases, communicate timeline |
| **DevOps** | Infrastructure ready, deployment scripts |
---
## 📊 Success Metrics
Track these per release:
- **Lead Time**: Time from code commit to production
- **Deployment Frequency**: How often you release
- **Change Failure Rate**: % of releases needing rollback
- **Time to Recovery**: Time to fix production issues
- **User Adoption**: % of users on latest version
---
## 📚 Related Documentation
- [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) - Mobile app releases
- [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) - Emergency procedures
- [../../RELEASE_STRATEGY.md](../../RELEASE_STRATEGY.md) - Original detailed guide
- [../../CHANGELOG.md](../../CHANGELOG.md) - Root version history
---
## ✅ Implementation Status
- ✅ Versioning strategy: SemVer
- ✅ Environments: dev, stage, prod
- ✅ Tag naming: Product-specific with brand prefix
- ✅ Product dependencies: Defined
- ✅ Release cadence: 3 levels
- ⏳ GitHub Actions: To be set up
- ⏳ Deployment automation: To be set up
---
**Next Step**: Review [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) for app-specific process.

727
docs/RELEASE/mobile-releases.md Normal file
View File

@@ -0,0 +1,727 @@
# Mobile App Release Process
**For Staff Mobile & Client Mobile Apps**
**Document Version**: 2.0
**Last Updated**: 2026-03-06
**Status**: ✅ Production Ready
---
## 📱 Overview
This document covers the complete release process for both mobile applications:
- **Staff Mobile App** (Worker Mobile) - `krow-withus-worker-mobile`
- **Client Mobile App** - `krow-withus-client-mobile`
Both apps:
- Built with Flutter
- Distributed via iOS App Store & Google Play Store
- Maintain independent versions
- Have independent CHANGELOGs
- Released via GitHub Actions workflows
---
## 📐 Versioning Strategy
### Semantic Versioning with Milestones
We use **Semantic Versioning 2.0.0** with milestone suffixes:
```
MAJOR.MINOR.PATCH-milestone
```
**Examples:**
- `0.0.1-m3` - Milestone 3 release
- `0.0.1-m4` - Milestone 4 release
- `1.0.0` - First production release (no suffix)
- `1.0.1` - Production patch release
**Version Rules:**
- **MAJOR**: Breaking changes, major architectural updates
- **MINOR**: New features, backward-compatible changes
- **PATCH**: Bug fixes, minor improvements
- **SUFFIX**: `-m3`, `-m4`, etc. for milestone tracking
### Version Location
Versions are defined in `pubspec.yaml`:
**Staff Mobile:** `apps/mobile/apps/staff/pubspec.yaml`
```yaml
version: 0.0.1-m4+1
```
**Client Mobile:** `apps/mobile/apps/client/pubspec.yaml`
```yaml
version: 0.0.1-m4+1
```
**Format:** `X.Y.Z-suffix+buildNumber`
- `0.0.1-m4` = version with milestone
- `+1` = build number (for app stores)
### Version Auto-Extraction
GitHub Actions workflows automatically extract the version from `pubspec.yaml` using `.github/scripts/extract-version.sh`. **No manual version input required.**
---
## 📝 CHANGELOG Management
### File Locations
- **Staff Mobile:** `apps/mobile/apps/staff/CHANGELOG.md`
- **Client Mobile:** `apps/mobile/apps/client/CHANGELOG.md`
### Format Standard
```markdown
# [App Name] - Change Log
## [v0.0.1-m4] - Milestone 4 - 2026-03-05
### Added - [Category Name]
- Feature description
- Another feature
### Fixed
- Bug fix description
### Changed
- Changed behavior
---
## [v0.0.1-m3] - Milestone 3 - 2026-02-15
### Added - [Category Name]
...
```
### Section Guidelines
Use these standard categories:
- **Added**: New features
- **Fixed**: Bug fixes
- **Changed**: Changes to existing functionality
- **Deprecated**: Soon-to-be removed features
- **Removed**: Removed features
- **Security**: Security fixes
### When to Update CHANGELOG
✅ **Update BEFORE release:**
- When milestone is complete
- Document all user-facing changes
- Include technical features if relevant
❌ **Don't document:**
- Internal refactoring (unless architecturally significant)
- Development-only changes
- Code formatting/linting
---
## 🏷️ Git Tag Format
### Tag Structure
```
krow-withus-<app>-mobile/<env>-v<version>
```
### Examples
**Staff Mobile (Worker):**
```
krow-withus-worker-mobile/dev-v0.0.1-m3
krow-withus-worker-mobile/stage-v0.0.1-m4
krow-withus-worker-mobile/prod-v1.0.0
```
**Client Mobile:**
```
krow-withus-client-mobile/dev-v0.0.1-m3
krow-withus-client-mobile/stage-v0.0.1-m4
krow-withus-client-mobile/prod-v1.0.0
```
### Tag Components
| Component | Values | Example |
|-----------|--------|---------|
| Product | `worker`, `client` | `worker` |
| Type | `mobile` | `mobile` |
| Environment | `dev`, `stage`, `prod` | `dev` |
| Version | From pubspec.yaml | `v0.0.1-m3` |
**Note:** Tags include the full version with milestone suffix (e.g., `v0.0.1-m4`, not just `v0.0.1`)
---
## 🚀 Release Workflows
### Release Types
We have **2 GitHub Actions workflows** for releases:
1. **Product Release** (`.github/workflows/product-release.yml`) - Standard releases
2. **Hotfix Branch Creation** (`.github/workflows/hotfix-branch-creation.yml`) - Emergency fixes
Both workflows use **manual triggers only** (`workflow_dispatch`) - no automatic releases.
---
## 📦 Standard Release Process
### Step 1: Prepare Release
1. **Ensure milestone is complete**
- All features implemented
- All tests passing
- Code reviews completed
2. **Update CHANGELOG**
```bash
# Edit the appropriate CHANGELOG file
vi apps/mobile/apps/staff/CHANGELOG.md
# OR
vi apps/mobile/apps/client/CHANGELOG.md
```
3. **Update version in pubspec.yaml**
```yaml
# apps/mobile/apps/staff/pubspec.yaml
version: 0.0.1-m4+1
```
4. **Commit changes**
```bash
git add apps/mobile/apps/staff/CHANGELOG.md apps/mobile/apps/staff/pubspec.yaml
git commit -m "docs(mobile): prepare staff app v0.0.1-m4 release"
git push origin dev
```
### Step 2: Trigger Release Workflow
1. **Navigate to GitHub Actions**
- Go to: https://github.com/Oloodi/krow-workforce/actions
- Select **"📦 Product Release"** workflow
2. **Click "Run workflow"**
3. **Select parameters:**
- **Branch**: `dev` (or release branch)
- **Product**: `worker-mobile-app` or `client-mobile-app`
- **Environment**: `dev`, `stage`, or `prod`
- **Pre-release**: Check if this is not a production release
4. **Click "Run workflow"**
### Step 3: Monitor Workflow
The workflow performs these steps automatically:
1. ✅ **Validate & Create Release** (Job 1)
- Extract version from pubspec.yaml
- Validate version format
- Generate tag name
- Create Git tag
- Extract release notes from CHANGELOG
- Create GitHub Release with formatted notes
2. 🔨 **Build Mobile Artifacts** (Job 2)
- Setup Node.js 20
- Install Firebase CLI
- Generate Data Connect SDK
- Setup Java 17
- Setup Flutter 3.38.x
- Bootstrap with Melos
- Decode keystore from secrets
- Build signed APK
- Verify APK signature
- Upload APK to GitHub Release
### Step 4: Verify Release
1. **Check GitHub Releases page**
- URL: https://github.com/Oloodi/krow-workforce/releases
- Verify release was created with correct tag
- Verify release notes display correctly
- Verify APK is attached (if applicable)
2. **Test the release**
- Download APK (dev releases)
- Install on test device
- Verify app launches and core features work
---
## 🔥 Hotfix Process
### When to Use Hotfix
✅ **Use hotfix for:**
- Critical bug in production affecting users
- Data loss or security vulnerability
- Service unavailable or major feature broken
- Customer-blocking issue
❌ **Don't use hotfix for:**
- Minor bugs (can wait for next release)
- Feature requests
- UI/UX improvements
- Styling issues
### Hotfix Workflow
1. **Navigate to GitHub Actions**
- Go to: https://github.com/Oloodi/krow-workforce/actions
- Select **"🚨 Product Hotfix - Create Branch"** workflow
2. **Click "Run workflow"**
3. **Fill in parameters:**
- **Product**: `worker-mobile-app` or `client-mobile-app`
- **Current Production Version**: e.g., `1.0.0` (without 'v' prefix)
- **Issue Description**: Brief description of the bug (used in CHANGELOG and branch name)
4. **The workflow automatically:**
- Creates hotfix branch: `hotfix/krow-withus-worker-mobile/prod-v1.0.1`
- Increments PATCH version: `1.0.0` → `1.0.1`
- Updates `pubspec.yaml` with new version
- Updates CHANGELOG.md with hotfix entry
- Creates Pull Request with hotfix instructions
5. **Fix the bug:**
```bash
# Checkout the hotfix branch
git fetch origin
git checkout hotfix/krow-withus-worker-mobile/prod-v1.0.1
# Make your fix
# ... edit files ...
# Test thoroughly
flutter test
# Commit your fix
git add .
git commit -m "fix(mobile): resolve critical production bug"
git push origin hotfix/krow-withus-worker-mobile/prod-v1.0.1
```
6. **Merge and Release:**
- Review and merge the Pull Request to `main` (or production branch)
- Trigger **Product Release** workflow with `prod` environment
- Workflow will create tag `krow-withus-worker-mobile/prod-v1.0.1`
- Deploy hotfix to production
7. **Backport to dev:**
```bash
git checkout dev
git merge hotfix/krow-withus-worker-mobile/prod-v1.0.1
git push origin dev
```
---
## 🔐 APK Signing Setup
### Overview
All Android builds require signing with keystores. We use **24 GitHub Secrets** (12 per app × 2 apps):
- 6 keystores (2 apps × 3 environments)
- 4 secrets per keystore (base64, password, alias, key password)
### Keystore Files
**Worker Mobile (Staff App):**
- `krow_with_us_staff_dev.jks` - ✅ Committed to repo
- `krow_staff_staging.jks` - ⚠️ Store in GitHub Secrets only
- `krow_staff_prod.jks` - ⚠️ Store in GitHub Secrets only
**Client Mobile:**
- `krow_with_us_client_dev.jks` - ✅ Committed to repo
- `krow_client_staging.jks` - ⚠️ Store in GitHub Secrets only
- `krow_client_prod.jks` - ⚠️ Store in GitHub Secrets only
### Required GitHub Secrets
#### Worker Mobile - 12 Secrets
**Dev Environment:**
- `WORKER_KEYSTORE_DEV_BASE64`
- `WORKER_KEYSTORE_PASSWORD_DEV`
- `WORKER_KEY_ALIAS_DEV`
- `WORKER_KEY_PASSWORD_DEV`
**Staging Environment:**
- `WORKER_KEYSTORE_STAGING_BASE64`
- `WORKER_KEYSTORE_PASSWORD_STAGING`
- `WORKER_KEY_ALIAS_STAGING`
- `WORKER_KEY_PASSWORD_STAGING`
**Production Environment:**
- `WORKER_KEYSTORE_PROD_BASE64`
- `WORKER_KEYSTORE_PASSWORD_PROD`
- `WORKER_KEY_ALIAS_PROD`
- `WORKER_KEY_PASSWORD_PROD`
#### Client Mobile - 12 Secrets
**Dev Environment:**
- `CLIENT_KEYSTORE_DEV_BASE64`
- `CLIENT_KEYSTORE_PASSWORD_DEV`
- `CLIENT_KEY_ALIAS_DEV`
- `CLIENT_KEY_PASSWORD_DEV`
**Staging Environment:**
- `CLIENT_KEYSTORE_STAGING_BASE64`
- `CLIENT_KEYSTORE_PASSWORD_STAGING`
- `CLIENT_KEY_ALIAS_STAGING`
- `CLIENT_KEY_PASSWORD_STAGING`
**Production Environment:**
- `CLIENT_KEYSTORE_PROD_BASE64`
- `CLIENT_KEYSTORE_PASSWORD_PROD`
- `CLIENT_KEY_ALIAS_PROD`
- `CLIENT_KEY_PASSWORD_PROD`
### Setup Using Helper Script
We provide an interactive script to configure all secrets:
```bash
.github/scripts/setup-mobile-github-secrets.sh
```
This script will:
1. Prompt for keystore file paths
2. Convert keystores to base64
3. Prompt for passwords and aliases
4. Display GitHub CLI commands to set secrets
5. Optionally execute the commands
### Manual Setup
If you prefer manual setup:
```bash
# 1. Convert keystore to base64
base64 -i /path/to/keystore.jks | pbcopy
# 2. Add to GitHub Secrets via web UI
# Go to: Repository → Settings → Secrets and variables → Actions
# Click "New repository secret"
# Name: WORKER_KEYSTORE_PROD_BASE64
# Value: Paste the base64 string
# 3. Repeat for all 24 secrets
```
Or use GitHub CLI:
```bash
# Set a secret using gh CLI
gh secret set WORKER_KEYSTORE_PROD_BASE64 < /path/to/keystore_base64.txt
# Set multiple secrets
gh secret set WORKER_KEYSTORE_PASSWORD_PROD -b "your_password"
gh secret set WORKER_KEY_ALIAS_PROD -b "your_alias"
gh secret set WORKER_KEY_PASSWORD_PROD -b "your_key_password"
```
### Verifying APK Signature
After build, the workflow automatically verifies the APK signature using:
```bash
.github/scripts/verify-apk-signature.sh <path-to-apk> <expected-alias>
```
---
## 📅 Release Cadence
### Development Releases (dev)
- **Frequency**: As needed (daily/weekly)
- **Purpose**: Test features, integration testing
- **Stability**: Unstable, may have bugs
- **Distribution**: Internal testing only
- **APK**: Signed with dev keystore
- **Tag example**: `krow-withus-worker-mobile/dev-v0.0.1-m3`
### Staging Releases (stage)
- **Frequency**: Bi-weekly (end of sprints)
- **Purpose**: QA testing, client demos
- **Stability**: Stable, feature-complete
- **Distribution**: QA team, stakeholders
- **APK**: Signed with staging keystore
- **Tag example**: `krow-withus-worker-mobile/stage-v0.0.1-m4`
### Production Releases (prod)
- **Frequency**: Monthly or milestone-based
- **Purpose**: Public release to app stores
- **Stability**: Production-grade, thoroughly tested
- **Distribution**: Public (App Store, Play Store)
- **APK**: Signed with production keystore
- **Tag example**: `krow-withus-worker-mobile/prod-v1.0.0`
---
## 🛠️ Helper Scripts Reference
All scripts are located in `.github/scripts/` and are used by workflows:
### 1. extract-version.sh
**Purpose**: Extract version from pubspec.yaml
**Usage**:
```bash
.github/scripts/extract-version.sh <path-to-pubspec.yaml>
```
**Example**:
```bash
VERSION=$(.github/scripts/extract-version.sh apps/mobile/apps/staff/pubspec.yaml)
echo $VERSION # Output: 0.0.1-m4
```
### 2. generate-tag-name.sh
**Purpose**: Generate consistent Git tag names
**Usage**:
```bash
.github/scripts/generate-tag-name.sh <app> <env> <version>
```
**Example**:
```bash
TAG=$(.github/scripts/generate-tag-name.sh worker dev 0.0.1-m4)
echo $TAG # Output: krow-withus-worker-mobile/dev-v0.0.1-m4
```
### 3. extract-release-notes.sh
**Purpose**: Extract CHANGELOG section for a specific version
**Usage**:
```bash
.github/scripts/extract-release-notes.sh <app> <env> <version> <tag>
```
**Example**:
```bash
NOTES=$(.github/scripts/extract-release-notes.sh worker dev 0.0.1-m4 krow-withus-worker-mobile/dev-v0.0.1-m4)
```
**Output format**:
```
**Environment:** DEV
**Tag:** krow-withus-worker-mobile/dev-v0.0.1-m4
## What is new in this release
[CHANGELOG content for v0.0.1-m4]
```
### 4. create-release-summary.sh
**Purpose**: Generate GitHub Step Summary with emojis
**Usage**:
```bash
.github/scripts/create-release-summary.sh <app> <env> <version> <tag>
```
**Creates**: Formatted summary in GitHub Actions UI
### 5. setup-apk-signing.sh
**Purpose**: Setup APK signing environment variables
**Usage** (in workflow):
```bash
.github/scripts/setup-apk-signing.sh <app> <env>
```
**What it does**:
- Decodes base64 keystore to file
- Sets `CM_KEYSTORE_PATH_<APP>` environment variable
- Sets keystore password, alias, and key password
### 6. verify-apk-signature.sh
**Purpose**: Verify APK is properly signed
**Usage**:
```bash
.github/scripts/verify-apk-signature.sh <apk-path> <expected-alias>
```
**Example**:
```bash
.github/scripts/verify-apk-signature.sh build/app/outputs/apk/release/app-release.apk androidreleasekey
```
### 7. attach-apk-to-release.sh
**Purpose**: Upload APK to existing GitHub Release
**Usage**:
```bash
.github/scripts/attach-apk-to-release.sh <tag> <apk-path> <app>
```
**Example**:
```bash
.github/scripts/attach-apk-to-release.sh krow-withus-worker-mobile/dev-v0.0.1-m4 build/app/outputs/apk/release/app-release.apk worker
```
### 8. setup-mobile-github-secrets.sh
**Purpose**: Interactive helper to configure all GitHub Secrets
**Usage**:
```bash
.github/scripts/setup-mobile-github-secrets.sh
```
**Interactive prompts for**:
- Keystore file paths
- Passwords and aliases
- Generates GitHub CLI commands
- Optionally executes commands
---
## 📋 Pre-Release Checklist
Before triggering a release, ensure:
### Code Quality
- [ ] All automated tests pass
- [ ] No critical linting errors
- [ ] Code review completed (for stage/prod)
- [ ] Security audit passed (for prod)
### Documentation
- [ ] CHANGELOG.md updated with all changes
- [ ] Version in pubspec.yaml matches CHANGELOG
- [ ] Breaking changes documented
- [ ] Migration guide created (if needed)
### Testing
- [ ] Feature testing completed
- [ ] Regression testing passed
- [ ] Performance testing acceptable
- [ ] Device compatibility verified
### Configuration
- [ ] Environment variables configured
- [ ] API endpoints correct for environment
- [ ] Feature flags set appropriately
- [ ] Analytics tracking verified
### GitHub Secrets (First-time setup)
- [ ] All 24 secrets configured
- [ ] Keystore passwords verified
- [ ] Test build succeeded with signing
---
## 🐛 Troubleshooting
### Workflow Fails: "Version not found in pubspec.yaml"
**Cause**: Invalid version format or missing version
**Solution**:
```yaml
# Ensure version line in pubspec.yaml looks like:
version: 0.0.1-m4+1
# Not:
version: 0.0.1 # Missing build number
version: "0.0.1-m4+1" # Don't quote the version
```
### Workflow Fails: "Secret not found"
**Cause**: Missing GitHub Secret
**Solution**:
1. Check secret name matches exactly (case-sensitive)
2. Run `.github/scripts/setup-mobile-github-secrets.sh`
3. Verify secrets at: Repository → Settings → Secrets and variables → Actions
### APK Signing Fails
**Cause**: Invalid keystore or wrong password
**Solution**:
1. Verify keystore base64 encoding: `base64 -i keystore.jks | base64 -d > test.jks`
2. Test password locally: `keytool -list -keystore test.jks`
3. Verify alias: `keytool -list -v -keystore test.jks | grep "Alias name"`
### CHANGELOG Not Extracted
**Cause**: Version format doesn't match in CHANGELOG
**Solution**:
```markdown
# CHANGELOG.md must have this EXACT format:
## [v0.0.1-m4] - Milestone 4 - 2026-03-05
# OR
## [0.0.1-m4] - Milestone 4 - 2026-03-05
# The script tries both [vX.Y.Z] and [X.Y.Z] formats
```
### Tag Already Exists
**Cause**: Trying to create a duplicate tag
**Solution**:
```bash
# Delete the existing tag (CAREFUL!)
git tag -d krow-withus-worker-mobile/dev-v0.0.1-m4
git push origin :refs/tags/krow-withus-worker-mobile/dev-v0.0.1-m4
# Then re-run the workflow
```
---
## 📚 Additional Resources
### Related Documentation
- [Agent Development Rules](../MOBILE/00-agent-development-rules.md)
- [Architecture Principles](../MOBILE/01-architecture-principles.md)
- [Mobile CI Workflow](../../.github/workflows/mobile-ci.yml)
### GitHub Actions Workflows
- **Product Release**: `.github/workflows/product-release.yml`
- **Hotfix Branch Creation**: `.github/workflows/hotfix-branch-creation.yml`
- **Mobile CI**: `.github/workflows/mobile-ci.yml`
### Useful Commands
```bash
# View current version
grep "^version:" apps/mobile/apps/staff/pubspec.yaml
# List all mobile tags
git tag -l "krow-withus-*-mobile/*"
# View latest releases
gh release list --limit 10
# Download APK from release
gh release download krow-withus-worker-mobile/dev-v0.0.1-m4 --pattern "*.apk"
```
---
## 🔄 Version History
| Version | Date | Changes |
|---------|------|---------|
| 2.0 | 2026-03-06 | Consolidated all release docs into single file |
| 1.0 | 2026-03-05 | Initial separate documentation files |
---
**Questions or Issues?**
Contact the DevOps team or create an issue in the repository.