Skip to main content

Workspaces

Workspaces let teams collaborate on shared connections, backups, comparisons, and deployments. Everything in HubSpot Deploy belongs to a workspace.

Overview​

A workspace is a shared environment where your team can:

  • Connect HubSpot portals and Git repositories
  • Create and manage backups
  • Compare metadata between environments
  • Deploy changes to portals
  • Collaborate with team members

Key benefits:

  • Team collaboration: Multiple users working together
  • Resource isolation: Each workspace has its own connections and data
  • Access control: Role-based permissions (admin vs member)
  • Organization: Separate workspaces for different clients, projects, or environments

Creating a Workspace​

Your First Workspace​

When you sign up, a default workspace is automatically created for you. You can rename it or create additional workspaces.

Creating Additional Workspaces​

  1. Click the workspace switcher in the top navigation bar
  2. Select New Workspace
  3. Enter a workspace name (e.g., "Acme Corp", "Production Environment")
  4. Click Create

You become the admin of any workspace you create.

Workspace Naming​

Good names:

  • ✅ "Acme Corp - Production"
  • ✅ "Client: TechStart"
  • ✅ "Development Team"
  • ✅ "Q1 2024 Project"

Avoid:

  • ❌ "Workspace 1"
  • ❌ "Test"
  • ❌ "My Workspace"

Switching Between Workspaces​

Using the Workspace Switcher​

The workspace switcher is located in the top navigation bar:

  1. Click the workspace name (shows current workspace)
  2. A dropdown appears with all your workspaces
  3. Click any workspace to switch to it
  4. The page reloads with the new workspace context

What changes when you switch:

  • All connections shown are from the new workspace
  • All comparisons and deployments are from the new workspace
  • All backups are from the new workspace
  • Your role may be different (admin in one, member in another)

Keyboard Shortcut​

Coming soon: Quick workspace switching with keyboard shortcuts.

Workspace Roles​

Admin Role​

Full access to everything in the workspace:

Can do:

  • ✅ Create and delete connections
  • ✅ Create and manage backups
  • ✅ Create and delete comparisons
  • ✅ Create and execute deployments
  • ✅ Invite and remove members
  • ✅ Change member roles
  • ✅ Rename and delete workspace

Use case: Team leads, project managers, senior developers

Member Role​

Read access with limited write permissions:

Can do:

  • ✅ View all connections
  • ✅ View all backups
  • ✅ Create comparisons
  • ✅ View comparisons
  • ✅ View deployment history

Cannot do:

  • ❌ Create or delete connections
  • ❌ Create or manage backups
  • ❌ Delete comparisons
  • ❌ Create or execute deployments
  • ❌ Manage workspace members
  • ❌ Rename or delete workspace

Use case: Junior developers, QA team, stakeholders who need visibility

Changing Roles​

Only admins can change member roles:

  1. Go to Workspace Settings
  2. Find the member in the list
  3. Click Change Role
  4. Select new role (Admin or Member)
  5. Confirm

Note: You cannot change your own role if you're the only admin.

Inviting Members​

How to Invite​

Only workspace admins can invite members:

  1. Go to Workspace Settings
    • Click workspace switcher → Settings
    • Or click profile menu → Workspace Settings
  2. Click Invite Member
  3. Enter the invitee's email address
  4. Select a role (Admin or Member)
  5. Click Send Invite

Invitation Process​

What happens:

  1. Invitee receives an email with invitation link
  2. They click the link to accept
  3. If they don't have an account, they sign up
  4. They're added to the workspace with the specified role

Invitation expiry: Invitations expire after 7 days.

Pending Invitations​

View pending invitations in Workspace Settings:

  • See who was invited and when
  • See what role they'll have
  • Cancel invitation if needed

To cancel:

  1. Go to Workspace Settings
  2. Find the pending invitation
  3. Click Cancel Invitation
  4. Confirm

Managing Members​

Viewing Members​

In Workspace Settings, you can see:

  • All current members
  • Their roles (Admin or Member)
  • When they joined
  • Pending invitations

Removing Members​

Only admins can remove members:

  1. Go to Workspace Settings
  2. Find the member to remove
  3. Click Remove
  4. Confirm removal

What happens:

  • Member loses access to the workspace immediately
  • They can no longer see workspace connections, comparisons, or deployments
  • They remain in other workspaces they belong to

Note: You cannot remove yourself if you're the only admin. Assign another admin first.

Workspace Settings​

Renaming a Workspace​

Only admins can rename workspaces:

  1. Go to Workspace Settings
  2. Click Rename Workspace
  3. Enter new name
  4. Click Save

Best practices:

  • Use descriptive names
  • Include client or project name
  • Indicate environment if applicable (Production, Staging)

Deleting a Workspace​

⚠️ Warning: Deleting a workspace is permanent and cannot be undone.

What gets deleted:

  • All connections (HubSpot and Git)
  • All comparisons
  • All backups and backup schedules
  • All deployment history
  • All member associations

What's preserved:

  • Nothing. All data is permanently deleted.

To delete a workspace:

  1. Go to Workspace Settings
  2. Scroll to Danger Zone
  3. Click Delete Workspace
  4. Type the workspace name to confirm
  5. Click Delete Permanently

