1. Smart Custom Commands Setup
| Practice | Why it matters | How to do it |
|---|---|---|
| Order commands by dependency | Later commands may depend on earlier installs. | Run package installation first: npm ci && npm run build or pip install -r requirements.txt && pytest -q |
| Use exact package managers | Consistent lockfiles prevent version drift. | Use npm ci (not npm install), pnpm -w i, or pip install -r requirements.txt for reproducible builds |
| Chain related steps with && | Stops build on first failure, saves debugging time. | npm ci && npm run build && npm run test fails fast if any step breaks |
| Make scripts executable early | Avoid permission errors mid-build. | Add chmod +x ./scripts/setup.sh && bash ./scripts/setup.sh or use bash ./scripts/setup.sh directly |
| Keep commands idempotent | Re-running setup shouldn’t break things. | Use flags like pip install --no-deps or check for existing files before creating them |
| Minimize heavy operations | Long builds slow down workspace creation. | Focus on essential setup; defer optional tools to manual installation later |
Tip: Test your setup commands locally first. Each command runs withbashstrict mode (set -euo pipefail) at the repo root.
2. Git Workflows Inside a Remote Workspace
Branch Fast
Create feature branches as you would locally:
git checkout -b feature/workspace-improvements.Commit Often
Short commit cycles reduce merge pain and keep your workspace snapshot small.
Push via HTTPS
Remote credentials are injected automatically—no need to copy SSH keys.
Use Rebase for Clean History
git pull --rebase origin main keeps your branch up-to-date without noisy merge commits.Remember: everything you do in a remote workspace happens inside the cloud environment. Your local machine stays untouched until you pull changes down.
3. Workflow Patterns That Scale
Spin-Up-Per-Task
Spin-Up-Per-Task
Treat remote workspaces as disposable: create one per ticket or PR, then archive when merged.
Benefits: perfect isolation, zero “works on my machine” drift.
Benefits: perfect isolation, zero “works on my machine” drift.
Shared Review Environments
Shared Review Environments
Parallel Environments
Parallel Environments
Need to test multiple branches? Launch two workspaces and attach them to separate sessions; switch context without killing processes.
4. Team Collaboration Tips
| Tip | Details |
|---|---|
| Name workspaces clearly | Use service-purpose-branch (e.g., api-auth-refactor) so teammates know what’s running. |
| Document entry commands | Add a README_REMOTE_WORKSPACE.md with common tasks (npm run dev, pytest)—new hires onboard instantly. |
5. Troubleshooting at a Glance
| Symptom | Resolution |
|---|---|
| Rebuild is slow | Verify .dockerignore, cache heavy installs in image, use lighter base. |
| Git asks for credentials | Ensure repository integration is enabled in Integrations → Repositories. |
| Out-of-disk errors | Prune package caches (npm cache clean --force) or rebuild workspace. |
Quick Checklist Before Merging Code
- All tests pass inside remote workspace
- Linter is green
- Workspace hibernated or archived