GaeaFlow Gitspace

Connect to your GaeaFlow Gitspaces directly from VS Code via SSH.

Features

• 🌐 Multi-Server Support: Manage multiple GaeaFlow server instances
• 🔐 Flexible Authentication: Support Personal Access Token authentication
• 📋 Gitspace List: View all your Gitspaces organized by spaces
• 🚀 One-Click SSH: Connect to running Gitspaces with a single click
• 🔗 URI Handler: Open Gitspaces directly via custom URI links
• 🔑 Smart SSH Auth: Automatic key authentication with password fallback
• 🔄 Auto-Refresh: Configurable automatic list refresh
• ✨ Status Indicators: Real-time Gitspace state visualization
• 🎯 Cross-Compatible: Works with VS Code, VS Code Insiders, Cursor, and VSCodium

Requirements

• VS Code 1.85.0 or higher
• Remote - SSH extension
• Access to a GaeaFlow server
• SSH key pair (or password for Gitspace access)

Quick Start

1. Install the Extension

Install from the VS Code Marketplace or from a VSIX file:

code --install-extension gaeaflow-gitspace-1.0.1.vsix

2. Configure GaeaFlow Server

Method 1: Using Secure Token Storage (Recommended)

1. Open Command Palette (Cmd/Ctrl + Shift + P)
2. Run command: GaeaFlow: Set Token
3. Enter your Personal Access Token

Method 2: Using Settings

1. Open VS Code Settings (Cmd/Ctrl + ,)
2. Search for "GaeaFlow"
3. Configure the following settings:
   • GaeaFlow Host: Your GaeaFlow server URL (e.g., https://flow.example.com)

Getting Your Token

1. Visit your GaeaFlow profile page: {host}/profile
2. Create a new Personal Access Token
3. Copy the token and use Method 1 above to store it securely

🔒 Security Note: Tokens are now stored securely using VS Code's Secret Storage API, not in plain text settings.

3. Connect to a Gitspace

1. Click the GaeaFlow icon in the Activity Bar
2. Browse your Gitspaces organized by spaces
3. Find a running Gitspace (indicated by green status)
4. Click on the Gitspace to connect
5. The Remote SSH window will open automatically

URI Handler

Open and connect to Gitspaces directly using custom URI links. This feature enables deep linking from external tools, browsers, or documentation.

URI Format

vscode://gaeaflow.gaeaflow-gitspace/{spaceRef}/{gitspaceId}

Parameters:

• spaceRef: The space reference (e.g., ops, dev, team-alpha)
• gitspaceId: The Gitspace identifier

Examples

Full format (recommended):

# Open Gitspace in 'ops' space
open "vscode://gaeaflow.gaeaflow-gitspace/ops/optimistic-rogue-dos7v4-nlxvwu"

Simplified format (when space is not critical):

# Open Gitspace by ID only
open "vscode://gaeaflow.gaeaflow-gitspace/optimistic-rogue-dos7v4-nlxvwu"

Open extension view only:

# Just open the GaeaFlow extension view
open "vscode://gaeaflow.gaeaflow-gitspace"

Use Cases

• Share Links: Send direct Gitspace links to teammates
• Documentation: Embed links in wikis or README files
• Browser Integration: Create bookmarks or browser extensions
• CI/CD: Integrate with automation tools
• Custom Dashboards: Build internal developer portals

How It Works

1. Click or open the URI link
2. VS Code opens automatically
3. GaeaFlow extension activates
4. Extension view displays
5. Gitspace is located and connected (if running)

Troubleshooting URI Links

Link doesn't open:

• Ensure VS Code is installed and set as the default handler for vscode:// URIs
• Try copying the link and running it from terminal using open (macOS) or start (Windows)

Gitspace not found:

• Verify the Gitspace ID is correct
• Check that you have access to the Gitspace
• Enable debug mode (gaeaflow.debug) and check logs
• Click "Show Logs" in the error message for available Gitspaces

Configuration

Configure the extension in VS Code settings (Cmd/Ctrl + ,):

Available Settings

Example Configuration

{
  "gaeaflow.host": "https://flow.example.com",
  "gaeaflow.token": "your-personal-access-token",
  "gaeaflow.sshKeyPath": "~/.ssh/id_rsa",
  "gaeaflow.autoRefreshInterval": 300,
  "gaeaflow.connectionTimeout": 45
}

Commands

Access commands via Command Palette (Cmd/Ctrl + Shift + P):

• GaeaFlow: Set Token - Set Personal Access Token securely
• GaeaFlow: Clear Token - Clear stored token
• GaeaFlow: Show Logs - Show extension logs for debugging
• GaeaFlow: Open Settings - Open GaeaFlow extension settings
• GaeaFlow: Refresh Gitspaces - Refresh Gitspace list
• GaeaFlow: Connect to Gitspace - Connect to a selected Gitspace
• GaeaFlow: Disconnect from Gitspace - Disconnect from current Gitspace
• GaeaFlow: Open in Browser - Open Gitspace in browser (for Web IDE)
• GaeaFlow: Open in GaeaFlow Web - Open Gitspace in GaeaFlow web interface

Troubleshooting

Cannot see any Gitspaces

Cause: Missing or incorrect configuration

Solution:

1. Check that gaeaflow.host is set correctly
2. Verify your gaeaflow.token is valid
3. Ensure you have access to Gitspaces on the server
4. Check the Output panel (GaeaFlow channel) for errors

SSH connection fails with "Connection timeout"

Cause: Gitspace is not running or network issue

Solution:

1. Verify Gitspace status is "RUNNING" in GaeaFlow web interface
2. Check your network connection and firewall settings
3. Increase gaeaflow.connectionTimeout value
4. Try connecting manually: ssh user@host -p port

SSH key authentication fails

Cause: Public key not configured or wrong key path

Solution:

1. Verify gaeaflow.sshKeyPath points to your private key
2. Check key permissions: chmod 600 ~/.ssh/id_rsa
3. Ensure your public key is configured in GaeaFlow
4. Use password authentication when prompted as fallback

Gitspace connection opens in wrong directory

Cause: Working directory not properly configured

Solution:

• This should be automatically detected from your Gitspace configuration
• If issues persist, check your Gitspace settings in GaeaFlow web interface

Extension doesn't work in Cursor/VSCodium

Cause: API compatibility issue

Solution:

1. Check Help → About for engine version ≥1.85
2. Check the Output panel (GaeaFlow channel) for errors
3. Contact your system administrator for support

Security Notes

• ✅ Secure Token Storage: Personal Access Tokens are stored using VS Code's Secret Storage API
• ✅ No Plain Text: Tokens are encrypted and never stored in plain text
• ✅ Automatic Migration: Old tokens from settings will be automatically migrated to secure storage
• ✅ SSH Key Security: SSH keys are managed by your system's SSH agent
• ✅ HTTPS Only: Always use HTTPS URLs for GaeaFlow server connections

Token Management:

• Use GaeaFlow: Set Token command to store tokens securely
• Use GaeaFlow: Clear Token to remove stored tokens
• Tokens are stored per VS Code workspace/machine

License

This extension is licensed under the Apache License 2.0.

Acknowledgments

• Built with VS Code Extension API
• Integrates with GaeaFlow Cloud Development Platform
• Uses Remote - SSH

Made with ❤️ for the GaeaFlow community