From ebf4b715b403fcfad84d820d3924b1f36d4b5fdc Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 19 Aug 2025 20:46:42 +0000
Subject: [PATCH 1/6] Initial plan


From 7aa2ebd6e04b359693f57be62fbb8794c86ccaec Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 19 Aug 2025 20:51:24 +0000
Subject: [PATCH 2/6] Add preview branch deployment workflow and comprehensive
 deployment documentation

Co-authored-by: litlfred <662242+litlfred@users.noreply.github.com>
---
 .github/workflows/preview-deploy.yml | 175 ++++++++++++++++
 README.md                            |  17 +-
 docs/deployment.md                   | 302 +++++++++++++++++++++++++++
 3 files changed, 493 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/preview-deploy.yml
 create mode 100644 docs/deployment.md

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.md b/docs/deployment.md
new file mode 100644
index 0000000..874e52c
--- /dev/null
+++ b/docs/deployment.md
@@ -0,0 +1,302 @@
+# 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)
+- [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 Review Apps Setup
+
+To enable automatic Heroku deployments for PRs:
+
+1. **Create a Heroku app** for your base environment
+2. **Enable Review Apps** in Heroku Dashboard
+3. **Configure GitHub variables**:
+   ```
+   HEROKU_APP_NAME=your-base-app-name
+   ```
+4. **Add Heroku secrets** to GitHub repository
+
+### 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

From ed2ef7dc19a1d58fea059a15904b36e35e209ef4 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 19 Aug 2025 20:52:53 +0000
Subject: [PATCH 3/6] Add deployment quick reference and validation tests

Co-authored-by: litlfred <662242+litlfred@users.noreply.github.com>
---
 docs/deployment-quick-reference.md | 53 ++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/deployment-quick-reference.md

diff --git a/docs/deployment-quick-reference.md b/docs/deployment-quick-reference.md
new file mode 100644
index 0000000..e11036e
--- /dev/null
+++ b/docs/deployment-quick-reference.md
@@ -0,0 +1,53 @@
+# 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
+
+### For Heroku Review Apps
+1. Set GitHub variable: `HEROKU_APP_NAME=your-app`
+2. Add secrets: `HEROKU_API_KEY`, `HEROKU_EMAIL`
+
+### 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

From 3ff92e5bf529a380e559d92ccb8f8f5ee8c866a4 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 19 Aug 2025 22:09:05 +0000
Subject: [PATCH 4/6] Add comprehensive Heroku deployment instructions

- Add detailed step-by-step Heroku setup guide to docs/deployment.md
- Include CLI installation, app creation, Review Apps configuration
- Add GitHub secrets/variables setup instructions
- Include troubleshooting section with common issues and solutions
- Add cost considerations and production deployment guidance
- Enhance quick reference with essential Heroku commands
- Address user request for detailed Heroku deployment instructions

Co-authored-by: litlfred <662242+litlfred@users.noreply.github.com>
---
 docs/deployment-quick-reference.md |  26 ++-
 docs/deployment.md                 | 272 ++++++++++++++++++++++++++++-
 2 files changed, 288 insertions(+), 10 deletions(-)

diff --git a/docs/deployment-quick-reference.md b/docs/deployment-quick-reference.md
index e11036e..aa93648 100644
--- a/docs/deployment-quick-reference.md
+++ b/docs/deployment-quick-reference.md
@@ -40,8 +40,30 @@ git push origin main && git push origin v1.2.3
 ## Quick Setup
 
 ### For Heroku Review Apps
-1. Set GitHub variable: `HEROKU_APP_NAME=your-app`
-2. Add secrets: `HEROKU_API_KEY`, `HEROKU_EMAIL`
+1. Create Heroku app: `heroku create your-app-name`
+2. Enable Review Apps in Heroku Dashboard
+3. Set GitHub variable: `HEROKU_APP_NAME=your-app-name`
+4. Add secrets: `HEROKU_API_KEY`, `HEROKU_EMAIL`
+
+### 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:
diff --git a/docs/deployment.md b/docs/deployment.md
index 874e52c..db40bc9 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -214,17 +214,273 @@ HEROKU_API_KEY=your_heroku_api_key
 HEROKU_EMAIL=your_heroku_email
 ```
 
-### Heroku Review Apps Setup
+### Heroku Deployment Setup
 
-To enable automatic Heroku deployments for PRs:
+This section provides complete step-by-step instructions for deploying the GDHCN Validator web application to Heroku, including both manual deployment and automated Review Apps for pull requests.
 
-1. **Create a Heroku app** for your base environment
-2. **Enable Review Apps** in Heroku Dashboard
-3. **Configure GitHub variables**:
-   ```
-   HEROKU_APP_NAME=your-base-app-name
+#### Prerequisites
+
+1. **Heroku Account**: Create a free account at [heroku.com](https://heroku.com)
+2. **Heroku CLI**: Install from [devcenter.heroku.com/articles/heroku-cli](https://devcenter.heroku.com/articles/heroku-cli)
+3. **Git**: Required for deployment
+4. **GitHub Repository Access**: Admin access to configure secrets and variables
+
+#### 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: Configure GitHub Repository
+
+##### 6.1: Add GitHub Secrets
+
+Go to your GitHub repository settings → Secrets and variables → Actions → Secrets:
+
+```bash
+# Get your Heroku API key
+heroku auth:token
+```
+
+Add these secrets:
+- **Name**: `HEROKU_API_KEY`
+- **Value**: `your-heroku-api-key-from-above-command`
+
+- **Name**: `HEROKU_EMAIL`  
+- **Value**: `your-heroku-account-email@example.com`
+
+##### 6.2: Add GitHub Variables
+
+Go to your GitHub repository settings → Secrets and variables → Actions → Variables:
+
+- **Name**: `HEROKU_APP_NAME`
+- **Value**: `your-app-name` (the base app name without any suffixes)
+
+#### Step 7: Test Review Apps
+
+1. **Create a test pull request**:
+   ```bash
+   git checkout -b test-heroku-deployment
+   echo "# Test deployment" >> README.md
+   git add README.md
+   git commit -m "Test: Heroku deployment"
+   git push origin test-heroku-deployment
    ```
-4. **Add Heroku secrets** to GitHub repository
+
+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`
+
+#### Step 8: Monitor and Manage Deployments
+
+##### View Heroku Apps
+```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
+```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
+```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 9: Production Deployment Configuration
+
+For production deployments, configure additional settings:
+
+```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
 

From 29a18bfa2c4424432cd236c3ccbb24be0f7b513a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 20 Aug 2025 11:00:56 +0000
Subject: [PATCH 5/6] Add detailed step-by-step GitHub secrets and variables
 setup instructions

Co-authored-by: litlfred <662242+litlfred@users.noreply.github.com>
---
 docs/deployment-quick-reference.md |  38 +++++-
 docs/deployment.md                 | 196 +++++++++++++++++++++++++++--
 2 files changed, 218 insertions(+), 16 deletions(-)

diff --git a/docs/deployment-quick-reference.md b/docs/deployment-quick-reference.md
index aa93648..65fdb67 100644
--- a/docs/deployment-quick-reference.md
+++ b/docs/deployment-quick-reference.md
@@ -39,11 +39,41 @@ git push origin main && git push origin v1.2.3
 
 ## Quick Setup
 
+## Quick Setup
+
 ### For Heroku Review Apps
-1. Create Heroku app: `heroku create your-app-name`
-2. Enable Review Apps in Heroku Dashboard
-3. Set GitHub variable: `HEROKU_APP_NAME=your-app-name`
-4. Add secrets: `HEROKU_API_KEY`, `HEROKU_EMAIL`
+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
diff --git a/docs/deployment.md b/docs/deployment.md
index db40bc9..5f0b229 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -10,6 +10,8 @@ This document provides comprehensive guidance for deploying the GDHCN Validator
 - [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
@@ -315,28 +317,198 @@ Review Apps automatically create temporary apps for each pull request, allowing
 
 #### Step 6: Configure GitHub Repository
 
-##### 6.1: Add GitHub Secrets
+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.
 
-Go to your GitHub repository settings → Secrets and variables → Actions → Secrets:
+##### 6.1: Get Required Information
+
+Before configuring GitHub, gather the required information:
 
 ```bash
-# Get your Heroku API key
+# 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.
+
+##### 6.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.
+
+##### 6.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
+```
+
+##### 6.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
+```
+
+##### 6.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
 ```
 
-Add these secrets:
-- **Name**: `HEROKU_API_KEY`
-- **Value**: `your-heroku-api-key-from-above-command`
+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
 
-- **Name**: `HEROKU_EMAIL`  
-- **Value**: `your-heroku-account-email@example.com`
+**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
 
-##### 6.2: Add GitHub Variables
+**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
 
-Go to your GitHub repository settings → Secrets and variables → Actions → Variables:
+**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
 
-- **Name**: `HEROKU_APP_NAME`
-- **Value**: `your-app-name` (the base app name without any suffixes)
+**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 7: Test Review Apps
 

From 385ff65cac7795c7a7562a949d0bb9a96a49f900 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 20 Aug 2025 11:12:10 +0000
Subject: [PATCH 6/6] Add comprehensive web-based Heroku deployment
 instructions alongside CLI methods

Co-authored-by: litlfred <662242+litlfred@users.noreply.github.com>
---
 docs/deployment-quick-reference.md |   9 +-
 docs/deployment.md                 | 281 ++++++++++++++++++++++++++---
 2 files changed, 264 insertions(+), 26 deletions(-)

diff --git a/docs/deployment-quick-reference.md b/docs/deployment-quick-reference.md
index 65fdb67..c06659e 100644
--- a/docs/deployment-quick-reference.md
+++ b/docs/deployment-quick-reference.md
@@ -39,9 +39,14 @@ git push origin main && git push origin v1.2.3
 
 ## Quick Setup
 
-## 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
 
-### For Heroku Review Apps
+**Option 2: CLI-Based Setup**
 1. **Heroku Setup**:
    ```bash
    heroku create your-app-name
diff --git a/docs/deployment.md b/docs/deployment.md
index 5f0b229..9bedde1 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -218,16 +218,161 @@ 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, including both manual deployment and automated Review Apps for pull requests.
+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. **Heroku CLI**: Install from [devcenter.heroku.com/articles/heroku-cli](https://devcenter.heroku.com/articles/heroku-cli)
-3. **Git**: Required for deployment
-4. **GitHub Repository Access**: Admin access to configure secrets and variables
+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
 
-#### Step 1: Install and Setup Heroku CLI
+---
+
+## 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)
@@ -243,7 +388,7 @@ curl https://cli-assets.heroku.com/install-ubuntu.sh | sh
 heroku login
 ```
 
-#### Step 2: Create Main Heroku Application
+### Step 2: Create Main Heroku Application
 
 ```bash
 # Create the main application
@@ -259,7 +404,7 @@ heroku config:set JAVA_TOOL_OPTIONS="-Xmx512m" --app your-app-name
 heroku apps:info your-app-name
 ```
 
-#### Step 3: Configure Heroku Application
+### Step 3: Configure Heroku Application
 
 ```bash
 # Set up Java buildpack (if not automatically detected)
@@ -272,7 +417,7 @@ heroku config:set SPRING_PROFILES_ACTIVE=production --app your-app-name
 heroku config --app your-app-name
 ```
 
-#### Step 4: Manual Deployment (One-time)
+### Step 4: Manual Deployment (One-time)
 
 ```bash
 # Clone and deploy the repository manually
@@ -292,7 +437,7 @@ heroku logs --tail --app your-app-name
 heroku open --app your-app-name
 ```
 
-#### Step 5: Enable Review Apps for Pull Requests
+### 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.
 
@@ -315,14 +460,40 @@ Review Apps automatically create temporary apps for each pull request, allowing
 4. Click **"Connect"**
 5. **Do not** enable automatic deploys for main branch (we use GitHub Actions instead)
 
-#### Step 6: Configure GitHub Repository
+### 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.
 
-##### 6.1: Get Required Information
+#### 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
@@ -336,7 +507,7 @@ heroku apps:info your-app-name | grep "Web URL"
 
 **Important**: Keep your API key secure and never share it publicly.
 
-##### 6.2: Add GitHub Secrets (Step-by-Step)
+#### 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.
 
@@ -369,7 +540,7 @@ HEROKU_EMAIL      Updated X seconds ago
 
 **Note**: You cannot view secret values after they're saved - this is a security feature.
 
-##### 6.3: Add GitHub Variables (Step-by-Step)
+#### 7.3: Add GitHub Variables (Step-by-Step)
 
 Variables store non-sensitive configuration that can be viewed by repository collaborators.
 
@@ -406,7 +577,7 @@ PREVIEW_DEPLOY_ENABLED    true
 STAGING_DEPLOY_ENABLED    true
 ```
 
-##### 6.4: Alternative Setup via GitHub CLI
+#### 7.4: Alternative Setup via GitHub CLI
 
 If you prefer command line setup, you can use the GitHub CLI:
 
@@ -433,7 +604,7 @@ gh secret list
 gh variable list
 ```
 
-##### 6.5: Verify Configuration
+#### 7.5: Verify Configuration
 
 **Test 1: Check GitHub Actions has access**
 1. Go to **Actions** tab in your repository
@@ -510,14 +681,18 @@ Error: App name is already taken
 - Review GitHub Actions logs regularly for security issues
 - Enable two-factor authentication for all admin accounts
 
-#### Step 7: Test Review Apps
+## 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" >> README.md
+   echo "# Test deployment - $(date)" >> README.md
    git add README.md
-   git commit -m "Test: Heroku deployment"
+   git commit -m "Test: Heroku deployment setup"
    git push origin test-heroku-deployment
    ```
 
@@ -532,9 +707,31 @@ Error: App name is already taken
    - A comment should appear on the PR with deployment links
    - A new Heroku app should be created: `your-app-name-pr-123`
 
-#### Step 8: Monitor and Manage Deployments
+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
 
-##### View Heroku Apps
+### Via CLI (Method B)
 ```bash
 # List all apps
 heroku apps
@@ -546,7 +743,15 @@ heroku apps:info your-app-name-pr-123
 heroku releases --app your-app-name
 ```
 
-##### Check Application Health
+### 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
@@ -558,7 +763,18 @@ heroku ps --app your-app-name
 heroku ps:scale web=1 --app your-app-name
 ```
 
-##### Manual Review App Management
+### 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
@@ -567,9 +783,26 @@ heroku review-apps:create --app your-app-name --pr 123
 heroku apps:destroy your-app-name-pr-123 --confirm your-app-name-pr-123
 ```
 
-#### Step 9: Production Deployment Configuration
+## 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
 
-For production deployments, configure additional settings:
+### Via CLI
 
 ```bash
 # Set production environment