Phabricator Administrator's Handbook/Projects

A generic icon of a Project in Phabricator.

In Phabricator almost everything can be organized or related to Projects.

Here you will learn more about them.

Use cases

Some Phabricator Projects with different colors and purposes.

Probably the first thing you will do after installing Phabricator is creating some projects. For example, with Projects you can:

• describe areas of interests to organize your work
• group members of companies and organizations
• create permissions and policies (for example: need to be part of a project to push into a repository)

Also but not limited to:

• a Project can have sub-Projects to organize hierarchies
• a Project can have lot of Milestones to organize releases, sprints, etc.

Creating a new Project

The Favourite menu opened, with the Create Project entry.

You can create a Project opening the Favorite menu, from the top of your homepage, and then click on Create Project.

You can find all your projects at the URL:

example.com/project/

Form fields:

Name

The Project name that will be displayed everywhere and that can be used in any search form. Ideally, one word. Multiple words should be connected with dashes in order to allow easy links from comments.

Description

A Description that will be shown in the Project homepage. You can write using the Remarkup syntax. The first sentence is important and will show up in the "Browse Project" result, so you can avoid unuseful preambles like This is a Project and as Project it keeps track of... etc.

Icon

An icon that may tell more about the purpose of this Project.

Color

See above. There is also a checkered color suitable for deadlines.

Additional Hashtags

Comma-separated "alternative" names that may be useful to refer to this Project, from comments or from search fields etc.

Initial Members

List of registered users to be part of this Project.

Visible To

who has the ability to just see this Project.

Editable By

who has the ability to edit this Project (change description, add members etc.).

Joinable By

who has the ability to just join this Project.

Note that these policies does not affect the stuff related to this project. In Phabricator every element has its own policies by design.

About Project policies

An important rule to understand about Projects is that, by design, adding or removing Projects to an object never affects who can see that object.

If you need to keep some policies when working in a Project you may be interested in #Space policies.

Space policies

Spaces (upstream documentation) allow configuring groups of objects (like Tasks) with the same view policies. Some group might have certain types of tasks in their projects which they can only make accessible to group members. In this case, a space for that group can be set up.

Spaces apply their "Visible To" policy to all objects (like tasks) inside the space. A Space's policy is absolute and stronger than any other policy rules. If a user cannot see a space, the user can never see objects inside the space either, even if they are author, assignee or subscriber of the task in that space. (To allow users which are not member of the space to view or edit an object in the Space, a Custom Policy needs to be applied on the object instead of a Space.) In addition to a Space's policy, the view policy on the specific object/task is still applied.

By default, objects are in the public Space (S1). Any other Spaces have a more restrictive "Visible To" policy applied to their objects.

Regarding file attachments attached to a task in a private Space, the file is protected by the same policy as the task it is attached to only if you use drag and drop to upload on the task. If you instead upload a file directly to the Files application via file/upload and then attach it to the task, you will not have the same protection.

Example of Spaces and limited Projects

A Space is not a project. Hence a Space itself does not offer a Workboard. In order to have a Phabricator project with a Workboard and other features, and also to limit access to tasks and other objects within the project, three separate entities may be created in Phabricator:

• A Phabricator project. The project itself is public.
• A Phabricator Space. Tasks within a public project can be created within the Space as well, in which case they are invisible and inaccessible to everyone not in the Space.
• An "ACL Project". Because managing the access list of a Space directly requires administrator access, the Space may be configured to use the access list of an "ACL Project". This is a regular Phabricator project, maybe following a special naming convention for trackability, whose membership may be controllable by a non-administrator. It should not be used for Tasks.

Renaming Projects

When you rename a project you may want to make sure that you are not leaving broken links after the change of name.

Check that the previous hashtag was kept as an "additional hashtag" (it currently does so automatically). Otherwise, the references to your project that people added in comments and descriptions will break.

Tip: if your Project has a volatile name use URLs with the project number instead of its name. This saves you problems when the project is renamed, since the project number stays the same.

This is an example of unique project URL:

https://example.com/project/board/5/

This is an example of a Project URL with its name:

https://example.com/tag/awesome-project-name/

See Also

• Projects User Guide - official documentation