Collaborate in a shared workspace

"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 overwriting or changing someone else's work, or messing up your team's versioning. 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. 

How are costs and billing covered? 
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. 

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 Dashboard (see screenshot below).

  

  1.2. In the popup menu, choose "Share" (circled).

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

  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.

What to expect

Your collaborator will receive an email that the workspace has been shared with them and should see the workspace right away in "My Workspaces".

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. 

How to share a workspace with a service account   

You may wish to share a workspace with a service account - a special type of account that manages permissions on your behalf, and authorizes access to cloud resources.

When to share with a service account

For example, if you want to use a product like TensorFlow to apply machine learning algorithms to data in a workspace bucket, you can register a service account to manage authorization to that bucket.

How to register a service account

To learn how to register a service account, see Register a service account for use in Terra.

For security purposes, service accounts cannot be created in Terra-created Google projects. You must create the service account in a different Google Cloud project.

Running this script will register the new service account, and print out an email address for that account that will look something like this:

svc_account_name@project_name.iam.gserviceaccount.com

Now, you can share the workspace with the service account as described in steps 1 and 2 of this article, entering that service account's email into the "user email" field. 

Workspaces with Authorization Domains

You need to add the service account to the authorization domain if the workspace has one.

See Sharing data and tools with workspace access controls for more details on Reader, Writer and Owner roles.