Skip to content

190 add a staging environment for previewing and testing ahead of a new deployment - #201

Merged
lmcdonough merged 24 commits into
mainfrom
190-add-a-staging-environment-for-previewing-and-testing-ahead-of-a-new-deployment
Feb 27, 2026
Merged

190 add a staging environment for previewing and testing ahead of a new deployment#201
lmcdonough merged 24 commits into
mainfrom
190-add-a-staging-environment-for-previewing-and-testing-ahead-of-a-new-deployment

Conversation

@lmcdonough

@lmcdonough lmcdonough commented Oct 23, 2025

Copy link
Copy Markdown
Collaborator

🚀 Add Automated PR Preview Deployments

Implements isolated staging environments for every pull request.

What This Does

  • Auto-deploys backend on PR open/update to RPi5 via Tailscale
  • Isolated per PR: Separate containers, networks, volumes, ports
  • Bot comments on PR with clickable URLs and testing instructions
  • Auto-cleanup when PR closes/merges

Architecture

  • Backend port: 4000 + PR_NUMBER
  • Postgres port: 5432 + PR_NUMBER
  • Docker namespace: pr-{number} (complete isolation)
  • Images tagged: ghcr.io/owner/repo:pr-{number}

Files Added

  • .github/workflows/deploy-pr-preview.yml - Deployment automation
  • .github/workflows/cleanup-pr-preview.yml - Cleanup automation
  • docker-compose.pr-preview.yaml - Multi-tenant template
  • docs/PR-PREVIEW.md - Usage documentation

Access

  1. Connect to Tailscale
  2. Check PR comment for URLs
  3. Test your changes in isolation

@lmcdonough lmcdonough self-assigned this Oct 23, 2025
@lmcdonough lmcdonough added the feature work Specifically implementing a new feature label Oct 23, 2025
@lmcdonough lmcdonough added the infrastructure DevOps related label Oct 23, 2025
@lmcdonough lmcdonough linked an issue Oct 23, 2025 that may be closed by this pull request
Add a staging environment for previewing and testing ahead of a new deployment #190
Closed
@lmcdonough
lmcdonough requested a review from Copilot October 24, 2025 00:16

This comment was marked as outdated.

Sign in to view

lmcdonough and others added 13 commits February 20, 2026 09:33
@lmcdonough @claude
fix: handle wildcard CORS origins for PR preview environments
f253535 
Use AllowOrigin::mirror_request() when ALLOWED_ORIGINS contains "*"
to support credentials with wildcard origins. The browser rejects
Access-Control-Allow-Origin: * when credentials are included, so
we mirror the request's Origin header instead.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@lmcdonough @claude
docs: add comprehensive CI/CD documentation suite
c700b02 
- docs/cicd/README.md: CI/CD pipeline overview and architecture
- docs/cicd/pr-preview-environments.md: PR preview system documentation
- docs/cicd/future-improvements.md: planned enhancements
- docs/cicd/gap-analysis.md: current vs desired state analysis
- Reorganize runbooks into docs/cicd/ (docker-quickstart, production-deployment)
- README.md: add CI/CD documentation section
- .gitignore: add new ignore rules
- .vscode/settings.json: remove from tracking (already in .gitignore)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@lmcdonough
docs: update CLAUDE.md with PR preview environment guidance
63dc4ee 
Document reusable workflow architecture, Docker Compose PR preview
stack, nginx path-based routing, CORS wildcard handling, entrypoint
schema flow, and secrets resolution order with stale secret warning.
@lmcdonough
fix: resolve cross-repo secret resolution and SSE routing for PR prev…
bcfa097 
…iews

The pr-preview environment secrets (MailerSend, Tiptap) were empty when
the frontend repo called the reusable workflow because GitHub Actions
resolves environment secrets from the caller repo, not the callee.

