How to collaborate in a shared workspace

Derek Caetano-Anolles
  • Updated

Sharing a workspace allows collaborators to actively work together in the same workspace. Sharing a workspace lets you see what sorts of changes your colleagues implement, troubleshoot efficiently as a team, and delegate work. Read on for step-by-step instructions.

Before you share... Protect from overwriting Collaborators may end up making overwriting or changing someone else's work, or messing up your team's versioning organization. Terra has a system for preventing Jupyter notebooks from being overwritten. However, you will want to establish a system so that you do not overwrite the documentation or workflows in a shared workspace.

Warning: All costs are covered by the owner's billing project
The original workspace billing project covers all work done and costs incurred in a shared workspace. This may be fine if all your collaborators are working in the same lab or with the same grant. You may need to assign more restrictive roles (i.e., non-compute) to others when sharing. For an alternative to sharing - with different implications for costs and billing - see this article on cloning a workspace

Workspace roles and what collaborators can see and do

Workspace owners control access to data and tools in a workspace by granting permissions to collaborators at the workspace level.


Can view the workspace dashboard, data tables, workflows, workflow configuration and workflow submission details, and notebooks.


Can also make changes to the workspace and edit and run workflows. Each user in a shared workspace will run workflows using their own Cromwell service and is able to see submission history and troubleshooting logs from other collaborators' submissions.


Can add or change collaborator roles for others in the workspace or delete the workspace entirely. Note that you are a workspace OWNER any time you create or clone a workspace.

Step-by-step guide to sharing workspaces in Terra

Step 1. Access the share form (from the three vertical dots icon)

  • 1.1. Click on the workspace action menu button on the top right of your workspace (see screenshot below):


    1.2. In the popup menu, choose "Share":

  • 1.1. To access the full list of Terra workspaces available to you, click on "View Workspaces" from the Terra homepage

    1.2. Click on the three vertical dots at the right of the card of the workspace you want to share:

    1.3. In the popup menu, choose "Share":

Step 2. Complete the sharing form

2.1. Type in the Terra user account address of the person you want to share with.


2.2. Hit "Return" or "Enter" on your keyboard. You should see the address populate below in the list of Current Collaborators surrounded by a pale green box.


If you don't see their name in a pale green box, go back to step 2.1 and make sure to hit return or enter. 

2.3. Choose the role you want to assign and check the permission checkboxes as needed.

2.4. Click the Save button.

Collaborators may not be able to access shared workspaces right away!There is a lag (a few hours) between when you share and when collaborators can access the workspace. This has to do with back-end processes around permissions.

Verifying your share

Check to make sure your share was successful by clicking the workspace action menu button again and selecting Share.

If you see an orange PENDING warning (screenshot below), this is most likely because of a typo in your collaborator's user ID. Cancel the share and try again. 


Was this article helpful?



Please sign in to leave a comment.