Lantern

Appearance

CI/CD Pipeline Implementation Complete ​

Date: 2026-01-14
Status: ✅ Complete
Related Feature(s): CI/CD Guide

Problem Statement / Goal ​

Implement a comprehensive CI/CD pipeline for the Lantern App repository to automate builds, tests, and deployments. This addresses the need for:

  • Automated quality checks on every commit and pull request
  • Prevented merges of failing code
  • Streamlined deployments to development and production environments
  • Firestore index validation to prevent production issues
  • Discord bot integration for deployment notifications

Solution Overview ​

Created a complete GitHub Actions-based CI/CD pipeline with:

  1. Main CI Workflow - Runs on all commits and PRs to validate code quality
  2. Development Deployment - Auto-deploys to dev environment on merge to dev branch
  3. Production Deployment - Auto-deploys to production on merge to main branch with environment protection
  4. Security Scanning - CodeQL analysis for vulnerability detection
  5. Comprehensive Documentation - Setup guides, troubleshooting, and maintenance procedures

Files Changed/Created ​

Workflow Files ​

Documentation ​

Implementation Details ​

CI Workflow Jobs ​

1. Lint Job ​

  • Runs ESLint on all JavaScript/JSX files
  • Validates code formatting with Prettier
  • Required to pass before merging

2. Build Job ​

  • Builds web application with Vite
  • Builds Storybook component library
  • Builds VitePress documentation
  • Uploads build artifacts for review
  • Uses development Firebase configuration
  • Required to pass before merging

3. Test Job ​

  • Runs Vitest unit tests with coverage
  • Uploads coverage reports to Codecov (optional)
  • Uses development Firebase configuration
  • Required to pass before merging

4. Security Job ​

  • Runs npm audit on main dependencies
  • Runs npm audit on Discord bot dependencies
  • Non-blocking but generates warnings for review

5. Validate Firestore Indexes Job ​

  • Verifies firestore.indexes.json exists
  • Validates JSON syntax
  • Warns about manual index deployment requirements
  • Required to pass to prevent missing index issues in production

6. All Checks Complete Job ​

  • Aggregates results from all jobs
  • Provides clear pass/fail status
  • Required to pass as final gate

Deployment Workflows ​

Development Deployment ​

Triggers: Push to dev branch

Deploys:

  • Web app to Cloudflare Pages (lantern-app-dev project)
  • Storybook to Cloudflare Pages (lantern-storybook-dev project)
  • Docs to Cloudflare Pages (lantern-docs-dev project)
  • Firestore rules and indexes to lantern-app-dev Firebase project
  • Cloud Storage rules to lantern-app-dev Firebase project

Notifications:

  • Sends deployment status to Discord webhook
  • Includes links to all deployed services
  • Color-coded status (green = success, red = failure)

Production Deployment ​

Triggers: Push to main branch OR manual workflow dispatch

Environment Protection:

  • Uses GitHub production environment
  • Requires manual approval from designated reviewers (if configured)
  • Supports emergency deployments with optional test skipping

Deploys:

  • Web app to Cloudflare Pages (lantern-app project)
  • Storybook to Cloudflare Pages (lantern-storybook project)
  • Docs to Cloudflare Pages (lantern-docs project)
  • Firestore rules and indexes to lantern-app-prod Firebase project
  • Cloud Storage rules to lantern-app-prod Firebase project

Notifications:

  • Sends deployment status to Discord webhook
  • Alerts team on failures with exit code 1
  • Includes deployment URLs for verification

Security Scanning ​

CodeQL Workflow:

  • Scans JavaScript/JSX code for vulnerabilities
  • Runs on push to main/dev, PRs, and weekly schedule
  • Uses security-extended and security-and-quality query suites
  • Uploads results to GitHub Security tab
  • Non-blocking but generates alerts for review

Key Features ​

  1. Concurrency Control - Cancels in-progress CI runs for the same PR/branch to save resources
  2. Artifact Storage - Saves build artifacts for 7 days for review and debugging
  3. Firebase Integration - Automatically deploys Firestore rules, indexes, and Storage rules
  4. Discord Notifications - Real-time deployment status updates in team Discord
  5. Environment Variables - Separate dev/prod Firebase configs for clean environment separation
  6. Branch Protection Ready - Workflow names align with required status checks
  7. Rollback Support - Documentation includes rollback procedures for emergency situations

Required GitHub Secrets ​

The workflows require 16 secrets to be configured:

Firebase Development (6):

  • VITE_FIREBASE_API_KEY_DEV
  • VITE_FIREBASE_AUTH_DOMAIN_DEV
  • VITE_FIREBASE_PROJECT_ID_DEV
  • VITE_FIREBASE_STORAGE_BUCKET_DEV
  • VITE_FIREBASE_MESSAGING_SENDER_ID_DEV
  • VITE_FIREBASE_APP_ID_DEV

Firebase Production (6):

  • VITE_FIREBASE_API_KEY_PROD
  • VITE_FIREBASE_AUTH_DOMAIN_PROD
  • VITE_FIREBASE_PROJECT_ID_PROD
  • VITE_FIREBASE_STORAGE_BUCKET_PROD
  • VITE_FIREBASE_MESSAGING_SENDER_ID_PROD
  • VITE_FIREBASE_APP_ID_PROD

Cloudflare (2):

  • CLOUDFLARE_API_TOKEN
  • CLOUDFLARE_ACCOUNT_ID

