MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-03-24 04:52:43 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs(workspaces): update onboarding to reflect unified architecture and npx usage

Browse Source
This commit is contained in:
mkorwel
2026-03-18 21:57:27 -07:00
parent 8cd24bf667
commit dfbe583050
1 changed files with 33 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
MAINTAINER_ONBOARDING.md
View File

@@ -1,83 +1,51 @@
# Gemini Workspaces: High-Performance Remote Development 🚀
# Gemini Workspaces: Maintainer Onboarding
Welcome to the Gemini Workspaces platform! This guide will help you set up your
remote development environment, which allows you to offload heavy tasks (reviews, fixes,
preflight) to a dedicated, high-performance GCP worker.
Gemini Workspaces allow you to offload heavy tasks (PR reviews, agentic fixes, full builds) to a high-performance GCP worker. It uses a **Unified Data Disk** architecture to ensure your work persists even if the VM is deleted or recreated.
## Prerequisites
## 1. Local Prerequisites
Before starting, ensure you have:
* **GCloud CLI**: Authenticated (`gcloud auth login`).
* **GitHub CLI**: Authenticated (`gh auth login`).
* **Project Access**: A GCP Project ID where you have `Editor` or `Compute Admin` roles.
1. **Google Cloud Access**: You will need a Google Cloud Project with billing enabled. You can use a shared team project or, **ideally, your own personal GCP project** for maximum isolation.
2. **GCloud CLI**: Authenticated locally (`gcloud auth login`).
3. **GitHub CLI**: Authenticated locally (`gh auth login`).
4. **Corporate Identity**: Run `gcert` (or your internal equivalent) recently to ensure SSH certificates are valid.
## Architecture: Persistent Cloud Workstations 🏗️
The system uses a **Workspace Provider** architecture to abstract the underlying infrastructure:
1. **GCE VM (Host)**: A high-performance machine running **Container-Optimized OS (COS)**.
2. **maintainer-worker (Container)**: A persistent Docker container acting as your remote workstation.
3. **Resilient Connectivity**: A verified corporate routing path using `nic0` and `.internal.gcpnode.com` for direct, high-speed access.
---
## Setup Workflow
### 1. The Turn-Key Setup
The entire environment can be initialized with a single command:
## 2. Initialization
Run the setup script using `npx tsx` to ensure all dependencies are available:
```bash
npm run workspace:setup
npx tsx .gemini/skills/workspaces/scripts/setup.ts
```
This interactive script will:
- **Phase 1: Configuration**: Auto-detect your repository origins, ask for your GCP project, and guide you through creating a secure GitHub token.
- **Phase 2: Infrastructure**: Automatically provision the "Magic" corporate network (VPC, Subnets, Firewalls) and the high-performance VM.
- **Phase 3: Initialization**: Synchronize your credentials and clone your repository into a persistent remote volume.
**What happens during setup:**
1. **Auth Discovery**: It will detect your `GEMINI_API_KEY` (from `~/.env`) and `GH_TOKEN`.
2. **Project Choice**: You will be prompted for your GCP Project and Zone.
3. **Infrastructure Check**: It verifies if your worker (`gcli-workspace-<user>`) exists.
4. **SSH Magic**: It generates a local `.gemini/workspaces/ssh_config` for seamless access.
---
## Daily Workflow
### Running a Workspace Job
To perform a deep behavioral review or an agentic fix on your remote worker:
## 3. Provisioning
If the setup informs you that the worker was not found, provision it:
```bash
# For a review
npm run workspace <PR_NUMBER> review
# For an automated fix
npm run workspace <PR_NUMBER> fix
npx tsx .gemini/skills/workspaces/scripts/fleet.ts provision
```
*This creates a VM with a 10GB Boot Disk and a 200GB Data Disk. Initialization takes ~1 minute.*
* **Isolation**: Each job runs in a dedicated **Git Worktree**.
* **Persistence**: Jobs run inside a `tmux` session. You can disconnect and reconnect without losing progress.
### Monitoring "Mission Control"
View the real-time state of your worker and all in-flight jobs:
## 4. Finalizing Remote Setup
Run the setup script one last time to clone the repo and sync credentials:
```bash
npm run workspace:status
npx tsx .gemini/skills/workspaces/scripts/setup.ts
```
*When you see "ALL SYSTEMS GO!", your workspace is ready.*
### Stopping Your Worker
## 5. Daily Usage
Once initialized, you can launch tasks directly through `npm`:
To save costs, shut down your worker when finished. The orchestrator will automatically wake it up when you start a new task.
* **Review a PR**: `npm run workspace <PR_NUMBER> review`
* **Fix a PR**: `npm run workspace <PR_NUMBER> fix`
* **Check Status**: `npx tsx .gemini/skills/workspaces/scripts/status.ts`
* **Stop Worker**: `npx tsx .gemini/skills/workspaces/scripts/fleet.ts stop` (Recommended when finished to save cost).
```bash
npm run workspace:fleet stop
```
---
## Resilience & Troubleshooting
### "SSH Connection Failed"
1. **Check Identity**: Run `gcert` to refresh your SSH credentials.
2. **Direct Path**: Ensure you are on the corporate network or VPN if required for `nic0` routing.
### "Worker Not Found"
The `setup` script will automatically offer to provision a worker if it can't find one. Simply follow the prompts.
## Troubleshooting
* **Permission Denied (Docker)**: The orchestrator handles this by using `sudo docker` internally.
* **Dubious Ownership**: The system automatically adds `/mnt/disks/data/main` to Git's safe directory list.
* **Missing tsx**: Always prefer `npx tsx` when running scripts manually.