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:

  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:

   git checkout -b test/cicd-setup

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

3. [ ] Commit and push:

   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:

   • [ ] https://dev.ourlantern.app
   • [ ] https://storybook.dev.ourlantern.app
   • [ ] https://docs.dev.ourlantern.app

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:

   • [ ] https://ourlantern.app
   • [ ] https://storybook.ourlantern.app
   • [ ] https://docs.ourlantern.app

---

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

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

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

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:

  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

---

Documentation Links

• Full CI/CD Guide - Complete documentation
• Branch Protection Setup - Detailed branch protection guide
• Deployment Overview - General deployment information
• Contributing Guide - Development workflow

---

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