- Make welcome email non-fatal in user creation (if-let-Err + warn log)
- Add || 'UNUSED' fallbacks for 6 backend-specific secrets in .env heredoc
- Fix misleading comments about cross-repo environment resolution
- Add dedicated SSE location blocks to both nginx preview configs
- Create deploy-pr-preview-dispatch.yml for correct secret resolution
- Fix frontend checkout steps to use explicit repository parameter
@lmcdonough
docs: update CLAUDE.md project structure to include all directories
3d0238f 
Added 7 missing directories: docs, events, nginx, nginx-preview,
scripts, sse, and testing-tools. Added brief descriptions for each.
@lmcdonough
docs: add new email template env vars to README
ddf0e11 
Added SESSION_SCHEDULED_EMAIL_TEMPLATE_ID, ACTION_ASSIGNED_EMAIL_TEMPLATE_ID,
and FRONTEND_BASE_URL to the email configuration section.
@lmcdonough
fix: use long-form depends_on for backend migrator dependency
38a33e5 
Addresses review comment by jhodapp on docker-compose.pr-preview.yaml:84
@lmcdonough
fix: restore clippy -D warnings flag in CI
f201fd8 
Addresses review comment by jhodapp on build-test-push.yml:47
@lmcdonough
fix: make cargo fmt check blocking in CI
46eaadc 
Addresses review comment by jhodapp on build-test-push.yml:51
@lmcdonough
fix: clean up secrets env file from runner on all paths
ce3f7b0 
Addresses review comment by jhodapp on ci-deploy-pr-preview.yml:955
@lmcdonough
fix: refuse wildcard CORS origins in production
ae76568 
Addresses review comment by jhodapp on web/src/lib.rs:137
@lmcdonough
fix: add port overflow validation for PR preview deployments
b887434 
Addresses review comment by jhodapp on ci-deploy-pr-preview.yml:791
@lmcdonough
fix: use strict SSH host key checking in PR preview workflow
21330bd 
Addresses review comment by jhodapp on ci-deploy-pr-preview.yml:867
@lmcdonough

lmcdonough commented Feb 21, 2026

Copy link
Copy Markdown
Collaborator Author

Already addressed.

@lmcdonough
fix: harden PR preview security and fix clippy warnings
f6c1cdb 
- Add EXIT trap for secrets env file cleanup on deploy failure
  (ci-deploy-pr-preview.yml). Without this, set -eo pipefail exits
  would leave DB passwords, GHCR PAT, and API keys on disk.

- Use StrictHostKeyChecking=yes in cleanup workflow to match deploy
  workflow (cleanup-pr-preview.yml). Fixes inconsistency where deploy
  used strict checking but cleanup used accept-new.

- Make PR preview lint gates match main CI: add -D warnings to clippy,
  remove continue-on-error from fmt (ci-deploy-pr-preview.yml).

- Fix clippy warnings: allow too_many_arguments on
  send_action_assigned_email, remove needless borrow in test code.

