Creating a Preview Environment

Creating a Preview Environment #

This guide walks you through creating a Preview Environment for your Pull Request.

Prerequisites #

Before creating a Preview Environment, ensure you have:

  • ✅ A GitHub account with access to the BonsAI repository
  • ✅ A Pull Request created against the main branch
  • ✅ Changes pushed to your branch
  • ✅ Appropriate permissions (all team members have access)

Step-by-Step Guide #

Step 1: Create Your Pull Request #

  1. Push your changes to a feature branch:

    git checkout -b your-feature-branch
git add .
git commit -m "Your commit message"
git push origin your-feature-branch

  2. Go to GitHub and create a Pull Request:

    • Click “New pull request”
    • Select your feature branch as the source
    • Ensure main is the target branch
    • Fill in the PR title and description
    • Click “Create pull request”

Step 2: Add the Preview Label #

Once your PR is created:

  1. Look for the “Labels” section on the right side of the PR page
  2. Click on the gear icon (⚙️) next to “Labels”
  3. Select the preview label from the dropdown
  4. The label will be applied immediately

Adding Preview Label

Note: Only PRs targeting the main branch can have Preview Environments.

Step 3: Wait for Environment Creation #

After adding the label:

  1. GitHub Actions Workflow Starts

    • The workflow is triggered automatically
    • You can monitor progress by clicking “Actions” tab in the PR
    • Look for the “Preview Environment” workflow

  2. Coder Workspace Creation (~40 minutes)

    • Provisions an EC2 instance
    • Installs Docker and development tools
    • Clones your PR branch
    • Builds all application services
    • Starts the application stack

  3. Progress Updates

    • A comment will be posted to your PR when the environment is ready
    • The PR description will be updated with access links

Step 4: Access Your Environment #

Once ready, you’ll see a comment like this:

🎉 Preview environment created!

| Resource | URL |
|----------|-----|
| 🌐 Application | [Open Preview](https://app--dev--coder-preview-123--john.coder.internal.gotofu.com/) |

Workspace: coder-preview-123

⏱️ The environment is being set up and should be fully ready in ~40 minutes.

💡 Note: This environment will be automatically updated when you push new commits,
and deleted when the PR is closed.

Click the “Open Preview” link to access your environment!

What Happens During Creation #

Phase 1: Infrastructure Provisioning (5-10 minutes) # 

┌──────────────────────────────────────────┐
│  AWS EC2 Instance                        │
│  ├── Type: t3.2xlarge                   │
│  ├── RAM: 32 GB                         │
│  ├── Storage: 500 GB SSD                │
│  └── Region: Tokyo (ap-northeast-1)     │
└──────────────────────────────────────────┘

Phase 2: System Setup (10-15 minutes) # 

┌──────────────────────────────────────────┐
│  System Installation                     │
│  ├── Docker (rootless mode)             │
│  ├── mise (tool version manager)        │
│  ├── GitHub CLI                         │
│  ├── Development tools                  │
│  └── Environment variables              │
└──────────────────────────────────────────┘

Phase 3: Application Build (20-25 minutes) # 

┌──────────────────────────────────────────┐
│  Application Setup                       │
│  ├── Clone PR branch                    │
│  ├── Install Rust toolchain             │
│  ├── Install Node.js dependencies       │
│  ├── Install Python dependencies        │
│  ├── Build Rust services                │
│  ├── Build Next.js application          │
│  ├── Pull Docker images                 │
│  └── Apply database migrations          │
└──────────────────────────────────────────┘

Phase 4: Service Startup (5 minutes) # 

┌──────────────────────────────────────────┐
│  Services Starting                       │
│  ├── PostgreSQL                         │
│  ├── RabbitMQ                           │
│  ├── Redis                              │
│  ├── LocalStack (S3)                    │
│  ├── BonsAPI                            │
│  ├── Webapp                             │
│  ├── Background Workers                 │
│  └── Nginx Proxy                        │
└──────────────────────────────────────────┘

Automatic Updates #

When You Push New Commits #

Preview Environments automatically rebuild when you push changes:

  1. Detect Changes

    • GitHub Actions monitors your PR for new commits
    • Automatically triggers rebuild when changes are detected

  2. Restart Workspace (~10 minutes)

    • Pulls latest changes from your branch
    • Rebuilds modified services
    • Restarts application stack

  3. Notification

    • A comment is posted to your PR:
    🔄 Preview environment updated!

| Resource | URL |
|----------|-----|
| 🌐 Application | [Open Preview](https://...) |

Workspace: coder-preview-123

⏱️ The environment is being rebuilt with your latest changes
and should be ready in ~10 minutes.

Important: Data in the database and file storage will be preserved during updates. However, running processes will be restarted.

Monitoring Creation Progress #

Via GitHub Actions #

  1. Go to your Pull Request
  2. Click the “Actions” tab at the top
  3. Find the “Preview Environment” workflow run
  4. Click to view detailed logs

Via Coder Dashboard #

  1. Go to Coder Workspaces
  2. Find your workspace: coder-preview-{PR-number}
  3. View status and health indicators
  4. Access terminal if needed for debugging

Common Scenarios #

Scenario 1: First-Time Preview #

  • Timeline: ~40 minutes
  • What’s happening: Complete environment setup from scratch
  • Action required: Wait for completion notification

Scenario 2: Updating Existing Preview #

  • Timeline: ~10 minutes
  • What’s happening: Rebuilding with your latest changes
  • Action required: Wait for completion notification

Scenario 3: Testing Integration Changes #

  • Timeline: Same as above + integration setup time
  • What’s happening: Environment rebuilds, then you configure integrations
  • Action required: Follow integration setup guide

Tips for Faster Creation #

  1. Minimize Dependencies

    • Avoid adding new large dependencies if possible
    • They increase build time significantly

  2. Test Locally First

    • Use mise run ci to verify your changes locally
    • Fix any build errors before creating preview

  3. Clear PR Description

    • Helps reviewers understand what’s being tested
    • Makes it easier for QA to know what to verify

  4. Monitor Build Logs

    • Check GitHub Actions if build seems stuck
    • Look for errors in the workflow logs

Troubleshooting Creation Issues #

Build Fails #

If the Preview Environment creation fails:

  1. Check the GitHub Actions logs for error messages
  2. Common causes:
    • Compilation errors in Rust code
    • TypeScript type errors
    • Missing dependencies
    • Database migration issues

Solution: Fix the errors and push a new commit. The workflow will automatically retry.

Workspace Not Starting #

If Coder workspace appears to be stuck:

  1. Go to Coder Workspaces
  2. Find your workspace
  3. Check the build logs
  4. Look for “Failed” or “Canceled” status

Solution: Contact a developer with Coder admin access to investigate.

Taking Too Long #

If creation takes longer than 50 minutes:

  1. Check if there are any AWS issues in the region
  2. Verify GitHub Actions workflow is still running
  3. Check Coder dashboard for workspace status

Solution: You can safely cancel and retry by:

  • Removing the preview label
  • Waiting 1 minute
  • Re-adding the preview label

Next Steps #