diff --git a/.github/workflows/preview-deploy.yml b/.github/workflows/preview-deploy.yml
new file mode 100644
index 0000000..893dae6
--- /dev/null
+++ b/.github/workflows/preview-deploy.yml
@@ -0,0 +1,175 @@
+name: Preview Branch Deployment
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+  push:
+    branches:
+      - main
+      - develop
+      - 'preview/**'
+      - 'feature/**'
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    if: github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref != 'refs/heads/main')
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: 17
+
+      - name: Cache gradle
+        uses: actions/cache@v4
+        with:
+          path: ~/.gradle/caches
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-
+
+      - name: Set branch name
+        id: branch
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            echo "branch_name=pr-${{ github.event.number }}" >> $GITHUB_OUTPUT
+            echo "deploy_url=pr-${{ github.event.number }}" >> $GITHUB_OUTPUT
+          else
+            branch_name=${GITHUB_REF#refs/heads/}
+            echo "branch_name=${branch_name//\//-}" >> $GITHUB_OUTPUT
+            echo "deploy_url=${branch_name//\//-}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run tests
+        run: ./gradlew test --no-daemon
+
+      - name: Build Android APK (Debug)
+        run: ./gradlew assembleDebug --no-daemon
+
+      - name: Build Web WAR
+        run: ./gradlew :web:bootWar --no-daemon
+
+      - name: Upload Android APK
+        uses: actions/upload-artifact@v4
+        with:
+          name: android-apk-${{ steps.branch.outputs.branch_name }}
+          path: app/build/outputs/apk/debug/app-debug.apk
+          retention-days: 7
+
+      - name: Upload Web WAR  
+        uses: actions/upload-artifact@v4
+        with:
+          name: web-war-${{ steps.branch.outputs.branch_name }}
+          path: web/build/libs/web.war
+          retention-days: 7
+
+      # Optional: Deploy to Heroku Review Apps (if configured)
+      - name: Deploy to Heroku Review App
+        if: github.event_name == 'pull_request' && vars.HEROKU_APP_NAME
+        uses: akhileshns/heroku-deploy@v3.13.15
+        with:
+          heroku_api_key: ${{ secrets.HEROKU_API_KEY }}
+          heroku_app_name: ${{ vars.HEROKU_APP_NAME }}-${{ steps.branch.outputs.deploy_url }}
+          heroku_email: ${{ secrets.HEROKU_EMAIL }}
+          usedocker: false
+          buildpack: heroku/java
+
+      # Optional: Deploy to custom preview environment
+      - name: Deploy to Preview Environment
+        if: vars.PREVIEW_DEPLOY_ENABLED == 'true'
+        run: |
+          echo "Deploying to preview environment: ${{ steps.branch.outputs.deploy_url }}"
+          # Add your custom deployment commands here
+          # For example, deploy to a staging server, cloud platform, etc.
+
+      - name: Comment deployment info on PR
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const branchName = '${{ steps.branch.outputs.branch_name }}';
+            const deployUrl = '${{ steps.branch.outputs.deploy_url }}';
+            
+            let body = `## 🚀 Preview Deployment\n\n`;
+            body += `**Branch:** \`${branchName}\`\n\n`;
+            body += `### Available Artifacts:\n`;
+            body += `- 📱 [Android APK](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})\n`;
+            body += `- 🌐 [Web WAR](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})\n\n`;
+            
+            if (process.env.HEROKU_APP_NAME) {
+              body += `### Live Preview:\n`;
+              body += `- 🌐 [Web App Preview](https://${{ vars.HEROKU_APP_NAME }}-${deployUrl}.herokuapp.com)\n\n`;
+            }
+            
+            body += `### Installation Instructions:\n`;
+            body += `1. Download the APK from the artifacts above\n`;
+            body += `2. Install on Android device: \`adb install app-debug.apk\`\n`;
+            body += `3. For web app: Download WAR and run \`java -jar web.war\`\n\n`;
+            body += `*Artifacts will be retained for 7 days*`;
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: body
+            });
+
+  deploy-main:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: 17
+
+      - name: Cache gradle
+        uses: actions/cache@v4
+        with:
+          path: ~/.gradle/caches
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-
+
+      - name: Run tests
+        run: ./gradlew test --no-daemon
+
+      - name: Build Android APK (Debug)
+        run: ./gradlew assembleDebug --no-daemon
+
+      - name: Build Web WAR
+        run: ./gradlew :web:bootWar --no-daemon
+
+      - name: Upload Android APK
+        uses: actions/upload-artifact@v4
+        with:
+          name: android-apk-main-latest
+          path: app/build/outputs/apk/debug/app-debug.apk
+          retention-days: 30
+
+      - name: Upload Web WAR
+        uses: actions/upload-artifact@v4
+        with:
+          name: web-war-main-latest
+          path: web/build/libs/web.war
+          retention-days: 30
+
+      # Optional: Deploy to staging environment
+      - name: Deploy to Staging
+        if: vars.STAGING_DEPLOY_ENABLED == 'true'
+        run: |
+          echo "Deploying main branch to staging environment"
+          # Add your staging deployment commands here
\ No newline at end of file
diff --git a/README.md b/README.md
index 0ed074f..e95ac96 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ anywhere. Our goal is to make a Verifier App with the widest possible verificati
 ### Project Documentation
 - [**Data Models**](docs/data-models.md) - Comprehensive documentation of all supported certificate data models (DDCC, DCC, DIVOC, SHC, ICAO, ICVP)
 - [**User Workflows**](docs/user-workflows.md) - User experience and technical workflow documentation