- Apply cargo fmt to all files.
@lmcdonough
fix: always build PR-specific frontend image for preview environments
6cb703c 
Backend PRs were reusing the main-arm64 frontend image which has
basePath="" baked in. Next.js basePath is a build-time config, so
PR previews needing basePath="/pr-<NUM>" for sub-path routing got
404s on all _next/static/* assets. Now frontend is always built
with the correct NEXT_PUBLIC_BASE_PATH regardless of repo_type.

Also adds branch fallback logic to checkout steps: if a specified
branch has been deleted (e.g. after merge), checkout falls back to
main for zero-downtime transitions.
@lmcdonough
fix: validate override images exist before skipping builds
35b25c7 
Override images (backend_image/frontend_image inputs) previously set
build_mode='skip' unconditionally. If the override pointed to a
deleted or nonexistent image, the workflow failed at docker pull
with no fallback. Now validates overrides with docker manifest
inspect — if missing, falls back to building from source.
@lmcdonough
fix: use frontend feature branch for PR previews
ad61a0d 
Frontend main branch lacks basePath support (NEXT_PUBLIC_BASE_PATH
in Dockerfile and next.config.mjs), causing _next/static/ asset 404s
in backend PR preview environments. Point to frontend feature branch
225 until PR #226 merges to main.
@jhodapp

This comment was marked as resolved.

Sign in to view
calebbourg

This comment was marked as resolved.

Sign in to view

jhodapp and others added 3 commits February 23, 2026 13:28
@jhodapp
Merge branch 'main' into 190-add-a-staging-environment-for-previewing…
19d8b10 
…-and-testing-ahead-of-a-new-deployment
@lmcdonough
merge: sync with origin/main
7a761ee 
Resolve merge conflicts in domain/src/emails.rs and
web/src/controller/organization/user_controller.rs by taking
main's refactored email patterns (ResolvedEmailConfig, private
send functions, internal error handling).
@lmcdonough
fix: remove Tailscale reference from PR preview comment
9a3b641 
Removes the "Access Requirements" section that mentioned Tailscale
from the automated PR comment template to avoid revealing internal
network infrastructure details.

Addresses review comment by jhodapp on PR #201
@lmcdonough

lmcdonough commented Feb 24, 2026

Copy link
Copy Markdown
Collaborator Author

Removed the Access Requirements section from the PR comment template.

@github-actions

github-actions Bot commented Feb 24, 2026

Copy link
Copy Markdown
Contributor

🚀 PR Preview Environment Deployed!

🔗 Access URLs

Service URL
Frontend http://neo/pr-201/
Backend API http://neo/pr-201/api
Health Check http://neo/pr-201/health
Base Path /pr-201/

📊 Environment Details

🧪 Testing

# Health check
curl http://neo/pr-201/health

# Frontend
curl http://neo/pr-201/

# API test
curl http://neo/pr-201/api/v1/users

🧹 Cleanup

Environment auto-cleaned when PR closes/merges

Deployed: 2026-02-24T22:20:00.551Z
Architecture: Native ARM64 build on Neo + Multi-tier caching

@jhodapp

jhodapp commented Feb 25, 2026

Copy link
Copy Markdown
Member

@lmcdonough approved from both Caleb and me. Before merging, you've got one merge conflict to take care of which Claude should be able to help you with if it's at all confusing.

@lmcdonough
merge: integrate main into PR preview feature branch
d104de2 
Resolve conflict in web/src/lib.rs keeping wildcard CORS logic
for PR preview environments while incorporating main's changes.
@lmcdonough
refactor: replace hardcoded frontend_branch with GitHub variable
ba09916 
Use PR_PREVIEW_FRONTEND_BRANCH repo variable instead of hardcoding the
frontend feature branch name. Falls back to 'main' when the variable is
unset or empty, eliminating post-merge code changes.
@github-actions

github-actions Bot commented Feb 27, 2026

Copy link
Copy Markdown
Contributor

🧹 PR Preview Environment Cleaned Up!

📊 Cleanup Summary

Resource Status
Containers ✅ Stopped and removed
PR-Specific Images (RPi5) ✅ Removed
Database Volume (RPi5) ✅ Removed
Network ✅ Removed
Compose File ✅ Deleted
Environment File ✅ Deleted
main-arm64 Image ❌ Build failed
PR Image (GHCR) ⚠️ Deletion skipped or failed

📝 Details

💡 Layer Caching Strategy

  • main-arm64 image now available for faster PR builds
  • Future PR builds will use main-arm64 layers as cache
  • Reduces build times and GHCR image accumulation
  • Single source of truth: main-arm64 image

Cleaned up: 2026-02-27T17:14:01.811Z
Workflow: cleanup-pr-preview.yml

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@calebbourg calebbourg calebbourg approved these changes
Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@jhodapp jhodapp jhodapp approved these changes

Assignees

@lmcdonough lmcdonough

Labels

feature work Specifically implementing a new feature infrastructure DevOps related

Projects

Refactor Coaching Platform
Status: ✅ Done

Milestone

1.0.0-beta3

Development

Successfully merging this pull request may close these issues.

Add a staging environment for previewing and testing ahead of a new deployment

4 participants

@lmcdonough @jhodapp @calebbourg