Requirements:

  • You must be an admin
  • You'll be asked to confirm by typing the workspace name

Workspace-Scoped Resources​

What's Scoped to Workspaces?​

Everything in HubSpot Deploy belongs to a workspace:

ResourceWorkspace-ScopedShared Across Workspaces
HubSpot Connections✅❌
Git Repositories✅❌
Comparisons✅❌
Deployments✅❌
Backups✅❌
Backup Schedules✅❌
Drift Detection✅❌
Members✅❌

What this means:

  • Connections in Workspace A are not visible in Workspace B
  • You must connect the same HubSpot portal separately in each workspace
  • Comparisons and deployments are isolated per workspace

Why Workspace Isolation?​

Benefits:

  • Security: Team A can't see Team B's data
  • Organization: Keep client work separate
  • Access control: Different permissions per workspace
  • Clarity: No confusion about which resources belong where

Common Scenarios​

Scenario 1: Agency with Multiple Clients​

Setup:

  • Create one workspace per client
  • Name: "Client: Acme Corp", "Client: TechStart"
  • Invite client stakeholders as Members
  • Agency team members are Admins

Benefits:

  • Client data completely isolated
  • Clients can view their own data only
  • Easy to manage permissions per client

Scenario 2: Company with Multiple Environments​

Setup:

  • Create workspaces: "Production", "Staging", "Development"
  • Connect same portals in each workspace
  • Different team members in each workspace

Benefits:

  • Clear separation of environments
  • Different access controls per environment
  • Prevent accidental production deployments

Scenario 3: Large Team with Role Separation​

Setup:

  • Single workspace for the team
  • Admins: Senior developers, DevOps
  • Members: Junior developers, QA, Product managers

Benefits:

  • Everyone has visibility
  • Only trusted users can deploy
  • Collaboration without risk

Scenario 4: Freelancer with Multiple Projects​

Setup:

  • Create one workspace per project
  • Name: "Project: Website Redesign", "Project: CRM Migration"
  • You're the only member (admin)

Benefits:

  • Keep projects organized
  • Easy to archive completed projects
  • Clear billing per project

Best Practices​

Organization​

1. Use descriptive names:

  • Include client or project name
  • Add environment if applicable
  • Keep names consistent

2. Create workspaces strategically:

  • Don't create too many (hard to manage)
  • Don't create too few (lack of isolation)
  • Balance between organization and simplicity

3. Document workspace purpose:

  • Add description in workspace settings (coming soon)
  • Share workspace conventions with team
  • Keep a list of what each workspace is for

Access Control​

1. Follow principle of least privilege:

  • Give Member role by default
  • Only promote to Admin when needed
  • Review member roles regularly

2. Audit workspace members:

  • Monthly review of who has access
  • Remove members who left the team
  • Cancel unused pending invitations

3. Separate production access:

  • Limit production workspace admins
  • Require approval for production deployments
  • Use staging workspace for testing

Maintenance​

1. Clean up old workspaces:

  • Archive completed projects
  • Delete unused workspaces
  • Keep active workspaces count manageable

2. Review connections regularly:

  • Remove unused connections
  • Re-authenticate expired connections
  • Update connection names for clarity

3. Manage invitations:

  • Cancel expired invitations
  • Resend if needed
  • Follow up with invitees

Permissions Summary​

ActionAdminMember
View connections✅✅
Create / delete connections✅❌
View backups✅✅
Create / edit backups✅❌
View comparisons✅✅
Create comparisons✅✅
Delete comparisons✅❌
Create deployments✅❌
Manage workspace members✅❌
Rename workspace✅❌
Delete workspace✅❌

For the full permissions reference, see Permissions.

Troubleshooting​

Cannot Create Workspace​

Problem: "Create Workspace" button is disabled or missing

Possible causes:

  • Account limit reached
  • Browser issue

Solution:

  1. Refresh the page
  2. Try a different browser
  3. Contact support if issue persists

Cannot Switch Workspaces​

Problem: Workspace switcher doesn't show other workspaces

Possible causes:

  • You only belong to one workspace
  • Workspaces not loading

Solution:

  1. Verify you've been invited to other workspaces
  2. Check your email for pending invitations
  3. Refresh the page

Invitation Not Received​

Problem: Invited member didn't receive email

Possible causes:

  • Email in spam folder
  • Wrong email address
  • Email delivery delay

Solution:

  1. Check spam/junk folder
  2. Verify email address is correct
  3. Wait 10 minutes for delivery
  4. Resend invitation if needed

Cannot Remove Member​

Problem: "Remove" button is disabled

Possible causes:

  • You're not an admin
  • Trying to remove yourself (and you're the only admin)

Solution:

  1. Verify you have admin role
  2. If removing yourself, assign another admin first
  3. Contact another admin to remove you

Workspace Deleted by Mistake​

Problem: Accidentally deleted workspace

Solution: Unfortunately, workspace deletion is permanent and cannot be undone. You'll need to:

  1. Create a new workspace
  2. Reconnect all portals and repositories
  3. Recreate backup schedules
  4. Re-invite team members

Prevention: Always double-check before deleting a workspace.

Next Steps​