+- [**Deployment Guide**](docs/deployment.md) - Complete guide for preview branch and production deployments
 - [**Adding New Schemas**](NEW_SCHEMAS.md) - Guide for adding support for new certificate formats
 
 ### Reference Documentation
@@ -145,6 +146,10 @@ Android will connect with your local IP. Just make sure the phone is in the same
 
 ## How to Deploy
 
+> **📖 For comprehensive deployment documentation, see the [Deployment Guide](docs/deployment.md)**
+
+### Quick Start - Production Release
+
 1. Generate a new signing key 
 ```
 keytool -genkey -v -keystore <my-release-key.keystore> -alias <alias_name> -keyalg RSA -keysize 2048 -validity 10000
@@ -159,7 +164,17 @@ keytool -genkey -v -keystore <my-release-key.keystore> -alias <alias_name> -keya
 5. Tag the commit with `v{x.x.x}`
 6. Let the [Create Release GitHub Action](https://github.com/WorldHealthOrganization/gdhcn-validator/actions/workflows/create-release.yml) build a new `aab` file. 
 7. Add your CHANGE LOG to the description of the new release
-8. Download the `aab` file and upload it to the` PlayStore. 
+8. Download the `aab` file and upload it to the PlayStore.
+
+### Preview Branch Deployment
+
+For testing changes before production:
+
+- **Pull Requests**: Automatic preview deployment with artifacts and optional live preview
+- **Feature Branches**: Push to `preview/*` or `feature/*` branches for manual deployment
+- **Main Branch**: Automatic staging deployment on every push to main
+
+See the [Deployment Guide](docs/deployment.md) for detailed instructions on preview deployments, configuration options, and troubleshooting. 
 
 # Contributing
 
