Spaces User GuidePhabricator User Documentation (Application User Guides)
Guide to the Spaces application.
Overview
The Spaces application makes it easier to manage large groups of objects which share the same access policy. For example:
- An organization might make a space for a project in order to satisfy a contractual obligation to limit access, even internally.
- An open source organization might make a space for work related to internal governance, to separate private and public discussions.
- A contracting company might make spaces for clients, to separate them from one another.
- A company might create a spaces for consultants, to give them limited access to only the resources they need to do their work.
- An ambitious manager might create a space to hide her team's work from her enemies at the company, that she might use the element of surprise to later expand her domain.
Phabricator's access control policies are generally powerful enough to handle these use cases on their own, but applying the same policy to a large group of objects requires a lot of effort and is error-prone.
Spaces build on top of policies and make it easier and more reliable to configure, review, and manage groups of objects with similar policies.
Creating Spaces
Spaces are optional, and are inactive by default. You don't need to configure them if you don't plan to use them. You can always set them up later.
To activate Spaces, you need to create at least two spaces. Create spaces from the web UI, by navigating to Spaces → Create Space. By default, only administrators can create new spaces, but you can configure this in the Applications application.
The first space you create will be a special "default" space, and all existing objects will be shifted into this space as soon as you create it. Spaces you create later will be normal spaces, and begin with no objects inside them.
Create the first space (you may want to name it something like "Default" or "Global" or "Public", depending on the nature of your organization), then create a second space. Usually, the second space will be something like "Secret Plans" and have a more restrictive "Visible To" policy.
Using Spaces
Once you've created at least two spaces, you can begin using them.
Application UIs will change for users who can see at least two spaces, opening up new controls which let them work with spaces. They will now be able to choose which space to create new objects into, be able to move objects between spaces, and be able to search for objects in a specific space or set of spaces.
In list and detail views, objects will show which space they're in if they're in a non-default space.
Users with access to only one space won't see these controls, even if many spaces exist. This simplifies the UI for users with limited access.
Space Policies
Briefly, spaces affect policies like this:
- Spaces apply their view policy to all objects inside the space.
- Space policies are absolute, and stronger than all other policies. A user who can not see a space can never see objects inside the space.
- Normal policies are still checked: spaces can only reduce access.
When you create a space, you choose a view policy for that space by using the Visible To control. This policy controls both who can see the space, and who can see objects inside the space.
Spaces apply their view policy to all objects inside the space: if you can't see a space, you can never see objects inside it. This policy check is absolute and stronger than all other policy rules, including policy exceptions.
For example, a user can never see a task in a space they can't see, even if they are an admin and the author and owner of the task, and subscribed to the task and the view and edit policies are set to "All Users", and they created the space originally and the moon is full and they are pure of heart and possessed of the noblest purpose. Spaces are impenetrable.
Even if a user satisfies the view policy for a space, they must still pass the view policy on the object: the space check is a new check in addition to any check on the object, and can only limit access.
The edit policy for a space only affects the space itself, and is not applied to objects inside the space.
Archiving Spaces
If you no longer need a space, you can archive it by choosing Archive Space from the detail view. This hides the space and all the objects in it without deleting any data.
New objects can't be created into archived spaces, and existing objects can't be shifted into archived spaces. The UI won't give you options to choose these spaces when creating or editing objects.
Additionally, objects (like tasks) in archived spaces won't be shown in most search result lists by default. If you need to find objects in an archived space, use the Spaces constraint to specifically search for objects in that space.
You can reactivate a space later by choosing Activate Space.
Application Email
After activating spaces, you can choose a space when configuring inbound email addresses in Applications.
Spaces affect policies for application email just like they do for other objects: to see or use the address, you must be able to see the space which contains it.
Objects created from inbound email will be created in the space the email is associated with.
Limitations and Caveats
Some information is shared between spaces, so they do not completely isolate users from other activity on the install. This section discusses limitations of the isolation model. Most of these limitations are intrinsic to the policy model Phabricator uses.
Shared IDs: Spaces do not have unique object IDs: there is only one T1, not a separate one in each space. It can be moved between spaces, but T1 always refers to the same object. In most cases, this makes working with spaces simpler and easier.
However, because IDs are shared, users in any space can look at object IDs to determine how many objects exist in other spaces, even if they can't see those objects. If a user creates a new task and sees that it is T5000, they can know that there are 4,999 other tasks they don't have permission to see.
Globally Unique Values: Some values (like usernames, email addresses, project hashtags, repository callsigns, and application emails) must be globally unique.
As with normal policies, users may be able to determine that a #yolo project exists, even if they can't see it: they can try to create a project using the #yolo hashtag, and will receive an error if it is a duplicate.
User Accounts: Spaces do not apply to users, and can not hide the existence of user accounts.
For example, if you are a contracting company and have Coke and Pepsi as clients, the CEO of Coke and the CEO of Pepsi will each be able to see that the other has an account on the install, even if all the work you are doing for them is separated into "Coke" and "Pepsi" spaces.