0
# Collaboration
1

2
User collaboration features for managing project access, team permissions, and multi-user workflows on the Surge platform.
3

4
## Capabilities
5

6
### Invite Collaborators
7

8
Invite users to collaborate on projects with appropriate access permissions.
9

10
```javascript { .api }
11
/**
12
 * Invite users as collaborators on projects
13
 * @param hooks - Optional lifecycle hooks
14
 * @returns Command function
15
 */
16
function invite(hooks?: HookConfig): CommandFunction;
17
```
18

19
**CLI Usage:**
20
```bash
21
# Invite collaborator to specific project
22
surge invite user@example.com example.surge.sh
23

24
# Interactive invitation
25
surge invite
26

27
# Invite with specific permissions
28
surge invite user@example.com --role developer
29

30
# Bulk invite
31
surge invite user1@example.com user2@example.com --project example.surge.sh
32
```
33

34
**CLI Options:**
35
- `-a, --add`: Add collaborator (alias for invite)
36
- `--role`: Specify collaborator role (owner, admin, developer, viewer)
37
- `--project`: Specify project for collaboration
38
- `--message`: Custom invitation message
39

40
**Library Usage:**
41
```javascript
42
surge.invite({})(process.argv.slice(2));
43
```
44

45
### Revoke Access
46

47
Remove collaborator access from projects and revoke permissions.
48

49
```javascript { .api }
50
/**
51
 * Revoke collaborator access from projects
52
 * @param hooks - Optional lifecycle hooks
53
 * @returns Command function
54
 */
55
function revoke(hooks?: HookConfig): CommandFunction;
56
```
57

58
**CLI Usage:**
59
```bash
60
# Revoke access from specific project
61
surge revoke user@example.com example.surge.sh
62

63
# Interactive revocation
64
surge revoke
65

66
# Revoke from all projects
67
surge revoke user@example.com --all
68

69
# Revoke specific permissions
70
surge revoke user@example.com --role developer
71
```
72

73
**CLI Options:**
74
- `-r, --remove`: Remove collaborator (alias for revoke)
75
- `--all`: Revoke access from all projects
76
- `--role`: Revoke specific role/permissions
77
- `--project`: Specify project for revocation
78

79
**Library Usage:**
80
```javascript
81
surge.revoke({})(process.argv.slice(2));
82
```
83

84
## Collaboration Roles
85

86
### Permission Levels
87

88
**Owner:**
89
- Full project control
90
- Manage all collaborators
91
- Billing and plan management
92
- Delete projects
93
- Transfer ownership
94

95
**Admin:**
96
- Deploy and manage projects
97
- Invite/revoke collaborators
98
- Configure project settings
99
- View analytics
100
- Cannot manage billing
101

102
**Developer:**
103
- Deploy to projects
104
- View project analytics
105
- Configure deployments
106
- Cannot manage users
107
- Cannot delete projects
108

109
**Viewer:**
110
- View project information
111
- Access analytics (read-only)
112
- View deployment history
113
- Cannot deploy or modify
114
- Cannot access billing
115

116
### Role Assignment
117

118
```bash
119
# Assign specific role during invitation
120
surge invite developer@example.com --role developer
121

122
# Change existing collaborator role
123
surge invite developer@example.com --role admin --update
124

125
# View current collaborators and roles
126
surge list --collaborators example.surge.sh
127
```
128

129
## Team Management
130

131
### Project Access Control
132

133
**Project-Level Permissions:**
134
- Each project has independent collaborator lists
135
- Roles can differ across projects
136
- Granular access control per project
137

138
**Organization-Level Access:**
139
- Enterprise plans support organization management
140
- Centralized user management
141
- Role inheritance across projects
142

143
### Collaboration Workflows
144

145
**Development Teams:**
146
```bash
147
# Frontend team
148
surge invite frontend@company.com --role developer
149
surge invite designer@company.com --role viewer
150

151
# Backend team  
152
surge invite backend@company.com --role admin
153
surge invite devops@company.com --role owner
154
```
155

156
**Client Collaboration:**
157
```bash
158
# Give client view access
159
surge invite client@external.com --role viewer
160

161
# Temporary contractor access
162
surge invite contractor@freelance.com --role developer --expire 30days
163
```
164

165
### Multi-Project Management
166

167
**Project Groups:**
168
```bash
169
# Add collaborator to multiple projects
170
surge invite developer@company.com staging.company.surge.sh production.company.surge.sh
171

172
# Bulk role assignment
173
surge invite team@company.com --role developer --projects staging,production,demo
174
```
175

176
**Template Permissions:**
177
```bash
178
# Apply permission template
179
surge invite newuser@company.com --template developer-standard
180

181
# Create permission template
182
surge config --template developer-standard --role developer --projects staging,demo
183
```
184

185
## Invitation Management
186

187
### Invitation Process
188

189
**Invitation Flow:**
190
1. Owner/Admin sends invitation
191
2. Invitee receives email notification
192
3. Invitee accepts invitation
193
4. Access granted to specified projects
194
5. Collaborator can immediately deploy/view
195

196
**Invitation Status:**
197
- **Pending**: Invitation sent, not yet accepted
198
- **Accepted**: User has joined as collaborator
199
- **Expired**: Invitation expired (default 7 days)
200
- **Revoked**: Invitation cancelled before acceptance
201

202
### Managing Invitations
203