diff --git a/docs/deployment-quick-reference.md b/docs/deployment-quick-reference.md
new file mode 100644
index 0000000..c06659e
--- /dev/null
+++ b/docs/deployment-quick-reference.md
@@ -0,0 +1,110 @@
+# Quick Deployment Reference
+
+> **📖 For complete documentation, see [docs/deployment.md](deployment.md)**
+
+## Preview Branch Deployment
+
+### Automatic (Pull Requests)
+- ✨ **Just create a PR** - deployment happens automatically
+- 📱 Get Android APK and Web WAR artifacts  
+- 🌐 Optional live preview on Heroku Review Apps
+- 💬 Automatic PR comment with download links
+
+### Manual (Feature Branches)
+```bash
+# Deploy any branch for testing
+git push origin feature/my-feature
+git push origin preview/my-feature
+
+# Triggers automatic build and artifact creation
+```
+
+## Main Branch Deployment
+```bash
+# Deploy to staging/latest
+git push origin main
+
+# Creates "latest" artifacts with 30-day retention
+```
+
+## Production Release
+```bash
+# 1. Update version in app/build.gradle
+# 2. Commit and tag
+git tag v1.2.3
+git push origin main && git push origin v1.2.3
+
+# Creates signed APK, AAB, and WAR files
+```
+
+## Quick Setup
+
+### Choose Your Deployment Method
+
+**Option 1: Web-Based Setup (No CLI required)**
+1. **Heroku**: Create app via [dashboard.heroku.com](https://dashboard.heroku.com) → Connect GitHub repository
+2. **Review Apps**: Enable via Dashboard → Deploy tab → Review Apps section  
+3. **GitHub**: Add secrets/variables via Settings → Secrets and variables → Actions
+
+**Option 2: CLI-Based Setup**
+1. **Heroku Setup**:
+   ```bash
+   heroku create your-app-name
+   heroku buildpacks:set heroku/java
+   ```
+2. **Enable Review Apps**: Go to Heroku Dashboard → Deploy → Enable Review Apps
+3. **GitHub Secrets** (Settings → Secrets and variables → Actions → Secrets):
+   - `HEROKU_API_KEY` = `heroku auth:token` output
+   - `HEROKU_EMAIL` = your Heroku account email
+4. **GitHub Variables** (Settings → Secrets and variables → Actions → Variables):
+   - `HEROKU_APP_NAME` = `your-app-name` (base name only)
+
+### GitHub Configuration (Detailed)
+```bash
+# Get required info
+heroku auth:token    # Copy this for HEROKU_API_KEY
+heroku auth:whoami   # Copy this for HEROKU_EMAIL
+
+# Repository Settings → Secrets and variables → Actions
+# Add Secrets:
+#   HEROKU_API_KEY = <token from above>
+#   HEROKU_EMAIL = <email from above>
+# Add Variables:
+#   HEROKU_APP_NAME = your-app-name
+```
+
+### Alternative: GitHub CLI Setup
+```bash
+gh secret set HEROKU_API_KEY --body "your-api-key"
+gh secret set HEROKU_EMAIL --body "your-email@example.com"
+gh variable set HEROKU_APP_NAME --body "your-app-name"
+```
+
+### Essential Heroku Commands
+```bash
+# Setup
+heroku login
+heroku create your-app-name
+heroku buildpacks:set heroku/java
+
+# Deploy manually
+git push heroku main
+
+# Monitor
+heroku logs --tail
+heroku ps
+heroku apps:info your-app-name
+
+# Review Apps
+heroku apps                    # List all apps
+heroku apps:destroy app-name   # Clean up old review apps
+```
+
+### For Signed Releases  
+Add these GitHub secrets:
+- `KEY_ALIAS`, `KEY_PASSWORD`, `KEY_STORE_PASSWORD`, `SIGNING_KEY`
+
+## Artifacts Location
+- **GitHub Actions** → Workflow runs → Artifacts section
+- **Releases** → GitHub Releases page  
+- **Live previews** → Check PR comments for links
\ No newline at end of file
diff --git a/docs/deployment.md b/docs/deployment.md
new file mode 100644
index 0000000..9bedde1
--- /dev/null
+++ b/docs/deployment.md
@@ -0,0 +1,963 @@
+# Deployment Guide
+
+This document provides comprehensive guidance for deploying the GDHCN Validator application, covering both preview branch deployments and production releases.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Preview Branch Deployment](#preview-branch-deployment)
+- [Main Branch Deployment](#main-branch-deployment)
+- [Production Release Deployment](#production-release-deployment)
+- [Configuration](#configuration)
+  - [Heroku Deployment Setup](#heroku-deployment-setup)
+  - [GitHub Repository Configuration](#step-6-configure-github-repository)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+The GDHCN Validator consists of two main components:
+
+1. **Android App** (`/app`) - Mobile application for QR code scanning and verification
+2. **Web App** (`/web`) - Spring Boot web application providing web-based verification
+
+Both components can be deployed independently or together depending on your needs.
+
+## Architecture
+
+```
+┌─────────────────┐    ┌─────────────────┐
+│   Android App   │    │    Web App      │
+│   (APK/AAB)     │    │  (Spring Boot)  │
+└─────────────────┘    └─────────────────┘
+         │                       │
+         │                       │
+         ▼                       ▼
+┌─────────────────┐    ┌─────────────────┐
+│   Play Store    │    │   Web Server    │
+│   Distribution  │    │ (Heroku/Cloud)  │
+└─────────────────┘    └─────────────────┘
+```
+
+## Preview Branch Deployment
+
+Preview deployments allow testing changes before they are merged to main. The system automatically creates preview deployments for:
+
+- **Pull Requests**: Automatic deployment on PR creation/updates
+- **Feature Branches**: Manual deployment via branch push
+- **Development Branches**: Continuous deployment for `develop` and `preview/**` branches
+
+### Workflow Triggers
+
+The preview deployment workflow (`.github/workflows/preview-deploy.yml`) is triggered by:
+
+```yaml
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+  push:
+    branches:
+      - main
+      - develop
+      - 'preview/**'
+      - 'feature/**'
+```
+
+### What Gets Deployed
+
+For each preview deployment:
+
+1. **Android APK** (Debug build)
+   - Built from current branch code
+   - Available as GitHub Actions artifact
+   - Retained for 7 days
+
+2. **Web Application WAR**
+   - Spring Boot WAR file
+   - Can be deployed to Heroku Review Apps
+   - Available as GitHub Actions artifact
+
+### Accessing Preview Deployments
+
+#### Via Pull Request Comments
+
+When a PR is created or updated, the workflow automatically adds a comment with:
+
+```markdown
+## 🚀 Preview Deployment
+
+**Branch:** `pr-123`
+
+### Available Artifacts:
+- 📱 [Android APK](https://github.com/repo/actions/runs/123)
+- 🌐 [Web WAR](https://github.com/repo/actions/runs/123)
+
+### Live Preview:
+- 🌐 [Web App Preview](https://app-name-pr-123.herokuapp.com)
+
+### Installation Instructions:
+1. Download the APK from the artifacts above
+2. Install on Android device: `adb install app-debug.apk`
+3. For web app: Download WAR and run `java -jar web.war`
+```
+
+#### Via GitHub Actions Artifacts
+
+1. Go to the GitHub Actions tab
+2. Find the "Preview Branch Deployment" workflow run
+3. Download artifacts from the run summary
+
+### Manual Preview Deployment
+
+To deploy a feature branch for testing:
+
+1. **Push to a preview branch:**
+   ```bash
+   git checkout -b preview/my-feature
+   git push origin preview/my-feature
+   ```
+
+2. **Or push to an existing feature branch:**
+   ```bash
+   git push origin feature/my-feature
+   ```
+
+The workflow will automatically build and deploy the preview.
+
+## Main Branch Deployment
+
+When code is pushed to the `main` branch, the system creates a "latest" deployment that can be used for staging or integration testing.
+
+### Automatic Main Deployment
+
+Every push to `main` triggers:
+
+1. **Test execution** - Ensures code quality
+2. **Android APK build** - Debug build for testing
+3. **Web WAR build** - Production-ready WAR file
+4. **Artifact upload** - Longer retention (30 days)
+5. **Optional staging deployment** - If configured
+
+### Accessing Main Deployments
+
+Main branch deployments are available as GitHub Actions artifacts with extended retention:
+
+- **Android APK**: `android-apk-main-latest`
+- **Web WAR**: `web-war-main-latest`
+
+## Production Release Deployment
+
+Production releases are created through the existing tag-based workflow.
+
+### Creating a Production Release
+
+1. **Update version numbers** in `app/build.gradle`:
+   ```gradle
+   versionCode 23
+   versionName "0.2.0"
+   ```
+
+2. **Commit and tag** the release:
+   ```bash
+   git add app/build.gradle
+   git commit -m "Bump version to 0.2.0"
+   git tag v0.2.0
+   git push origin main
+   git push origin v0.2.0
+   ```
+
+3. **Release workflow runs** automatically:
+   - Builds signed APK and AAB files
+   - Builds production WAR file
+   - Creates GitHub release
+   - Uploads all artifacts
+
+4. **Manual steps**:
+   - Download AAB from GitHub release
+   - Upload to Google Play Console
+   - Deploy WAR to production web server
+
+### Production Artifacts
+
+The release workflow creates:
+
+- **`app-release-v0.2.0.apk`** - Signed Android APK
+- **`app-release-v0.2.0.aab`** - Android App Bundle for Play Store
+- **`web-release-v0.2.0.war`** - Production web application
+
+## Configuration
+
+### Required Secrets
+
+For signed releases, configure these GitHub secrets:
+
+```
+KEY_ALIAS=your_key_alias
+KEY_PASSWORD=your_key_password
+KEY_STORE_PASSWORD=your_keystore_password
+SIGNING_KEY=base64_encoded_keystore_file
+```
+
+### Optional Configuration
+
+Configure these GitHub variables for enhanced functionality:
+
+```
+HEROKU_APP_NAME=your-app-name          # Enables Heroku Review Apps
+PREVIEW_DEPLOY_ENABLED=true            # Enables custom preview deployment
+STAGING_DEPLOY_ENABLED=true            # Enables staging deployment
+```
+
+Configure these GitHub secrets for external deployments:
+
+```
+HEROKU_API_KEY=your_heroku_api_key
+HEROKU_EMAIL=your_heroku_email
+```
+
+### Heroku Deployment Setup
+
+This section provides complete step-by-step instructions for deploying the GDHCN Validator web application to Heroku. You can choose between **CLI-based deployment** or **web-based deployment** depending on your preference.
+
+#### Prerequisites
+
+1. **Heroku Account**: Create a free account at [heroku.com](https://heroku.com)
+2. **GitHub Repository Access**: Admin access to configure secrets and variables
+3. **Git**: Required for CLI deployment method
+4. **Heroku CLI**: Only required for CLI deployment method - install from [devcenter.heroku.com/articles/heroku-cli](https://devcenter.heroku.com/articles/heroku-cli)
+
+#### Deployment Methods
+
+Choose one of the following deployment methods:
+- **[Method A: Web-Based Deployment](#method-a-web-based-deployment)** - Using Heroku Dashboard (no CLI required)
+- **[Method B: CLI-Based Deployment](#method-b-cli-based-deployment)** - Using Heroku CLI and command line
+
+---
+
+## Method A: Web-Based Deployment
+
+This method uses the Heroku Dashboard web interface exclusively - no command line tools required.
+
+### Step 1: Create Heroku Application via Dashboard
+
+1. **Sign in to Heroku**:
+   - Go to [dashboard.heroku.com](https://dashboard.heroku.com)
+   - Log in with your Heroku account
+
+2. **Create a new app**:
+   - Click the **"New"** button in the top-right corner
+   - Select **"Create new app"**
+   - Enter an **App name** (e.g., `gdhcn-validator` or `your-app-name`)
+     - App names must be unique across all Heroku apps
+     - Use lowercase letters, numbers, and hyphens only
+   - Choose a **Region** (United States or Europe)
+   - Click **"Create app"**
+
+3. **Verify app creation**:
+   - You'll be redirected to your app's dashboard
+   - Note the app URL: `https://your-app-name.herokuapp.com`
+   - The app is now created but not yet deployed
+
+### Step 2: Connect GitHub Repository
+
+1. **Navigate to Deploy tab**:
+   - In your app dashboard, click the **"Deploy"** tab
+
+2. **Connect to GitHub**:
+   - In the **"Deployment method"** section, click **"GitHub"**
+   - Click **"Connect to GitHub"** button
+   - If prompted, authorize Heroku to access your GitHub account
+
+3. **Select repository**:
+   - In the **"Connect to GitHub"** section:
+     - **Repo-owner**: Select `WorldHealthOrganization`
+     - **Repo-name**: Enter `gdhcn-validator`
+     - Click **"Search"**
+     - Click **"Connect"** next to the repository
+
+4. **Configure deployment settings**:
+   - **Manual deploy** section: Choose `main` branch
+   - **Automatic deploys** section: 
+     - Choose `main` branch
+     - Check **"Wait for CI to pass before deploy"** (recommended)
+     - Click **"Enable Automatic Deploys"** (optional - for automatic deployment on every push to main)
+
+### Step 3: Configure Application Settings
+
+1. **Set Java buildpack**:
+   - Click the **"Settings"** tab
+   - Scroll down to **"Buildpacks"** section
+   - Click **"Add buildpack"**
+   - Select **"heroku/java"** or enter `heroku/java`
+   - Click **"Save changes"**
+
+2. **Configure environment variables**:
+   - In the **"Config Vars"** section, click **"Reveal Config Vars"**
+   - Add the following variables one by one:
+
+   **Variable 1:**
+   - **KEY**: `JAVA_TOOL_OPTIONS`
+   - **VALUE**: `-Xmx512m`
+   - Click **"Add"**
+
+   **Variable 2:**
+   - **KEY**: `SPRING_PROFILES_ACTIVE`
+   - **VALUE**: `production`
+   - Click **"Add"**
+
+   **Variable 3 (automatically set):**
+   - **KEY**: `PORT`
+   - **VALUE**: (automatically managed by Heroku)
+   - This should appear automatically - don't modify it
+
+### Step 4: Deploy Application
+
+1. **Manual deployment**:
+   - Go back to the **"Deploy"** tab
+   - Scroll down to **"Manual deploy"** section
+   - Ensure `main` branch is selected
+   - Click **"Deploy Branch"**
+
+2. **Monitor deployment**:
+   - The deployment process will start and show real-time logs
+   - Wait for the message: **"Your app was successfully deployed"**
+   - This process may take 5-10 minutes for the first deployment
+
+3. **Verify deployment**:
+   - Click **"View"** button to open your deployed application
+   - The app should load at `https://your-app-name.herokuapp.com`
+
+### Step 5: Enable Review Apps for Pull Requests
+
+Review Apps create temporary applications for each pull request automatically.
+
+1. **Enable Review Apps**:
+   - In your app dashboard, go to the **"Deploy"** tab
+   - Scroll down to **"Review Apps"** section
+   - Click **"Enable Review Apps..."**
+
+2. **Configure Review Apps settings**:
+   - **Create new review apps for pull requests automatically**: ✅ Check this
+   - **Destroy stale review apps automatically**: ✅ Check this (recommended)
+   - **Stale time**: Set to `5` days (recommended)
+   - Click **"Enable Review Apps"**
+
+3. **Configure inherited settings**:
+   - **Config vars**: All variables from parent app will be copied
+   - **Add-ons**: Select any add-ons to inherit (usually none needed)
+   - **Buildpacks**: Will inherit the Java buildpack automatically
+   - Click **"Create"** if any additional confirmation is needed
+
+### Step 6: Get API Credentials for GitHub Actions
+
+To enable GitHub Actions to deploy to Heroku, you need to get your API credentials:
+
+1. **Get Heroku API Key**:
+   - In Heroku Dashboard, click your avatar (top-right)
+   - Select **"Account settings"**
+   - Scroll down to **"API Key"** section
+   - Click **"Reveal"** to show your API key
+   - **Copy this key** - you'll need it for GitHub configuration
+
+2. **Note your email**:
+   - Your Heroku email is displayed at the top of the Account settings page
+   - **Copy this email** - you'll need it for GitHub configuration
+
+3. **Proceed to GitHub Configuration**: Continue to [Step 7: Configure GitHub Repository](#step-7-configure-github-repository)
+
+---
+
+## Method B: CLI-Based Deployment
+
+This method uses the Heroku CLI for setup and deployment.
+
+### Step 1: Install and Setup Heroku CLI
+
+```bash
+# Install Heroku CLI (macOS)
+brew tap heroku/brew && brew install heroku
+
+# Install Heroku CLI (Ubuntu/Debian)
+curl https://cli-assets.heroku.com/install-ubuntu.sh | sh
+
+# Install Heroku CLI (Windows)
+# Download installer from https://devcenter.heroku.com/articles/heroku-cli
+
+# Login to Heroku
+heroku login
+```
+
+### Step 2: Create Main Heroku Application
+
+```bash
+# Create the main application
+heroku create gdhcn-validator
+
+# Or use a custom name
+heroku create your-app-name
+
+# Set Java runtime version
+heroku config:set JAVA_TOOL_OPTIONS="-Xmx512m" --app your-app-name
+
+# Verify the app was created
+heroku apps:info your-app-name
+```
+
+### Step 3: Configure Heroku Application
+
+```bash
+# Set up Java buildpack (if not automatically detected)
+heroku buildpacks:set heroku/java --app your-app-name
+
+# Configure environment variables
+heroku config:set SPRING_PROFILES_ACTIVE=production --app your-app-name
+
+# View current configuration
+heroku config --app your-app-name
+```
+
+### Step 4: Manual Deployment (One-time)
+
+```bash
+# Clone and deploy the repository manually
+git clone https://github.com/WorldHealthOrganization/gdhcn-validator.git
+cd gdhcn-validator
+
+# Add Heroku remote
+heroku git:remote -a your-app-name
+
+# Deploy current branch
+git push heroku main
+
+# View logs
+heroku logs --tail --app your-app-name
+
+# Open the deployed application
+heroku open --app your-app-name
+```
+
+### Step 5: Enable Review Apps for Pull Requests
+
+Review Apps automatically create temporary apps for each pull request, allowing you to test changes before merging.
+
+##### 5.1: Enable Review Apps in Heroku Dashboard
+
+1. Go to [dashboard.heroku.com](https://dashboard.heroku.com)
+2. Select your main app (`your-app-name`)
+3. Click on the **"Deploy"** tab
+4. Scroll down to **"Review Apps"** section
+5. Click **"Enable Review Apps"**
+6. Choose **"Create new review apps for pull requests automatically"**
+7. Set **"Destroy stale review apps automatically"** (recommended: after 5 days)
+8. Click **"Enable Review Apps"**
+
+##### 5.2: Connect GitHub Repository
+
+1. In the same **"Deploy"** tab, find **"Deployment method"**
+2. Click **"GitHub"** and connect your GitHub account
+3. Search for and select **"WorldHealthOrganization/gdhcn-validator"**
+4. Click **"Connect"**
+5. **Do not** enable automatic deploys for main branch (we use GitHub Actions instead)
+
+### Step 6: Get API Credentials for GitHub Actions
+
+To enable GitHub Actions integration, get your API credentials:
+
+```bash
+# Get your Heroku API key (save this for later)
+heroku auth:token
+
+# Get your Heroku email (usually your login email)
+heroku auth:whoami
+
+# Confirm your app name
+heroku apps:info your-app-name | grep "Web URL"
+```
+
+**Important**: Keep your API key secure and never share it publicly.
+
+---
+
+## Step 7: Configure GitHub Repository
+
+**This step is the same for both deployment methods** - it configures GitHub Actions integration regardless of whether you used the web interface or CLI to create your Heroku app.
+
+This step configures the GitHub repository with the necessary secrets and variables for automated Heroku deployments. You need repository admin access to complete these steps.
+
+#### 7.1: Get Required Information
+
+Before configuring GitHub, gather the required information:
+
+**If you used Method A (Web-based deployment)**:
+- Use the API key you copied from Heroku Dashboard → Account settings
+- Use the email from your Heroku account settings
+
+**If you used Method B (CLI-based deployment)**:
+```bash
+# Get your Heroku API key (save this for later)
+heroku auth:token
+
+# Get your Heroku email (usually your login email)
+heroku auth:whoami
+
+# Confirm your app name
+heroku apps:info your-app-name | grep "Web URL"
+```
+
+**Important**: Keep your API key secure and never share it publicly.
+
+#### 7.2: Add GitHub Secrets (Step-by-Step)
+
+Secrets store sensitive information like API keys and passwords that should not be visible in your repository.
+
+**Step 1: Navigate to Repository Settings**
+1. Go to your GitHub repository: `https://github.com/WorldHealthOrganization/gdhcn-validator`
+2. Click the **"Settings"** tab (you need admin access)
+3. In the left sidebar, scroll down to the **"Security"** section
+4. Click **"Secrets and variables"**
+5. Click **"Actions"** from the dropdown
+
+**Step 2: Add HEROKU_API_KEY Secret**
+1. Click the **"Secrets"** tab (should be selected by default)
+2. Click the **"New repository secret"** button
+3. In the **"Name"** field, enter exactly: `HEROKU_API_KEY`
+4. In the **"Secret"** field, paste your Heroku API key from the `heroku auth:token` command
+5. Click **"Add secret"**
+
+**Step 3: Add HEROKU_EMAIL Secret**
+1. Click the **"New repository secret"** button again
+2. In the **"Name"** field, enter exactly: `HEROKU_EMAIL`
+3. In the **"Secret"** field, enter your Heroku account email (from `heroku auth:whoami`)
+4. Click **"Add secret"**
+
+**Step 4: Verify Secrets Were Added**
+After adding both secrets, you should see:
+```
+HEROKU_API_KEY    Updated X seconds ago
+HEROKU_EMAIL      Updated X seconds ago
+```
+
+**Note**: You cannot view secret values after they're saved - this is a security feature.
+
+#### 7.3: Add GitHub Variables (Step-by-Step)
+
+Variables store non-sensitive configuration that can be viewed by repository collaborators.
+
+**Step 1: Switch to Variables Tab**
+1. While still in **Settings → Secrets and variables → Actions**
+2. Click the **"Variables"** tab (next to "Secrets")
+
+**Step 2: Add HEROKU_APP_NAME Variable**
+1. Click the **"New repository variable"** button
+2. In the **"Name"** field, enter exactly: `HEROKU_APP_NAME`
+3. In the **"Value"** field, enter your base Heroku app name (e.g., `gdhcn-validator`)
+   - **Important**: Use only the base name without any suffixes like `-pr-123`
+   - This should match the app name you created in Step 2
+4. Click **"Add variable"**
+
+**Step 3: Add Optional Variables (Recommended)**
+Add these optional variables for enhanced functionality:
+
+1. **PREVIEW_DEPLOY_ENABLED**:
+   - **Name**: `PREVIEW_DEPLOY_ENABLED`
+   - **Value**: `true`
+   - **Purpose**: Enables custom preview deployments
+
+2. **STAGING_DEPLOY_ENABLED**:
+   - **Name**: `STAGING_DEPLOY_ENABLED`
+   - **Value**: `true`
+   - **Purpose**: Enables automatic staging deployments
+
+**Step 4: Verify Variables Were Added**
+After adding variables, you should see:
+```
+HEROKU_APP_NAME           gdhcn-validator
+PREVIEW_DEPLOY_ENABLED    true
+STAGING_DEPLOY_ENABLED    true
+```
+
+#### 7.4: Alternative Setup via GitHub CLI
+
+If you prefer command line setup, you can use the GitHub CLI:
+
+```bash
+# Install GitHub CLI (if not already installed)
+# macOS: brew install gh
+# Ubuntu: sudo apt install gh
+# Windows: winget install GitHub.cli
+
+# Login to GitHub CLI
+gh auth login
+
+# Add secrets
+gh secret set HEROKU_API_KEY --body "your-heroku-api-key"
+gh secret set HEROKU_EMAIL --body "your-heroku-email@example.com"
+
+# Add variables
+gh variable set HEROKU_APP_NAME --body "gdhcn-validator"
+gh variable set PREVIEW_DEPLOY_ENABLED --body "true"
+gh variable set STAGING_DEPLOY_ENABLED --body "true"
+
+# Verify secrets and variables
+gh secret list
+gh variable list
+```
+
+#### 7.5: Verify Configuration
+
+**Test 1: Check GitHub Actions has access**
+1. Go to **Actions** tab in your repository
+2. Look for any recent workflow runs
+3. Click on a workflow run and check if variables appear in the environment
+
+**Test 2: Create a test deployment**
+```bash
+# Create a test branch to trigger the workflow
+git checkout -b test-github-setup
+echo "# Test GitHub configuration" >> README.md
+git add README.md
+git commit -m "Test: GitHub secrets and variables setup"
+git push origin test-github-setup
+```
+
+Create a pull request for this branch - the workflow should run and you should see:
+- No errors about missing secrets/variables
+- Successful authentication with Heroku
+- Automatic Heroku Review App creation
+
+##### 6.6: Troubleshooting GitHub Configuration
+
+**Issue**: `HEROKU_API_KEY` authentication fails
+```
+Error: Invalid credentials
+```
+**Solutions**:
+1. Regenerate API key: `heroku auth:token`
+2. Verify the key was copied completely (no extra spaces)
+3. Re-add the secret with the new key
+
+**Issue**: Variables not accessible in workflow
+```
+Error: HEROKU_APP_NAME is not set
+```
+**Solutions**:
+1. Verify variable name is exactly `HEROKU_APP_NAME` (case-sensitive)
+2. Check that variable was added to the correct repository
+3. Ensure you have admin access to the repository
+
+**Issue**: Heroku app name conflicts
+```
+Error: App name is already taken
+```
+**Solutions**:
+1. Use a unique app name: `gdhcn-validator-yourorg`
+2. Check your Heroku apps: `heroku apps`
+3. Update `HEROKU_APP_NAME` variable with the correct name
+
+**Issue**: Review Apps not being created
+**Solutions**:
+1. Verify Review Apps are enabled in Heroku Dashboard
+2. Check GitHub-Heroku connection is active
+3. Ensure base app (`HEROKU_APP_NAME`) exists in Heroku
+
+##### 6.7: Security Best Practices
+
+**For Secrets**:
+- Never commit API keys to your repository
+- Rotate API keys regularly (every 90 days recommended)
+- Use least-privilege access for service accounts
+- Monitor secret access in GitHub audit logs
+
+**For Variables**:
+- Don't store sensitive data in variables (use secrets instead)
+- Use descriptive names for clarity
+- Document variable purposes in your README
+- Keep variable values simple and avoid special characters
+
+**Access Control**:
+- Limit repository admin access to trusted team members
+- Use branch protection rules for production deployments
+- Review GitHub Actions logs regularly for security issues
+- Enable two-factor authentication for all admin accounts
+
+## Step 8: Test Review Apps
+
+Now test that your complete setup is working by creating a test deployment.
+
+### Method A & B: Testing Review Apps
+
+1. **Create a test pull request**:
+   ```bash
+   git checkout -b test-heroku-deployment
+   echo "# Test deployment - $(date)" >> README.md
+   git add README.md
+   git commit -m "Test: Heroku deployment setup"
+   git push origin test-heroku-deployment
+   ```
+
+2. **Create PR on GitHub**:
+   - Go to your repository on GitHub
+   - Click "Compare & pull request"
+   - Create the pull request
+
+3. **Verify automatic deployment**:
+   - GitHub Actions workflow should trigger automatically
+   - Check the Actions tab for "Preview Branch Deployment" workflow
+   - A comment should appear on the PR with deployment links
+   - A new Heroku app should be created: `your-app-name-pr-123`
+
+4. **Check the Review App**:
+   - **Via Heroku Dashboard**: Go to your main app → Deploy tab → Review Apps section
+   - **Via GitHub**: Look for the workflow comment with the Heroku URL
+   - **Direct URL**: `https://your-app-name-pr-123.herokuapp.com`
+
+## Step 9: Monitor and Manage Deployments
+
+### Via Heroku Dashboard (Both Methods)
+
+1. **View all apps**:
+   - Go to [dashboard.heroku.com](https://dashboard.heroku.com)
+   - All your apps (main and review apps) will be listed
+
+2. **Monitor specific app**:
+   - Click on any app name
+   - **Overview tab**: App status, dyno usage, recent activity
+   - **Activity tab**: Deployment history and build logs
+   - **Logs tab**: Real-time application logs
+   - **Metrics tab**: Performance metrics (if enabled)
+
+3. **View deployment history**:
+   - In any app dashboard, click **"Activity"** tab
+   - See all builds, deployments, and configuration changes
+
+### Via CLI (Method B)
+```bash
+# List all apps
+heroku apps
+
+# View specific app info
+heroku apps:info your-app-name-pr-123
+
+# View recent deployments
+heroku releases --app your-app-name
+```
+
+### Check Application Health
+
+**Via Dashboard**:
+1. Go to your app dashboard
+2. Click **"Logs"** tab for real-time logs
+3. Check **"Metrics"** tab for performance data
+4. Review **"Overview"** tab for dyno status
+
+**Via CLI**:
+```bash
+# View logs
+heroku logs --tail --app your-app-name
+
+# Check app status
+heroku ps --app your-app-name
+
+# Scale dynos (if needed)
+heroku ps:scale web=1 --app your-app-name
+```
+
+### Manual Review App Management
+
+**Via Dashboard**:
+1. Go to your main app dashboard
+2. Click **"Deploy"** tab
+3. Scroll to **"Review Apps"** section
+4. See all active review apps with options to:
+   - **View**: Open the review app
+   - **Destroy**: Delete the review app manually
+   - **View Activity**: See deployment history
+
+**Via CLI**:
+```bash
+# Create a review app manually
+heroku review-apps:create --app your-app-name --pr 123
+
+# Destroy a review app
+heroku apps:destroy your-app-name-pr-123 --confirm your-app-name-pr-123
+```
+
+## Step 10: Production Deployment Configuration
+
+For production deployments, you can configure additional settings using either method:
+
+### Via Heroku Dashboard
+
+1. **Go to your main app** → **Settings** tab
+2. **Config Vars section** → **Reveal Config Vars**
+3. **Add production variables**:
+   - `NODE_ENV` = `production`
+   - `SPRING_PROFILES_ACTIVE` = `production`
+4. **SSL Configuration**:
+   - Go to **Settings** tab → **Domains and certificates**
+   - SSL is automatically enabled on paid plans
+5. **Custom Domain** (optional):
+   - In **Domains and certificates** section
+   - Click **"Add domain"**
+   - Enter your custom domain
+
+### Via CLI
+
+```bash
+# Set production environment
+heroku config:set NODE_ENV=production --app your-app-name
+heroku config:set SPRING_PROFILES_ACTIVE=production --app your-app-name
+
+# Configure SSL (automatically enabled on paid plans)
+heroku certs:auto:enable --app your-app-name
+
+# Set up custom domain (optional)
+heroku domains:add yourdomain.com --app your-app-name
+
+# Configure logging
+heroku logs --tail --app your-app-name
+```
+
+#### Troubleshooting Heroku Deployments
+
+##### Common Issues and Solutions
+
+**Issue**: Review App creation fails
+```
+Error: Could not create review app
+```
+**Solutions**:
+1. Verify `HEROKU_API_KEY` secret is correct
+2. Check that Review Apps are enabled in Heroku Dashboard
+3. Ensure the base app exists and is accessible
+4. Verify GitHub-Heroku connection is active
+
+**Issue**: Build failure during deployment
+```
+Error: Failed to compile app
+```
+**Solutions**:
+1. Check Heroku build logs: `heroku logs --app your-app-name-pr-123`
+2. Verify `Procfile` is present and correct
+3. Check `system.properties` specifies Java 17
+4. Ensure `gradlew build` works locally
+
+**Issue**: Application won't start
+```
+Error R10 (Boot timeout)
+```
+**Solutions**:
+1. Check application logs: `heroku logs --tail --app your-app-name`
+2. Verify `$PORT` environment variable is used in the application
+3. Check that the WAR file is built correctly
+4. Increase dyno memory if needed: `heroku ps:scale web=1:standard-1x`
+
+**Issue**: Review Apps not being destroyed
+**Solutions**:
+1. Enable automatic destruction in Heroku Dashboard
+2. Manually destroy old apps: `heroku apps:destroy app-name --confirm app-name`
+3. Set up automated cleanup with GitHub Actions
+
+##### Debug Commands
+
+```bash
+# Check Heroku configuration
+heroku config --app your-app-name
+
+# View application processes
+heroku ps --app your-app-name
+
+# Access application shell
+heroku run bash --app your-app-name
+
+# View build logs
+heroku builds --app your-app-name
+
+# Check app size and resources
+heroku apps:info your-app-name
+```
+
+#### Cost Considerations
+
+- **Free Tier**: Up to 5 apps, 550-1000 dyno hours/month
+- **Review Apps**: Each PR creates a new app (counts toward app limit)
+- **Automatic Scaling**: Consider destroying stale review apps automatically
+- **Production**: Hobby ($7/month) or Professional ($25-500/month) plans for production use
+
+For more information, see [Heroku Pricing](https://www.heroku.com/pricing)
+
+### Custom Preview Environments
+
+To deploy to custom infrastructure, modify the workflow:
+
+```yaml
+- name: Deploy to Preview Environment
+  if: vars.PREVIEW_DEPLOY_ENABLED == 'true'
+  run: |
+    # Add your deployment commands here
+    # Examples:
+    # - Deploy to AWS ECS/Fargate
+    # - Deploy to Kubernetes cluster
+    # - Deploy to DigitalOcean App Platform
+    # - Upload to S3 and update CloudFront
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Build Failures
+
+**Problem**: Gradle build fails with dependency resolution errors
+```
+Could not resolve com.android.tools.build:gradle:8.7.1
+```
+
+**Solution**: Check network connectivity and Android SDK setup
+```bash
+# Verify Java version
+java -version
+
+# Clean and rebuild
+./gradlew clean build --refresh-dependencies
+```
+
+#### Deployment Failures
+
+**Problem**: Heroku deployment fails
+```
+Error: Could not find or access app
+```
+
+**Solutions**:
+1. Verify `HEROKU_APP_NAME` variable is set correctly
+2. Check `HEROKU_API_KEY` secret is valid
+3. Ensure app exists in Heroku dashboard
+
+#### Artifact Download Issues
+
+**Problem**: Can't download artifacts from GitHub Actions
+
+**Solutions**:
+1. Check artifact retention period (7 days for preview, 30 days for main)
+2. Verify you have repository access permissions
+3. Check if the workflow run completed successfully
+
+### Getting Help
+
+1. **Check GitHub Actions logs** for detailed error messages
+2. **Review workflow run artifacts** for build outputs
+3. **Check repository issues** for known problems
+4. **Contact repository maintainers** for deployment-specific questions
+
+### Debugging Workflows
+
+Enable debug logging by adding this to your workflow run:
+
+```bash
+# Add this environment variable to workflow steps
+ACTIONS_STEP_DEBUG: true
+```
+
+Or check logs in the GitHub Actions UI for detailed execution information.
\ No newline at end of file