Lantern

Appearance

CI/CD Quick Setup Checklist ​

This is a quick reference checklist for setting up the CI/CD pipeline for Lantern. For detailed instructions, see CICD_GUIDE.md.

Prerequisites ​

  • [ ] GitHub repository with workflows in .github/workflows/
  • [ ] Cloudflare account with Pages projects created
  • [ ] Firebase projects (dev and prod) set up
  • [ ] Discord webhook created
  • [ ] Admin access to repository settings

Step 1: Configure GitHub Secrets ​

Go to Settings → Secrets and variables → Actions → New repository secret

Firebase Development (6 secrets) ​

  • [ ] 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 secrets) ​

  • [ ] 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 secrets) ​

  • [ ] CLOUDFLARE_API_TOKEN (from Cloudflare dashboard → API Tokens)
  • [ ] CLOUDFLARE_ACCOUNT_ID (from Cloudflare dashboard → Account)

Firebase CLI (1 secret) ​

  • [ ] FIREBASE_TOKEN (run firebase login:ci to generate)

Discord (1 secret) ​

  • [ ] DISCORD_WEBHOOK_URL (from Discord server settings)

Optional ​

  • [ ] CODECOV_TOKEN (from codecov.io, optional for coverage reports)

Total: 16 required secrets + 1 optional

Step 2: Enable GitHub Actions ​

  • [ ] Go to Settings → Actions → General
  • [ ] Select Allow all actions and reusable workflows
  • [ ] Scroll to Workflow permissions
  • [ ] Select Read and write permissions
  • [ ] ✅ Check Allow GitHub Actions to create and approve pull requests
  • [ ] Click Save

Step 3: Set Up Branch Protection ​

Go to Settings → Branches → Add branch protection rule

For main branch ​

  • [ ] Branch name pattern: main
  • [ ] ✅ Require a pull request before merging
    • [ ] Required approvals: 1
    • [ ] ✅ Dismiss stale pull request approvals when new commits are pushed
  • [ ] ✅ Require status checks to pass before merging
    • [ ] ✅ Require branches to be up to date before merging
    • [ ] Add required checks (only appear after first run):
      • [ ] lint
      • [ ] build
      • [ ] test
      • [ ] validate-firestore-indexes
      • [ ] all-checks-complete
  • [ ] ✅ Require conversation resolution before merging
  • [ ] ✅ Do not allow bypassing the above settings
  • [ ] ✅ Include administrators
  • [ ] Click Create

For dev branch ​

  • [ ] Repeat above steps with branch name pattern: dev

Note: Required status checks only appear in the dropdown AFTER they've run at least once. Push a test PR to populate them.

Step 4: Configure Production Environment ​

Go to Settings → Environments → New environment

  • [ ] Environment name: production
  • [ ] ✅ Required reviewers
    • [ ] Add at least one reviewer who can approve production deployments
  • [ ] (Optional) ✅ Wait timer: 5 minutes
  • [ ] Click Save protection rules

Step 5: Configure Cloudflare Pages ​

Ensure these Cloudflare Pages projects exist:

Development ​

  • [ ] lantern-app-dev (production branch: dev)
  • [ ] lantern-storybook-dev (production branch: dev)
  • [ ] lantern-docs-dev (production branch: dev)

Production ​

  • [ ] lantern-app (production branch: main)
  • [ ] lantern-storybook (production branch: main)
  • [ ] lantern-docs (production branch: main)

Custom domains:

  • [ ] dev.ourlantern.app → lantern-app-dev
  • [ ] storybook.dev.ourlantern.app → lantern-storybook-dev
  • [ ] docs.dev.ourlantern.app → lantern-docs-dev
  • [ ] ourlantern.app → lantern-app
  • [ ] storybook.ourlantern.app → lantern-storybook
  • [ ] docs.ourlantern.app → lantern-docs

Step 6: Deploy Firestore Indexes ​

The workflows will deploy indexes automatically, but they must exist locally:

  • [ ] Verify firestore.indexes.json exists and is valid
  • [ ] Test manual deployment:
    bash
    firebase deploy --only firestore:indexes --project lantern-app-dev
