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.
Repository context, transfer and publication
A repository binding lets a stdio MCP session use the checkout's project when supported tools omit it. Bindings are lookup keys; they do not grant project membership or select a different server.
Project archives copy a project to a new private destination with its content, linked files and history. Memberships, credentials, saved views and repository bindings do not transfer. Importing does not delete the source or merge into an existing project.
Public projects expose current issues, pages, comments and linked files through a separate anonymous read surface. Publication is off by default and includes content written before it was enabled. Plans, content history and account records stay outside that surface. It does not change the ordinary API's authentication policy or make an otherwise open instance safe to expose to the Internet.