Firebase CLI (1):

  • FIREBASE_TOKEN

Discord (1):

  • DISCORD_WEBHOOK_URL

Optional:

  • CODECOV_TOKEN (for coverage reports)

Testing Results ​

YAML Validation ​

All workflow files validated successfully:

  • ✅ ci.yml - Valid
  • ✅ deploy-dev.yml - Valid
  • ✅ deploy-prod.yml - Valid
  • ✅ codeql.yml - Valid
  • ✅ discord-notify.yml - Valid (existing)

Documentation Review ​

All documentation follows project standards:

  • ✅ Clear structure and navigation
  • ✅ Troubleshooting sections included
  • ✅ Quick reference commands provided
  • ✅ Links to related documentation
  • ✅ Follow CAPS_SNAKE_CASE.md naming convention

Firestore Index Considerations ​

The CI/CD pipeline includes special handling for Firestore indexes:

  1. Validation Job - Ensures firestore.indexes.json is valid JSON
  2. Deployment Jobs - Deploy indexes to both dev and prod Firebase projects
  3. Warning Messages - Remind developers to verify indexes exist in both environments
  4. Documentation - Includes troubleshooting for missing index errors

Why this matters:

  • Firestore queries fail with cryptic errors if indexes don't exist
  • Indexes may exist in dev but not prod (or vice versa)
  • Manual verification is still needed after auto-deployment
  • CI validation catches JSON syntax errors before deployment

Discord Bot Integration Notes ​

The deployment workflows send notifications to Discord:

Success Notification:

  • ✅ Green embed color
  • Lists all deployed services with status
  • Provides direct links to deployed sites
  • Shows commit SHA and author

Failure Notification:

  • ❌ Red embed color
  • Lists failed jobs
  • Alerts team to check logs
  • Exits with code 1 to flag issue

Important: If Discord webhook fails, deployments still complete successfully. The notification is informational only.

Branch Protection Recommendations ​

Documentation includes setup guide for:

  • Required status checks before merge
  • Required approvals (1 for main, 0-1 for dev)
  • Dismiss stale approvals on new commits
  • Require conversation resolution
  • Do not allow bypassing (even for admins)

Required Checks:

  • lint
  • build
  • test
  • validate-firestore-indexes
  • all-checks-complete

Note: Status checks only appear in branch protection settings AFTER they've run at least once on a PR!

Next Steps ​

The following items are ready for implementation:

  1. Configure GitHub Secrets - Add all required secrets to repository settings
  2. Enable Branch Protection - Set up protection rules for main and dev branches
  3. Configure Production Environment - Add required reviewers for production deployments
  4. Test CI Pipeline - Create a test PR to verify all jobs run successfully
  5. Test Deployments - Verify automatic deployments to dev and prod environments
  6. Monitor CodeQL - Review initial security scan results

Deployment Workflow Diagram ​

Feature Branch
     ↓
   Commit
     ↓
CI Workflow Runs
  ├─ Lint
  ├─ Build (app, storybook, docs)
  ├─ Test (with coverage)
  ├─ Security (npm audit)
  └─ Validate Firestore Indexes
     ↓
All Checks Pass?
  ├─ Yes → Enable merge button
  └─ No → Block merge
     ↓
Merge to dev
     ↓
Deploy to Development
  ├─ Deploy app to dev.ourlantern.app
  ├─ Deploy storybook to storybook.dev.ourlantern.app
  ├─ Deploy docs to docs.dev.ourlantern.app
  ├─ Deploy Firebase rules/indexes (dev)
  └─ Send Discord notification
     ↓
Merge dev to main
     ↓
Deploy to Production
  ├─ Manual approval (if configured)
  ├─ Deploy app to ourlantern.app
  ├─ Deploy storybook to storybook.ourlantern.app
  ├─ Deploy docs to docs.ourlantern.app
  ├─ Deploy Firebase rules/indexes (prod)
  └─ Send Discord notification

Maintenance Recommendations ​

Weekly:

  • Review CodeQL security scan results
  • Check for npm audit warnings in CI logs

Monthly:

  • Update dependencies with npm update
  • Review and update Firestore indexes if queries changed
  • Verify all deployments are healthy

Quarterly:

  • Rotate Firebase tokens (firebase login:ci)
  • Rotate Cloudflare API tokens
  • Review and optimize CI/CD workflows
  • Update GitHub Actions versions

Security Considerations ​

  1. Secrets Management - All sensitive data stored in GitHub Secrets, never in code
  2. Environment Separation - Distinct dev/prod Firebase projects prevent data leakage
  3. Branch Protection - Prevents accidental direct commits to main
  4. CodeQL Scanning - Weekly vulnerability scans with security-extended queries
  5. npm Audit - Dependency vulnerability checks on every CI run
  6. Token Rotation - Documentation recommends quarterly rotation of all tokens

Cost Impact ​

GitHub Actions:

  • Free tier: 2,000 minutes/month for private repos
  • Estimated usage: ~300-400 minutes/month (CI + deployments)
  • Cost: $0 (well within free tier)

Cloudflare Pages:

  • Unlimited deployments on free tier
  • 500 builds/month limit (more than sufficient)
  • Cost: $0

Firebase:

  • Firestore rules/indexes deployment: Free
  • No additional costs for CI/CD

Total Additional Cost: $0

Status: Implementation complete. Ready for secret configuration and testing.

Built with VitePress

Copyright © 2026 Lantern