diff --git a/.github/workflows/cleanup-pr-preview-frontend.yml b/.github/workflows/cleanup-pr-preview-frontend.yml new file mode 100644 index 00000000..51c7068e --- /dev/null +++ b/.github/workflows/cleanup-pr-preview-frontend.yml @@ -0,0 +1,40 @@ +# ============================================================================= +# Frontend PR Preview Cleanup Overlay Workflow +# ============================================================================= +# Purpose: Trigger cleanup when frontend PRs are closed/merged +# Calls: refactor-platform-rs/cleanup-pr-preview.yml (reusable workflow) +# ============================================================================= + +name: Cleanup PR Preview (Frontend) + +on: + pull_request: + # Trigger on PR close (includes merge) + types: [closed] + +permissions: + contents: read + packages: write + pull-requests: write + +jobs: + # =========================================================================== + # JOB: Call reusable cleanup workflow from backend repo + # =========================================================================== + cleanup-frontend-pr: + name: Cleanup Frontend PR Preview + # Call the reusable workflow from backend repository + uses: refactor-group/refactor-platform-rs/.github/workflows/cleanup-pr-preview.yml@190-add-a-staging-environment-for-previewing-and-testing-ahead-of-a-new-deployment + with: + # This is a frontend PR cleanup + repo_type: 'frontend' + # PR number to cleanup + pr_number: ${{ github.event.pull_request.number }} + # Branch name for image identification + branch_name: ${{ github.head_ref }} + secrets: inherit + # ========================================================================= + # NO SECRETS NEEDED! + # ========================================================================= + # The reusable workflow uses the backend repo's pr-preview environment + # which contains all necessary secrets for cleanup. diff --git a/.github/workflows/pr-preview-frontend.yml b/.github/workflows/pr-preview-frontend.yml new file mode 100644 index 00000000..e13c3223 --- /dev/null +++ b/.github/workflows/pr-preview-frontend.yml @@ -0,0 +1,68 @@ +# ============================================================================= +# Frontend PR Preview Overlay Workflow +# ============================================================================= +# Purpose: Trigger PR preview deployments when frontend PRs are opened/updated +# Strategy: Build frontend from PR branch, use main-arm64 backend image +# Calls: refactor-platform-rs/ci-deploy-pr-preview.yml (reusable workflow) +# ============================================================================= + +name: PR Preview (Frontend) + +on: + pull_request: + # Trigger on PR lifecycle events + types: [opened, synchronize, reopened] + # Only run for frontend code changes + paths-ignore: + - '**.md' + - 'docs/**' + - '.github/**' + - '!.github/workflows/pr-preview-frontend.yml' + - '!.github/workflows/cleanup-pr-preview-frontend.yml' + +# Prevent multiple deployments for the same PR +concurrency: + group: pr-preview-frontend-${{ github.event.pull_request.number }} + cancel-in-progress: true + +permissions: + contents: read + packages: write + pull-requests: write + attestations: write + id-token: write + +jobs: + # =========================================================================== + # JOB: Call reusable workflow with frontend-specific configuration + # =========================================================================== + deploy-frontend-pr: + name: Deploy Frontend PR Preview + # Call the reusable workflow from backend repository + # TODO: After backend PR #201 merges, update both: + # - uses: line to @main (instead of branch name) + # - backend_branch: to 'main' (instead of PR branch) + uses: refactor-group/refactor-platform-rs/.github/workflows/ci-deploy-pr-preview.yml@190-add-a-staging-environment-for-previewing-and-testing-ahead-of-a-new-deployment + with: + # This is a frontend PR deployment + repo_type: 'frontend' + # Use the PR number for port allocation and naming + pr_number: ${{ github.event.pull_request.number }} + # Build frontend from this PR's branch + branch_name: ${{ github.head_ref }} + # TEMPORARY: Use backend PR branch until #201 merges (compose file exists there) + # After merge: Change back to 'main' + backend_branch: '190-add-a-staging-environment-for-previewing-and-testing-ahead-of-a-new-deployment' + # Optional: override with specific image tags if needed + # backend_image: '' # Leave empty to use main-arm64 + # frontend_image: '' # Leave empty to build from PR branch + # Optional: force complete rebuild + force_rebuild: false + # ========================================================================= + # SECRETS - Resolved from backend repo's pr-preview environment + # ========================================================================= + # The reusable workflow (defined in backend repo) uses 'environment: pr-preview' + # which resolves to the BACKEND repo's pr-preview environment, not the frontend's. + # All secrets are consolidated in the backend repo's pr-preview environment. + # We use 'secrets: inherit' to pass GITHUB_TOKEN for cross-repo operations. + secrets: inherit diff --git a/README.md b/README.md index dcd373a5..8a870479 100644 --- a/README.md +++ b/README.md @@ -156,3 +156,19 @@ All tests should pass before merging code. The test suite is designed to: For more detailed testing information, see [docs/testing/frontend-testing-strategy.md](./docs/testing/frontend-testing-strategy.md). #### For Working with and Running the Application in Docker, navigate to the [Container-README](./docs/runbooks/Container-README.md) + +--- + +## PR Preview Environments + +This repository automatically deploys **isolated preview environments** for each pull request. When you open a PR, a complete stack (backend + frontend + database) deploys to a dedicated server on our Tailnet for testing before merge. + +**What happens automatically:** + +- ✅ PR opened → Environment deploys +- ✅ New commits → Environment updates +- ✅ PR closed/merged → Environment cleans up + +**Access:** Requires Tailscale VPN connection. Access URLs are posted as a comment on your PR in the GitHub Web UI. + +For detailed information, see the [PR Preview Environments Runbook](docs/runbooks/pr-preview-environments.md). diff --git a/docs/runbooks/pr-preview-environments.md b/docs/runbooks/pr-preview-environments.md new file mode 100644 index 00000000..12979495 --- /dev/null +++ b/docs/runbooks/pr-preview-environments.md @@ -0,0 +1,115 @@ +# PR Preview Environments - Developer Guide + +This guide explains how to use automatic PR preview environments for the Refactor Platform. + +## 🚀 Quick Start + +**Open a PR = Get a live preview environment automatically!** + +Every PR in `refactor-platform-rs` (backend) or `refactor-platform-fe` (frontend) triggers an automatic deployment of a full-stack preview environment. + +### What Happens When You Open a PR + +1. ✅ **Automatic deployment** starts (~5-10 min for first build) +2. ✅ **Full stack** deployed: Postgres + Backend + Frontend +3. ✅ **Unique ports** assigned based on PR number +4. ✅ **PR comment** posted with access URLs +5. ✅ **Auto-cleanup** when PR closes/merges + +### Access Your Preview + +After deployment completes, check the PR comment for your URLs: + +``` +🚀 PR Preview Environment Deployed! + +Frontend: http://rpi5-hostname:3042 +Backend: http://rpi5-hostname:4042 +Health: http://rpi5-hostname:4042/health + +Ports: Frontend: 3042 | Backend: 4042 | Postgres: 5474 +``` + +**Requirements:** +- 🔐 Must be connected to Tailscale VPN + +--- + +## 📖 Full Documentation + +For complete documentation including troubleshooting, advanced usage, and monitoring: + +👉 **See: [Backend Repo PR Preview Runbook](https://github.com/refactor-group/refactor-platform-rs/blob/main/docs/runbooks/pr-preview-environments.md)** + +The complete runbook covers: +- Port allocation formula +- Deployment architecture +- Testing & debugging +- Manual cleanup procedures +- Advanced configuration options +- Security considerations + +--- + +## 🎯 Quick Reference + +### Port Formula + +| Service | Formula | Example (PR #42) | +|---------|---------|------------------| +| Frontend | 3000 + PR# | 3042 | +| Backend | 4000 + PR# | 4042 | +| Postgres | 5432 + PR# | 5474 | + +### Common Commands + +**Health check:** +```bash +curl http://rpi5-hostname:4042/health +``` + +**View logs:** +```bash +ssh user@rpi5-hostname +docker logs pr-42-frontend-1 -f +docker logs pr-42-backend-1 -f +``` + +**Check status:** +```bash +ssh user@rpi5-hostname +docker compose -p pr-42 ps +``` + +--- + +## 🔧 How Frontend PRs Work + +When you open a frontend PR: +1. **Frontend:** Builds from your PR branch 📦 +2. **Backend:** Uses main-arm64 image (or builds if missing) +3. **Deploy:** Full stack with your frontend changes + +**No secrets needed in frontend repo!** All configuration is managed centrally in the backend repo's `pr-preview` environment. + +--- + +## 🐛 Troubleshooting + +**Deployment failed?** +- Check workflow logs: PR → "Checks" tab → View failed workflow +- Common: Lint errors, test failures, build errors + +**Can't access preview?** +- Verify Tailscale: `tailscale status` +- Check correct port from PR comment +- Ensure workflow succeeded + +**Need help?** +- Check full runbook (linked above) +- Ask in #engineering Slack +- Open an issue + +--- + +**Happy Testing! 🚀**