204
```bash
205
# View pending invitations
206
surge invite --status pending
207

208
# Resend invitation
209
surge invite user@example.com --resend
210

211
# Cancel pending invitation
212
surge invite user@example.com --cancel
213

214
# Set invitation expiration
215
surge invite user@example.com --expire 14days
216
```
217

218
## Access Control
219

220
### Project Security
221

222
**Access Restrictions:**
223
- IP-based access control (enterprise)
224
- Time-based access expiration
225
- Project-specific permissions
226
- Audit logging for all actions
227

228
**Security Policies:**
229
```bash
230
# Require 2FA for collaborators
231
surge config example.surge.sh --require-2fa
232

233
# Set IP restrictions
234
surge config example.surge.sh --ip-whitelist 192.168.1.0/24
235

236
# Enable audit logging
237
surge config example.surge.sh --audit-log enabled
238
```
239

240
### Authentication Integration
241

242
**SSO Integration (Enterprise):**
243
- SAML 2.0 support
244
- OAuth integration
245
- Active Directory sync
246
- Custom authentication providers
247

248
**API Access:**
249
```bash
250
# Generate team API tokens
251
surge token --team frontend-team
252

253
# Revoke team tokens
254
surge token --revoke --team frontend-team
255

256
# List team tokens
257
surge token --list --team all
258
```
259

260
## Collaboration Features
261

262
### Communication
263

264
**Project Comments:**
265
- Add comments to deployments
266
- Tag team members in comments
267
- Email notifications for mentions
268
- Comment history and threading
269

270
```bash
271
# Add deployment comment
272
surge comment "Fixed navigation bug" --tag @developer@company.com
273

274
# View deployment comments
275
surge comments example.surge.sh --deployment latest
276
```
277

278
**Activity Feed:**
279
- Real-time activity notifications
280
- Deployment notifications
281
- Collaborator changes
282
- System alerts
283

284
### Shared Configuration
285

286
**Team Settings:**
287
```bash
288
# Share project configuration
289
surge config example.surge.sh --share-with team@company.com
290

291
# Synchronize settings across projects
292
surge config --sync staging.surge.sh production.surge.sh
293

294
# Team-wide defaults
295
surge config --team-defaults --ssl enabled --analytics detailed
296
```
297

298
**Environment Management:**
299
- Shared environment variables
300
- Team-wide deployment configurations
301
- Consistent build settings
302
- Shared SSL certificates
303

304
## Notification Management
305

306
### Email Notifications
307

308
**Notification Types:**
309
- New collaborator invitations
310
- Deployment success/failure
311
- Analytics reports
312
- System maintenance
313
- Security alerts
314

315
**Notification Settings:**
316
```bash
317
# Configure notification preferences
318
surge notifications --email deploy,invite,security
319

320
# Disable specific notifications
321
surge notifications --disable analytics
322

323
# Set notification frequency
324
surge notifications --frequency daily
325
```
326

327
### Webhook Integration
328

329
**Custom Webhooks:**
330
```bash
331
# Add deployment webhook
332
surge webhook add https://api.company.com/deploy --events deploy,rollback
333

334
# Slack integration
335
surge webhook add slack --channel #deployments --events deploy,invite
336

337
# Remove webhook
338
surge webhook remove webhook-id
339
```
340

341
**Webhook Events:**
342
- `deploy`: New deployments
343
- `rollback`: Deployment rollbacks
344
- `invite`: New collaborator invitations
345
- `revoke`: Access revocations
346
- `error`: Deployment failures
347

348
## Best Practices
349

350
### Team Organization
351

352
1. **Role Hierarchy**: Use appropriate roles for team members
353
2. **Project Separation**: Separate staging and production access
354
3. **Regular Audits**: Review collaborator access monthly
355
4. **Documentation**: Maintain team member and project documentation
356

357
### Security Guidelines
358

359
1. **Principle of Least Privilege**: Grant minimum necessary permissions
360
2. **Regular Access Reviews**: Audit and remove unused access
361
3. **Strong Authentication**: Enforce 2FA for all team members
362
4. **Monitoring**: Enable audit logging for security events
363

364
### Workflow Optimization
365

366
1. **Automation**: Use API tokens for CI/CD integration
367
2. **Templates**: Create role templates for consistent permissions
368
3. **Communication**: Establish clear deployment communication protocols
369
4. **Training**: Ensure team members understand their roles and permissions
370

371
## Troubleshooting
372

373
### Invitation Issues
374

375
**Invitation Not Received:**
376
- Check spam/junk folders
377
- Verify email address spelling
378
- Resend invitation
379
- Contact support for delivery issues
380

381
**Cannot Accept Invitation:**
382
- Check invitation expiration
383
- Verify Surge account exists
384
- Try different browser/device
385
- Clear browser cache and cookies
386

387
### Access Problems
388

389
**Permission Denied:**
390
- Verify current role and permissions
391
- Check project-specific access
392
- Confirm account authentication
393
- Review IP restrictions
394

395
**Missing Projects:**
396
- Check role permissions
397
- Verify project still exists
398
- Confirm collaborator status
399
- Review organization settings
400

401
### Collaboration Conflicts
402

403
**Simultaneous Deployments:**
404
- Coordinate deployment schedules
405
- Use staging environments
406
- Implement deployment locks
407
- Monitor deployment queues
408

409
**Configuration Conflicts:**
410
```bash
411
# Check current project settings
412
surge config example.surge.sh --show
413

414
# Resolve configuration conflicts
415
surge config example.surge.sh --merge-conflicts
416

417
# Reset to default configuration
418
surge config example.surge.sh --reset
419
```