firebase deploy --only firestore:indexes --project lantern-app-prod

Step 7: Test CI/CD Pipeline ​

Test CI Workflow ​

  1. [ ] Create a test branch:

    bash
    git checkout -b test/cicd-setup

  2. [ ] Make a small change (add a comment to any file)

  3. [ ] Commit and push:

    bash
    git add .
git commit -m "test: verify CI pipeline"
git push origin test/cicd-setup

  4. [ ] Open a pull request to dev

  5. [ ] Verify:

    • [ ] CI workflow runs automatically
    • [ ] All jobs complete successfully (lint, build, test, security, validate-firestore-indexes)
    • [ ] "Merge" button is enabled only after checks pass

Test Development Deployment ​

  1. [ ] Merge the test PR to dev branch

  2. [ ] Verify:

    • [ ] Deploy to Development workflow triggers
    • [ ] All deployments succeed (app, storybook, docs, firebase)
    • [ ] Discord notification received

  3. [ ] Check deployed sites:

Test Production Deployment (Optional) ​

  1. [ ] Merge dev to main (via PR)

  2. [ ] Verify:

    • [ ] Manual approval required (if environment protection enabled)
    • [ ] Deploy to Production workflow triggers after approval
    • [ ] All deployments succeed
    • [ ] Discord notification received

  3. [ ] Check deployed sites:

Step 8: Enable CodeQL Security Scanning ​

CodeQL should run automatically, but verify:

  • [ ] Go to Security → Code scanning
  • [ ] Verify CodeQL workflow ran successfully
  • [ ] Check for any alerts

Scheduled: CodeQL runs weekly on Mondays at 6:30 AM UTC

Step 9: Monitor Workflows ​

  • [ ] Go to Actions tab
  • [ ] Verify all workflows show green checkmarks
  • [ ] Click on any workflow to view logs
  • [ ] Bookmark this page for future monitoring

Troubleshooting Quick Reference ​

CI Fails: Lint Errors ​

bash
npm run lint:fix
npm run format

CI Fails: Build Errors ​

  • Check for TypeScript/JavaScript errors
  • Verify environment variables in GitHub Secrets

CI Fails: Test Errors ​

bash
npm test

Fix failing tests locally

Deployment Fails: Cloudflare API Error ​

  • Verify CLOUDFLARE_API_TOKEN is valid
  • Check token has Pages:Edit permissions
  • Verify CLOUDFLARE_ACCOUNT_ID is correct

Deployment Fails: Firebase Error ​

bash
firebase login:ci

Update FIREBASE_TOKEN secret with new token

Discord Notification Not Received ​

  • Verify DISCORD_WEBHOOK_URL is correct
  • Check webhook exists in Discord server
  • Test webhook:
    bash
    curl -X POST $DISCORD_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"content": "Test notification"}'

Post-Setup Verification ​

After completing all steps above, verify:

  • [ ] All GitHub secrets are set (16 required)
  • [ ] Branch protection enabled for main and dev
  • [ ] Production environment configured with approvers
  • [ ] Test PR successfully passed CI checks
  • [ ] Test deployment to dev environment worked
  • [ ] Discord notifications received
  • [ ] All deployed sites are accessible
  • [ ] CodeQL scan completed without critical issues

Maintenance Schedule ​

Weekly ​

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

Monthly ​

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

Quarterly ​

  • [ ] Rotate Firebase tokens
  • [ ] Rotate Cloudflare API tokens
  • [ ] Review and optimize CI/CD workflows

Next Steps ​

Once CI/CD is fully set up:

  1. [ ] Document any custom configurations in team wiki
  2. [ ] Train team on PR workflow and CI checks
  3. [ ] Set up monitoring alerts for failed deployments
  4. [ ] Consider adding integration tests (E2E tests)
  5. [ ] Explore performance budgets in CI

Questions or issues? Create a GitHub issue with the documentation label or ask in the team Discord channel.

Built with VitePress

Copyright © 2026 Lantern