Skip to main content

Working with Projects

Projects group related work inside a workspace. Each project has a name, a short project key (e.g. ENG, MKTG), an optional configuration blob, a status, and any number of tags.

Browsing projects​

  • /workspaces/projects — every project you belong to, across all your workspaces. Bulk archive/delete actions are hidden on this view because selections could span workspaces.
  • /workspaces/:workspaceId/projects — projects in a single workspace, with full bulk actions enabled.

Both routes use the membership-scoped myProjects query — you only see projects you have access to.

Filters​

The toolbar above the list lets you narrow results by:

  • Search — matches name and key.
  • Status — Active, Inactive, or all.
  • Archive state — Active Projects (default-ish), Archived, or all.
  • Tags — click any tag badge on a project card to add it to the active filter set. The Tag match mode dropdown switches between Match all tags (project must have every selected tag) and Match any tag.

Click Clear Filters to reset everything in one shot.

Views​

Toggle between grid and list with the icons next to the Create Project button. The setting persists across sessions.

Pagination​

Up to 500 projects are fetched per page. If your access list exceeds that, the footer shows Showing X of Y projects and flags that more matches may exist outside the current page.

Opening a project​

Click any project card, or go to /workspaces/:workspaceId/projects/:projectId. See Project detail page for everything you can do there.

Creating a project​

  1. From the projects list, click Create Project (visible only with project:create).
  2. In the dialog:
  • Project Name — 2-100 characters.
  • Project Key — uppercase letters, numbers, underscores, or hyphens, 2-10 characters. Auto-generated from the name; editable.
  • Description (optional) — stored as part of the project configuration.
  1. Click Create Project. The dialog closes and the new project appears in the list.

Permissions: project:create on the workspace.

Editing a project​

Open the project, then use:

  • The Tags card to add or remove universal tags.
  • The actions dropdown (vertical-dots icon, top-right) for Archive / Unarchive and Delete Project.

Editable fields like project name, status, and config are managed through the same project detail flows. See Project detail page.

Permissions:

  • project:update to change tags, name, or config.
  • project:archive to archive or unarchive.
  • project:delete to delete.

Archiving and unarchiving​

Archive when work is paused but history should be kept. Unarchive returns a project to active.

  • Single project — from the project detail page's actions menu (Archive / Unarchive).
  • Multiple projects — on /workspaces/:workspaceId/projects, tick the checkboxes on the project cards (or Select all visible), then click Archive Selected or Unarchive Selected. The buttons show the count of eligible projects. Bulk actions are only available on the per-workspace projects view.

Permissions: project:archive.

Deleting a project​

Soft-deletes the project; this cannot be undone from the UI.

  • Single project — from the actions menu, choose Delete Project, then confirm in the dialog.
  • Bulk — from the per-workspace list, select projects and click Delete Selected. You will see a confirmation prompt with the count.

Permissions: project:delete.

Tagging projects​

Tags are universal tags managed by the tags service. Use them to group projects by department, BU, OKR, or any taxonomy your team uses.

  • Add or remove tags on the project detail page's Tags card.
  • Click any tag badge on a project card in the list view to toggle that tag as a filter on the projects list (see Filters above).

Tips​

  • Projects are workspace-scoped — a project in workspace A is never visible from workspace B.
  • The project key appears in URLs, notifications, and tickets — pick something short and memorable, then leave it alone.
  • The membership-scoped myProjects query means you only see projects you have direct access to; admins with broader visibility see more.