Projects
Projects, identifiers, membership, and project visibility.
A project is the scope for issues, modules, labels, folders, pages, plans, and membership.
Projects can also be filed into named groups that organize the sidebar. A group belongs to the user who created it: it is not shared, other members never see it, and filing a project into a group changes nothing about the project itself. A group lists only the projects its owner can still see, so losing access to a project removes it from the listing without unfiling it. Filing a project the user cannot view is refused.
Project fields
A project has a name, identifier, description, optional icon, optional primary lead, creation time, and update time.
The identifier is unique. It is used to construct issue, page, and plan identifiers.
Project identifiers follow these rules:
- They contain one to five characters.
- The first character is an uppercase ASCII letter.
- Remaining characters are uppercase ASCII letters or digits.
DOCis reserved for workspace page identifiers.
For example, a project with identifier LIF can have issue LIF-42, page LIF-DOC-3, and plan LIF-PLAN-2.
Members and roles
Project membership connects one user to one project role. The roles are ordered from lowest to highest access.
| Role | Permission level |
|---|---|
viewer | Read project resources and create/read comments. |
maintainer | Viewer access plus issue/page/plan content mutations, issue relations and plan-step links, and project structure mutations such as modules, labels, and folders. |
lead | Maintainer access plus project settings, membership/role management, and project deletion. |
| administrator | Bypasses project membership checks. Workspace-level administrative actions still require administrator access. |
A project can have a primary lead. Setting a primary lead also creates or updates that user's lead membership. A project can have more than one member with the lead role.
The system prevents removal or demotion of the last lead member. Another member must become a lead first.
Visibility and authorization
Project-scoped authorization is controlled by the instance setting authz_enforced.
When enforcement is enabled, a user must be a project member with a sufficient role to access project content. Viewer access is used for reads. Maintainer access is used for content, structure, relation, and plan-step mutations. Lead access is used for project settings, membership, and deletion. Administrators pass project access checks. Workspace-level page mutations require an administrator; project-page mutations use the containing project's role.
Operations that touch two projects, such as linking issues or attaching an issue to a plan step, require the required role in both projects. API clients can inspect their effective role with GET /api/projects/{id}/my-role.
When enforcement is disabled, membership rows do not create default-deny visibility. Interfaces retain their legacy permission behavior.
Connected tool accounts use the access of their owning user.