What is a Workspace?
A workspace is a logical container that:- Groups related projects together
- Has its own member list with independent permissions
- Provides isolation between different environments or teams
- Contains projects that share a common purpose
Common Workspace Patterns
- By Environment
- By Team
- By Product
Creating a Workspace
1
Navigate to your organization
From the dashboard, select the organization where you want to create a workspace.
2
Click 'New Workspace'
Click the New Workspace button.
3
Enter workspace details
- Name: A descriptive name for the workspace (e.g., “Production”, “Backend Team”)
- Slug: Auto-generated URL identifier
- Description (optional): Describe the purpose of this workspace
4
Create
Click Create to set up your workspace. You’ll automatically become an admin.
Workspace Roles
Workspace permissions are independent from organization roles. A member of an organization must be explicitly invited to a workspace to access its projects.| Role | Permissions |
|---|---|
| Admin | Full control over the workspace, including managing members and deleting projects |
| Editor | Can create, modify, and delete deployments. Cannot manage workspace settings or members. |
| Viewer | Read-only access. Can view deployments and logs but cannot make changes. |
Organization admins and owners can access all workspaces by default, but regular organization members must be explicitly invited to each workspace.
Managing Workspace Members
Inviting Members
1
Open workspace settings
Navigate to your workspace and click Settings or the members tab.
2
Invite a member
Select an organization member to invite, or enter an email for someone not yet in the organization.
3
Assign a role
Choose the appropriate workspace role (Admin, Editor, or Viewer).
Updating Member Roles
You can change a member’s role at any time:- Go to the workspace members list
- Click on the member’s current role
- Select the new role from the dropdown
Removing Members
To remove someone from a workspace:- Find them in the members list
- Click the remove button
- Confirm the removal
Removing someone from a workspace doesn’t remove them from the organization. They can be re-invited to the workspace later.
Workspace Settings
Basic Information
Update your workspace’s:- Name: The display name
- Description: Purpose or scope of the workspace
- Slug: URL-friendly identifier (changing this will update all URLs)
Deleting a Workspace
To delete a workspace:- Go to workspace settings
- Scroll to the danger zone
- Click Delete Workspace
- Confirm by typing the workspace name
Best Practices
Separate environments with workspaces
Separate environments with workspaces
Use different workspaces for production, staging, and development to prevent accidental changes to production.
Use meaningful names
Use meaningful names
Name workspaces clearly so team members know their purpose at a glance.
Limit admin access
Limit admin access
Only grant admin roles to people who need to manage the workspace structure. Most developers should be editors.
Use viewers for read-only access
Use viewers for read-only access
Give the viewer role to stakeholders who need to monitor deployments but shouldn’t make changes.