--- url: 'https://docs.plane.so/introduction/home.html' description: >- Plane is agentic work infrastructure: projects, knowledge, and work intake in one shared system for people and AI agents. Learn what Plane does and how to get it. --- # Introduction This page gives you a quick rundown of Plane and highlights why it's a great choice for managing your projects. ![Plane interface](https://media.docs.plane.so/introduction/introduction-plane.webp#hero) ## What is Plane Plane is agentic work infrastructure: a shared system for projects, knowledge, and work intake, where people and supported AI agents can act with context, ownership, permissions, and history visible. Project management is a core Plane capability. Teams use Plane to plan, track, and manage their work, and to keep documentation, incoming requests, and AI-agent activity connected to that work. Whether you're a startup, a growing business, or a large enterprise, Plane adapts to your team's specific needs. ## Why Plane Plane strikes a balance between simplicity, adaptability, and powerful features: * **Flexible and adaptable** Plane adjusts to your team's unique workflow. It evolves with your processes, whether you follow Agile, Scrum, or a hybrid approach. * **Intuitive and easy to use** With a simple, user-friendly interface, Plane has a minimal learning curve. Anyone from startup founders to project managers can quickly get started without much setup or training. * **Cloud and self-hosted options** Choose between cloud or self-hosted solutions. For regulated industries, running Plane on your own infrastructure provides crucial data control. * **Integrated workspace** Combine project management and knowledge management in one software, reducing silos and keeping everything centralized. ## Get Plane You can setup Plane in two ways: * **[Plane Cloud](https://app.plane.so/sign-up)** Sign up for a free cloud account - it's the easiest and quickest way to start using Plane. * **[Self-host Plane](https://developers.plane.so/self-hosting/overview)** Install and run Plane on your own servers if you want full control over your data and infrastructure. ## What's next * **New to Plane?** Start with [Tutorials](/introduction/tutorials/overview). * **Want to understand key concepts?** Explore [Core Concepts](/introduction/core-concepts). --- --- url: 'https://docs.plane.so/introduction/quickstart.html' description: Get a functional workspace with team members working on their first project. --- # Quickstart guide This walkthrough will help you get up and running with Plane in no time. You’ll learn how to set up your workspace, create projects, add and manage work items, and organize work into cycles, all through easy-to-follow steps. What you'll accomplish: * Workspace ready for your team * Team members invited and working * First project with real work items * Sprint planning with cycles ## Choose the right setup The steps in this guide cover the essentials for any new Plane workspace. If you are responsible for setting up Plane across an organization, start with the guide that matches where you are today. [**How to Plane: For startups**](https://docs.plane.so/introduction/quickstart/startups)\ Set up a simple structure that helps your team ship faster and leaves room to grow. [**How to Plane: For growing teams**](https://docs.plane.so/introduction/quickstart/growing-teams)\ Coordinate teams with shared workflows, approvals, planning, and organization-wide visibility. [**How to Plane: For enterprise teams**](https://docs.plane.so/introduction/quickstart/enterprise-teams)\ Establish governance, identity and access controls, auditability, deployment, and rollout across a the organization with multiple workspaces. ## Before you begin * [Create a Plane account](/#get-plane) ## Set up your workspace When you sign up for the first time on Plane, we'll prompt you to create a new Workspace. In this guide, you'll see how to customize the Workspace and invite your team members. Your workspace is the central hub where all your projects and team collaboration will happen, so let’s make it feel like home. ### Customize workspace details ![Workspace settings](https://media.docs.plane.so/quickstart/workspace-settings.webp#hero-tl) 1. Click on the workspace name at the top left. 2. Select **Settings**. 3. In the **General** tab under **Administration**: * Upload your company logo. * Update workspace name if you need to change it. ### Invite your team Get your team members into the workspace so they can start collaborating. ![Invite team members](https://media.docs.plane.so/quickstart/invite-team-members.webp#hero) 1. Under Workspace settings, click the **Members** tab in the left pane. 2. Click the **Add member** button. 3. In the **Invite people to collaborate** dialog: * Type the email address in the provided box. * Select the role you want them to have. * Admin: Full workspace control and settings access. * Member (Default): Can create projects, work items, and collaborate fully. * Guest: Limited access to specific projects they're invited to. * Use the **Add more** link to invite multiple people at once. 4. Click **Send invitations**. Team members will receive email invitations and can access the workspace. ## Create your project Now that your workspace is ready, it’s time to create your first project. Projects keep all related tasks and work items organized in one place, making it easy to focus on specific goals. Let's set up a project and add work items with basic properties to get your team started on their tasks. ![Create project](https://media.docs.plane.so/quickstart/create-project.webp#hero) 1. Look for **Projects** tab under the **Workspace** section on your sidebar. 2. Click the **Add Project** button. 3. In the project creation form: 1. Enter the name and write a brief description explaining what this project aims to accomplish. 2. By default, the project access is **Public**. This means that all Workspace Admins and Members can see and join this project. Change this to **Private** if you want members to join only through invite. 3. Assign a project Lead and add the Members you want to be part of this project. 4. Click **Create project** to finish the basic setup. 5. You’ll see a modal with all the features enabled for this project. Leave the defaults as they are and click **Open project**. Your team can see the project and access it from their workspace. ## Create your work items Add tasks so your team can start working immediately. ![Create work item](https://media.docs.plane.so/quickstart/create-work-item.webp#hero) 1. Navigate to the **Work items** page under your new project. 2. Click **Add work item**. 3. Enter title and brief description about the work item.\ *Example:* * **Title**\ *Design new homepage layout* * **Description**\ *Create a fresh layout for the homepage focusing on improved navigation, modern visuals, and clear call-to-actions.* 4. Set work item properties: * **Assignee**: `You` * **Priority**: `Medium` * **Start date**: Today * **Due date**: One week from today 5. Click **Save** to create the work item. 6. You'll see a new row added in the List layout. 7. Add a few more work items in the same manner. Team members see their assigned work and can start immediately. ## Plan your first Cycle In this final step, you’ll learn how to organize your work into cycles (time-bound periods) for managing tasks like sprints. Cycles help you track progress, prioritize tasks, and stay on top of deadlines. ![Create cycles](https://media.docs.plane.so/quickstart/create-cycles.webp#hero) 1. Click **Cycles** in your project sidebar. 2. Click the **Add cycle** button on the top right. 3. In the Create cycle modal: * Name your cycle: `Sprint 1`. * Set date range: 2 weeks (today through next Friday) * Click **Create cycle**. 4. Click on your newly created cycle name to open it. 5. Click **Add existing work item** 6. Select the work items you created earlier. 7. Click **Add to cycle**. 8. Return to the main Cycles page to view your active cycle with progress indicators. Your active cycle shows work items with progress tracking and burndown visualization. ::: tip Cycles work best when they're 1-2 weeks long and contain achievable goals for your team. ::: 🎉 Congratulations! You've set up a complete workspace in under 20 minutes. Your team is ready to start collaborating effectively. ## What's next? * **Ready to level up?** Explore these detailed [tutorials](/introduction/tutorials/overview). --- --- url: 'https://docs.plane.so/introduction/quickstart/startups.html' description: >- A lightweight Plane setup for managing company priorities, product work, customer feedback, and delivery in one place. --- # How to Plane: For startups Startups need enough structure to keep priorities, product context, and execution connected. They do not need a process for every possible situation. By the end of this guide, you will have a lightweight Plane setup for managing company priorities, product work, customer feedback, and delivery in one place. You will also know which capabilities to introduce as your startup grows. This guide is for startups and small teams that: * Work on one primary product or a small number of outcomes * Share context directly across the team * Have few formal handoffs * Change priorities frequently * Optimize for speed, learning, and customer feedback * Do not yet need governance across several departments This often applies to organizations with fewer than 25 people, but your operating model matters more than your headcount. ## 1. Plan Recommendation: Start with Plane Pro [Plane Pro](https://plane.so/pro) is the recommended plan if Plane will be the operating system for your startup. Pro gives you the structure to connect planning, execution, and company knowledge without requiring the workflow controls of a larger organization. It includes: * Custom work item types and properties * Workspace Wiki * Work item and page templates * Initiatives * Teamspaces * Dashboards * Time tracking and work logs * Published pages and views * 1,000 AI credits * Integrations and the Plane Marketplace The [Free plan](https://plane.so/pricing) works when you need projects, work items, cycles, modules, views, project pages, estimates, and in-app Intake for a team of up to 12 users. Choose Free if you are testing Plane or need a shared backlog before you need company-wide knowledge, custom work types, templates, initiatives, time tracking, or additional workspace structure. > **Tip:** Start with Pro if you already know Plane will hold your product work and company context. Moving from Free to Pro does not require a new workspace or a second migration. ## 2. Set up Plane Plane organizes work across four levels: | Level | What it represents | | --------- | ---------------------------------------------------------- | | Workspace | Your company's main environment in Plane | | Teamspace | A stable team or function working across multiple projects | | Project | A product area, outcome, or continuing stream of work | | Work item | A task, bug, feature, improvement, or other unit of work | Understanding this structure first makes it easier to decide where projects, imported work, and connected tools should live. ### Create one workspace Most startups should begin with one workspace for the company. This keeps members, projects, documentation, product context, and reporting connected. Create another workspace only when the company needs a genuine boundary, such as a separate legal entity, strict access requirements, or an independently managed business. ### Add Teamspaces [Teamspaces](/core-concepts/workspaces/teamspaces) group related projects for stable teams or functions. A very small startup may not need Teamspaces immediately. Enable this feature when teams like product, engineering, design, content, and more work across multiple projects. Create Teamspaces around stable areas of responsibility, not temporary initiatives. A feature launch or company objective usually belongs in a project, module, or initiative rather than a new Teamspace. ![Teamspaces](https://media.docs.plane.so/for-startup/teamspaces.webp) ### Create one or two projects [Projects](/core-concepts/projects/overview) should represent a defined product area, outcome, or continuing stream of work. A startup might begin with: * Product Development * Website * GTM - MENA Add another project when the work needs different ownership, access, workflow, or reporting. Do not create a separate project for every feature. **Projects Overview** ![Projects overview](https://media.docs.plane.so/for-startup/projects-overview.webp) ### Invite the team Add members after the initial workspace structure is clear. Keep administrative access limited and give external collaborators access only to the projects they need. Review [roles and permissions](/roles-and-permissions/overview) before inviting contractors, agencies, advisors, or other external collaborators. ### Connect development tools [Plane integrations](/integrations/about) keep development activity and team communication connected to the work in Plane. | Integration | What it connects | | ---------------- | ----------------------------------------------------------------------- | | GitHub or GitLab | Issues, pull requests or merge requests, commits, and delivery activity | | Slack | Discussions, notifications, requests, and follow-up work | | Sentry | Production errors and the work created to resolve them | Connect the tools your team already uses. An integration should reduce manual updates, make ownership clearer, or preserve context that would otherwise be lost. ## 3. Import active work [Plane importers](/importers/overview) help you move existing work from tools such as Jira, Linear, Asana, ClickUp, Notion, Confluence, and CSV files. Import the projects and work your team still needs. Old backlogs, outdated labels, duplicate tasks, and abandoned processes do not need to follow the team into Plane. Start with one active project: 1. Review the project and remove work that is no longer relevant. 2. Map users, states, labels, dates, and custom fields. 3. Run the import. 4. Check assignees, comments, attachments, and links. 5. Fix any structural problems before importing the remaining work. This first import gives you a chance to test the workspace structure before bringing everything across. **Importer mapping** ![Importer mapping](https://media.docs.plane.so/for-startup/imports.webp) ## 4. Turn priorities into work Keep the execution model easy to understand. The team should spend more time delivering work than maintaining the system around it. ### Define work item types [Work item types](/work-items/workspace-work-item-types) describe the nature of work your team manages. Start with a short list: * Feature * Bug * Task * Improvement Add another type only when it changes how the team assigns, plans, filters, or reports the work. Use custom properties for information that helps the team make decisions, such as product area, customer impact, confidence, or release target. ### Write useful work items A work item should give its operator enough context to act without reconstructing the original conversation. * Name the outcome or problem clearly. * Assign relevant owners. * Add the product or customer context that affects the work. * Link the relevant Page, design, discussion, or pull request. * Use sub-work items when several pieces of work contribute to one deliverable. Use an epic work item type when a larger deliverable contains several related work items that need to be tracked together. **Work item** ![Work item](https://media.docs.plane.so/for-startup/work-item.webp) ### Keep workflows simple Begin with a small workflow such as: * Backlog * Planned * In Progress * In Review * Done Add a state only when it represents a meaningful change in responsibility or progress. Use labels for flexible context that does not need its own workflow state. Review labels occasionally and merge duplicates before they become part of the team's vocabulary. ### Plan in short horizons A lightweight planning loop is enough for most startups: 1. Choose the most important outcomes for the next planning window. 2. Break those outcomes into owned work. 3. Confirm priorities and dependencies. 4. Review progress during the window. 5. Carry forward only the work that still matters. Short planning horizons allow the company to respond when customer feedback, delivery constraints, or business priorities change. ![Short planning horizons](https://media.docs.plane.so/for-growing-teams/gatt-chart.webp) ### Set priorities Priority should help the team decide what to work on next. Keep the priority scale small and apply it consistently. If everything is marked urgent, the field is no longer helping the team make a choice. ### Plan recurring work with Cycles [Cycles](/core-concepts/cycles) give the team a recurring planning window without changing the underlying project structure. Cycles are Plane's equivalent to sprints. Introduce Cycles when the team plans and reviews work on a regular rhythm. Keep each Cycle short enough for the team to change direction as the company learns. ### Group related work with Modules [Modules](/core-concepts/modules) organize work connected to the same feature, component, or deliverable. A module can span multiple Cycles, making it useful for work that belongs together but won't necessarily be completed in a single cycle. For example, a mobile application project might contain separate modules for Authentication, Onboarding, and Notifications. ### Connect projects with Initiatives Use [Initiatives](/core-concepts/projects/initiatives) when several projects contribute to the same company objective. An initiative can connect product, engineering, growth, and operational projects without consolidating all the work items in a single project. Introduce Initiatives only when the startup is coordinating outcomes across multiple projects or spanning a longer term. One or two straightforward projects usually do not need another planning layer. ### Estimates work when it informs a decision [Estimates](/core-concepts/issues/estimates) are useful when they help the team compare scope, identify effort, or decide what fits into a Cycle. Skip estimates when they add maintenance but do not change a planning or delivery decision. ## 5. Document product decisions Product work is easier to understand and revisit when decisions, documentation, and delivery remain connected. [Project Pages](/core-concepts/pages/overview) hold briefs, specifications, meeting notes, and decisions connected to a project. The [Workspace Wiki](/core-concepts/pages/wiki) holds knowledge used across the company, such as: * Product principles * Engineering standards * Architecture * Onboarding material * Research * Operating practices Keep project-specific context with the project. Move durable knowledge to the Wiki when people outside the project will need it again. ![Workspace Wiki](https://media.docs.plane.so/for-startup/wiki.webp) ### Reuse repeated processes Create a template after the team has repeated a process enough to understand which information is consistently useful. * Use Page templates for briefs, decisions, retrospectives, and research notes. * Use work item templates for common bugs, experiments, launches, or reviews. Do not turn every good example into a template. A small collection of maintained templates is easier to use than a large library of near-duplicates. ### Record product learning For an experiment, discovery project, or major product decision, record: * The original assumption * The evidence collected * The result * The decision that followed Link this record to the project or work items it changed. This preserves the reasoning behind the decision and prevents the team from repeating the same investigation later. > **Tip:** A short decision record written at the time is more useful than a detailed retrospective nobody can find later. ## 6. Manage incoming work [Plane Intake](/intake/overview) gives requests and feedback submitted inside Plane a visible path into the team's workflow. ### Create one Intake queue Start with one Intake queue and make one person responsible for reviewing it. The owner should: * Triage new submissions * Clarify requests when necessary * Merge duplicates * Accept or decline each submission * Decide whether accepted work belongs in the project backlog A single owned queue is easier to maintain than several channels that nobody reviews consistently. ![Intake queue](https://media.docs.plane.so/for-startup/intake.webp) ### Move accepted requests into planned work Review each submission before adding it to the project backlog. An accepted request should become a work item with a clear owner, priority, and enough context for the team to act. Decline requests the team will not pursue and merge submissions that describe the same need. > **Tip:** Intake should support triage, not become another backlog that nobody reviews. ## 7. Share progress Progress reporting should answer a recurring question. Start with the smallest view that gives someone enough information to act. ### Create views for recurring questions Create saved Views for questions your team asks repeatedly: * What is blocked? * What needs review? * What is planned for the current Cycle? * Which work has no owner? * Which Intake submissions still need a decision? Keep personal Views flexible. Standardize a View only when several people rely on the same definition. ### Publish project updates [Project updates](/communication-and-collaboration/project-updates) give stakeholders a predictable summary without requiring them to inspect individual work items. A useful update covers: * Current health * Progress since the previous update * Blockers * Decisions needed * The next step Keep the cadence consistent enough that a missed update signals a real gap. ### Share selected work externally Publish a Page or View when an advisor, customer, investor, or partner needs selected information but should not have access to the workspace. Review the content before publishing and remove access when the information no longer needs to be shared. ### Add dashboards when Views are not enough [Dashboards](/dashboards) help teams track work, create visibility, and compare progress across projects, all from one place. Build a dashboard around a decision, such as: * Which project is falling behind? * Where is work blocked? * How is the current Cycle progressing? * Which projects have not been updated? A small dashboard with a clear purpose is more useful than a screen filled with widgets. ### Track time when the data affects a decision Use time tracking when the team needs the data for client work, capacity planning, cost analysis, or another operational decision. Do not introduce time tracking as a default measure of individual productivity. ## 8. Plane AI [Plane AI](/ai/plane-ai) helps whether a workspace is brand new or already full of work items, documentation, and project history. ![Plane AI](https://media.docs.plane.so/for-startup/plane-ai.webp) **Setting up a workspace** Use Plane AI to help a new team get moving instead of staring at an empty project: * Turn a brief, meeting note, or rough idea into a first set of work items * Propose an initial project structure, states, labels, work item types, based on how the team says it works * Draft a starting Wiki page or onboarding doc for a new project * Suggest an initial Cycle or Module breakdown from a rough plan **Once work is underway** Use Plane AI to help the team move faster within work already in the system: * Find information across the workspace * Summarize project context * Draft work item descriptions * Turn notes into a useful first version * Improve existing content * Flag likely duplicate work items * Suggest labels for incoming requests * Answer questions about workspace data, such as what's blocked or what shipped this week * Draft a project update from recent activity Begin with tasks that save time without automatically changing work. ## 9. Add structure as the startup grows Add a capability when the team can name the coordination problem it needs to solve. This keeps Plane useful as the company grows without turning a startup workspace into a complex operating system too early. ### Add capabilities when coordination becomes difficult | Signal | What to add | | ------------------------------------------------------- | ------------------------------- | | The team plans within a recurring window | Cycles | | Larger deliverables contain several related work items | Modules or epic work item types | | Several projects contribute to one objective | Initiatives | | Stable teams need separate spaces for their work | Teamspaces | | The same work or document is created repeatedly | Work item or Page templates | | Stakeholders need recurring metrics | Dashboards | | Selected work needs to be shared externally | Published Pages or Views | | Team members need a controlled path for submitting work | In-app Intake | | Time data affects billing, capacity, or cost decisions | Time tracking | ### Review the workspace every month A short monthly review keeps the setup useful: * Archive completed or abandoned projects. * Remove stale Views, labels, and templates. * Check unowned and blocked work. * Review guest and external access. * Confirm that integrations still have an owner. * Update project status. * Close outdated Intake submissions. * Add structure only where the same coordination problem keeps returning. ### Move to the growing teams setup The startup model is no longer enough when: * Several teams need shared standards. * Leadership needs comparable reporting across teams. * Access becomes harder to manage. * The company regularly coordinates work across many projects. * Different teams need separate operating models. * Workspace administration becomes an ongoing responsibility. At that point, define a small set of shared work item types, project fields, update expectations, and workspace rules. Keep local planning decisions with teams unless the information needs to be understood across the company. See [For growing teams](/introduction/quickstart/growing-teams) for that setup. ## Start using Plane Pro Begin with one workspace, add Teamspaces where stable teams need separation, create one or two projects, and import only the active work your team still needs. Connect the tools your team already uses, keep the workflow simple, and add more structure when a recurring coordination problem makes it necessary. [Start a 14-day Plane Pro trial](https://plane.so/pricing) ### Related resources [Plane documentation](https://docs.plane.so/) | [Developer documentation](https://developers.plane.so/) | [Compare Plane plans](https://plane.so/pricing) --- --- url: 'https://docs.plane.so/introduction/quickstart/growing-teams.html' description: >- Structure Plane for multiple teams, introduce the right capabilities at the right time, and create reliable cross-team visibility without adding unnecessary administration. --- # How to Plane: For growing teams Once several teams share products, dependencies, and company goals, informal coordination stops being enough. Requests get lost, ownership becomes unclear, and leaders need answers that span more than one project. Plane gives each team a focused place to manage its work while creating enough shared structure for the company to plan and report across teams. This guide is for: * Operations leads * Engineering and product managers * Workspace Owners and Admins * Anyone responsible for maintaining Plane alongside another role By the end of this guide, you will know how to structure Plane for multiple teams, introduce the right capabilities at the right time, and create reliable cross-team visibility without adding unnecessary administration. ## Choose the right Plane plan [Plane Pro](https://plane.so/pro) is a practical starting point for many growing companies. It provides the structure needed to manage multiple teams, including Work Item Types, Teamspaces, Milestones, Initiatives, Dashboards, Wiki, time tracking, and advanced estimates. Move to [Business](https://plane.so/business), when the company needs capabilities such as: * Intake Forms and Intake Email * Customer request tracking * Reusable project and work item templates * Recurring work * Configurable workflows * Custom automations * Nested Pages and embeds * Advanced reporting controls Review the current capabilities on the [Plane pricing page](https://plane.so/pricing) before choosing a plan. Most growing companies can begin with Plane Cloud. Consider self-hosting when infrastructure control, data residency, security policies, or customer requirements make it necessary. See the [Plane self-hosting documentation](https://developers.plane.so/self-hosting/overview) for deployment options. [**Compare Plane plans**](https://plane.so/pricing) ## Import active work Plane provides importers for tools including [Jira](/importers/jira), [Linear](/importers/linear), and [ClickUp](/importers/clickup). You can also use the [CSV importer](/importers/csv). Review the [importers overview](/importers/overview) for all available migration paths. Move active work, recent context, and records the team still needs. Historical data that has no role in current planning or reporting can remain in a read-only archive. ![Importing active work](https://media.docs.plane.so/for-growing-teams/imports.webp) > **Tip:** Clean up states and labels before importing. Mapping several variations of "in progress" into Plane only carries the existing inconsistency into the new Workspace. ## Set roles and ownership Start by deciding who will manage Plane at the Workspace level and who will manage each Project. ### Assign Workspace Admins Keep the group of Workspace Admins small. They can change settings that affect every team, so assign this role only to people responsible for the overall Plane setup. ### Assign a Project Admin to every Project Give each active Project at least one Admin who understands the team's workflow. Project Admins can manage members, states, features, and project-level settings without requiring Workspace Admin access. Plane separates Workspace roles from Project roles. Someone can remain a Workspace Member while serving as a Project Admin for the Projects they own. Use this access model as a starting point: | Responsibility | Recommended access | | -------------------------------------- | --------------------- | | Manage company-wide Plane settings | Workspace Admin | | Manage a team's Project and workflow | Project Admin | | Create and update the team's work | Member or Contributor | | Review work without changing it | Commenter | | Submit requests or access limited work | Guest | Review the [roles and permissions overview](/roles-and-permissions/overview) and [permissions matrix](/roles-and-permissions/permissions-matrix) before assigning access. ### Limit access for external collaborators Give contractors, agencies, customers, and other external collaborators access only to the Projects they need. Use the Guest role when someone needs limited access without becoming a full Workspace Member. > **Note:** Team leads and managers do not automatically require Workspace Admin access. Project-level administration is usually enough. ### Create consistency across Projects Teams do not need identical workflows. They need enough shared meaning for people to understand work across projects. Standardize the information that supports company-wide planning and reporting: * Priority definitions * Broad state groups * Ownership * Target or due dates * Work item relationships * A small set of cross-project labels * Project health and update language Teams can add local states, labels, properties, and views around this shared minimum. For example, one team may use states like "Development" and "Code Review" while another uses "In Progress" and "Verification". Both can still map active work to the same broad state group for cross-team reporting. ## Organize teams and projects **How work is organized in a Plane Workspace** ```text Workspace ├── Projects │ ├── Work items │ │ ├── Work item types (Epics) │ │ ├── Custom properties │ │ ├── Sub work items │ │ ├── Relations │ │ ├── Comments │ │ ├── Links │ │ ├── Attachments │ │ ├── Activity history │ │ ├── Work logs │ │ └── Archives │ ├── Cycles │ │ ├── Work items │ │ ├── Burndown and progress │ │ └── Work item transfer │ ├── Modules │ │ ├── Work items │ │ └── Progress │ ├── Milestones │ │ └── Work items │ ├── Views │ │ ├── Layouts │ │ ├── Filters │ │ ├── Display properties │ │ └── Access control │ ├── Pages │ ├── Intake │ │ ├── Intake work items │ │ ├── Intake forms │ │ ├── Email intake │ │ └── Triage │ ├── Project updates │ ├── Workflows │ │ ├── States │ │ ├── Transition rules │ │ └── Approvals │ └── Project settings │ ├── General │ ├── Members and roles │ ├── Project states │ ├── Labels │ ├── Estimates │ └── Features ├── Teamspaces │ ├── Projects │ ├── Work items [rollup] │ ├── Cycles [rollup] │ ├── Views │ ├── Pages │ └── Members ├── Wiki [workspace knowledge] │ ├── Collections │ │ └── Pages │ ├── Pages │ │ ├── Sub-pages │ │ ├── Private pages │ │ ├── Public pages │ │ ├── Sharing │ │ ├── Comments │ │ ├── Version history │ │ ├── Page templates │ │ ├── Locking │ │ └── Archives │ ├── Blocks │ │ ├── Headings and text │ │ ├── Lists and to-dos │ │ ├── Quotes │ │ ├── Callouts │ │ ├── Toggles │ │ ├── Tables │ │ ├── Code blocks │ │ ├── Images and media │ │ ├── File attachments │ │ ├── External embeds │ │ ├── Work item embeds │ │ ├── Mentions │ │ ├── Dividers │ │ └── Database blocks │ └── Databases │ ├── Properties │ ├── Views │ └── Records ├── Initiatives │ ├── Projects │ ├── Work items (epics) [rollup] │ └── Work items [rollup] ├── Releases │ ├── Work items │ ├── Release tags │ ├── Release labels │ └── Changelog ├── Customers │ ├── Requests │ ├── Custom properties │ └── Linked work items ├── Dashboards │ ├── Private dashboards │ ├── Public dashboards │ ├── Widgets │ │ ├── Bar chart │ │ ├── Line chart │ │ ├── Area chart │ │ ├── Donut chart │ │ ├── Pie chart │ │ └── Number │ └── Layout ├── Analytics │ ├── Overview │ ├── Projects │ ├── Users │ ├── Work items │ ├── Cycles │ ├── Modules │ └── Intake ├── Plane AI │ ├── Modes │ │ ├── Talk to build │ │ ├── Ask to know │ │ └── Assign to ship │ ├── Agents │ │ ├── Built-in agents │ │ ├── Custom agents │ │ └── Skills │ ├── Models │ │ ├── Model routing │ │ └── Model cocktailing │ └── Usage │ ├── Consumption │ ├── Limits │ ├── Per-model breakdown │ └── Per-agent breakdown ├── Integrations │ ├── GitHub │ ├── GitLab │ ├── Slack │ ├── Sentry │ ├── Draw.io │ ├── Agents (Claude, Cursor, VS Code MCP) │ └── Importers (Jira, Linear, Asana, ClickUp, Confluence, Notion) └── Workspace settings ├── General ├── Members ├── Roles and permission groups ├── Security and identity │ └── SSO / SAML / OIDC ├── Work item types │ ├── Hierarchy levels │ └── Type properties ├── Automations │ ├── Global automations │ └── Project automations ├── Billing and plans ├── API tokens ├── Webhooks ├── Imports ├── Exports └── Audit logs ``` The Workspace is the shared company environment. Projects contain the work owned by a specific team, product, or area of responsibility. A project should have a clear group responsible for its backlog, workflow, and updates. Projects might represent: * Frontend * Backend * Mobile Applications * Platform * Infrastructure * Security * Product Design * Growth * Customer Experience Not every temporary initiative needs a new project. If several teams contribute to the same launch or company objective, keep their work in their existing projects and connect it through an Initiative or Milestone. See [how projects work in Plane](/core-concepts/projects/overview). ### Keep project names clear Choose names that remain understandable as the company grows. | Project | Identifier | Description | | ------------------- | ---------- | ---------------------------------------------------- | | Web Application | WEB | Customer-facing web application | | Backend | API | APIs, services, and core business logic | | Mobile Applications | MOB | iOS and Android product development | | Platform | PLAT | Shared developer infrastructure and internal tooling | | Security | SEC | Product security, reviews, and remediation | Avoid names based on temporary managers, quarters, or internal abbreviations that new employees will not understand. ### Keep project features focused Projects can have their own set of enabled features and workflows. This allows each team to work within the same Workspace without using an identical setup. Start with how the team plans and manages its work, then enable the features that support it. For example: * Engineering teams may use Cycles for planning, Modules for grouping related work, and Pages for project context. * Support teams may rely on Intake and Views to review and organize incoming requests. * Security teams may use Work Item Types and custom properties to capture risk, severity, and review details. **Projects organized by team** ![Projects organized by team](https://media.docs.plane.so/for-growing-teams/projects.webp) ### Create Teamspaces for shared team context A [Teamspace](/core-concepts/workspaces/teamspaces) brings together the people, projects, Pages, Views, dependencies, and activity associated with a durable team. Create a Teamspace when a team works across more than one project or needs a shared place for its knowledge and reporting. For example, a Product Engineering Teamspace might include the Frontend, Backend, and Mobile Applications projects. A Platform Teamspace might include Infrastructure, Developer Experience, and Security. Teamspaces should follow real organizational ownership. Do not create a Teamspace for every temporary initiative, launch, or reporting category. A useful Teamspace description states: * What the team owns * Which products or systems it supports * Who depends on it * Where requests should be submitted **Teamspace** ![Teamspace](https://media.docs.plane.so/for-growing-teams/teamspaces.webp) ### Organize work by type Every work item has a type, and the type decides which properties that item carries. A Bug carries severity and environment. An Epic carries an owner and a target date. Projects start with one default type for general work. Use [Work Item Types](/work-items/project-work-item-types) to create the rest. Teams can create types such as Bug, Feature Request, Security Review, Incident Follow-up, or Content Request. Each type can have properties suited to the work. ![Work item types](https://media.docs.plane.so/for-growing-teams/work-item-type.webp) | Work Item Type | Useful properties | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Epic | Owner (member), Target date (date), Health (dropdown: on track, at risk, off track), Success metric (text) | | Bug | Severity (dropdown: S1 to S4), Environment (dropdown: production, staging, local), Affected version (text), Steps to reproduce (text), Regression (boolean) | | Security Review | System (dropdown), Risk level (dropdown: critical, high, medium, low), Reviewer (member), Remediation due (date) | | Content Request | Channel (dropdown: blog, docs, email, social), Audience (dropdown), Reviewer (member), Publish date (date), Brief (URL) | Keep the number of types manageable. If two types require the same information and follow the same workflow, they may not need to be separate. Work Item Types cannot be turned off after they are enabled for a project, although individual types can be disabled. Agree on the initial structure before enabling them broadly. ### Keep labels useful Labels work best for information that people regularly filter, group, or report on. Useful shared labels might include: * Customer reported * Technical debt * Compliance * Reliability * Accessibility Do not create a label when the information already belongs in a state, priority, assignee, project, Work Item Type, or custom property. Give shared labels a clear owner. Merge duplicates and archive labels that no longer support a decision. ### Create the Views teams need [Views](/core-concepts/views) save filters, layouts, grouping, and sorting without duplicating work items. Useful project Views include: * Unassigned high-priority work * Work blocked by another team * Customer-reported bugs * Work due this month * Items waiting for review * Work without an estimate or target date Workspace Views bring together work from several projects. They can show all blocked work across Product Engineering, every security-related item due this quarter, or unassigned high-priority work across the company. Create Views around recurring planning, review, and delivery conversations. If no one uses a View to answer a question or make a decision, it does not need to be maintained. ## Connect the tools teams already use Connect Plane to the tools your teams already use: * [GitHub](/integrations/github) and GitHub Enterprise for syncing issues and pull requests * [GitLab](/integrations/gitlab) for linking issues and tracking merge requests * [Bitbucket](/integrations/bitbucket) for connecting repositories and development activity * [Slack](/integrations/slack) for creating work items and managing updates from Slack * [Sentry](/integrations/sentry) for turning application errors into trackable work * [Cursor](/integrations/cursor) for working with Plane issues from Cursor * [Draw.io](/integrations/draw-io) for embedding diagrams in Plane Pages For custom connections, read the [Plane API](https://developers.plane.so/api-reference/introduction), and [webhooks](https://developers.plane.so/webhooks/overview). Review the [integrations overview](/integrations/about) for the complete list and setup instructions. Integrations exist so context lands next to the work. Commits, pull requests, and deploys show up on the work item they belong to. Errors arrive with the trace attached. A Slack thread becomes a work item without anyone leaving the channel. The repository still holds the code and the CRM still holds the account record, but the decision, its owner, and the evidence behind it end up in Plane. Enable integrations project by project. Confirm the events flowing in are the ones you want before applying the same configuration across the workspace. ## Keep project knowledge close to the work [Project Pages](/core-concepts/pages/overview) hold context that belongs to a specific project, including: * Project briefs * Technical decisions * Research summaries * Release plans * Retrospectives * Runbooks Link relevant Pages to work items so people can move directly between a decision and its execution. Use the [Workspace Wiki](/core-concepts/pages/wiki) for knowledge that applies across teams, including: * Planning principles * Shared workflow definitions * Product and engineering standards * Onboarding material * Security policies * Release processes * Incident procedures * Shared terminology **Workspace Wiki** ![Workspace wiki](https://media.docs.plane.so/for-growing-teams/wiki.webp) Business adds [nested Pages](/pages/nested-pages) for larger documentation structures. Add nesting when a flat structure becomes difficult to navigate. ## Manage incoming requests Give stakeholders a clear path for submitting work before requests begin arriving through direct messages, meetings, emails, and spreadsheets. ### Set up Intake for each team [Plane Intake](/intake/overview) creates a queue where teams can review, clarify, accept, decline, or defer requests before they enter the project workflow. In-app Intake supports requests submitted by members and guests. Business adds [Intake Forms](/intake/intake-forms) for public submissions and [Intake Email](/intake/intake-email) for requests sent to a dedicated address. Create separate Intake paths when teams make different decisions. Product feedback, security reviews, design requests, and platform support should not all enter one company-wide queue. Each Intake queue needs: * A named owner or rotation * A response window * Clear acceptance criteria * A small set of request categories * A process for duplicates and incomplete requests * A way to communicate the outcome to the requester Accepted requests should enter the team's normal project workflow. Intake should not become a second backlog that exists alongside the project. > **Note:** Intake captures demand. It does not determine priority. Teams must still compare accepted requests with existing commitments. **Review incoming requests before they enter the team's planned workflow.** ![Reviewing incoming requests](https://media.docs.plane.so/for-growing-teams/intake.webp) ### Connect customer requests to delivery work Customer profiles and request tracking are available on Business. Use [Customers in Plane](/customers) to connect customer context to requests and delivery work. This helps teams answer: * Which customers are affected? * How many customers raised a similar request? * Is the request connected to planned work? * Who needs an update when the work changes? * Which customer segments are generating the most demand? Keep implementation work in the project that owns delivery. Customer records and requests should provide context, not create parallel copies of the same work. ## Plan and organize delivery Introduce each planning object for a specific question the team needs to answer. ### Organize time-based work with Cycles [Cycles](/core-concepts/cycles) are Plane's version of a sprint: a fixed window of time with work items committed to it. Pick a cadence and hold it, weekly, two weeks, or monthly. Each cycle gives you a commitment, a view of what was added or dropped mid-cycle, and a fixed point to review what shipped. A project runs one cycle at a time by default. Turn on parallel cycles when two teams in one project need separate cadences, or when the next cycle needs planning while the current one closes. Repeated carryover points at oversized work items, shifting priorities, unresolved dependencies, or more unplanned demand than the team can absorb. Read it as a signal about the work, not the person. **Cycles** ![Cycles](https://media.docs.plane.so/for-growing-teams/cycles.webp) ### Group related work with Modules [Modules](/core-concepts/modules) group work by theme, component, feature, or deliverable. A Module spans Cycles. A Module might represent: * Authentication * Mobile onboarding * Billing migration * Search improvements * A launch campaign * A backend service **Modules** ![Modules](https://media.docs.plane.so/for-growing-teams/modules.webp) A Module can span several work items. Work can remain grouped around the same deliverable even when it is completed over multiple planning periods. ### Track important dates with Milestones [Milestones](/core-concepts/projects/milestones) align work around a meaningful target date or checkpoint Use Milestones for: * Product launches * Contractual commitments * Compliance deadlines * Major migrations * Quarterly deliverables A Milestone should represent a date the company intends to manage, not every internal deadline. > **Tip:** If the question is "When are we working on this?", look at the Cycle. If it is "What body of work does this belong to?", look at the Module. If it is "Which important date are we working toward?", look at the Milestone. ### Connect detailed work through Epics An [Epic](/core-concepts/issues/epics) is a Work Item Type used as a parent for a larger deliverable. Create an Epic when a deliverable contains several related work items that need a shared owner, target date, health, and progress view. For example, an *Introduce passkeys* Epic might contain work for: * Authentication service changes * Web settings * Mobile support * Recovery flows * Analytics * Documentation Keep the Epic in the project that owns the outcome. Keep the Epic in the project of the team responsible for the outcome. When another team contributes, link their work items to the Epic. Their work stays on their board, and the Epic still shows everything feeding into it. Do not create an Epic for every small group of tasks. Use it when someone needs to monitor the larger outcome independently from its individual steps. ## Coordinate work across teams Once teams manage their work consistently, connect delivery across projects and company priorities. ### Track dependencies within projects Dependencies become difficult to manage when they are discussed in meetings but not represented in the system. Some work cannot start until other work is finished. That is what [work item dependencies](/core-concepts/issues/overview#add-dependencies) record. On the item that has to wait, add the item it is waiting for. Say the dashboard needs the API endpoint first: open the dashboard item and add the endpoint. Both items now show the link, from each side. When two items are connected but neither has to wait, use *related*. When the same thing was filed twice, use *duplicate*. ![Work item dependencies](https://media.docs.plane.so/for-growing-teams/gatt-chart.webp) An important dependency should make four things clear: * What is needed * Which team owns it * When it is expected * What will be affected if it moves Assign an owner on both sides of the handoff and review blocked work during planning and project updates. ### Connect team execution to company priorities [Initiatives](/core-concepts/projects/initiatives) connect related projects and work to a company-level outcome. Create an Initiative when leadership needs to understand progress across several teams. Examples include: * FedRAMP readiness * GTM launch: MENA and APAC * Zero critical vulnerabilities by end of year * Data residency: EU and India * Take 12 legacy services off the deprecated runtime Each Initiative should have: * A clear outcome * One accountable owner * A small set of success measures * Connected projects or work items * A target period * Regular status updates Do not create an Initiative for an individual team project. Keep the number of active Initiatives small enough that leadership can genuinely prioritize between them. **An Initiative across projects** ![An Initiative across projects](https://media.docs.plane.so/for-growing-teams/initatives.webp) ### Share project updates consistently [Project updates](/communication-and-collaboration/project-updates) communicate what changed, whether a project is healthy, and where attention is needed. A useful update covers: * Current health * Progress since the previous update * The next important step * Risks or blockers * Decisions needed * Changes to scope or target dates Choose a cadence that matches the pace of the work. Weekly updates may suit an active launch, while monthly updates may be enough for longer-running internal work. Define On Track, At Risk, and Off Track consistently. If each team interprets project health differently, company-wide reporting will be difficult to trust. ## Reports Build reporting after ownership, states, dates, and relationships are reliable. ### Build Dashboards around decisions [Dashboards](/dashboards) combine information from multiple projects into charts, metrics, and tables. Start with the question the Dashboard needs to answer. Useful examples include: * Which high-priority work has no owner? * What is blocked across Product Engineering? * Which Initiatives are at risk? * What is due this month? * Which customer-reported bugs remain unresolved? * How much Cycle work was added after planning? * Where is work concentrated across products or priorities? Different audiences need different views. Team leads may need workload, blockers, and Cycle progress. Product leadership may need Initiative progress and customer demand. Executives may need a concise view of outcomes, health, and major risks. Keep each Dashboard focused. Remove widgets that no longer change a conversation or decision. Business adds advanced Dashboard widgets for deeper analysis and more flexible reporting. > **Note:** A Dashboard can only be as reliable as its underlying data. Improve ownership, states, dates, and relationships before adding more reporting. **Build Dashboards around the decisions teams and leaders make regularly** ![Leadership dashboard](https://media.docs.plane.so/for-growing-teams/dashboards.webp) ## Automate stable workflows Business supports [custom automations](/automations/custom-automations) that use triggers, conditions, and actions to handle repetitive project work. Good early automations include: * Assigning a default owner to a specific request type * Adding a label when a defined condition is met * Notifying an owner when a request enters Intake * Creating recurring operational work * Applying a standard template to repeated work * Moving completed work out of an active View Start with low-risk actions that have a clear owner. Monitor the results and review automations when workflows or team responsibilities change. Do not automate an unclear process or use automation to compensate for inconsistent data. It will reproduce the inconsistency faster. > **Tip:** Begin with stable processes where an incorrect action would be easy to identify and reverse. **A focused automation** ![A focused automation](https://media.docs.plane.so/for-growing-teams/automation.webp) ## Introduce Plane AI gradually [Plane AI](/ai/plane-ai) can answer questions about Workspace data, prepare actions, generate charts, work with Pages, and help manage projects. Begin with read-only questions that help teams evaluate the quality of their Workspace information: * Which high-priority work items are unassigned? * What is blocking the current Cycle? * What shipped this week? * Which customer requests are connected to planned work? * How has the scope of this Cycle changed? ![Plane AI answering workspace questions](https://media.docs.plane.so/for-growing-teams/plane-ai.webp) Once you are satisfied with the answers, introduce reviewed actions for clearly defined work. A person should inspect proposed changes before they are applied. Allow autonomous actions only when the instruction is narrow, precise, and reversible. Avoid broad actions that can change several projects, owners, or commitments at once. AI works from the information in the Workspace. It cannot correct unclear priorities or missing ownership on its own. > **Note:** AI assistance does not transfer accountability. The project owner still owns the resulting plan, update, or Workspace change. ## Roll Plane out across teams Set up the operating model before introducing Plane across the company. Rollout should then follow a repeatable team-by-team process. ### Start with a representative team Choose a team with active work, a clear owner, and enough cross-team interaction to expose gaps in the setup. Define: * The project the team will work from * The Work Item Types it needs * A small set of states and priorities * The work that needs to be imported * The tools that need to connect to Plane * The Views the team uses during planning and delivery Run the setup through one complete planning cycle. Note what the team changes, what information people struggle to find, and which parts of the workflow they actually use. > **Tip:** Choose a representative team, not the simplest one. A pilot without real dependencies or incoming requests will not show whether the setup can support the rest of the company. ### Build adoption through daily work Adoption begins when Plane becomes part of the team's regular planning, reviews, and updates. For each team: * Assign a rollout owner * Explain what belongs in Plane * Provide a short onboarding Page * Train people on the features relevant to their roles * Collect feedback after the first planning cycle * Remove parallel trackers once Plane is working reliably Measure adoption through working habits, not sign-ins. Teams should update work regularly, keep ownership visible, and answer delivery questions directly from Plane. > **Tip:** Establish a few consistent habits first. Add more capabilities as the team becomes comfortable with the workflow. ### Expand to the next team Apply what you learned from the pilot before adding the next team. Reuse the shared definitions that worked, but adjust the project workflow, features, Views, and training to match the work the new team owns. Do not copy the pilot configuration. The goal is to preserve a shared operating model while giving each team enough flexibility to manage its work effectively. Repeat the process until teams can work from Plane consistently and company-wide reporting no longer depends on separate trackers or manual status collection. ## Know when Enterprise becomes necessary A growing company does not need Enterprise simply because it has several teams. [Plane Enterprise Grid](https://plane.so/enterprise) becomes relevant when governance and infrastructure requirements become formal. Common triggers include: * Centralized identity and user provisioning * LDAP or advanced directory requirements * Detailed auditability * Stricter access controls * Managed or controlled deployment * Formal security or compliance obligations * Dedicated platform administration * Multiple Workspaces requiring centralized governance At that point, the question is no longer only how teams organize work. It is also how the company controls access, enforces policy, verifies activity, and operates Plane as shared infrastructure. [**Talk to Plane about Enterprise Grid**](https://plane.so/talk-to-sales) For a governance-first walkthrough of that transition, see [For enterprise teams](/introduction/quickstart/enterprise-teams). ## Keep the operating model simple A growing company needs coordination, but every team does not need to work in exactly the same way. Standardize the information that must be understood across teams. Let teams shape the rest of their workflow around the work they own. Start with real work. Add each planning layer for a specific reason. Keep ownership visible and review the system as the company changes. The goal is not to build the most detailed Plane Workspace. It is to give teams a system they can work from every day and give the company a reliable view of what it is delivering. ## Where to go from here * **Live reference:** [Plane's docs site](https://docs.plane.so). This guide is a snapshot. That page has the current pricing, seat limits, and feature availability by plan. * **Build on Plane:** [the developer docs](https://developers.plane.so), for the API, webhooks, the MCP server, and self-hosting guides. * **Talk to sales:** [reach out here](https://plane.so/talk-to-sales), for Enterprise Grid scoping, migration services, or anything else this guide didn't answer. --- --- url: 'https://docs.plane.so/introduction/quickstart/enterprise-teams.html' description: >- Set up Plane across your organization with common governance, clear visibility, and enough flexibility for teams to work in the way that suits them. --- # How to Plane: For enterprise teams Set up Plane across your organization with common governance, clear visibility, and enough flexibility for teams to work in the way that suits them. This guide is for CTOs, Heads of Engineering, IT and Platform teams, and Workspace Admins responsible for setting up and rolling out Plane across a large organization. By the end of this guide, you will have a practical model for choosing a deployment, setting up access, structuring workspaces, migrating teams, standardizing shared processes, and rolling Plane out across the organization. The goal is not to make every team work the same way. It is to give the organization a shared source of truth while letting every team work their own way. > **A useful rule:** Standardize what needs to be understood across the organization. Let teams decide what only affects their own work. If you are setting up Plane for a smaller organization, see [For startups](/introduction/quickstart/startups) or [For growing teams](/introduction/quickstart/growing-teams) instead. ## Plan the rollout Start with the foundation, test it with one team, and expand from there. A practical rollout looks like this: 1. Set up identity, access, and security. 2. Choose the deployment and workspace structure. 3. Define the standards teams will share. 4. Migrate one representative team. 5. Fix what you learn during the pilot. 6. Add teams in manageable groups. 7. Connect the tools teams already use. 8. Create clear intake paths. 9. Set up leadership reporting. 10. Add workflows and automation where they remove manual work. 11. Introduce AI after permissions and governance are in place. Bring the Security team into the process from the beginning. Include the platform or infrastructure team before migration, especially for self-hosted deployments and organization-wide integrations. The first team should be representative of the wider organization, but not under pressure from an immediate deadline. Document the decisions, problems, and changes that come out of the pilot. Use those lessons to improve the next phase of the rollout. > **Tip:** Avoid starting with either the simplest team or the most complicated one. Choose a team whose work, permissions, and integrations resemble what most teams will need. ## Choose the right Plane plan The [Business plan](https://plane.so/pricing) covers many of the workflows in this guide, including advanced work management, custom properties, project templates, dashboards, intake, customers, and knowledge management. [Enterprise Grid](https://plane.so/enterprise-grid) is the better fit when the organization needs centralized governance, granular access control, LDAP support, API-enabled audit logs, multiple workflows and approvals, private or managed deployments, or migration and implementation support. Enterprise Grid includes: * Granular access control * Custom roles and permission schemes * Multiple workflows and approvals * LDAP support and group synchronization * API-enabled audit logs * Private and managed deployment options * Migration and implementation services * Enterprise support * Flexible AI credits and usage controls The right plan depends on the controls and deployment model the organization needs, not headcount alone. > **Note:** Feature availability can vary by plan and deployment. Check the current [Plane pricing page](https://plane.so/pricing) before finalizing your rollout. ## Choose a deployment option Plane can be deployed in three ways: * **Cloud:** Plane manages the infrastructure and updates. * **Self-hosted:** Plane runs in your organization's infrastructure. * **Air-gapped:** Plane runs in an isolated environment with restricted or no external network access. Choose based on your security, infrastructure, network, and data requirements. | | Cloud | Self-hosted | Air-gapped | | ------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------- | ------------------------------- | | Infrastructure, capacity, monitoring, incident response | Plane | Yours | Yours | | Upgrades | Automatic | You schedule and test | You schedule, offline | | Backups | Automatic | Yours, including recovery-testing | You, and you prove it | | SSO | Business and above | SAML and OIDC from Pro and above | SAML and OIDC included | | Network egress | Required | Required | None | | Best when | No hard constraint | Residency, policy, or a contract requires you to control the deployment | Isolation is a hard requirement | Self-hosting gives the organization more control, but it also creates ongoing responsibility for deployment, upgrades, backups, monitoring, and recovery. Review the [self-hosting documentation](https://developers.plane.so/self-hosting/overview) before deciding whether your team can operate the deployment over the long term. Before choosing a deployment, confirm: * Where data must be stored * Whether outbound network access is permitted * Who will operate and upgrade the instance * How backups and recovery will work * Which integrations the deployment must support * Whether approved AI providers can be accessed * What availability and support commitments are required ## 1. Identity, access, and governance Set up access before inviting teams or importing their work. Plane should fit into the identity and security systems the organization already uses. Retrofitting those controls after rollout creates avoidable cleanup. ## Connect your identity provider Verify the organization's domain and configure the approved authentication method. Depending on the plan and deployment, Plane supports enterprise identity options such as [single sign-on](/authentication/sso), LDAP, and [identity-provider group sync](/authentication/group-sync). Directory-driven access makes onboarding and off-boarding easier to manage. It also reduces the number of permissions administrators need to maintain manually. Before rollout, test: * Sign-in for each required user group * Group and role mapping * New employee provisioning * Role changes * Employee off-boarding * Guest access * Administrator recovery access ![Identity provider sign-in](https://media.docs.plane.so/for-enterprise/identity.webp) > **Tip:** Test off-boarding as carefully as onboarding. Confirm that removing someone from the identity provider removes the access you expect it to remove in Plane. ## Design roles around responsibilities Plane uses [roles and permissions](/roles-and-permissions/overview) at the workspace, teamspace, and project levels. Default roles cover common access patterns. Enterprise Grid organizations can use Granular Access Control to create [custom roles](/roles-and-permissions/custom-roles) from reusable [permission schemes](/roles-and-permissions/permission-schemes). **RBAC** is the default. Every user holds a role, either a system-defined one (owner, admin, member, guest, contributor, or commenter) or a custom one, and that role carries a fixed set of permissions. All plans include the system-defined roles. **GAC** unlocks custom roles, available on Enterprise Grid only. A role is what you assign to a user. A permission scheme is a named, reusable bundle of permissions that a role is built from. A custom role can combine one scheme or several, and its effective permissions are the union of everything attached to it, for example, a "Release Manager" role built from a Contributor scheme plus a custom Release Publishing scheme. A practical role model might look like this: | Role | Typical responsibility | | ----------------- | ------------------------------------------------------------ | | Workspace owner | Organization-level ownership, billing, and critical settings | | Workspace admin | Members, projects, integrations, and workspace configuration | | Project admin | Project configuration, membership, and delivery oversight | | Contributor | Creating and updating project work | | Commenter | Reviewing and commenting without changing project work | | Guest | Limited access to selected projects | | Security reviewer | Reviewing configuration, access, and audit activity | Keep the number of custom roles manageable. If two roles have nearly identical permissions, they probably do not need to be separate. > **Tip:** Name roles after responsibilities, not individuals or temporary organizational structures. "Security Reviewer" will remain useful longer than a role named after a person. ## Keep external access limited Contractors, vendors, customers, and other external collaborators rarely need the same access as employees. Give each external user access only to the projects and actions required for their work. Decide whether they need to create work, edit it, comment, or simply follow progress. Review external access regularly. Project completion, contract changes, and extended inactivity are useful review points. > **Note:** Document who can invite external collaborators and who is responsible for removing them. Guest access should not become a permanent workaround for unclear access policies. ## Set it up to be auditable Define audit requirements before rollout. Agree on: * Which administrative and security-sensitive actions need to be reviewed * Who reviews audit activity * How often access reviews happen * Which events should reach existing security tools * Whether logs need to be exported * What records are required during an incident investigation Enterprise Grid provides [workspace audit logs](/workspaces-and-users/audit-logs) with time-stamped records of sign-ins, membership changes, role changes, settings changes, integration activity, and other security-sensitive events. Workspace Owners and Admins can filter and export the logs. **Workspace audit logs** ![Workspace audit logs](https://media.docs.plane.so/for-enterprise/audit-logs.webp) > **Tip:** Include audit-log exports in the organization's existing security review or evidence-collection process. Do not leave them as a feature that is only checked after an incident. ## 2. Workspace structure Workspace structure determines where governance boundaries sit and how easily teams can collaborate. Create separate workspaces for meaningful boundaries such as business units, regions, legal entities, or confidentiality requirements. Different team workflows do not always require different workspaces. [Teamspaces](/core-concepts/workspaces/teamspaces), projects, roles, and project-level configuration can often provide the separation teams need within one workspace. **How work is organized in a Plane workspace** ```text Workspace ├── Projects │ ├── Work items │ │ ├── Work item types (Epics) │ │ ├── Custom properties │ │ ├── Sub work items │ │ ├── Relations │ │ ├── Comments │ │ ├── Links │ │ ├── Attachments │ │ ├── Activity history │ │ ├── Work logs │ │ └── Archives │ ├── Cycles │ │ ├── Work items │ │ ├── Burndown and progress │ │ └── Work item transfer │ ├── Modules │ │ ├── Work items │ │ └── Progress │ ├── Milestones │ │ └── Work items │ ├── Views │ │ ├── Layouts │ │ ├── Filters │ │ ├── Display properties │ │ └── Access control │ ├── Pages │ ├── Intake │ │ ├── Intake work items │ │ ├── Intake forms │ │ ├── Email intake │ │ └── Triage │ ├── Project updates │ ├── Workflows │ │ ├── States │ │ ├── Transition rules │ │ └── Approvals │ └── Project settings │ ├── General │ ├── Members and roles │ ├── Project states │ ├── Labels │ ├── Estimates │ └── Features ├── Teamspaces │ ├── Projects │ ├── Work items [rollup] │ ├── Cycles [rollup] │ ├── Views │ ├── Pages │ └── Members ├── Wiki [workspace knowledge] │ ├── Collections │ │ └── Pages │ ├── Pages │ │ ├── Sub-pages │ │ ├── Private pages │ │ ├── Public pages │ │ ├── Sharing │ │ ├── Comments │ │ ├── Version history │ │ ├── Page templates │ │ ├── Locking │ │ └── Archives │ ├── Blocks │ │ ├── Headings and text │ │ ├── Lists and to-dos │ │ ├── Quotes │ │ ├── Callouts │ │ ├── Toggles │ │ ├── Tables │ │ ├── Code blocks │ │ ├── Images and media │ │ ├── File attachments │ │ ├── External embeds │ │ ├── Work item embeds │ │ ├── Mentions │ │ ├── Dividers │ │ └── Database blocks │ └── Databases │ ├── Properties │ ├── Views │ └── Records ├── Initiatives │ ├── Projects │ ├── Epics │ └── Work items [rollup] ├── Releases │ ├── Work items │ ├── Release tags │ ├── Release labels │ └── Changelog ├── Customers │ ├── Requests │ ├── Custom properties │ └── Linked work items ├── Dashboards │ ├── Private dashboards │ ├── Public dashboards │ ├── Widgets │ │ ├── Bar chart │ │ ├── Line chart │ │ ├── Area chart │ │ ├── Donut chart │ │ ├── Pie chart │ │ └── Number │ └── Layout ├── Analytics │ ├── Overview │ ├── Projects │ ├── Users │ ├── Work items │ ├── Cycles │ ├── Modules │ └── Intake ├── Plane AI │ ├── Modes │ │ ├── Talk to build │ │ ├── Ask to know │ │ └── Assign to ship │ ├── Agents │ │ ├── Built-in agents │ │ ├── Custom agents │ │ └── Skills │ ├── Models │ │ ├── Model routing │ │ └── Model cocktailing │ └── Usage │ ├── Consumption │ ├── Limits │ ├── Per-model breakdown │ └── Per-agent breakdown ├── Integrations │ ├── GitHub │ ├── GitHub Enterprise Server │ ├── GitLab │ ├── GitLab Enterprise │ ├── Slack │ ├── Sentry │ ├── Draw.io │ ├── Agents (Claude, Cursor, VS Code MCP) │ └── Importers (Jira, Jira Server, Linear, Asana, ClickUp, Confluence, Notion) └── Workspace settings ├── General ├── Members ├── Roles and permission groups ├── Granular access control ├── Security and identity │ ├── SSO / SAML / OIDC │ └── LDAP (Enterprise Grid) ├── Work item types │ ├── Hierarchy levels │ └── Type properties ├── Automations │ ├── Global automations │ └── Project automations ├── Plane Runner (Enterprise Grid) │ ├── Transition scripts │ ├── Automation scripts │ └── Functions ├── Billing and plans ├── API tokens ├── Webhooks ├── Imports ├── Exports └── Audit logs ``` ### Structure workspaces around real boundaries Enterprise Grid supports organizations that need to manage multiple workspaces under a shared enterprise arrangement. An organization might have separate workspaces for Product and Engineering, Business Operations, and a regulated regional operation. Within each workspace, teamspaces can group related people and projects. Ask these questions before creating another workspace: * Does this group need a separate security boundary? * Does it have different regulatory or data requirements? * Should administrators govern it independently? * Does its work need to be hidden from the rest of the organization? * Would a teamspace or private project provide enough separation? > **Tip:** Fewer workspaces are easier to govern. Add a workspace when it represents a real organizational boundary, not simply because a team wants different labels or states. ### Set predictable visibility defaults Decide when projects should be public within the workspace and when they should be private. Broad visibility works well where discoverability and cross-team collaboration matter. Private access is more appropriate for confidential, customer-sensitive, security, legal, or personnel-related work. Document the default and its exceptions. Teams should not need to make a new policy decision every time they create a project. ## 3. Shared standards Standardization should make work easier to understand across teams. It should not force every team into an identical operating model. A practical split looks like this: | Standardize across the organization | Leave to teams | | ----------------------------------- | -------------------------- | | Core work item types | Team-specific labels | | Required project fields | Saved views | | Shared workflow states | Board and list layouts | | Project and work item templates | Cycle length | | Approval requirements | Module structure | | Update cadence | Local planning practices | | Project naming rules | Optional custom properties | The exact split will vary. The important question is who needs to understand the information. If leadership compares something across teams, standardize it. If the information is only useful inside one team, let that team manage it. ## Keep the work taxonomy small Use a small, consistent set of conventions for how work is organized across teams. Keep names predictable, use each object for its intended purpose, and review the taxonomy regularly. | Object | Suggested convention | Examples | | ---------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------- | | [Teamspaces](/core-concepts/workspaces/teamspaces#teamspaces) | Team or function name | Design team, Backend team, Platform team | | [Projects](/core-concepts/projects/overview) | Product or workstream name | Mobile app, Product design | | [Work item types](/work-items/workspace-work-item-types#workspace-work-item-types) | Singular noun naming the nature of work | Epic, Bug, Task, Feature request | | [Modules](/core-concepts/modules) | Focused area of work or specific goal | Mobile push notifications, Website redesign | | [Initiatives](/core-concepts/projects/initiatives#initiatives) | Long-term, strategic objective | Q3-Q4 roadmap, FY27-28 GTM strategy | | [Labels](/core-concepts/issues/labels#work-item-labels) | Classification or characteristic of the work | Enhancement, security, performance | Avoid creating multiple names for the same concept. Synonyms such as `bug`, `Bug`, `bugs`, and `defect` make cross-project reporting harder to trust and understand. Teams can add properties for their own context, but the common work item types should remain easy to recognize across the organization. Plane supports both [workspace work item types](/work-items/workspace-work-item-types) and [project work item types](/work-items/project-work-item-types). > **Tip:** If a new employee needs a glossary to tell two work item types apart, the taxonomy is probably too detailed. ## Create reusable project templates [Project templates](/templates/project-templates) give teams a reliable starting point without requiring administrators to configure every project. A template can include the project structure and configuration that a recurring type of work needs. Create templates for repeatable processes such as product development, incident response, customer implementation, or security review. Do not create a separate template for every team. A smaller set of well-maintained templates is easier to understand and update. **Project template** ![Project template](https://media.docs.plane.so/for-enterprise/project-templates.webp) ## 4. Migration Define the target workspace structure and shared standards before the first import. Start with one representative team. Validate the structure, permissions, work item mapping, and reporting before moving additional teams. Plane provides [importers](/importers/overview) for Jira, Linear, Asana, ClickUp, Confluence, Notion, and CSV data. During the pilot, check: * User and assignee mapping * Project and work item structure * States and workflows * Labels and custom fields * Comments and attachments * Links between related work * Dates and historical information * Permissions after import * Reporting after import Not every field from the old system needs to be preserved. Keep information that remains useful and archive what no longer has operational value. > **Tip:** Do not redesign every process during migration. Define the target structure, move representative work into it, and adjust based on what the pilot reveals. **Importer mapping** ![Importer mapping](https://media.docs.plane.so/for-enterprise/imports.webp) **Migration guides:** [Import from Jira](/importers/jira) | [Import from Linear](/importers/linear) | [Import from CSV](/importers/csv) Planning a large migration? [Talk to the Plane team](https://plane.so/talk-to-sales) about migration planning and implementation support. ## 5. Strategy and planning Leadership needs a view of strategic work without requiring teams to report every task upward. ### Connect initiatives to projects [Initiatives](/core-concepts/projects/initiatives) bring related projects together around a larger objective. Leadership can follow progress, dates, owners, and state at the initiative level. Teams can continue managing delivery through projects, cycles, modules, milestones, and work items. Keep initiative names focused on the intended outcome. "Improve enterprise activation" communicates more than "Activation projects." **Initiative** ![Initiative](https://media.docs.plane.so/for-enterprise/initatives.webp) > **Tip:** An initiative should help leadership understand progress and make decisions. If it only groups unrelated projects, it will not provide a useful strategic view. ### Give every project an owner and outcome Every active project should have: * A clear name * One accountable owner * A defined outcome * A target date or planning horizon * A current state * A regular update Choose a project naming convention while the number of projects is still manageable. For example: * ENG / Enterprise SSO * ENG / Mobile App * GTM / Customer Expansion * OPS / Regional Rollout The exact format matters less than consistent use. ## Cycles, Modules, and Milestones All three give teams different ways to organize and track project work. **Cycles** help teams plan work within a defined period, such as a week, two weeks, or a month. Teams can use them to decide what to focus on next, monitor progress during the cycle, and carry unfinished work forward when needed. **Modules** group work connected to the same feature, component, or deliverable. A module can span multiple cycles, making it useful for tracking work that belongs together but will not be completed within a single planning period. **Milestones** mark significant points in a project, such as a beta release, security review, product launch, or customer rollout. They give teams and stakeholders a clear view of the major outcomes and dates that matter. For example, a mobile app launch may be tracked as a milestone. Authentication, onboarding, and notifications may be organized into separate modules, while the work required for each module is planned across several cycles. Teams can use all three together or only the ones that fit their planning process. **Cycles** ![Cycles](https://media.docs.plane.so/for-enterprise/cycles.webp) ## 6. Integrations Connect the systems that already create or update important work. For engineering organizations, this often starts with source control, error monitoring, and communication tools. Plane provides native integrations for tools including GitHub, GitLab, Sentry, Slack, Bitbucket, and Cursor. | Integration | Use case | | -------------------------- | ------------------------------------------------------------------------------ | | GitHub / GitHub Enterprise | Two-way sync between work items and pull requests | | GitLab | Automatic linking and tracking of merge requests against work items | | BitBucket | A single Plane workspace, connected to many Bitbucket workspaces, kept in sync | | Slack | Work item creation, actions, and discussion sync, without leaving Slack | | Sentry | Sentry issues converted into work items, with state kept in sync | | Draw.io | Diagrams embedded directly into pages | Start with the integrations used by the pilot team. Confirm that work moves as expected before making them available organization wide. **Integrations** ![Integrations](https://media.docs.plane.so/for-enterprise/integrations.webp) ## Define ownership before connecting tools For each integration, record: * The business purpose * The system owner * The Plane owner * The permissions or scopes it receives * Which workspaces or projects it can access * Where credentials are stored * How failures are monitored * How access is reviewed * What happens when the integration is removed API keys, OAuth applications, and webhooks should have named owners. Avoid credentials tied to an individual employee where a service or organization-level identity is available. > **Note:** An integration can create or change work without someone opening Plane. Treat it as part of the organization's access model. ## Extend Plane through approved paths For organization-specific workflows, Plane provides a [REST API](https://developers.plane.so/api-reference/introduction), [webhooks](https://developers.plane.so/dev-tools/intro-webhooks), and tools for building custom applications and integrations. Keep custom extensions under shared ownership. Document what they do, which permissions they have, and how they are maintained. ## 7. Intake and customer requests Incoming work needs one visible path and a clear owner. [Plane Intake](/intake/overview) can collect work through: * [In-app submissions](/core-concepts/intake) * [Public forms](/intake/intake-forms) * [Email](/intake/intake-email) Submissions enter a triage state before they become planned project work. Teams can review, clarify, accept, decline, merge, or prioritize requests before adding them to the backlog. ## Give every intake queue an owner Decide: * Who reviews new submissions * How quickly submissions should be reviewed * Which information submitters must provide * How duplicates are handled * What qualifies for planned work * How requesters receive an update * Who covers the queue when the main owner is unavailable > **Tip:** Keep forms short enough that people will complete them, but collect enough context for the team to make an initial decision. **Intake requests** ![Intake requests](https://media.docs.plane.so/for-enterprise/intake.webp) Teams can create intake forms for structured submissions or accept requests through intake email. ## Connect requests to delivery [Customers and customer requests](/customers) connect external demand to the work addressing it. Support and Customer Success teams can follow whether a request has been accepted, linked to planned work, or completed without maintaining a separate delivery tracker. **Customer requests** ![Customer requests](https://media.docs.plane.so/for-enterprise/customers.webp) ## 8. Knowledge and documentation Shared knowledge should be easy to find outside individual projects. Use the [Wiki](/core-concepts/pages/wiki) for durable organizational knowledge such as: * Engineering standards * Architecture * Runbooks * Product principles * Planning processes * Policies * Decision records * Onboarding material Project Pages are better suited to knowledge connected to a specific project, such as briefs, meeting notes, specifications, and launch plans. Organize the Wiki through [collections](/pages/collections) and [nested pages](/pages/nested-pages) so people can browse it without already knowing the title of the page they need. **Organization Wiki** ![Organization wiki](https://media.docs.plane.so/for-enterprise/wiki-docs.webp) ## Keep decision records consistent For significant decisions, record: * What was decided * Why it was decided * Which alternatives were considered * Who made the decision * When it was made * When it should be reviewed again A short, consistent decision record is more useful than a detailed document nobody maintains. > **Tip:** Link decision records to the projects, initiatives, or work items they affect. People should be able to move from the decision to the work without searching for it. ## 9. Reporting and leadership visibility Reporting should answer a known question for a known audience. Teams need operational views. Functional leaders need progress, risk, and dependency information. Executives need a clear view of strategic commitments. ## Start with saved views Saved views are often enough for recurring operational questions such as: * What is blocked? * What is overdue? * Which incidents remain open? * What needs review? * Which work has no owner? Do not build a dashboard if a saved view answers the question clearly. ## Build dashboards around decisions [Dashboards](/dashboards) should help someone decide or act. Useful leadership questions include: * Which initiatives are at risk? * Where are dependencies blocking delivery? * Which projects have missed an update? * What work is consuming capacity? * What shipped during the current period? Keep dashboards focused. A screen filled with widgets can provide less clarity than three well-chosen measures. **Leadership dashboard** ![Leadership dashboard](https://media.docs.plane.so/for-enterprise/dashboards.webp) > **Tip:** Assign an owner to every dashboard. Review it periodically and remove anything that no longer informs a decision. ## Set an update cadence Numbers show what changed. Updates explain why. A practical reporting rhythm might include: **Weekly functional updates** * Initiative progress * Major blockers * Material changes * Decisions needed **Monthly executive updates** * Progress against commitments * Major risks * Capacity shifts * Cross-team dependencies * Changes since the previous update The cadence should match how often the audience can act on the information. [Project updates](/communication-and-collaboration/project-updates) give teams a consistent place to record health, progress, blockers, and next steps. ## 10. Workflows and approvals Create [workflows and approvals](/workflows-and-approvals/workflows) around processes the organization genuinely needs to enforce. Shared workflows are useful for: * Production changes * Security reviews * Incident response * Customer escalations * Procurement * Release readiness Approvals should represent real decision points. Adding approval steps to ordinary work slows teams down without improving control. For every approval, define: * What is being approved * Who can approve it * What information the approver needs * What happens after approval * What happens after rejection * Who handles exceptions **Workflow with approval** ![Workflow with approval](https://media.docs.plane.so/for-enterprise/workflows.webp) > **Tip:** If approvals regularly happen outside Plane, check whether the workflow includes enough context and the right approver. ## 11. Automation Automate stable, repeatable processes like: * Routing work based on type or property * Updating a state after a defined event * Adding standard comments * Sending reminders * Creating recurring work * Calling an approved webhook * Running scheduled maintenance * Applying organization-specific business rules Start with a small number of automations that solve visible problems. Monitor the results before expanding them across projects. Plane supports project automations, while Enterprise Grid provides additional capabilities for organization-wide and more advanced automation requirements. Review the [custom automation documentation](/automations/custom-automations) and current plan comparison before deciding which automations belong in the rollout. **Automation builder** ![Automation builder](https://media.docs.plane.so/for-enterprise/automation.webp) For every automation, record: * What starts it * Which conditions it checks * Which actions it takes * Which projects it affects * Who owns it * How failures are detected * When it was last reviewed > **Note:** Someone should be able to explain why every organization-wide automation exists and what would happen if it stopped running. ## 12. Plane AI Plane AI is built into the workspace you already use, not a separate chat window bolted onto the side. It reads and acts on the same projects, work items, and pages your team works in. What it's allowed to do without asking depends on the mode. ## The three modes | Mode | What it does | | --------- | -------------------------------------------------------------------------------- | | Ask | Read-only. Answers questions from your workspace, changes nothing. | | Build | Plans a set of actions, shows them to you as cards, waits for your confirmation. | | Autopilot | Same planning as Build, but executes immediately. No review step. | ![Plane AI modes](https://media.docs.plane.so/for-enterprise/plane-ai.webp) Introduce Plane AI after the organization has clear permissions, reliable workflows, and defined data boundaries. [Plane AI](/ai/plane-ai) can help people search, summarize, draft, and work with project information. [MCP connectors](/ai/mcp-connectors) can extend that work to approved external tools and data sources. These capabilities should follow the same governance model as employees and integrations. ## Set an AI policy Before broad access, decide: * Which AI features are approved * Which teams and workspaces can use them * Which model providers are permitted * What data can be shared with external providers * Whether private or locally hosted models are required * How usage and cost are monitored * Who reviews generated output * Which actions require human approval The policy should distinguish between generating content and taking action. Summarizing a project update carries a different level of risk from changing work, calling an external system, or running a script. ## Control access to MCP connectors Review each connector before making it available. Confirm: * What data it can access * What actions it can take * Which credentials it uses * Which users or teams can use it * Who owns the connection * How access will be reviewed and removed Start with contained use cases and expand access only after the organization understands how the connector behaves. Teams building their own connections can use the Plane MCP server. > **Tip:** If an AI connection does not have a clear owner, it should not have access to organizational work or external systems. ## 13. Ongoing ownership A successful rollout needs clear ownership after the initial implementation. | Area | Typical owner | | ---------------------------------- | -------------------------------------------------- | | Identity and access | IT or Security | | Workspace structure and governance | Platform, Operations, or workspace administration | | Migration | Platform team and team champions | | Shared standards | Workspace administration and functional leadership | | Integrations and API access | Platform and Security | | Intake | The team receiving the requests | | Dashboards and reporting | Functional or operational leadership | | Workflows and automation | Platform team or workflow owner | | AI and MCP connectors | AI governance owner, Security, and platform team | | Adoption and training | Department champions | | Self-hosted operations | Infrastructure or SRE | The exact owners will vary, but ownership should be explicit. Create a regular review for: * Administrators and privileged roles * External users * Inactive accounts * Integrations and credentials * Workspace and project visibility * Organization-wide templates * Workflows and automations * Dashboards * AI access and MCP connectors * Self-hosted upgrades and backups > **Tip:** Keep the review lightweight and regular. A short quarterly review is easier to run than a large cleanup after access and configuration have accumulated for a year. ## Roll out Plane with a clear operating model Plane gives large organizations a common operating system without requiring every team to work in exactly the same way. Establish governance centrally, roll Plane out team by team, and assign clear ownership as the system grows. ## Where to go from here * **Live reference:** [Plane's docs site](https://docs.plane.so). This guide is a snapshot. That page has the current pricing, seat limits, and feature availability by plan. * **Build on Plane:** [the developer docs](https://developers.plane.so), for the API, webhooks, the MCP server, and self-hosting guides. * **Talk to sales:** [reach out here](https://plane.so/talk-to-sales), for Enterprise Grid scoping, migration services, or anything else this guide didn't answer. --- --- url: 'https://docs.plane.so/introduction/core-concepts.html' description: >- Learn the essential building blocks of Plane - workspaces, projects, work items, cycles, views, and pages. Master these concepts to organize your team's workflow effectively. --- # Core concepts This page explains how Plane is structured and how its features work together. Understanding these concepts helps you organize work effectively and collaborate with your team. ## Understand Plane's structure Plane is organized in a hierarchy that reflects how teams naturally work together: At the top level, **Workspaces** contain everything - typically one per organization. Inside workspaces, you create **Projects** for specific products, initiatives, or goals. Within projects, you manage **Work items** (the individual tasks your team completes). You can organize these work items using **Cycles** (time-boxed periods) and **Views** (saved filters and layouts). Finally, **Pages** provide space to document context and decisions alongside your work. This structure gives you flexibility to work at whatever level makes sense. Sometimes you'll focus on a single work item. Other times, you'll view an entire project or cycle to understand the bigger picture. ## How features connect Understanding relationships between Plane's features helps you use them effectively. ### Workspaces Think of a workspace as the central hub for everything you do on Plane. It’s the top-level space where all your projects and work items live. Workspaces are typically set up for a company or client, and everyone within a workspace can collaborate on projects and access shared resources. You can also think of each workspace as a different organization or client you're working with, keeping things separate and organized. Inside a workspace, you have the freedom to create projects on your own or invite collaborators to join and share it as a team — it’s entirely up to you! Learn more about [Workspaces](/core-concepts/workspaces/overview). ### Projects Projects are the big, overarching containers for related tasks and work items. You might create a project for a product launch, major features, or even an ongoing initiative. Each project keeps everything in one place, making it easy to track progress and focus on specific goals. Inside a project, you’ll organize and manage work items, assign team members, set deadlines, and structure work into more manageable parts. Learn more about [Projects](/core-concepts/projects/overview). ### Work items Work items are the heart of task management in Plane. Each work item represents a specific task or item of work within a project, whether that’s a bug fix, a new feature, or a to-do. You can assign work items to team members, add due dates, prioritize them, and link related work items together to give context. Work items in Plane are highly customizable, making it easy to tailor them to the needs of your team. Each work item is identified by a unique, project-specific number (e.g., VIH-19), making it easy to track and reference. At a minimum, every work item needs a title and a state, but you can customize it further with additional properties and relations as needed. Learn more about [Work items](/core-concepts/issues/overview). ### Cycles Cycles help you organize work into time-bound periods, like sprints or phases. They’re perfect for planning work over specific intervals, letting your team know what’s coming up and what needs to be wrapped up. Cycles can contain multiple work items from different projects, making it easy to see your team’s workload at a glance and keep an eye on deadlines. * You can move existing work items into a new or ongoing cycle or create new work items directly within a cycle. * Bulk operations are supported - you can add or update multiple work items to cycles at once. * You can't update work items after a cycle is completed, however, the pending work items can be transferred to a new or upcoming cycle. Learn more about [Cycles](/core-concepts/cycles). ### Views Views help you filter and organize work items to see exactly what matters right now. Instead of manually configuring filters every time, views save your layout, filters, and display settings so you can access them instantly. The same work item can appear in multiple views simultaneously. Views exist at both project and workspace levels. Project views show work from a single project, while workspace views can display work items across all projects you have access to. Learn more about [Views](/core-concepts/views). ### Pages Pages are where you can jot down notes, add documentation, or outline plans — think of them as an AI-powered notepad. They’re perfect for quickly capturing ideas, taking notes during meetings, or starting your day with an organized list. Pages help you keep all your project-related information in one place, and because they’re easily accessible, you can refer to them whenever needed. Use Pages to record processes, share best practices, or simply keep team notes that everyone can refer to as needed. Learn more about [Pages](/core-concepts/pages/overview). *** With these core concepts under your belt, you’re ready to start exploring Plane and putting it to work for your team. Each feature is designed to help you and your team stay organized, collaborate effectively, and deliver your projects with ease. --- --- url: 'https://docs.plane.so/introduction/tutorials/overview.html' description: >- Step-by-step guides to master Plane's essential features and build effective team workflows. --- # Tutorials Master Plane's core features with hands-on, step-by-step tutorials designed to get you and your team productive quickly. These tutorials follow a logical progression from workspace setup to advanced collaboration, ensuring you build skills systematically. ## Getting started with Plane Build your workspace and team structure: **[Create workspace](/introduction/tutorials/create-workspace)**\ Set up your dedicated workspace, navigate the Plane interface, and understand the sidebar. Learn to switch between workspaces and access essential settings and support resources. *Time: 5 minutes* **[Invite members](/introduction/tutorials/invite-members)**\ Bring your team into Plane with appropriate roles and permissions. Master workspace roles, manage team members, and handle invitations effectively. *Time: 3-5 minutes* **[Create projects](/introduction/tutorials/create-project)**\ Set up your first project where teams organize work and collaborate. Configure project settings, add team members, customize workflows, and organize work with labels. *Time: 8-10 minutes* ## Working with tasks and collaboration Learn to create, manage, and collaborate on work: **[Create work items](/introduction/tutorials/create-work-items)**\ Add your first tasks with clear titles, descriptions, and properties. Navigate different views, move work through workflow states, and complete the full work item lifecycle. *Time: 8-10 minutes* **[Collaborate on work items](/introduction/tutorials/collaborate-on-work-items)**\ Transform individual tasks into team collaboration opportunities. Use comments and mentions, create sub-work items, manage notifications, and track activity effectively. *Time: 10-12 minutes* ## Organization and planning Organize and plan work for maximum team effectiveness: **[Organize and view your work](/introduction/tutorials/organize-and-view-work)**\ Master work organization using layouts, filters, and custom views. Create workspace-level views, use personal dashboards, and build effective daily routines. *Time: 12-15 minutes* **[Plan work with Cycles](/introduction/tutorials/plan-and-create-cycles)**\ Transform scattered work into focused, time-boxed periods. Create cycles with clear boundaries, track team velocity, and build sustainable planning rhythms. *Time: 10-12 minutes* **[Write content with Pages](/introduction/tutorials/create-pages)**\ Create professional documentation, meeting notes, and project requirements. Master the block-based editor, share pages effectively, and configure settings for different use cases. *Time: 5 minutes* *** ## Tutorial pathways ### For workspace administrators * Create workspace → Invite members → Create projects → Advanced organization features ### For project managers * Create projects → Create work items → Plan with Cycles → Organize and view work ### For team contributors * Create work items → Collaborate on work items → Organize and view work → Write content with Pages ## What you'll accomplish By completing these tutorials, you'll have: **Essential skills:** * Functional workspace with proper team access and permissions * Project structure that matches your team's workflow * Work creation and management capabilities * Effective collaboration patterns and communication practices **Advanced capabilities:** * Custom views and organization systems that support different work contexts * Time-based planning with cycles for consistent delivery * Documentation and knowledge sharing through Pages * Personal productivity systems that integrate with team workflows *** *These tutorials provide the foundation for effective team collaboration in Plane. Work through them at your own pace, and don't hesitate to revisit sections.* --- --- url: 'https://docs.plane.so/introduction/tutorials/create-workspace.html' description: >- Learn how to create and set up your first Plane workspace. Get started with workspace naming and basic navigation. --- # Create workspace Let's get you set up your workspace where you and your team can collaborate on projects. In this tutorial, you'll: * Create and configure a new workspace * Navigate the Plane interface and understand the sidebar * Switch between workspaces when working with multiple teams * Access workspace settings and support resources ## Create new workspace If you've already signed up for Plane, you have your first workspace created during [signup](https://app.plane.so/sign-up). This tutorial shows you how to create additional workspaces. ::: info 💡 Don't need another workspace right now? You can skip to the next section. ::: ![Workspace switcher](https://media.docs.plane.so/tutorials/workspace-switcher.webp#hero) 1. **Access workspace switcher** * Click on your current workspace name in the top-left corner. * You'll see the workspace switcher with your existing workspaces. 2. **Create new workspace** * Click **Create workspace** at the bottom of the switcher. * The workspace creation form opens. ![Workspace creation form](https://media.docs.plane.so/tutorials/workspace-creation-form.webp#hero) 3. **Name your workspace** * Enter a name that's familiar and recognizable for your team. * Usually your company name works best. You can always change this later in settings. 4. **Set workspace URL** * Your URL is auto-generated from the workspace name. * Customize it if needed: `app.plane.so/`. ::: warning This URL choice is permanent and cannot be changed later. Make sure it's exactly how you want it. ::: 5. **Select team size** * Choose the range that matches your expected team size. This helps optimize your Plane experience. * You can always invite more people later. 6. **Complete setup** * Click **Create workspace** to finish. * You're automatically set as **Admin** with full permissions. Your new workspace appears in the top-left and shows 1 Member (you). ## Explore your workspace Home After creating your workspace, you'll land on the Home page. ![Workspace Home](https://media.docs.plane.so/tutorials/workspace-home.webp#hero) ### Understanding the Home page **Key sections you'll see:** * **Quicklinks:** Save links to frequently accessed resources * **Recents:** Recently accessed work items, pages, and projects * **Your stickies:** Personal notes and reminders ## Navigate the sidebar Understanding the sidebar helps you move efficiently around Plane. ### Personal section * **Home:** Your workspace home * **Your work:** All work items assigned to you across projects ### Workspace section * **Projects:** All projects in your workspace * **More:** Click to pin additional workspace features like Views, Analytics, Drafts, and Archives to your sidebar for quick access. ::: tip Search Use the search bar at the top to quickly find work items, projects, or pages across your workspace. ::: ### Projects section * Direct links to individual projects for both configuration and daily work * Shows all projects you're part of or have access to ## Manage multiple workspaces Learn to work with multiple workspaces effectively. ### Switch between workspaces 1. **Access workspace switcher** * Click your workspace name (top-left). * All your workspaces are listed. * Current workspace shows a checkmark ✓. * Member count and your role appear for each. 2. **Navigate between workspaces** * Click any workspace to switch to it. * Each workspace maintains its own projects and settings. ### Join other workspaces **When someone invites you:** * You'll receive an email notification. * Accept from email or directly in Plane. **To join from within Plane:** * Look for **Workspace invites** at the bottom of the switcher. * Pending invitations appear here. * Click to accept invitations from other teams. ## Configure workspace settings Customize your workspace to match your team's needs. ### Access settings ![Workspace settings](https://media.docs.plane.so/tutorials/workspace-settings.webp#hero) 1. **Open workspace settings** * Click your workspace name (top-left) to open the workspace switcher * Click **Settings** next to your workspace name or on the siderail. 2. **Key settings to explore** * **General:** Change workspace name, upload company logo, and update team size * **Members:** View and manage team members. You can successfully navigate to workspace settings and see customization options. ## What's next? * [Invite members](/introduction/tutorials/invite-members) to get your team on board --- --- url: 'https://docs.plane.so/introduction/tutorials/invite-members.html' description: >- Learn how to invite team members to your Plane workspace, assign roles, and manage member permissions. --- # Invite members Let's get your colleagues set up so you can start collaborating on projects together. In this tutorial, you'll: * Invite team members to your workspace with appropriate roles * Understand workspace roles and permissions * Manage team members after they join * Handle pending invitations and role adjustments ## Access Members page There are two ways to invite team members to your workspace: **From the workspace switcher** 1. Click on your workspace name in the top-left corner. 2. Next to your current workspace, click **Invite members**. **From workspace settings** ![Workspace members](https://media.docs.plane.so/tutorials/invite-team-members.webp#hero) 1. Click your workspace name, then **Settings**. 2. In the left pane, click **Members** under **Administration**. 3. Click the **Add member** button in the top-right. Both options open the same invitation dialog. ## Add team members Configure who joins your workspace and what they can do. ![Add members](https://media.docs.plane.so/tutorials/add-members.webp#hero) In the **Invite people to collaborate** dialog: - Type email address in the provided field. - Use the **+ Add more** link to invite multiple people at once. ::: tip 💡 Start with core team members who will actively use Plane. You can always add more people later. ::: ### Choose member roles For each person you're inviting, select their role from the dropdown. #### 👑 Admin * Full workspace control and settings access. * Can invite or remove members and manage billing. * Best for Workspace owners, team leads, IT administrators. #### 👥 Member (Default) * Can create projects, work items, and collaborate fully. * Cannot change workspace settings or manage other members. * Best for most team members, developers, designers, project contributors. #### 👁️ Guest * Limited access to specific projects they're invited to. * Cannot see other projects or workspace-level information. * Best for external contractors, clients, temporary collaborators. ::: tip 💡 Want a deeper breakdown? Check out the [full guide](/roles-and-permissions/permissions-matrix) on roles and permissions. ::: ## Send invitations Once you've added email addresses and selected roles: 1. Review your invitation list. 2. Click **Send invitations**. 3. Each person will receive an email invitation to join your workspace. ### What happens next **For invitees:** * They receive an email with a join link. * Can accept directly from email or from the workspace switcher. * Join with the role you assigned them. ## Manage your members Learn to adjust roles and monitor team membership. ### View member information **Access member management:** Go to **Workspace settings → Members** to see complete member information: **Member details displayed:** * Full name and display name * Email address and account type * Current role (Admin/Member/Guest) * Billing status (Active/Inactive) * Authentication method (Email/SSO) * Joining date ### Adjust member roles 1. Click the role dropdown next to any member's name. 2. Change between **Admin**, **Member**, or **Guest** as needed. 3. Changes take effect immediately. ### Remove members from workspace ![Remove members](https://media.docs.plane.so/tutorials/remove-member.webp#hero) 1. Find the member in your Members list. 2. Click the three dots (...) next to their name. 3. Select **Remove**. Removed members lose access to all workspace projects and data immediately. They can be re-invited later if needed. ## What's next? Your team now has access to collaborate effectively in Plane. **Ready to start collaborating?** * [Create your first project](/introduction/tutorials/create-project) to set up a space for your team's work --- --- url: 'https://docs.plane.so/introduction/tutorials/create-project.html' description: >- Learn how to create and configure your first Plane project with the right features, workflow states, and team members --- # Create project Set up your first project where your team can organize work, track progress, and collaborate effectively. In this tutorial, you'll: * Navigate the Projects section and understand project visibility * Create a project with proper configuration * Enable essential features for your team's workflow * Set up workflow states that match how your team works * Add team members and organize work with labels ## Explore the Projects section Before creating your project, let's understand where all projects live in your workspace. ![Workspace Projects](https://media.docs.plane.so/tutorials/workspace-projects.webp#hero) 1. Look for **Projects** under the Workspace section in your sidebar. 2. Select **Browse all projects** in the dropdown at the top. 3. You might see a few projects already there that other members may have created. 4. This is where all workspace projects are displayed. ### Understand project visibility * Public projects show for all workspace members (except Guests) with the **Join** option. * Projects you're part of display directly in your sidebar under the **Projects** section. * Private projects are only visible if you're specifically invited. ## Create your project Start building a space for your team's work and collaboration. 1. **Begin the creation process** * Click **Projects** in your workspace sidebar to view all projects. * Click **Add Project** button (top-right). * The project creation form opens. ::: tip You can also create projects quickly using the **+** button next to the **Projects** section in your sidebar. ::: 2. **Configure basic project information** ![Create project](https://media.docs.plane.so/tutorials/create-project.webp#hero) * **Project name**: Enter something clear and recognizable. Choose names your team will instantly understand. *Examples*: "Website Redesign", "Mobile App v2.0", "Q4 Marketing Campaign" * **Description**: Add 1-2 sentences explaining the project's purpose.\ *Example*: "Complete redesign of company website focusing on improved user experience and modern design" * **Project ID**: Plane automatically suggests a Project ID based on your project name (like "WEB" for "Website Redesign"). This ID will prefix all your work items (WEB-1, WEB-2, etc.). You can customize it, but keep it short (3-5 characters). * **Set project access**: Keep **Public** selected for now. This allows all workspace Admins and Members to see and join the project. You can change this to **Private** later if needed. 3. **Create the project** * Click **Create project** to finish basic setup. * You’ll see a modal with all the features enabled for this project. Leave the defaults as they are and click **Open project**. * Your new project appears in the sidebar under the **Projects** section. ## Configure project settings Customize your project to match how your team works. ![Project settings](https://media.docs.plane.so/tutorials/access-project-settings.webp#hero) 1. **Access project settings** * Click the three dots (...) next to your project name in the sidebar. * Select **Settings**. * You'll land on the **General** tab by default. 2. **Customize project details** * **Project icon and cover**: Choose an emoji and a header image for your project. * **Project visibility (Network)**: Choose based on your team's collaboration needs. * **Public**: All workspace members can see and join the project. * **Private**: Only invited members can access the project. * **Project timezone**: Set the timezone for project scheduling and deadlines. 3. **Save your changes** * Click **Update project** to apply your modifications. * Your project now reflects the updated configuration. ## Add team members to your project Get the right people contributing to your project. ![Project members](https://media.docs.plane.so/tutorials/add-project-members.webp#hero) 1. **Access member management** * In project settings, select **Members** in the left pane. * You'll see the Members section with current project members 2. **Configure project lead** * **Project Lead** - Select a project lead from the dropdown. * **Default Assignee** - Set a default assignee for new work items. * **Guest access** - Toggle ON to allow guests view access to all project work items. 3. **Add team members** * Click **Add member**. * Click **Select co-worker** to see all workspace members. * Add 2-3 key team members who will actively contribute. Key team members are added and can access the project to start contributing. ## Set up workflow states Workflow states define how work moves through your team's process. ![Project states](https://media.docs.plane.so/tutorials/project-states.webp#hero) 1. **Access states configuration** * In project settings, click **States** in the left pane. * You'll see default state groups already created 2. **Understand state groups** * **Backlog**: For ideas and future work * **Unstarted**: Ready to work on but not yet started * **Started**: Work currently in progress * **Completed**: Finished work * **Cancelled**: Work that won't be completed 3. **Customize states for your workflow** * Click on any state group to see individual states inside. * Use the **+** button to add new states. * Rename states to match your team's language. * Reorder states to reflect your actual process. **Example workflows** *Simple development workflow*: * Backlog: "Backlog" * Unstarted: "Ready", "Assigned" * Started: "In Progress", "In Review" * Completed: "Done" *Design workflow*: * Backlog: "Ideas" * Unstarted: "Scheduled", "Ready for Design" * Started: "Designing", "Review", "Revisions" * Completed: "Approved" Don't overthink this - you can always adjust states later as your team's process evolves. ## Create useful labels Labels help categorize and organize your work. ![Project labels](https://media.docs.plane.so/tutorials/project-labels.webp#hero) 1. **Access labels configuration** * In project settings, click **Labels** in the sidebar. * You'll see any existing labels (may be empty). 2. **Create essential labels** * Click **Add label** to create new labels. * Add a few labels that match your work types Examples: `frontend`, `backend`, `database`, `API`, `design`, `documentation`, `testing`, `research` 3. **Customize label appearance** * Choose colors for each label to make them easily distinguishable. ## What's next? Your project foundation is complete. You're ready to: * [Create your first work items](/introduction/tutorials/create-work-items) to begin tracking tasks. --- --- url: 'https://docs.plane.so/introduction/tutorials/create-work-items.html' description: >- Learn how to create, organize, and track work items in Plane with titles, descriptions, priorities, assignments, and workflow states. --- # Create work items Now that your project is set up, let's add your first piece of work to track. Work items are the fundamental building blocks in Plane - they represent any task or piece of work your team needs to complete. In this tutorial, you'll: * Create work items with clear titles and descriptions * Set essential properties like priority, assignee, and dates * Navigate different views and work item layouts * Move work items through your workflow states * Complete the full work item lifecycle ## Create your first work item Add a real piece of work to your project with proper details and organization. ![Create work items](https://media.docs.plane.so/tutorials/create-work-items.webp#hero) 1. **Navigate to your project** * Click your project name in the sidebar. * Make sure you're in the Work items tab. 2. **Start creating tasks** * Click **Add work item** in the top-right corner. * The work item creation dialog opens 3. **Add title and description** * Title: Be specific and actionable * Description: Provide context and details ::: tip Example **Title**\ "Fix login button alignment on mobile" **Description**\ The login button on mobile devices is misaligned and appears cut off on screens smaller than 375px width. Steps to reproduce:\ a) Visit login page on mobile device.\ b) Notice button extends beyond screen edge. Expected result:\ Button should be fully visible and properly centered. ::: 4. **Configure work item properties** * **State:** * Choose where this work fits in your workflow. * Select `Planned` since you're ready to work on it. * **Priority:** * Indicate urgency level. * Choose `Medium` priority for this tutorial. * **Assignees:** * Choose who will do the work. * Assign this first work item to yourself. * **Labels:** * Categorize the work type. * Select `frontend` label for this example. * **Dates:** * Set timeline expectations * For this tutorial, set a due date a few days from now or skip dates. 5. **Save your work item** * Click **Save** to create the work item. * You'll see it appear in the List layout with a unique ID (like "ENG-1" or "PROJ-1") ::: info Unfinished work items automatically save to your **Drafts** section, so you can always come back to complete them later. ::: ## View and update work items Learn different ways to view and access your work items. ![View and update work items](https://media.docs.plane.so/tutorials/view-and-update-work-items.webp#hero) 1. By default, the work items appear in the List layout. * Your newly created item appears with key details visible. * You can see title, state, priority, assignee, and labels at a glance. * Items are organized by their current workflow state. 2. **Open work item details** **Peek view (Quick access):** * Click anywhere on your work item row. * Side panel opens showing details without leaving the main page. * Good for quick updates and viewing. **Full view (Detailed work):** * Click the expand icon (diagonal arrows) in peek view. * Provides full editing and collaboration interface. 3. **Update work item state** * Open your work item in peek view or full view * Click on the **State** field. * Change it from `Planned` to `In Progress`. * The change saves automatically. Notice how the work item moves to a different section in your layout view, reflecting its new state. 4. **Modify other properties** * **Priority:** Change based on new urgency levels * **Due date:** Adjust timeline based on progress * **Labels:** Add or remove as you learn more about the work * **Assignees:** Reassign if responsibility changes All changes save automatically, and you'll see them reflected immediately in your view. 5. **Move work to completion** ![Switch to board layout](https://media.docs.plane.so/tutorials/switch-to-board-layout.webp#hero) * Look for the layout options on the top right of the screen. * Click the Board icon. * You'll now see your work items organized in columns by state. * Find your work item in the current state column (likely "In Progress"). * Drag and drop the work item card to the "Done" column. The work item automatically updates its state when you drop it, and you'll see it move visually from one column to another. If you prefer, you can still update the state directly by opening your work item and clicking the **State** field to select `Done`. Both methods accomplish the same result - the drag and drop approach gives you a visual, intuitive way to move work through your workflow states. You've successfully created and managed your first work item! ## Practice with real work Now create 2-3 more work items using actual tasks from your project. This gives you realistic data to work with as you learn more Plane features. **Examples:** * "Update company logo on homepage" * "Research competitor pricing strategies" * "Fix bug in user registration flow" * "Create onboarding email template" ## What's next? You now understand the complete work item lifecycle and can effectively track work in Plane. You're ready to: * Collaborate on work items to learn comments, mentions, and team communication --- --- url: 'https://docs.plane.so/introduction/tutorials/collaborate-on-work-items.html' description: >- Learn how to collaborate effectively on work items in Plane using comments, mentions, sub-work items, and activity tracking. --- # Collaborate on work items Now that you can create and manage work items, let's learn how to collaborate with your team. In this tutorial, you'll: * Use comments and @mentions for effective team communication * Create sub-work items to break down complex tasks * Navigate your Inbox for notifications and updates * Configure email notifications to stay informed * Track activity and manage collaborative workflows ## Add your first comment Start conversations that move work forward effectively. ![Add comments](https://media.docs.plane.so/tutorials/add-comments.webp#hero) 1. **Open a work item for collaboration** * Navigate to your project and go to **Work items**, * Click any work item to open it. 2. **Add a meaningful comment** * Scroll to the **Activity** section. * Click in the **Add comment** text area. * Write a comment that provides value to the team.\ ::: tip Example Started working on this - I've identified the CSS issue and should have a fix ready by tomorrow. The problem is with the media query breakpoint at 375px. ::: 3. **Use formatting options** * Bold important information with **text**. * Create lists for multiple points. * Add code snippets or quotes. 4. **Post your comment** * Click **Comment** to publish. * Your comment appears in the activity timeline. * Relevant team members receive notifications. ## Use @mentions Ensure the right people see important messages and requests. 1. Type @ followed by a team member's name. 2. Select the person from the dropdown that appears. 3. Continue writing your message with context. ## Divide work with sub-work items Organize large tasks into manageable, assignable pieces. ![Sub-work items](https://media.docs.plane.so/tutorials/create-sub-work-items.webp#hero) 1. **Use sub-work items for:** * Large tasks requiring multiple steps * Tasks needing different skills or team members * Work that can be done in parallel 2. **Add a sub-work item** * In your work item, look for **Add sub-work item** button. * Click to create a related, smaller task. * Fill in the sub-item details with specificity.\ ::: tip Example **Parent task:** "Implement user authentication system" **Sub-work items:** * "Design login page wireframes" → Designer * "Set up authentication database tables" → Backend developer * "Create password reset flow" → Frontend developer * "Write user registration API endpoints" → Backend developer ::: 3. **Understand sub-item benefits** * Each sub-item has independent lifecycle and can be worked on separately. * Team members focus on specific sub-items while staying connected to bigger picture. * Clear ownership and accountability for different aspects of complex work. ## Track activity and filter updates Stay informed about work progress without information overload. 1. **Understand the Activity section** The activity feed shows chronological updates: * **Work item changes:** State updates, priority changes, assignment changes. * **Comments:** Team discussions and communications. 2. **Use activity filters** * Click **Filters** button in the Activity section. * Control what information you see: * **Updates:** Show only property changes (state, priority, assignments) * **Comments:** Display only team discussions and communications * **Worklogs:** View only time tracking entries 3. **Use activity tracking strategically** * **Catch up quickly:** See what happened while you were away. * **Understand decisions:** Read discussions that led to changes. * **Track progress:** Monitor how work moves through workflow. * **Maintain context:** Keep team members informed of important developments. ## Explore your notification center Understand how Plane keeps you informed about team activity. ### Discover the Inbox ![Inbox overview](https://media.docs.plane.so/tutorials/inbox-notifications.webp#hero) 1. **Navigate to your Inbox** * Click **Inbox** in your sidebar. * This is your notification center for all workspace activity. 2. **Understand Inbox organization** * **All tab:** Shows all notifications and updates. * **Mentions tab:** Filters to only @mentions directed at you. * Notifications include comments, work item changes, and mentions. ## Configure notification preferences Set up email notifications to stay informed about important updates. ### Access account settings ![Account settings](https://media.docs.plane.so/tutorials/email-notifications.webp#hero) 1. **Open your account settings** * Click your profile avatar (bottom of sidebar). * Select **Settings** from the dropdown. * Select **Notifications** in the left pane. 2. **Ensure all notifications are enabled** * This ensures you receive email updates about all important work item activity. ### Understand notification triggers **You receive notifications when:** * Someone @mentions you in comments. * Work items assigned to you are updated. * Work items you created have activity. * Someone comments on work items you're subscribed to. ## What's next? Your collaboration skills are solid! You're ready to: * [Create custom views](/introduction/tutorials/organize-and-view-work) to filter and organize work items for different contexts. --- --- url: 'https://docs.plane.so/introduction/tutorials/organize-and-view-work.html' description: >- Learn how to organize and visualize your work items using layouts, filters, display options, and custom views in Plane to boost your team's productivity. --- # Organize and view work Now that you can create and collaborate on work items, let's learn how to organize and view them effectively. Plane provides powerful tools to help you see exactly the work that matters to you, when you need to see it. In this tutorial, you'll: * Switch between different layout views to match your workflow * Navigate workspace and project level views * Use filters and display options to focus on relevant work * Create and save custom views for recurring organizational needs ## Explore different layouts Layouts change how your work items are visually organized. Each layout shows the same work items but optimized for different tasks. ![Explore layouts](https://media.docs.plane.so/tutorials/explore-layouts.webp#hero) 1. **Access your project work items** * Navigate to any project in your sidebar. * Look for layout icons in the top-right corner of the Work Items page. 2. **Experiment with each layout:** **List** - Text-based view for task organization * Best for: Quick scanning of all project activities, grouping work items by properties, viewing parent-child relationships * Use when: Reviewing status updates, bulk property changes, organizing tasks by priority/assignee **Board** - Visual workflow cards * Best for: Drag-and-drop state management, team discussions * Use when: Sprint planning, workflow visualization **Calendar** - Timeline view * Best for: Deadline management and scheduling * Use when: Planning due dates, avoiding conflicts **Table** - Excel-like grid * Best for: Bulk editing and data manipulation * Use when: Mass updates, data analysis **Timeline** - Project timeline view * Best for: Dependencies and milestone tracking * Use when: Project planning, dependency management **Try switching between layouts** to see which feels more natural for your current work. ## Apply filters to work items Filters help you see only the work items relevant to your current task. ![Explore layouts](https://media.docs.plane.so/tutorials/filter-work-items.webp#hero) 1. **Access the filters interface** * Click the **Filters** button between the toolbar and your work items. * Filters are applied as visual chips that you can see and modify easily. 2. **Smart filter combinations** * Each filter appears as a chip showing the property and selected values: * Priority: "Priority is any of High, Urgent" * Assignee: "Assignees is any of alex, amara" * State: "State is not Completed" Multiple filters work together automatically, no need to manually combine them. 3. Click the **x** on any filter chip to remove it. 4. Use **Clear all** to reset all filters at once. The work items list updates in real-time as you add or remove filters, giving you exactly the view you need for your current context. ## Customize display options Display options control what information you see for each work item. The display options change based on your layout. ![Display options](https://media.docs.plane.so/tutorials/display-options.webp#hero) 1. **Control visible information** * Click the **Display** dropdown on the top right of the screen. * Toggle properties on/off to reduce visual clutter. 2. **Organize your work items** * **Group by:** Cluster work items logically (by State, Assignee, Priority, or Labels). * **Order by:** Sort items within groups (by Priority for planning, Due date for deadlines, or Updated date for recent activity). * **Sub-work items:** Show or hide nested tasks depending on detail needs. ## Save and manage custom views Views save your perfect combination of layout, filters, and display settings so you can reuse them instantly. 1. **Create a view from your current configuration** * Set up your ideal combination: Board layout + your assignee + active states * Click **Save View** in the top-right corner * Give it a clear, descriptive name: "My Active Sprint Work" * Your view saves with all current settings 2. **Create views from scratch** * Click **Views** in your project sidebar. * Click **Add view** button. * Configure layout, filters, and display options step by step. * Name your view clearly and click **Create View**. Both methods create views that appear in your project sidebar under **Views**. ## Use Your work dashboard Your work dashboard gives you a unified view of all your work across every project in your workspace. ![Your work dashboard](https://media.docs.plane.so/tutorials/explore-your-work.webp#hero) 1. **Access Your work dashboard** * Click **Your work** in the workspace section of your sidebar. * This shows all your work from every project unified in one location. 2. **Understand each tab's purpose:** **Summary** - Work overview with visual insights * Visual charts showing task distribution and priority breakdown * Recent activity across all your work * Use for: Understanding your overall workload balance **Assigned** - Your current responsibilities * All work items currently assigned to you, organized by project * Priorities and due dates clearly visible * Use for: Daily task execution and priority management **Created** - Your originated work * Work items you've created, regardless of current assignee * Useful for tracking your ideas and requests * Use for: Following up on work you've initiated **Subscribed** - Work you're following * Items you're monitoring without being assigned * Keeps you informed on important work * Use for: Staying updated on work progress **Activity** - Complete timeline * All activity on work you're involved with across projects * Use for: Catching up on updates and team progress ### Build a daily routine Use Your work as your starting point each morning. Check the Summary tab for workload balance and priority distribution, then switch to Assigned to see today's specific tasks. The Activity tab catches you up on overnight updates and team progress. This cross-project view helps you prioritize when you're working on multiple projects and ensures nothing falls through the cracks. Your work dashboard becomes your personal mission control for staying organized across your entire workspace. ## What's next? Your work organization skills are solid! You're ready to: * [Plan work with cycles](/introduction/tutorials/plan-and-create-cycles) to group work into time-based iterations. --- --- url: 'https://docs.plane.so/introduction/tutorials/plan-and-create-cycles.html' description: >- Learn how to create and manage cycles in Plane to organize work into time-boxed periods, track progress, and deliver results as a team. --- # Plan work with cycles Cycles help you organize work into focused time periods - like sprints. Instead of endless lists of work items, cycles create clear boundaries with start dates, end dates, and specific goals your team can work toward together. In this tutorial, you'll: * Understand when and why to use cycles for time-based planning * Create cycles with clear timeframes and achievable goals * Add and organize work items within cycle boundaries * Track progress and team velocity over time * Complete cycles and extract learning for future planning ## Understand cycle-based planning **Cycles are time-boxed containers** for your work that create focused periods where your team commits to completing specific work items within set timeframes. **Key benefits:** * Clear deadlines create urgency and focus * Team alignment on what's being worked on when * Progress tracking shows velocity and capacity over time * Regular delivery of completed work to stakeholders ### When to use cycles * **Sprint planning** - 1-2 week focused work periods for agile development * **Release cycles** - Group work leading to specific product releases * **Feature development** - Time-boxed periods for completing related functionality * **Goal-driven work** - Organize work around specific outcomes or milestones ## Create your first cycle Build a focused work period with clear boundaries and achievable goals. ![Create cycle dialog](https://media.docs.plane.so/tutorials/create-cycle.webp#hero) 1. **Begin creating your cycle** * In your project sidebar, click **Cycles**. * Click **Add cycle** button (top-right). * The cycle creation dialog opens. 2. **Set up cycle information:** **Choose a clear title** * Name that describes the cycle's purpose and timeframe. * Example: "Sprint 1: User Authentication". * Be specific enough that team members understand the focus. **Add a helpful description** * Explain what this cycle aims to accomplish. * Include success criteria or goals. * Example: "Complete core user authentication features including login, registration, password reset, and basic profile management. Goal is to have a functional auth system ready for beta testing." **Set your timeframe** * **Start date:** When work begins (often Monday for team alignment). * **End date:** When work should be complete (typically 1-2 weeks later). * **Recommended:** Try a 2-week period for your first cycle. 3. **Create the cycle** * Click **Create cycle** to save. * Your cycle appears in **Upcoming** or **Active** section based on start date. ## Navigate the cycles interface Explore how Plane organizes your cycles and provides timeline visibility. ![Cycles overview](https://media.docs.plane.so/tutorials/cycles-interface.webp#hero) **Understand cycle organization:** * **Active** - Currently running cycles * **Upcoming** - Planned but not yet started * **Completed** - Finished cycles with results This gives you comprehensive perspective on your project's planned work across past, present, and future periods. ## Add work items to your cycle Populate your cycle with the right amount of work for your team's capacity. ![Cycle detail view](https://media.docs.plane.so/tutorials/add-work-items-to-cycle.webp#hero) 1. **Open your cycle for planning** * Click on your newly created cycle name. * You'll see the cycle detail view with progress charts and work item areas. 2. **Choose your work addition method:** * **Create new work items:** Build tasks specifically for this cycle. * **Add existing work items:** Move work from backlog into the cycle. 3. **Start with appropriate scope:** * **New team:** 3-5 work items to build confidence. * **Experienced team:** 5-8 work items based on past velocity. * **Solo work:** 2-4 work items for manageable focus. 4. **Plan for success:** * **Under-commit and over-deliver** rather than consistently missing deadlines. * Choose work that can realistically be completed in the timeframe. * Leave buffer time for unexpected challenges or scope changes. * You can always add more items if you finish early. ## Track cycle progress Once your cycle is active with work items, monitor progress regularly to ensure successful delivery and continuous improvement. ![Cycle progress tracking](https://media.docs.plane.so/tutorials/view-cycle-progress.webp#hero) 1. **Monitor key metrics on the cycle detail page** * **Completion percentage:** How much work is done * **Burn-down chart:** Work remaining over time * **Work item breakdown:** Status distribution (pending, started, completed) 2. **Establish daily check-in routine** * See which work items need attention * Identify blockers or delays early * Adjust scope if needed (move items out rather than extending deadlines) * Celebrate completed work to maintain momentum 3. **Build team velocity insights** * How much work your team can realistically complete * Which types of work take longer than expected * When to adjust cycle length or team capacity * What external factors affect team productivity You can interpret cycle progress metrics and use them to make informed decisions about scope and timeline. ## Complete cycles effectively Finish cycles with clear outcomes and learning for future improvement. 1. **Focus on delivery as deadlines approach** * **Prioritize completion** over starting new work items. * **Move incomplete work** to the next cycle or back to backlog. * **Avoid scope creep** by resisting urge to add last-minute work. 2. **Conduct cycle review** * **Completed work items:** What the team delivered successfully * **Incomplete items:** What needs to carry over and why * **Lessons learned:** What worked well and what needs improvement 3. **Extract actionable insights** * **Velocity calibration:** Adjust work estimates for next cycle * **Process improvements:** Address recurring blockers or inefficiencies * **Team capacity:** Better understand realistic commitments * **Scope management:** Improve work breakdown and estimation You've created your first cycle and learned the fundamentals of time-boxed work planning. This approach helps teams deliver consistently and makes progress visible to everyone. ## What's next? Your cycle planning skills are established! You're ready to: * [Create content with Pages](/introduction/tutorials/create-pages) for documentation, meeting notes, and other project requirements. --- --- url: 'https://docs.plane.so/introduction/tutorials/create-pages.html' description: >- Learn to create documentation, meeting notes, and project requirements using Plane's built-in rich text editor with blocks and formatting options. --- # Write content with pages Learn to create and share documentation, meeting notes, and project requirements using Plane's powerful Pages. You'll master the basics of content creation, formatting, and sharing in just a few minutes. By the end of this tutorial, you'll: * Create and customize pages in your project * Use editor blocks to structure content effectively * Share pages with your team * Configure page settings for different use cases ## Create your first page Start by creating a new page in your project. ![Create new page](https://media.docs.plane.so/tutorials/create-page.webp#hero) 1. In your sidebar, click **Pages** under your project name. 2. Notice the three tabs: **Public**, **Private**, and **Archived**. By default, all pages you create are Public - meaning other project members can view and edit them. 3. Click **Add page** in the top-right corner. A new untitled page opens in the editor 4. Click the icon placeholder next to "Untitled" to choose an icon. 5. Click on "Untitled" and replace with `Project Requirements Document`. The page automatically saves your changes. ## Add content using editor blocks Learn to structure your content with Plane's powerful block-based editor. ![Editor blocks](https://media.docs.plane.so/tutorials/editor-blocks.webp#hero) ### Use the slash command 1. Click in the content area below your title. 2. Type `/` to open the blocks menu. Browse available content types. 3. Try these essential blocks: * Type `/h1` then "Project Overview" for a main heading. * Type `/bullet` to create a bulleted list of requirements. * Type `/todo` to add checkable task items. * Type `/h2` then "Timeline" for a subheading. ### Format your content ![Format content](https://media.docs.plane.so/tutorials/format-content.webp#hero) 1. Select text to see formatting options or use the formatting toolbar at the top for all styling options. 2. Add links by selecting text and using the link option. 3. Create a complete document structure: ``` # Project Requirements Document ## Project Overview Brief description of project goals and scope. ## Key Requirements • Requirement 1 • Requirement 2 • Requirement 3 ## Action Items ☐ Task 1 ☐ Task 2 ☐ Task 3 ``` ::: tip Explore all available editor blocks in our complete editor blocks [reference guide](/core-concepts/pages/editor-blocks). ::: ## Page options ![Page settings menu](https://media.docs.plane.so/tutorials/page-options.webp#hero) ### Get shareable link * Click the link icon in the top toolbar * The page URL is copied to your clipboard * Paste this link in Slack, email, or anywhere you want to share the page * Anyone with project access can view the page using this link ### Configure page options 1. Click the three dots (...) on the top right corner of your page. 2. Review available configuration options. Key settings to know: * **Full width:** Toggle on for wider content display (useful for tables and large content) * **Make private:** Restrict page access to specific team members (advanced sharing options available) * **Make a copy:** Duplicate page for templates or variations --- --- url: 'https://docs.plane.so/core-concepts/workspaces/overview.html' description: Create and manage Workspaces in Plane. --- # Manage workspace Think of a Workspace in Plane as your command center, the place where everything comes together. It’s the top-level space that holds all your projects, work items, cycles, modules, and pages. The workspace is where your team gathers to work on projects, track progress, and get things done. You can create your own projects, invite others to join, and collaborate as a group, or just do your own thing if that’s how you roll. ## What's inside a workspace Every workspace in Plane has two main components: * **Projects**\ Projects serve as the cornerstone for all activities within the product. You can create work items, assign tasks to members, and track progress for whatever you’re working on. If you envision your organization as NASA, each mission can be likened to a project. [Learn more here](/core-concepts/projects/overview). * **Members**\ Invite your teammates, collaborators, or managers to join your workspace. Each user gets a role, like Admin, Member, or Guest, to control what they can do. [Explore roles here](/roles-and-permissions/member-roles). ## Create workspace **First-time setup**\ When you first sign up for Plane, you'll create your workspace during onboarding. **Create additional workspaces** 1. Click your workspace name in the top-left corner of the sidebar. 2. Select **Create workspace** from the dropdown menu. 3. Enter your workspace name and URL slug. 4. Click **Create**. ![Create workspace](https://media.docs.plane.so/workspaces/workspace-creation-form.webp#hero) ::: info Workspace URL Each workspace gets a unique URL (slug). You can have duplicate workspace names, but URLs must be unique. ::: ## Join an existing workspace If you are a team member or contributor and are invited to a workspace, you don’t need to create your own. Just accept the invitation through: **Email invitation**\ Click the invitation link in the email you received. **Workspace invites page** 1. Click your workspace name in the top-left corner. 2. Select **Workspace invites** from the dropdown menu. 3. View pending invitations. 4. Click Accept on the workspace you want to join. ## Access workspace settings 1. Click your workspace name in the top-left corner. 2. Select **Settings** from the dropdown menu. ![workspace-settings](https://media.docs.plane.so/workspaces/workspace-settings.webp#hero-tl) From workspace settings, you can: * Manage workspace members and roles * Configure integrations * Import or export data * Manage workspace settings ## Switch between workspaces If you belong to multiple workspaces: 1. Click your current workspace name in the top-left corner. 2. Select a different workspace from the dropdown menu. All your workspaces must be associated with the same email address. ## Delete workspace Workspace admins are the only ones who can delete a workspace. ::: warning Deleting a workspace permanently removes all data including projects, work items, cycles, modules, and pages. Plane does not provide automatic backups. Export any important data before deleting. ::: 1. Navigate to **Workspace settings**. 2. In the **General** tab, scroll to the **Delete this workspace** section. 3. Confirm the deletion. --- --- url: 'https://docs.plane.so/core-concepts/workspaces/members.html' description: 'Add, update, and remove workspace members' --- # Manage workspace members Manage who can access your workspace and what they can do. This guide covers inviting members, importing them in bulk, changing roles, removing members, and viewing audit history. For background on the available roles, see [Member roles](/roles-and-permissions/member-roles). ## Invite members to your workspace You can add members individually or in bulk using CSV import. ![Invite user](https://media.docs.plane.so/workspaces/add-user.webp#hero) 1. Navigate to **Workspace settings → Members**. 2. Click **Add member**. 3. In the modal: * Enter the email address of the person you're inviting. * Select their role. * To invite multiple people at once, click **Add more** and repeat. 4. Click **Send invitations**. The invited person receives an email notification with instructions to join your workspace. **If the invitation isn't accepted:** * The invitation remains pending until accepted or declined. * You can manually remove pending invitations using the Remove option (see below). ## Import members from CSV Workspace admins can bulk invite members by importing a CSV file. This is useful when onboarding teams or migrating users from another system. ![Import members from CSV](https://media.docs.plane.so/workspaces/import-members.webp#hero) **To import members:** 1. Navigate to **Workspace settings → Members**. 2. Click **Import**. 3. Upload your CSV file (drag and drop or click to browse). 4. Select **Import** to bulk invite the members. Imported users are added directly to the workspace. **CSV format requirements** Your CSV must contain these columns in this exact order: ``` Email, Display Name, First Name, Last Name, Role ``` **Example CSV:** ``` Email,Display Name,First Name,Last Name,Role alex@company.com,Alex Chen,Alex,Chen,member sarah@company.com,Sarah Kim,Sarah,Kim,admin mike@company.com,Mike Rodriguez,Mike,Rodriguez,guest ``` **Valid roles:** * `owner` — Workspace Owner * `admin` — Workspace Admin * `member` — Workspace Member * `guest` — Workspace Guest ::: info Backward compatibility For backward compatibility, numeric role values still work: `5` for Guest, `15` for Member, `20` for Admin. We recommend using slugs. ::: **Important notes** * Only `.csv` files are supported. * Valid users appear immediately in the Members list after import. * Invalid entries are skipped (check your CSV for errors if some users don't appear). ::: warning Self-hosted Plane instance Ensure your SMTP server is properly configured to send invite emails successfully. See [Configure SMTP for email](https://developers.plane.so/self-hosting/govern/communication) for more information. ::: ## Change a member's role ![Update user role](https://media.docs.plane.so/workspaces/update-user.webp#hero-tr) 1. Navigate to **Workspace settings → Members**. 2. Find the member whose role you need to change. 3. Click the role dropdown next to their name. 4. Select the new role. The role change takes effect immediately. ## View workspace member activity Track member actions like invitations, role changes, and removals to maintain visibility over workspace management. ![Workspace member activity](https://media.docs.plane.so/workspaces/workspace-member-activity.webp#hero-bl) **To view member activity:** 1. Navigate to **Workspace settings → Members**. 2. Click **Activity** in the top right. The activity panel shows recent workspace member events: * **Member invitations** - Who invited which members and when * **Invitation acceptances** - When members accepted and joined the workspace * **Role changes** - Role updates with who made the change and when * **Member removals** - Who removed members from the workspace Each activity entry shows: * The action taken * Who performed the action * When it happened (relative time like "about 1 month ago" or "5 days ago") This audit trail helps workspace admins monitor membership changes and troubleshoot access issues. Activity is retained for workspace history and can be filtered by clicking on specific activity types. ## Remove a member from your workspace ![Remove user](https://media.docs.plane.so/workspaces/remove-user.webp#hero-bl) 1. Navigate to **Workspace settings → Members**. 2. Find the member you want to remove. 3. Click **Remove** next to their name. 4. Confirm the removal. The member loses access to the workspace and all its projects immediately. ::: warning Removing members doesn't change your seat count or billing. You must [remove seats](/workspaces-and-users/add-remove-seats#remove-unused-seats) separately. ::: ## Leave a workspace If you no longer need access to a workspace, you can leave it yourself. Click the … menu next to your own name in **Workspace settings → Members** and select **Leave**. You'll lose access to the workspace and all its projects immediately. If you need to rejoin later, a Workspace Admin or Owner will need to invite you again. ::: warning Last admin protection If you're the only Owner or Admin in the workspace, you cannot leave. Promote another user to Owner or Admin first. ::: ## See also * [Member roles](/roles-and-permissions/member-roles) * [Manage project members](/core-concepts/projects/manage-project-members) * [Permissions matrix](/roles-and-permissions/permissions-matrix) --- --- url: 'https://docs.plane.so/workspaces-and-users/search-workspace.html' description: 'Find work items, projects, pages, and other content across your workspace.' --- # Search workspace Use workspace search to quickly find work items, projects, cycles, modules, pages, and other content across your entire workspace. ## Open search Click the search icon (🔍) in the top navigation or press `Cmd/Ctrl + K`. ![Search workspace](https://media.docs.plane.so/workspaces/search-workspace.webp#hero-tr) ## How search works Type your query and results appear instantly, organized by type. Use the tabs at the top to filter results: * **All** - Shows everything across all categories * **Projects** - Your workspace projects * **Work items** - Work items across projects * **Cycles** - Project cycles * **Modules** - Project modules * **Views** - Saved views * **Pages** - Project pages * **Teamspaces** - Teamspaces * **Comments** - Work item comments Each tab shows the number of matching results ## Find work items **By work item ID**\ Type the project identifier and number to jump directly to that work item. **By title or keywords**\ Search finds work items with matching text in their titles or descriptions. ## Find other content **Projects**\ Search by project name or identifier. **Cycles and modules**\ Search by cycle or module name. **Pages**\ Search page titles and content. **Work item comments**\ Search finds comments containing your keywords. ## What you can search Search looks through: * Work item titles and descriptions * Project names and identifiers * Cycle and module names * Page titles and content * Saved view names * Comment text * Teamspace names **Search features:** * **Real-time results** - Updates as you type * **Partial matching** - "dev" finds "development" * **Case insensitive** - Capitalization doesn't matter ## What you won't see Search only shows content you have permission to access: * Private projects you're not a member of won't appear * Archived and deleted items are hidden * Work items from projects you can't access are filtered out This keeps your search results relevant and maintains project security. ## See also * [Power K](/core-concepts/power-k) --- --- url: 'https://docs.plane.so/core-concepts/account/overview.html' description: >- Customize your Home page with quick links, recent activity, and sticky notes to create a personalized dashboard for improved productivity. --- # Personalize homepage The Home page serves as your personalized page, giving you quick access to essential tools, recent activity, and key features to enhance productivity. Here's everything you need to know about setting up and using the Home page efficiently. ![Home](https://media.docs.plane.so/account/home-page.webp#hero) ### Manage widgets This section allows you to customize the visibility of different content areas on the Home page. You can choose to show or hide the **Quick links**, **Recents**, and **Your stickies** sections as per your preferences. This flexibility enables you to tailor the Home page to display only the information you find most relevant and useful. ### Add quick links Pin links to projects, pages, or external resources you frequently access. Save time by jumping directly to important destinations without navigating through menus. ### See recent visits This section helps you quickly pick up where you left off or revisit items you've recently worked on. You can customize the view to show specific types of activity, such as only recent work items or projects. ### Manage stickies Stickies allow you to create, organize, and personalize notes or reminders directly on your Home page: * Click **Add Sticky** to quickly jot down ideas, tasks, or important reminders. * Edit and modify your notes as needed. * Format the content and choose colors for your stickies to match your preferences or highlight priorities. * Keep all your notes in one easily accessible and visible place, ensuring nothing gets overlooked. ## See also * [Your work](/your-work) * [Stickies](/core-concepts/stickies) --- --- url: 'https://docs.plane.so/core-concepts/power-k.html' description: >- Use the Power K command palette to quickly search across projects, access settings, create new items, and navigate efficiently with keyboard shortcuts. --- # Power K ![](https://media.docs.plane.so/power-k/power-k1.webp#hero) ## The power of Power K ### Search * Remember just a few words from the titles of anything in Plane? Power-K it. As you start typing, work items, cycles, and modules from your project matching your search term will start showing up. ![](https://media.docs.plane.so/power-k/power-k2.webp#hero) * Expand the scope of this search to include projects in your workspace with just a toggle—powerful when you have several projects and are hunting a work item in all of them. ![](https://media.docs.plane.so/power-k/power-k3.webp#hero) ::: info 🎯 Roadmap item Search profiles, comments, and work item descriptions ::: ### Quick access * **Workspace and preference settings** Quickly toggle between light and dark mode or access workspace settings for APIs and Webhooks in just two clicks. ![](https://media.docs.plane.so/power-k/power-k4.webp#hero) * Keyboard shortcuts Get to your list of keyboard shortcuts with the Power K menu in two steps. ![](https://media.docs.plane.so/power-k/power-k5.webp#hero) * Documentation and Support Chat with us, see our docs, or report a bug—all from the Power K menu. ### Create * Create anything—projects, work items, cycles, modules, views, pages, and even workspaces, using Power K's create options. * Press ⌘ + K on a work item page to change states, priority, assignments or just to copy work item links. ![](https://media.docs.plane.so/power-k/power-k6.webp#hero) --- --- url: 'https://docs.plane.so/workspaces-and-users/customize-navigation.html' description: >- Personalize your Plane sidebar by showing or hiding sections. Customize your navigation to match your workflow. --- # Customize navigation Personalize your sidebar by choosing which items stay visible and how your project navigation is displayed. These settings are personal to you and won't affect anyone else in your workspace. ## Customize sidebar items Control which sections appear in your sidebar to streamline your navigation and focus on what matters most to you. ![Customize personal and workspace items](https://media.docs.plane.so/workspaces/customize-personal-and-workspace-items.webp#hero) To customize sidebar visibility: 1. Click the Filters icon in your sidebar. 2. Check the items you want to keep visible in your sidebar. 3. Uncheck items you'd prefer to access only from the More menu. 4. Drag items to reorder them. Selected items will always appear in your sidebar. Unchecked items can still be accessed from the More menu anytime. ## Project navigation style Choose how feature tabs appear within your projects: **Accordion navigation control** ![Accordion navigation style](https://media.docs.plane.so/workspaces/accordion-navigation-style.webp#hero) Feature tabs appear as nested items under each project in the sidebar and act as an accordion. When you expand one project, others automatically collapse. This works well when you focus on one project at a time and want a compact sidebar. **Horizontal navigation bar** ![Horizontal navigation bar](https://media.docs.plane.so/workspaces/horizontal-navigation-bar.webp#hero) Feature tabs appear as horizontal tabs inside the project view at the top of the page. This works well when you switch between different sections of the same project frequently and want quick access to all tabs. To change your project navigation: 1. Click the Filters icon in your sidebar. 2. Scroll to the **Projects** section. 3. Choose either **Accordion navigation control** or **Horizontal navigation bar**. ## Limit sidebar projects If you're a member of many projects, you can limit how many appear directly in your sidebar to keep it manageable. ![Limit sidebar projects](https://media.docs.plane.so/workspaces/limit-sidebar-projects.webp#hero) 1. In the Customize navigation settings, turn on **Show limited projects on sidebar**. 2. Enter the number of projects to display (e.g., 5). 3. Your most recently accessed projects will appear in the sidebar. 4. Access other projects through the ... More menu. This helps keep your sidebar focused on active projects while maintaining access to everything else. --- --- url: 'https://docs.plane.so/roles-and-permissions/overview.html' description: >- Understand how roles, permissions, and access control work in Plane — including system roles, custom roles, conditional grants, and how access is evaluated across workspaces, projects, and teamspaces. --- # Roles and permissions Plane uses a layered access control system to determine what every user can see and do. This page explains how that system works conceptually so you can design role assignments confidently. If you're looking for what a specific role can or can't do, see the [Permissions matrix](/roles-and-permissions/permissions-matrix). If you want a list of system roles, see [Member roles](/roles-and-permissions/member-roles). If you want to perform a task, see the how-to guides linked at the bottom of this page. ## Essential differences between RBAC and GAC RBAC is the default inside Plane. GAC lets you define roles with fine-grained permissions. **Role-Based Access Control (RBAC)**\ Every user holds a role—either a system-defined one like Owner, Admin, Member, Guest, Contributor, or Commenter or a [custom one](/roles-and-permissions/custom-roles)—and that role carries a defined set of permissions. All of our plans come with pre-set system-defined roles. **Granular Access Control (GAC)**\ GAC unlocks custom roles, each composed of one or more permission schemes. This lets you go beyond system-defined roles to create and control exactly what a role can and cannot do. :::tip Owner, Member, and Guest are available on all plans. Other system-defined roles are exclusive to the Business plan and higher. See [Plan availability](/roles-and-permissions/overview#plan-availability). ::: ## What changed from earlier versions Three things were renamed or restructured: * **"Workspace Admin" is now called "Workspace Owner."** * **"Project Member" is now called "Contributor."** * **"Guest view access to Guests" is now the Commenter role.** Previously, you toggled "Grant guest users view access to all the project work items" on a Guest. Now, instead of toggling, you assign the user the Commenter role. The role gives view access to project content plus the ability to add comments. If you've used Plane before, your existing assignments are mapped automatically — no action required. ## Scope hierarchy Plane's permission system operates at three scopes: ``` Workspace ├── Project │ ├── Work items, Modules, Cycles │ ├── Pages, Views, Intake │ └── Labels, States, Estimates, ... ├── Teamspace ──(grants access to)──► Project ├── Wiki, Initiatives, Releases, Dashboards └── Integrations, Webhooks, Analytics, ... ``` Permissions inherit upward. If a user has Admin on a project, they have access to everything inside that project. If a user has Admin on the workspace, they have access to all projects and their content. ## Roles, schemes, and how they fit together A **role** is what you assign to a user. A **permission scheme** is a named bundle of permissions that a role is built from. System roles ship with a single matching scheme — for example, the "Workspace Owner" role uses the "Workspace Owner" scheme. Custom roles can compose from one scheme or several. The role's effective permissions are the union of all schemes attached to it. This design exists so admins can build roles by combining focused, reusable scheme bundles rather than ticking hundreds of individual checkboxes for every role. ## Plan availability Different roles and capabilities are available on different plans. | Capability | Free | Pro | Business | Enterprise | | -------------------------------------------- | ---- | --- | -------- | ---------- | | Workspace Owner, Member, Guest | ✓ | ✓ | ✓ | ✓ | | Project Admin, Contributor, Commenter, Guest | ✓ | ✓ | ✓ | ✓ | | **Workspace Admin role** | — | — | ✓ | ✓ | | **Custom roles** | — | — | — | ✓ | | **Custom permission schemes** | — | — | — | ✓ | ## Conditional grants Some permissions only apply when a condition is met. The two conditions used in Plane are: * **Creator** — the user must have created the resource. A Contributor can delete work items they created, but not work items created by others. * **Lead** — the user must be the lead of the teamspace. A teamspace Member can edit teamspace settings only if they're the lead. When permissions combine, an unconditional grant always wins over a conditional one. If a user holds both `workitem:delete` and `workitem:delete+creator`, they can delete any work item — the unconditional grant takes effect and the condition is irrelevant. ## How permission checks work When a user attempts an action, the system evaluates access in a fixed order, starting at the most specific scope and walking upward. 1. **Role permissions** on this scope: * Unconditional match → allowed. * Conditional match → check the condition (creator, lead). If it's satisfied, allowed. 2. **Link relations** — does the user have access via a Teamspace linked to this project? 3. **Inherit from parent scope** — repeat the same checks one level up (project → workspace). 4. If nothing matched after walking the full chain → **denied by default**. A few worked examples make this concrete. **Can Bob edit work items?** Bob has the Contributor role on the project. The system finds Bob's Contributor role on the project, sees that Contributor includes `workitem:edit`, and allows the edit. **Can Carol delete modules?** Carol has the Contributor role on the project. Contributor has `module:delete+creator`. The system checks whether Carol created the module — if yes, allowed; if no, denied. **Can Dave (a workspace Admin with no project membership) view work items?** No project-level grant exists for Dave. The system walks up to the workspace, finds Dave's Admin role, which includes wildcard access to all project resource types, and allows the view. ## How workspace, project, and teamspace roles interact Permissions check from the most specific scope upward, which means workspace-level roles can grant project-level access without an explicit project membership. **Workspace Owners and Admins** have wildcard grants over all project resource types. They can access any project's content without being added to it explicitly. Removing a workspace Owner or Admin from a project has no functional effect — their workspace role still grants access via inheritance. **Auto-join role mapping.** When a workspace member joins a public project, their project role is derived from their workspace role: | Workspace role | → Project role | | --------------------- | -------------- | | Owner | Admin | | Admin | Admin | | Member or custom role | Contributor | | Guest | Guest | **Teamspace → project link relations.** A teamspace can be linked to one or more projects, and the link carries a role. All teamspace members get that role on the linked project without a separate project membership being created. A user can have both a direct project membership and teamspace-derived access — both are evaluated, and access resolves to whichever permits the action. **Guest ceiling.** Workspace Guests are restricted from receiving high-privilege project roles. When you add a workspace Guest to a project, you can only assign them the Guest or Commenter role — both default and custom project roles beyond these are blocked. Attempting to assign Admin, Contributor, or any custom project role returns an error. This prevents privilege escalation through project assignment. ## Caching and timing Permission decisions are cached per user for 5 minutes, and role definitions are cached for 24 hours. When an admin changes a user's role or modifies a role definition, the relevant caches are invalidated immediately. The user's next request fetches fresh permissions. ## Audit trail (coming soon) Every permission change is logged with the actor, the subject, the affected resource, the role before and after the change, and a timestamp. Role definition changes are tracked field by field, so you can see exactly which permission was added or removed and by whom. This audit trail is available to workspace admins for compliance reporting and access troubleshooting. ## Where to go next * For lookups about what a specific role can do, see the [Permissions matrix](/roles-and-permissions/permissions-matrix). * For the system role catalog, see [Member roles](/roles-and-permissions/member-roles). * To add and manage workspace members, see [Manage workspace members](/core-concepts/workspaces/members). * To add and manage project members, see [Manage project members](/core-concepts/projects/manage-project-members). * To create custom roles, see [Create custom roles](/roles-and-permissions/custom-roles). * To build reusable permission bundles, see [Create permission schemes](/roles-and-permissions/permission-schemes). --- --- url: 'https://docs.plane.so/roles-and-permissions/member-roles.html' description: >- Reference for every system role in Plane — Owner, Admin, Member, Guest at the workspace level, and Admin, Contributor, Commenter, Guest at the project level. Includes plan availability, role slugs, and guidance on when to use each. --- # Member roles Every user in Plane holds a role at the workspace level and, for each project they're added to, a role at the project level. This page is a reference for all system roles and what they're for. For the conceptual background, see [Roles and permissions](/roles-and-permissions/overview). For exhaustive permission breakdowns, see the [Permissions matrix](/roles-and-permissions/permissions-matrix). ## Workspace roles Workspace roles control access to workspace-level resources — settings, members, billing, integrations, the wiki, workspace views, initiatives, and the project list. They also determine what a user can do across the projects they're added to. ### Owner Owner is the highest workspace role. It carries full access to everything in the workspace, including the two operations no other role can perform: deleting the workspace and transferring ownership to another user. Use Owner for the founder or principal administrator of the workspace. Most workspaces only have one Owner. ::: info Renamed from "Admin" The role previously called "Admin" at the workspace level is now called "Owner." ::: ### Admin Admin gives full management of the workspace — settings, members, billing, projects, integrations, webhooks, and roles — without the ability to delete the workspace or transfer ownership. An Admin can access any project's content without being added as a project member. This is by design: workspace administrators sometimes need to step into a project to fix a misconfiguration or audit work, and forcing them to be added to every project would be impractical. Use Admin for technical leads, ops staff, or anyone who needs to administer the workspace without being its principal owner. ### Member Member is the standard role for internal contributors. A Member can view the workspace, browse the project list, create and contribute to wiki pages, create workspace views, view analytics, and use integrations. Members do not have access to project content unless they're explicitly added to a project. When they join a public project, they automatically become a Contributor on it. Use Member for full-time team members who actively work on projects. #### Let members create projects By default, only workspace owners and admins can create projects. Enabling this setting lets non-admin workspace members create projects directly. 1. Go to **Workspace Settings - Project states** 2. Find the toggle for "Let members create projects" 3. Toggle on or off 4. Click Save When enabled: * Workspace members see a "Create project" button in their projects view * Members can create projects with the same capabilities as admins * Members become project owners of projects they create When disabled: * Only workspace owners and admins can create projects * Members see no project creation option Only workspace owners and admins can change this setting. The change is recorded in [audit logs](/workspaces-and-users/audit-logs). ### Guest Guest is the most restricted workspace role. A Guest can only see projects they've been explicitly added to. When a workspace Guest is added to a project, they can only be assigned the Guest or Commenter role. They cannot be promoted to Contributor or Admin within a project. This guardrail prevents external collaborators from being accidentally over-privileged. Use Guest for clients, contractors, or external stakeholders who need restricted access to specific projects only. ## Project roles Project roles control what a user can do inside a specific project. ### Project Admin Project Admin has full control over the project — settings, members, work items, cycles, modules, pages, views, intake, automations, workflows, labels, states, and estimates. Project Admins can also delete or archive the project itself. Use Project Admin for project leads, managers, or anyone responsible for the project's setup and execution. ### Contributor Contributor is the standard project role for people doing the work. Contributors can create and edit work items, modules, cycles, pages, and views. They can delete content they created themselves, but not content created by others. They can add comments, attach files, log work, and add reactions. Contributors cannot manage project settings, change member roles, manage labels or states, or delete content created by others. ::: info Renamed from "Member" The role previously called "Member" at the project level is now called "Contributor." ::: Use Contributor for everyone who actively works on the project's content. ### Commenter Commenter can view all work items and add comments and reactions. They can also create Intake submissions. They cannot create or edit work items, modules, cycles, or pages. ::: info Replaces "Guest view access" Previously, a project Guest could be granted view access via a project-level toggle. That toggle no longer exists. To give someone view-only access to work items plus commenting, assign them the Commenter role. ::: Use Commenter for stakeholders who need to follow along, leave feedback, and submit intake requests, but shouldn't create or modify work. ### Guest Project Guest is the most restricted project role. They can submit intake forms and view, edit, and delete intake issues they created themselves. They cannot see or create work items in the project. Use Guest for external collaborators whose only interaction with the project is submitting requests through intake. ## Teamspace role Teamspaces have a single role, and conditions on the lead determine what each member can do beyond their own content. All teamspace members can view the teamspace and its pages, views, and comments. They can create new pages, views, and comments, and they can edit pages collaboratively. Each member can edit and delete their own comments and views. Only the **teamspace lead** can edit the teamspace's settings, delete the teamspace, manage its members, or delete content created by other members. ## When to use each role For workspace assignments: * **Owner** — the principal owner of the workspace. Reserve for one or two people. * **Admin** — anyone who needs to manage workspace settings, billing, integrations, members, or roles. * **Member** — internal contributors who do project work. * **Guest** — external clients, contractors, or stakeholders with project-specific access only. For project assignments: * **Admin** — project leads who own the project's setup and execution. * **Contributor** — anyone actively doing the work. * **Commenter** — stakeholders who need read access plus the ability to comment and submit intake. * **Guest** — external collaborators interacting only via intake. ## Role hierarchy Roles have an internal authority level used to enforce who can manage whom. A user can only modify members whose role level is lower than their own. * Only Owners can manage other Owners. * Owners and Admins can manage Admins. * The last Admin or Owner of a workspace cannot leave or be demoted. * The last Admin of a project cannot leave. ## Custom roles Workspace owners and admins can create custom roles composed from any combination of permission schemes. Custom roles cannot include workspace deletion or ownership transfer (those are reserved for Owner). For details, see [Create custom roles](/roles-and-permissions/custom-roles). ## Paid seat classification Most workspace roles count as paid seats for billing purposes. Workspace Guest is the only role that does not. | Role | Counts as paid seat | | ------------ | ------------------- | | Owner | Yes | | Admin | Yes | | Member | Yes | | Guest | No | | Custom roles | Yes | ## See also * [Roles and permissions](/roles-and-permissions/overview) * [Permissions matrix](/roles-and-permissions/permissions-matrix) * [Manage workspace members](/core-concepts/workspaces/members) * [Manage project members](/core-concepts/projects/manage-project-members) --- --- url: 'https://docs.plane.so/roles-and-permissions/permission-schemes.html' description: >- Build reusable permission bundles that can be combined to compose custom roles. Permission schemes group related permissions so you can manage access in modular pieces. --- # Permission schemes A **permission scheme** is a named bundle of permissions that you can attach to one or more custom roles. Schemes are the modular building blocks of custom roles — instead of defining every permission individually for each role, you create reusable schemes and combine them. For background, see [Roles and permissions](/roles-and-permissions/overview). To create roles that use schemes, see [Create custom roles](/roles-and-permissions/custom-roles). ## Why use permission schemes Permission schemes give you three advantages: * **Reuse.** The same scheme can power multiple roles. Update the scheme once, and every role using it picks up the change. * **Modularity.** Build focused schemes that do one thing well, then combine them. A "Release Manager" role might combine **Project Contributor** + a custom **Release Publishing** scheme. * **Clarity.** Schemes have descriptive names and clear scopes, making role definitions easier to read and audit. ![Custom permission schemes](https://media.docs.plane.so/roles-and-permissions/workspace-custom-permission-scheme.webp#hero) ## Create a workspace permission scheme Workspace schemes contain permissions that apply at the workspace level. 1. Navigate to **Workspace settings > Roles and permissions schemes > Workspace**. 2. Click the **Permission Schemes** tab. 3. Click **Create Permission Scheme** in the top right. 4. In the **Create permission scheme** form: * **Scheme name** — a short, descriptive name. * **Description** — optional explanation of the scheme's purpose. 5. In the permissions section, check the boxes for the permissions this scheme should grant. 6. Use **Select All** within a group to enable every permission in that group, or **Search permissions** at the top to find specific permissions. 7. Click **Create permission scheme**. The scheme is saved and immediately available to attach to roles. ## Create a project permission scheme Project schemes contain permissions that apply within projects. 1. Navigate to **Workspace settings > Roles and permissions schemes > Project**. 2. Click the **Permission Schemes** tab. 3. Click **Create Permission Scheme**. 4. Fill in the scheme name and description. 5. Select permissions from the project-level groups. 6. Click **Create permission scheme**. ## Edit a permission scheme 1. Navigate to the **Permission Schemes** tab. 2. Click the **…** menu next to the scheme. 3. Select **Edit permission scheme**. 4. Update the name, description, or selected permissions. 5. Save your changes. ::: warning Changes propagate to roles Editing a scheme immediately updates the effective permissions of every role that has it attached. Members assigned those roles will have their permissions refreshed on their next request. ::: ## Delete a permission scheme 1. Click the **…** menu next to the scheme. 2. Select **Delete permission scheme**. 3. Confirm. ::: warning Schemes attached to roles Deleting a scheme removes its permissions from any role using it. If a role had that scheme as its only source of permissions, the role will be left with no effective permissions until you attach another scheme. ::: ::: info System schemes can't be deleted System schemes (e.g., **Workspace Owner**, **Workspace Admin**, **Workspace Member**, **Workspace Guest**) are tagged "System" and cannot be edited or deleted. ::: ## Attach a scheme to a role 1. Open the role from the **Roles** tab. 2. In the **Permissions Schemes** section, click **Attach Permissions Schemes**. 3. Check the schemes you want to attach. 4. Click **Add**. The role's effective permissions become the union of all attached schemes. ## How permissions combine When a role has multiple schemes attached, the effective permission set is the union of all of them. The combination rules are: * **Unconditional grants win over conditional ones.** If one scheme grants `workitem:delete` and another grants `workitem:delete+creator`, the role gets unconditional `workitem:delete`. * **More permissive wins.** If schemes grant the same permission, it's still granted. Scheme combination is union-only — you cannot subtract permissions by adding another scheme. * **Permission dependencies are auto-managed.** Enabling a permission auto-enables its prerequisites (e.g., enabling Edit auto-enables View). Disabling a prerequisite auto-disables permissions that depend on it. ## See also * [Create custom roles](/roles-and-permissions/custom-roles) * [Roles and permissions](/roles-and-permissions/overview) * [Permissions matrix](/roles-and-permissions/permissions-matrix) --- --- url: 'https://docs.plane.so/roles-and-permissions/custom-roles.html' description: >- Create custom workspace and project roles tailored to your organization. Compose roles from permission schemes, base them on system roles, and assign them to members. --- # Custom roles Custom roles let you define exactly what users in your workspace can do. Build a "Release Manager" role that can publish but not delete, a "QA Reviewer" who can comment and edit but not create, or anything else your organization needs. For background, see [Roles and permissions](/roles-and-permissions/overview). To understand permission schemes (the building blocks of custom roles), see [Create permission schemes](/roles-and-permissions/permission-schemes). ![Custom roles](https://media.docs.plane.so/roles-and-permissions/workspace-custom-role.webp#hero) ## Create a custom workspace role Custom workspace roles control access to workspace-level resources — settings, members, integrations, the wiki, and more. 1. Navigate to **Workspace settings > Roles and permissions schemes > Workspace**. 2. Click the **Roles** tab. 3. Click **Create Role** in the top right. 4. In the **Create new role** modal: * Enter a **Role title** (e.g., "Billing Administrator"). * Add an optional **Description** to clarify the role's purpose. 5. Click **Create role**. The role is created with no permissions attached. You'll be taken to the role's detail page where you can attach permission schemes. ## Create a custom project role Custom project roles control access within projects. 1. Navigate to **Workspace settings > Roles and permissions schemes > Project** 2. Click the **Roles** tab. 3. Click **Create Role**. 4. Enter the **Role title** and **Description**. 5. Click **Create role**. ## Attach permission schemes to a role A role's effective permissions are the combined set of all schemes attached to it. 1. Open the role from the **Roles** tab. 2. In the **Permissions Schemes** section, click **Attach Permissions Schemes**. 3. Select one or more schemes from the right-hand panel: * System schemes (e.g., **Workspace Member**, **Workspace Admin**, **Project Contributor**) come pre-built and cannot be modified. * Custom schemes can be created and edited — see [Create permission schemes](/roles-and-permissions/permission-schemes). 4. Click **Add**. The role now has all permissions from the selected schemes. If a scheme grants `workitem:edit` and another scheme grants `workitem:edit+creator`, the unconditional permission wins — the role can edit any work item. ## Edit a custom role 1. Navigate to **Workspace settings > Workspace** or **Project** under **Roles And Permissions Schemes**. 2. Click the **…** menu next to the role. 3. Select **Edit role**. 4. Update the title, description, or attached permission schemes. Changes take effect immediately for all members assigned the role. ## Delete a custom role 1. Click the **…** menu next to the role. 2. Select **Delete role**. 3. If members are assigned the role, you'll be prompted to choose a replacement role. All affected members will be reassigned to the replacement. 4. Confirm. ::: warning System roles can't be deleted System roles (Owner, Admin, Member, Guest, Contributor, Commenter) cannot be deleted. ::: ## Constraints on custom roles A few rules govern what custom roles can and cannot do: * **Cannot include reserved permissions.** Custom roles cannot grant **Delete Workspace**, **Transfer Ownership**, or full access. These are reserved for the Owner role. * **Workspace-scoped.** Custom roles are defined per workspace. They don't propagate to other workspaces. * **Counted as paid seats.** Members assigned custom roles count as paid seats for billing. ## Base a custom role on a system role A common pattern is to create a custom role that's "system role X plus extra permissions." For example, a "Senior Contributor" role that has all Contributor permissions plus the ability to manage labels and states. 1. Create the new role with a title and description. 2. Attach the system permission scheme (e.g., **Project Contributor**) to inherit those permissions. 3. Create or attach a custom scheme that adds the extra permissions you want. ::: info The custom role inherits the system scheme's permissions at the moment of attachment. If the system scheme changes later, your custom role automatically reflects the changes (since it references the same scheme). ::: ## See also * [Create permission schemes](/roles-and-permissions/permission-schemes) * [Roles and permissions](/roles-and-permissions/overview) * [Permissions matrix](/roles-and-permissions/permissions-matrix) --- --- url: 'https://docs.plane.so/roles-and-permissions/permissions-matrix.html' description: >- Complete permissions reference for every role in Plane. Organized by the same permission groups used in the role builder so you can compare exactly what each role can and can't do. --- # Permissions matrix This is the exhaustive permissions reference for every system-defined role in Plane. For conceptual background, see [Roles and permissions](/roles-and-permissions/overview). For the role catalog, see [Member roles](/roles-and-permissions/member-roles). Plane has two sets of roles: workspace roles that control what someone can do across the entire workspace, and project roles that control what they can do inside a specific project. A person's project role is independent of their workspace role — you can be a workspace Member but a project Admin. ## Symbols used on this page * ✓ - Permitted for any item * Own - Permitted only on items the user created (creator condition) * Lead - Permitted only when the user holds the Lead designation in that teamspace * — - Not permitted * \* - All actions permitted (wildcard grant in permission scheme) ## Workspace permissions > **Owner and Admin bypass:** Workspace Owners have unconditional full access. Workspace Admins have full access to all workspace resources and all project resources — without needing project membership. ### Workspace settings | Permission | Owner | Admin | Member | Guest | | ----------------------- | :---: | :---: | :----: | :---: | | View workspace settings | ✓ | ✓ | ✓ | ✓ | | Edit workspace settings | ✓ | ✓ | — | — | | Delete workspace | ✓ | — | — | — | | Transfer ownership | ✓ | — | — | — | ### Workspace members | Permission | Owner | Admin | Member | Guest | | -------------------------- | :---: | :---: | :----: | :---: | | View member list | ✓ | ✓ | ✓ | ✓ | | Invite by email | ✓ | ✓ | — | — | | Import members (CSV / SSO) | ✓ | ✓ | — | — | | Change a member's role | ✓ | ✓ | — | — | | Assign Owner role | ✓ | — | — | — | | Assign Admin role | ✓ | ✓ | — | — | | Remove a member | ✓ | ✓ | — | — | ### Custom Roles Custom roles are workspace-defined role definitions extending the base system roles. | Permission | Owner | Admin | Member | Guest | | -------------------- | :---: | :---: | :----: | :---: | | View custom roles | ✓ | ✓ | — | — | | Create a custom role | ✓ | ✓ | — | — | | Edit a custom role | ✓ | ✓ | — | — | | Delete a custom role | ✓ | ✓ | — | — | ### Projects (Workspace-level management) This covers project creation, discovery, and admin operations from the workspace level. For content access inside a project, see [Project permissions](#project-permissions). | Permission | Owner | Admin | Member | Guest | | ----------------------------- | :---: | :---: | :----: | :---: | | Browse / list all projects | ✓ | ✓ | ✓ | — | | Create a project | ✓ | ✓ | — | — | | Self-join a public project | ✓ | ✓ | ✓ | — | | Self-join a private project | ✓ | ✓ | — | — | | Edit project settings | ✓ | ✓ | — | — | | Archive a project | ✓ | ✓ | — | — | | Delete a project | ✓ | ✓ | — | — | | Publish project (make public) | ✓ | ✓ | — | — | > Workspace Owners and Admins have full access to all project content without needing explicit project membership. **Auto-join project role mapping** (when a workspace member self-joins a project): | Workspace role | Project role assigned | | -------------- | --------------------- | | Owner | Admin | | Admin | Admin | | Member | Contributor | | Guest | — (cannot self-join) | | Custom role | Contributor | ### Initiatives | Permission | Owner | Admin | Member | Guest | | -------------------------------- | :---: | :---: | :----: | :---: | | View initiatives | ✓ | ✓ | ✓ | — | | Create | ✓ | ✓ | — | — | | Edit | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | | React | ✓ | ✓ | ✓ | — | | Add / remove work items in scope | ✓ | ✓ | — | — | | Add / remove projects in scope | ✓ | ✓ | — | — | | Drag and drop (reorder) | ✓ | ✓ | — | — | #### Initiative links | Permission | Owner | Admin | Member | Guest | | ------------- | :---: | :---: | :----: | :---: | | View links | ✓ | ✓ | ✓ | — | | Add a link | ✓ | ✓ | — | — | | Edit a link | ✓ | ✓ | — | — | | Delete a link | ✓ | ✓ | — | — | #### Initiative attachments | Permission | Owner | Admin | Member | Guest | | --------------------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | ✓ | — | | Add attachment | ✓ | ✓ | — | — | | Edit attachment | ✓ | ✓ | — | — | | Delete any attachment | ✓ | ✓ | — | — | #### Initiative comments | Permission | Owner | Admin | Member | Guest | | ------------------ | :---: | :---: | :----: | :---: | | View comments | ✓ | ✓ | ✓ | — | | Create a comment | ✓ | ✓ | ✓ | — | | Edit own comment | ✓ | ✓ | Own | — | | Delete own comment | ✓ | ✓ | Own | — | | Delete any comment | ✓ | ✓ | — | — | | React to a comment | ✓ | ✓ | ✓ | — | #### Initiative updates | Permission | Owner | Admin | Member | Guest | | -------------------------- | :---: | :---: | :----: | :---: | | View updates | ✓ | ✓ | ✓ | — | | Create an update | ✓ | ✓ | — | — | | Edit an update | ✓ | ✓ | — | — | | Delete an update | ✓ | ✓ | — | — | | React to an update | ✓ | ✓ | ✓ | — | | Comment on an update | ✓ | ✓ | ✓ | — | | Edit own update comment | ✓ | ✓ | — | — | | Delete own update comment | ✓ | ✓ | — | — | | React to an update comment | ✓ | ✓ | ✓ | — | > Members can react and comment on initiative updates but cannot edit or delete those comments. ### Teamspaces (Workspace-level management) This covers workspace-admin operations over teamspaces. For actions taken by teamspace members inside a teamspace, see [Teamspace permissions](#teamspace-permissions). | Permission | Owner | Admin | Member | Guest | | ------------------------------- | :---: | :---: | :-----------: | :---: | | Browse / list teamspaces | ✓ | ✓ | — | — | | Create a teamspace | ✓ | ✓ | — | — | | View a teamspace | ✓ | ✓ | Members only¹ | — | | Edit teamspace settings | ✓ | ✓ | — | — | | Delete a teamspace | ✓ | ✓ | — | — | | Add members to teamspace | ✓ | ✓ | — | — | | Remove members from teamspace | ✓ | ✓ | — | — | | Assign Lead designation | ✓ | ✓ | — | — | | Link a project to teamspace | ✓ | ✓ | — | — | | Unlink a project from teamspace | ✓ | ✓ | — | — | > ¹ Workspace Members must be explicit teamspace members to view a teamspace's content. Owners and Admins bypass this. ### Wiki | Permission | Owner | Admin | Member | Guest | | -------------------------- | :---: | :---: | :----: | :---: | | View a page | ✓ | ✓ | ✓ | — | | Create a page | ✓ | ✓ | ✓ | — | | Edit a page | ✓ | ✓ | ✓ | — | | Lock / unlock a page | ✓ | ✓ | Own | — | | Make page public / private | ✓ | ✓ | Own | — | | Share a page | ✓ | ✓ | ✓ | — | | Archive a page | ✓ | ✓ | Own | — | | Restore a page | ✓ | ✓ | Own | — | | Duplicate a page | ✓ | ✓ | ✓ | — | | Delete a page | ✓ | ✓ | Own | — | | Move a page | ✓ | ✓ | Own | — | | Publish a page | ✓ | ✓ | Own | — | | Update page icon / logo | ✓ | ✓ | ✓ | — | | Export page | ✓ | ✓ | ✓ | — | | Favourite a page | ✓ | ✓ | ✓ | — | | Comment on a page | ✓ | ✓ | ✓ | — | | Restore from version | ✓ | ✓ | ✓ | — | > Commenting on workspace pages requires Owner or Admin. ### Wiki Collections | Permission | Owner | Admin | Member | Guest | | ------------------------------------------ | :---: | :---: | :----------------: | :---: | | **Collections** | | | | | | View public collections | ✓ | ✓ | ✓ | — | | View private collections | ✓ | ✓ | If invited¹ | — | | Create a public collection | ✓ | ✓ | ✓ | — | | Create a private collection | ✓ | ✓ | — | — | | Edit a collection (rename, icon) | ✓ | ✓ | Own | — | | Delete a collection | ✓ | ✓ | Own | — | | **Pages in a public collection** | | | | | | View pages | ✓ | ✓ | ✓ | — | | Create a new page | ✓ | ✓ | ✓ | — | | Add existing pages | ✓ | ✓ | ✓ | — | | Remove pages | ✓ | ✓ | ✓ | — | | Reorder pages | ✓ | ✓ | ✓ | — | | Move a page to another collection | ✓ | ✓ | ✓ | — | | **Pages in a private collection** | | | | | | View pages | ✓ | ✓ | If invited¹ | — | | Create a new page | ✓ | ✓ | Own or Edit² | — | | Add existing pages | ✓ | ✓ | Own or Edit³ | — | | Remove pages | ✓ | ✓ | Edit + page owner⁴ | — | | Reorder pages | ✓ | ✓ | Edit² | — | | Move a page out | ✓ | ✓ | Edit + page owner⁴ | — | | **Private collection - member management** | | | | | | View member list | ✓ | ✓ | If invited¹ | — | | Invite members | ✓ | ✓ | Own | — | | Change a member's access level | ✓ | ✓ | Own | — | | Remove a member | ✓ | ✓ | Own | — | ¹ Any membership level (View, Comment, or Edit) grants access.\ ² Must be collection owner, or have Edit-level membership.\ ³ Must be collection owner, or have Edit-level membership **and** own the root page being added.\ ⁴ Must have Edit-level membership **and** own the root page. ### Workspace Views | Permission | Owner | Admin | Member | Guest | | ------------------------ | :---: | :---: | :----: | :---: | | View all workspace views | ✓ | ✓ | ✓ | ✓¹ | | Create a view | ✓ | ✓ | ✓ | — | | Edit own view | ✓ | ✓ | Own | — | | Edit any view | ✓ | ✓ | — | — | | Delete own view | ✓ | ✓ | Own | — | | Delete any view | ✓ | ✓ | — | — | | Share / make public | ✓ | ✓ | — | — | | Publish externally | ✓ | ✓ | — | — | | Export | ✓ | ✓ | ✓ | — | | Favourite / pin | ✓ | ✓ | ✓ | — | > ¹ Guests can view workspace views but only see work items from projects they have explicit access to. ### Workspace Drafts | Permission | Owner | Admin | Member | Guest | | ------------------------------- | :---: | :---: | :----: | :---: | | View drafts | ✓ | ✓ | ✓ | — | | Create a draft | ✓ | ✓ | ✓ | — | | Edit a draft | ✓ | ✓ | ✓ | — | | Delete own draft | ✓ | ✓ | Own | — | | Delete any draft | ✓ | ✓ | — | — | | Duplicate a draft | ✓ | ✓ | ✓ | — | | Move draft to a project | ✓ | ✓ | ✓ | — | | Manage drafts (bulk operations) | ✓ | ✓ | ✓ | — | ### Releases | Permission | Owner | Admin | Member | Guest | | -------------------------------- | :---: | :---: | :----: | :---: | | View releases | ✓ | ✓ | ✓ | — | | Create a release | ✓ | ✓ | — | — | | Edit a release | ✓ | ✓ | — | — | | Delete a release | ✓ | ✓ | — | — | | Add work items to a release | ✓ | ✓ | — | — | | Remove work items from a release | ✓ | ✓ | — | — | | Add / edit / delete links | ✓ | ✓ | — | — | | Add attachment | ✓ | ✓ | — | — | | Delete attachment | ✓ | ✓ | — | — | | Edit changelog | ✓ | ✓ | — | — | | Manage tags | ✓ | ✓ | — | — | | Add a comment | ✓ | ✓ | — | — | | Edit own comment | ✓ | ✓ | — | — | | Delete own comment | ✓ | ✓ | — | — | | React to a comment | ✓ | ✓ | — | — | | View activity | ✓ | ✓ | ✓ | — | ### Customers | Permission | Owner | Admin | Member | Guest | | ----------------- | :---: | :---: | :----: | :---: | | View customers | ✓ | ✓ | — | — | | Create a customer | ✓ | ✓ | — | — | | Edit a customer | ✓ | ✓ | — | — | | Delete a customer | ✓ | ✓ | — | — | | Add attachment | ✓ | ✓ | — | — | | Delete attachment | ✓ | ✓ | — | — | ### Workspace Analytics | Permission | Owner | Admin | Member | Guest | | ------------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | ✓ | — | | Export | ✓ | ✓ | ✓ | — | | Apply filters | ✓ | ✓ | ✓ | — | ### Dashboards | Permission | Owner | Admin | Member | Guest | | ----------------------------------- | :---: | :---: | :----: | :---: | | View dashboards | ✓ | ✓ | ✓ | — | | Create a dashboard | ✓ | ✓ | — | — | | Edit a dashboard (rename, settings) | ✓ | ✓ | — | — | | Delete a dashboard | ✓ | ✓ | — | — | | Add a widget | ✓ | ✓ | — | — | | Edit a widget | ✓ | ✓ | — | — | | Delete a widget | ✓ | ✓ | — | — | | Rearrange widgets | ✓ | ✓ | — | — | | Apply quick filters (view only) | ✓ | ✓ | ✓ | — | | Favourite a dashboard | ✓ | ✓ | — | — | | Permission | Owner | Admin | Member | Guest | | ----------------------------------- | :---: | :---: | :----: | :---: | | View dashboards | ✓ | ✓ | ✓ | — | | Create a dashboard | ✓ | ✓ | ✓ | — | | Edit a dashboard (rename, settings) | ✓ | ✓ | Own | — | | Delete a dashboard | ✓ | ✓ | Own | — | | Add a widget | ✓ | ✓ | Own | — | | Edit a widget | ✓ | ✓ | Own | — | | Delete a widget | ✓ | ✓ | Own | — | | Rearrange widgets | ✓ | ✓ | Own | — | | Apply quick filters (view only) | ✓ | ✓ | ✓ | — | | Favourite a dashboard | ✓ | ✓ | ✓ | — | ### Worklogs | Permission | Owner | Admin | Member | Guest | | ---------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | ✓ | — | | Export | ✓ | ✓ | ✓ | — | ### Workspace Activity Logs Audit trail of all changes made across the workspace. | Permission | Owner | Admin | Member | Guest | | ------------------------- | :---: | :---: | :----: | :---: | | View workspace activity | ✓ | ✓ | ✓ | — | | Export workspace activity | ✓ | ✓ | ✓ | — | ### User Activity Logs Per-member activity history showing what a specific workspace member has done. | Permission | Owner | Admin | Member | Guest | | -------------------- | :---: | :---: | :----: | :---: | | View user activity | ✓ | ✓ | ✓ | — | | Export user activity | ✓ | ✓ | ✓ | — | ### Workspace Automations | Permission | Owner | Admin | Member | Guest | | ---------------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | — | — | | Create | ✓ | ✓ | — | — | | Edit | ✓ | ✓ | — | — | | Enable / disable | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | ### Workspace Assets Files and images uploaded at workspace scope (logos, avatars, rich-text embeds not tied to a specific project). | Permission | Owner | Admin | Member | Guest | | --------------- | :---: | :---: | :----: | :---: | | View / download | ✓ | ✓ | ✓ | ✓ | | Upload | ✓ | ✓ | ✓ | — | | Edit | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | | Manage (bulk) | ✓ | ✓ | — | — | ### Workspace Project States Workspace-level project status definitions used for project grouping (Enterprise). | Permission | Owner | Admin | Member | Guest | | ---------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | ✓ | ✓ | | Create | ✓ | ✓ | ✓ | — | | Edit | ✓ | ✓ | ✓ | — | | Delete | ✓ | ✓ | ✓ | — | ### Workspace Features Controls for toggling workspace-level features on or off. | Permission | Owner | Admin | Member | Guest | | ------------------------- | :---: | :---: | :----: | :---: | | View feature settings | ✓ | ✓ | — | — | | Enable / disable features | ✓ | ✓ | — | — | ### Workspace Work Item Types | Permission | Owner | Admin | Member | Guest | | ---------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | — | — | | Create | ✓ | ✓ | — | — | | Edit | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | ### Workspace Custom Properties | Permission | Owner | Admin | Member | Guest | | ---------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | — | — | | Create | ✓ | ✓ | — | — | | Edit | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | ### Custom Relations | Permission | Owner | Admin | Member | Guest | | ---------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | ✓ | ✓ | | Create | ✓ | ✓ | ✓ | — | | Edit | ✓ | ✓ | ✓ | — | | Delete | ✓ | ✓ | ✓ | — | ### Favorites | Permission | Owner | Admin | Member | Guest | | ------------------------ | :---: | :---: | :----: | :---: | | View own favorites | ✓ | ✓ | ✓ | — | | Add a favorite | ✓ | ✓ | ✓ | — | | Edit (rename) a favorite | ✓ | ✓ | ✓ | — | | Remove a favorite | ✓ | ✓ | ✓ | — | ### Integrations Third-party integration connections (GitHub, Slack, Jira, Linear, etc.). | Permission | Owner | Admin | Member | Guest | | ------------------------------ | :---: | :---: | :----: | :---: | | View integrations | ✓ | ✓ | ✓ | — | | Connect an integration | ✓ | ✓ | — | — | | Configure an integration | ✓ | ✓ | — | — | | Disconnect an integration | ✓ | ✓ | — | — | | Admin-only operations (manage) | ✓ | ✓ | — | — | | Create integration | ✓ | ✓ | — | — | | Delete integration | ✓ | ✓ | — | — | ### Webhooks | Permission | Owner | Admin | Member | Guest | | ---------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | — | — | | Create | ✓ | ✓ | — | — | | Edit | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | ### Workspace API Tokens | Permission | Owner | Admin | Member | Guest | | ---------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | — | — | | Create | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | ### Billing | Permission | Owner | Admin | Member | Guest | | -------------- | :---: | :---: | :----: | :---: | | View billing | ✓ | ✓ | — | — | | Manage billing | ✓ | ✓ | — | — | ### Plane AI | Permission | Owner | Admin | Member | Guest | | --------------- | :---: | :---: | :----: | :---: | | Use AI features | ✓ | ✓ | ✓ | — | ### Work Item Templates | Permission | Owner | Admin | Member | Guest | | ---------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | — | — | | Create | ✓ | ✓ | — | — | | Edit | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | ### Page Templates | Permission | Owner | Admin | Member | Guest | | ---------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | — | — | | Create | ✓ | ✓ | — | — | | Edit | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | ### Project Templates | Permission | Owner | Admin | Member | Guest | | ----------------------- | :---: | :---: | :----: | :---: | | View | ✓ | ✓ | — | — | | Use to create a project | ✓ | ✓ | ✓ | — | | Publish | ✓ | ✓ | — | — | | Create | ✓ | ✓ | — | — | | Edit | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | ## Project permissions > **Workspace Owner / Admin bypass:** Workspace Owners and Admins have full access to all content in every project in their workspace without holding explicit project membership. ### Project Settings | Permission | Admin | Contributor | Commenter | Guest | | ----------------------------- | :---: | :---------: | :-------: | :---: | | View project settings | ✓ | ✓ | ✓ | ✓ | | Edit project settings | ✓ | — | — | — | | Archive project | ✓ | — | — | — | | Restore project | ✓ | — | — | — | | Delete project | ✓ | — | — | — | | Publish project (make public) | ✓ | — | — | — | ### Project Members | Permission | Admin | Contributor | Commenter | Guest | | -------------------------------- | :---: | :---------: | :-------: | :---: | | View member list | ✓ | ✓ | ✓ | ✓ | | Invite by email | ✓ | — | — | — | | Invite existing workspace member | ✓ | — | — | — | | Change a member's role | ✓ | — | — | — | | Remove a member | ✓ | — | — | — | | Leave project | ✓ | ✓ | ✓ | ✓ | ### Work Items #### Core actions | Permission | Admin | Contributor | Commenter | Guest | Notes | | ----------------------- | :---: | :---------: | :-------: | :---: | --------------------------------------- | | View work items | ✓ | ✓ | ✓ | Own | Guest: own intake submissions only | | Create a work item | ✓ | ✓ | — | — | | | Edit a work item | ✓ | ✓ | Own | Own | Blocked on archived items | | Delete a work item | ✓ | Own | Own | Own | | | Bulk edit | ✓ | ✓ | — | — | | | Assign to a user | ✓ | ✓ | — | — | | | Duplicate a work item | ✓ | ✓ | — | — | | | Archive a work item | ✓ | ✓ | — | — | | | Restore from archive | ✓ | ✓ | — | — | | | Export work items | ✓ | ✓ | — | — | | | Import work items | ✓ | — | — | — | | | Move to another project | ✓ | ✓¹ | — | — | ¹ Requires Contributor on both projects | | Mark as draft | ✓ | ✓ | — | — | | | React | ✓ | ✓ | ✓ | — | | | Subscribe / unsubscribe | ✓ | ✓ | Own | — | Tied to edit permission | | Vote | ✓ | ✓ | ✓ | — | | #### Property changes (all require edit permission) | Property | Admin | Contributor | Commenter | Guest | | --------------------------- | :---: | :---------: | :-------: | :---: | | State | ✓ | ✓ | — | — | | Priority | ✓ | ✓ | — | — | | Assignees | ✓ | ✓ | — | — | | Labels | ✓ | ✓ | — | — | | Work item type | ✓ | ✓ | — | — | | Parent (sub-task of) | ✓ | ✓ | — | — | | Start date | ✓ | ✓ | — | — | | Due date | ✓ | ✓ | — | — | | Estimate | ✓ | ✓ | — | — | | Cycle | ✓ | ✓ | — | — | | Module | ✓ | ✓ | — | — | | Milestone | ✓ | ✓ | — | — | | Drag and drop / reorder | ✓ | ✓ | — | — | | Restore description version | ✓ | ✓ | — | — | #### Conversion and structure | Permission | Admin | Contributor | Commenter | Guest | Notes | | --------------------- | :---: | :---------: | :-------: | :---: | ------------------------- | | Add sub-work item | ✓ | ✓ | — | — | Blocked on archived items | | Convert to sub-task | ✓ | ✓ | — | — | | | Switch work item type | ✓ | ✓ | — | — | Blocked on archived items | #### Work Item Relations | Permission | Admin | Contributor | Commenter | Guest | Notes | | ----------------- | :---: | :---------: | :-------: | :---: | ----- | | Add relation | ✓ | ✓ | — | — | | | Edit a relation | ✓ | ✓ | — | — | | | Remove a relation | ✓ | ✓ | — | — | | | View relations | ✓ | ✓ | ✓ | ✓ | | #### Work Item Links | Permission | Admin | Contributor | Commenter | Guest | Notes | | ------------- | :---: | :---------: | :-------: | :---: | ----- | | Add a link | ✓ | ✓ | — | — | | | Edit a link | ✓ | ✓ | — | — | | | Delete a link | ✓ | ✓ | — | — | | | View links | ✓ | ✓ | ✓ | — | | #### Work Item Attachments | Permission | Admin | Contributor | Commenter | Guest | Notes | | --------------------- | :---: | :---------: | :-------: | :---: | ---------------------- | | View attachments | ✓ | ✓ | ✓ | — | | | Add attachment | ✓ | ✓ | ✓ | — | Commenter: upload only | | Edit own attachment | ✓ | Own | — | — | | | Delete own attachment | ✓ | Own | — | — | | | Delete any attachment | ✓ | — | — | — | Admin only | #### Worklogs | Permission | Admin | Contributor | Commenter | Guest | Notes | | ----------------------- | :---: | :---------: | :-------: | :---: | ---------------------------- | | Log work (add work log) | ✓ | ✓ | — | — | Blocked on intake work items | | Edit own work log | ✓ | Own | — | — | | | Delete own work log | ✓ | Own | — | — | | ### Comments | Permission | Admin | Contributor | Commenter | Guest | Notes | | ------------------ | :---: | :---------: | :-------: | :---: | ------------------------------ | | Create comment | ✓ | ✓ | ✓ | — | Blocked on archived work items | | Edit own comment | ✓ | Own | Own | — | Blocked on archived work items | | Delete own comment | ✓ | Own | Own | — | Not blocked by archived status | | Delete any comment | ✓ | — | — | — | Admin only | | React to comment | ✓ | ✓ | ✓ | ✓ | | | Resolve a comment | ✓ | ✓ | ✓ | — | | ### Project Updates | Permission | Admin | Contributor | Commenter | Guest | | -------------------- | :---: | :---------: | :-------: | :---: | | View updates | ✓ | ✓ | ✓ | ✓ | | Create an update | ✓ | ✓ | — | — | | Edit own update | ✓ | Own | — | — | | Delete own update | ✓ | Own | — | — | | React to an update | ✓ | ✓ | ✓ | — | | Comment on an update | ✓ | ✓ | — | — | | Edit own comment | ✓ | Own | — | — | | Delete own comment | ✓ | Own | — | — | | React to a comment | ✓ | ✓ | ✓ | — | ### Cycles | Permission | Admin | Contributor | Commenter | Guest | | --------------------------------- | :---: | :---------: | :-------: | :---: | | View cycles | ✓ | ✓ | ✓ | — | | Create a cycle | ✓ | ✓ | — | — | | Edit a cycle | ✓ | ✓ | — | — | | Archive a cycle | ✓ | ✓ | — | — | | Restore (unarchive) | ✓ | ✓ | — | — | | Delete a cycle | ✓ | Own | — | — | | Manage cycle (admin operations) | ✓ | — | — | — | | Add work items to cycle | ✓ | ✓ | — | — | | Remove work items from cycle | ✓ | ✓ | — | — | | Transfer work items to next cycle | ✓ | ✓ | — | — | | Edit cycle filters | ✓ | ✓ | — | — | | Export cycle | ✓ | ✓ | — | — | | Favourite a cycle | ✓ | ✓ | ✓ | — | ### Modules | Permission | Admin | Contributor | Commenter | Guest | | -------------------------------- | :---: | :---------: | :-------: | :---: | | View modules | ✓ | ✓ | ✓ | — | | Create a module | ✓ | ✓ | — | — | | Edit a module | ✓ | ✓ | — | — | | Archive a module | ✓ | ✓ | — | — | | Restore (unarchive) | ✓ | ✓ | — | — | | Delete a module | ✓ | Own | — | — | | Manage module (admin operations) | ✓ | — | — | — | | Add work items to module | ✓ | ✓ | — | — | | Remove work items from module | ✓ | ✓ | — | — | | Add members to module | ✓ | ✓ | — | — | | Remove members from module | ✓ | ✓ | — | — | | Export module | ✓ | ✓ | — | — | ### Milestones | Permission | Admin | Contributor | Commenter | Guest | | -------------------------------- | :---: | :---------: | :-------: | :---: | | View milestones | ✓ | ✓ | ✓ | — | | Create a milestone | ✓ | ✓ | — | — | | Edit a milestone | ✓ | ✓ | — | — | | Delete a milestone | ✓ | ✓ | — | — | | Add work items to milestone | ✓ | ✓ | — | — | | Remove work items from milestone | ✓ | ✓ | — | — | ### Intake | Permission | Admin | Contributor | Commenter | Guest | Notes | | -------------------------------- | :---: | :---------: | :-------: | :---: | ------------------------------- | | Submit a new intake item | ✓ | ✓ | ✓ | ✓ | All roles can submit | | View all submissions | ✓ | ✓ | ✓ | Own | Guest: own only | | Edit own submission | ✓ | Own | Own | Own | | | Delete own submission | ✓ | Own | Own | Own | | | Add attachment to own submission | ✓ | Own | Own | Own | | | Accept a submission | ✓ | — | — | — | Only while in actionable status | | Decline a submission | ✓ | — | — | — | Only while in actionable status | | Snooze a submission | ✓ | — | — | — | | | Mark as duplicate | ✓ | — | — | — | | | Mark as spam | ✓ | — | — | — | | | React to a submission | ✓ | ✓ | ✓ | ✓ | | | Comment on a submission | ✓ | ✓ | ✓ | — | | | Export intake | ✓ | ✓ | — | — | | | Configure intake settings | ✓ | — | — | — | | | Manage intake | ✓ | — | — | — | | ### Pages | Permission | Admin | Contributor | Commenter | Guest | Notes | | -------------------------- | :---: | :---------: | :-------: | :---: | ---------------------------------------- | | View a page | ✓ | ✓ | ✓ | ✓ | Public pages viewable without role check | | Create a page | ✓ | ✓ | — | — | | | Edit page content / title | ✓ | ✓ | — | — | Blocked if archived or locked | | Lock a page | ✓ | ✓ | — | — | | | Unlock a page | ✓ | ✓ | — | — | | | Archive a page | ✓ | ✓ | — | — | | | Restore (unarchive) | ✓ | ✓ | — | — | | | Delete a page | ✓ | — | — | — | Admin only | | Duplicate a page | ✓ | ✓ | — | — | | | Make page public / private | ✓ | ✓ | — | — | | | Share page (publish link) | ✓ | Own | — | — | Contributor: own pages only | | Update page icon / logo | ✓ | ✓ | — | — | | | Move a page (reparent) | ✓ | ✓ | — | — | | | Favourite a page | ✓ | ✓ | — | — | | | Add comment on page | ✓ | ✓ | — | — | Uses page edit permission | | Export / download | ✓ | ✓ | ✓ | ✓ | Anyone who can view | ### Views | Permission | Admin | Contributor | Commenter | Guest | Notes | | ----------------------- | :---: | :---------: | :-------: | :---: | ------------------ | | View all views | ✓ | ✓ | ✓ | ✓ | | | Create a view | ✓ | ✓ | — | — | | | Edit own view | ✓ | Own | — | — | | | Edit any view | ✓ | — | — | — | Admin only | | Delete own view | ✓ | Own | — | — | | | Delete any view | ✓ | — | — | — | Admin only | | Share / make public | ✓ | Own | — | — | | | Publish externally | ✓ | Own | — | — | | | Export | ✓ | ✓ | — | — | | | Favourite / pin | ✓ | ✓ | ✓ | — | Personal favourite | | Configure views (admin) | ✓ | — | — | — | | ### States | Permission | Admin | Contributor | Commenter | Guest | | --------------- | :---: | :---------: | :-------: | :---: | | View | ✓ | ✓ | ✓ | ✓ | | Create | ✓ | — | — | — | | Edit | ✓ | — | — | — | | Delete | ✓ | — | — | — | | Reorder | ✓ | — | — | — | | Mark as default | ✓ | — | — | — | ### Labels | Permission | Admin | Contributor | Commenter | Guest | | ---------- | :---: | :---------: | :-------: | :---: | | View | ✓ | ✓ | ✓ | ✓ | | Create | ✓ | — | — | — | | Edit | ✓ | — | — | — | | Delete | ✓ | — | — | — | | Reorder | ✓ | — | — | — | ### Estimates | Permission | Admin | Contributor | Commenter | Guest | | ---------- | :---: | :---------: | :-------: | :---: | | View | ✓ | ✓ | ✓ | ✓ | | Create | ✓ | — | — | — | | Edit | ✓ | — | — | — | | Delete | ✓ | — | — | — | ### Workflows | Permission | Admin | Contributor | Commenter | Guest | | ---------------------- | :---: | :---------: | :-------: | :---: | | View | ✓ | ✓ | — | — | | Create / edit / delete | ✓ | — | — | — | | Manage | ✓ | — | — | — | ### Automations | Permission | Admin | Contributor | Commenter | Guest | | ---------------- | :---: | :---------: | :-------: | :---: | | View automations | ✓ | ✓ | — | — | | Create | ✓ | — | — | — | | Edit | ✓ | — | — | — | | Enable / disable | ✓ | — | — | — | | Delete | ✓ | — | — | — | | View run history | ✓ | ✓ | — | — | ### Recurring Work Items | Permission | Admin | Contributor | Commenter | Guest | | ---------- | :---: | :---------: | :-------: | :---: | | View | ✓ | ✓ | — | — | | Create | ✓ | ✓ | — | — | | Edit | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | ### Work Item Types and Custom Properties | Permission | Admin | Contributor | Commenter | Guest | | ---------- | :---: | :---------: | :-------: | :---: | | View | ✓ | ✓ | ✓ | — | | Create | ✓ | ✓ | — | — | | Edit | ✓ | ✓ | — | — | | Delete | ✓ | ✓ | — | — | ### Work Item Templates | Permission | Admin | Contributor | Commenter | Guest | | ---------- | :---: | :---------: | :-------: | :---: | | View | ✓ | ✓ | — | — | | Create | ✓ | — | — | — | | Edit | ✓ | — | — | — | | Delete | ✓ | — | — | — | ### Page Templates | Permission | Admin | Contributor | Commenter | Guest | | ---------- | :---: | :---------: | :-------: | :---: | | View | ✓ | ✓ | — | — | | Create | ✓ | — | — | — | | Edit | ✓ | — | — | — | | Delete | ✓ | — | — | — | ### Project Analytics | Permission | Admin | Contributor | Commenter | Guest | | ---------- | :---: | :---------: | :-------: | :---: | | View | ✓ | ✓ | ✓ | — | | Export | ✓ | ✓ | — | — | ### Project Links | Permission | Admin | Contributor | Commenter | Guest | | ------------- | :---: | :---------: | :-------: | :---: | | View | ✓ | ✓ | ✓ | — | | Add a link | ✓ | ✓ | — | — | | Edit a link | ✓ | ✓ | — | — | | Delete a link | ✓ | — | — | — | ### Project Assets Files and images uploaded within project scope — includes images embedded in pages or comments, and project-scoped uploads. Commenters can upload because they need to embed images in comments. | Permission | Admin | Contributor | Commenter | Guest | | ----------------- | :---: | :---------: | :-------: | :---: | | View / download | ✓ | ✓ | ✓ | ✓ | | Upload | ✓ | ✓ | ✓ | — | | Edit own upload | ✓ | Own | Own | — | | Delete own upload | ✓ | Own | Own | — | | Delete any upload | ✓ | — | — | — | ### Project Activity Logs Audit trail for all changes within the project. | Permission | Admin | Contributor | Commenter | Guest | | --------------------- | :---: | :---------: | :-------: | :---: | | View project activity | ✓ | ✓ | ✓ | ✓ | #### Project Member Activity Per-member activity scoped to this project — who changed what. | Permission | Admin | Contributor | Commenter | Guest | | -------------------- | :---: | :---------: | :-------: | :---: | | View member activity | ✓ | — | — | — | ## Teamspace Permissions > Workspace Owners and Admins have full access to all teamspace content without being teamspace members — they effectively hold wildcard grants on all teamspace resources.\ > Workspace Guests cannot be added to teamspaces. The tables below apply to users who are explicit **teamspace members**. Lead is a designation (condition), not a separate role level. ### Teamspace management (within a Teamspace) | Permission | Member | Lead | | ------------------------------------------------- | :----: | :--: | | View teamspace | ✓ | ✓ | | Edit teamspace settings (name, logo, description) | — | ✓ | | Delete teamspace | — | ✓ | | Manage teamspace | — | ✓ | | Add members | — | ✓ | | Remove members | — | ✓ | | Assign Lead designation | — | ✓ | | Link a project to teamspace | — | ✓ | | Unlink a project from teamspace | — | ✓ | | Create a work item in teamspace context | — | ✓ | ### Teamspace entity comments Comments posted directly on the teamspace entity (not on a page or view within it). | Permission | Member | Lead | Notes | | ------------------ | :----: | :--: | ----------------------------- | | View comments | ✓ | ✓ | Also: Workspace Owner / Admin | | Create a comment | ✓ | ✓ | | | Edit own comment | Own | Own | | | Delete own comment | Own | Own | | | Delete any comment | — | — | Workspace Owner / Admin only | | React to a comment | ✓ | ✓ | | ### Teamspace Views | Permission | Member | Lead | | ------------------------ | :----: | :--: | | View all teamspace views | ✓ | ✓ | | Create a view | ✓ | ✓ | | Edit own view | Own | Own | | Edit any view | — | ✓ | | Delete own view | Own | Own | | Delete any view | — | ✓ | | Favourite / pin a view | ✓ | ✓ | ### Teamspace Pages | Permission | Member | Lead | Notes | | -------------------------- | :----: | :--: | ----------------------------------------------- | | View a page | ✓ | ✓ | Private pages: owner + shared-access users only | | Create a page | ✓ | ✓ | | | Edit page content / title | ✓ | ✓ | Blocked if archived or locked | | Lock a page | ✓ | ✓ | | | Unlock a page | ✓ | ✓ | | | Duplicate a page | ✓ | ✓ | | | Move a page (reparent) | ✓ | ✓ | | | Update page icon / logo | ✓ | ✓ | | | Archive a page | Own | ✓ | Member: own pages only | | Restore (unarchive) | Own | ✓ | | | Delete a page | Own | ✓ | Member: own pages only | | Export / download | ✓ | ✓ | | | Favourite a page | ✓ | ✓ | | | Make page public / private | — | — | Not supported for teamspace pages | > Making a teamspace page public or private is hardcoded off — it is not a role restriction, the feature simply does not exist for teamspace pages. ### Teamspace Page Comments | Permission | Member | Lead | | ------------------ | :----: | :--: | | Create a comment | ✓ | ✓ | | Edit own comment | ✓ | ✓ | | Delete own comment | ✓ | ✓ | | Delete any comment | — | ✓ | | React to a comment | ✓ | ✓ | | Resolve a comment | ✓ | ✓ | ## See also * [Roles and permissions](/roles-and-permissions/overview) * [Member roles](/roles-and-permissions/member-roles) * [Manage workspace members](/core-concepts/workspaces/members) * [Manage project members](/core-concepts/projects/manage-project-members) * [Create custom roles](/roles-and-permissions/custom-roles) --- --- url: 'https://docs.plane.so/workspace-administration/workspace-governance.html' description: >- Centralize and standardize how projects are configured by managing states, workflows, work item types, and custom properties at the workspace level. --- # Workspace Governance Workspace governance lets workspace admins define shared configuration once, at the workspace level, and have every project use it. Instead of each project defining its own states, workflows, and work item types, governance centralizes these so your projects stay consistent and comply with a standard you control. When governance is on, workspace admins own the shared building blocks. Project admins can use those building blocks, but cannot create or modify them independently. :::danger Enabling governance is permanent Turning on workspace governance is a **one-way** change. It cannot be disabled or undone. Once enabled, project admins permanently lose the ability to create or edit states, workflows, work item types, templates, automations, and recurring work items inside their projects. Read this page in full before enabling. ::: ## What governance centralizes Enabling governance lifts all of the following from the project level to the workspace level. Each has its own detailed page: * [**States**](/core-concepts/issues/states) - the shared set of states for the whole workspace, including a single workspace triage state. * [**Workflows and approvals**](/workflows-and-approvals/workflows) - shared workflows that define how work items move between states. * [**Work item types and custom properties**](/work-items/workspace-work-item-types) - defined once and rolled out to projects. * [**Automations**](/automations/custom-automations#create-a-workspace-automation) - workspace-level automations. After governance is on, all of these are **workspace-managed**. Projects import and use them. ## How governance works Governance is a **binding layer**, not a copy and not a blanket override. This is the single most important thing to understand: * Workspace configuration is **not duplicated** into each project. Projects **reference** the shared workspace resources. * Governance does **not** force every project to look identical. It standardizes where you require it, and allows per-project flexibility where you permit it. * For workflows specifically, each project resolves an **effective workflow** for each work item type. The workspace controls how much freedom a project has over that choice. See [How projects use shared workflows](#how-projects-use-shared-workflows). ## Enable governance Governance moves through three states: **Disabled → Migration in progress → Enabled**. 1. Go to **Settings → Workspace Governance**. 2. Click **Enable governance**. 3. Step through the migration wizard. It has one step for each kind of configuration being centralized: **states, work item types, workflows, templates, automations, and recurring work items**. Each step shows a preview of what will be migrated so you can review before committing. 4. Confirm to start the migration. ### During migration While the migration runs, the workspace is temporarily **frozen for writes** so configuration can be moved safely and consistently. Requests to change configuration during this window are rejected until the migration completes. Do not plan configuration changes during the migration. ### After migration When the migration finishes, the governance page shows a summary: **Status** (Enabled), **Enabled on** (date), **Enabled by** (the admin), and **Entities migrated** (counts). :::warning The migration freeze makes the affected configuration temporarily read-only, and enabling cannot be reversed once it completes. Enable governance during a low-activity window. ::: ## What changes for projects after governance is on * Project admins can no longer **create or edit** states, workflows, work item types, templates, automations, or recurring work items inside a project. Editing one returns a "managed at the workspace level" error. * Projects **use** the workspace's shared configuration instead. * **New projects** created after governance is on automatically use the workspace's shared configuration, resolving to the workspace **default workflow** for each work item type unless the workspace mandates or pins a different one. * Work item types are enabled workspace-wide as part of governance. ## How projects use shared workflows You control how much choice a project has over which workflow applies to each work item type. This is set **per work item type**, using a **governance mode**: | Mode | What a project admin can do | | --------------- | -------------------------------------------------------------------------- | | **Any** | Choose any active workspace workflow for that work item type. | | **Constrained** | Choose only from an **allowlist** of workflows you define for that type. | | **Required** | No choice. The workspace mandates one workflow, and every project uses it. | ### Pins In **Any** or **Constrained** mode, you can **pin** a specific project to a specific workflow. This forces that one project's choice while leaving other projects free to choose. Pins are removed automatically if the type is later switched to Required. :::warning Setting a type to Required overrides all projects Switching a work item type to **Required** locks every project to the single mandated workflow. Any project currently using a different workflow is moved to the mandated one, and existing per-project pins for that type are removed. Preview the impact before switching. ::: ### Effective workflow resolution For any project and work item type, the workflow that actually applies (the **effective workflow**) is resolved in this order: 1. The project's **required** workflow, if the type is Required. 2. The project's **pin**, if one exists. 3. The project's **chosen** workflow (its pick), if set. 4. Otherwise, the **workspace default workflow**. The effective workflow determines the starting state, which states allow creation, and the allowed transitions for work items of that type in that project. ### The project admin's view From a project's work item type settings, a project admin sees, per type: a label showing whether the type is free to choose, **constrained** to an allowlist, **mandated** (required), or **pinned**; the current effective workflow and any workflows they may pick; and a **preview** of how existing work items would be remapped if they switch workflow, before applying the change. If a project admin tries to change a workflow they are not allowed to change, they get an error: the workflow is mandated by the workspace, assigned by the workspace (pinned), or outside the allowed list. :::warning Switching a workflow can move work items When a project's effective workflow changes, work items whose current state is not part of the new workflow are moved to a fallback state. Always review the preview before confirming a workflow change. ::: --- --- url: 'https://docs.plane.so/authentication/sso.html' description: >- Configure SAML or OIDC authentication to let your team sign in to Plane using corporate identity provider credentials. --- # Single sign-on (SSO) Single sign-on (SSO) lets your team sign in to Plane using your organization's identity provider instead of managing separate passwords. This centralizes authentication, improves security, and simplifies user management. ## Verify your domain Before configuring SSO, you must verify ownership of your organization's email domain. This ensures only authorized administrators can configure authentication for that domain. ::: warning Each domain can only be verified in one workspace at a time. If you've already verified a domain in another workspace, you'll need to remove it there first. ::: ### Add your domain 1. Navigate to **Workspace Settings → Identity**. 2. Under **Domain management**, click **Add domain**. ![Add domain](https://media.docs.plane.so/sso/add-domain.webp#hero-tl) 3. Enter your domain (for example, `acme.com`) and click Add domain. 4. In the **Verify your domain** modal that appears, copy the **TXT record value**. ![Verify domain](https://media.docs.plane.so/sso/verify-domain.webp#hero) ::: tip Click **I'll do it later** if you need time to access your DNS. Your domain will appear with a *Pending* status. To resume verification later, click the **⋯** menu next to your domain and select **Verify**. ::: ### Add the DNS record 1. Sign in to your DNS provider. 2. Create a new TXT record: * **Host/Name**: `@` (or leave blank for root domain). * **Value**: Paste the TXT record value from Plane. * **TTL**: Use default or 3600. 3. Wait a few minutes for DNS propagation. 4. Return to Plane and click **Verify domain**. Once verified, the status changes to *Verified* and you can configure SSO. ::: tip DNS propagation times vary by provider. If verification fails immediately, wait a few more minutes and try again. You can check if the TXT record is live using `dig TXT yourdomain.com` or online DNS lookup tools. ::: ## Configure SSO Plane supports two authentication protocols. Choose the one that matches your identity provider. ### OIDC (OpenID Connect) OIDC works best with modern cloud identity providers like Google Workspace, Auth0, Okta, and Keycloak. #### Get Plane connection details 1. Navigate to **Workspace Settings → Identity**. 2. Click **Configure** next to **Enable OIDC**. 3. Click **Get setup details** and copy these values: * **Origin URL** * **Redirect URL** * **Logout URL** You'll use these when configuring your IdP. #### Register Plane in your identity provider The exact steps vary by provider, but generally: 1. Sign in to your identity provider. 2. Create a new **Web Application** or **OIDC Client**. 3. Paste the **Redirect URL** from Plane into the redirect URI field. 4. Configure the application: * Application type: **Web Application**. * Enable authorization code flow. * Request scopes: `openid`, `email`, `profile`. 5. Save and note the **Client ID** and **Client Secret** your IdP generates. #### Configure OIDC in Plane ![Configure OIDC](https://media.docs.plane.so/sso/configure-oidc.webp#hero) 1. Return to Plane and enter the following details from your identity provider: | Field | Description | | ------------------- | ------------------------------------------------------------------ | | **Client ID** | The application ID from your IdP | | **Client secret** | The secret key for authentication | | **Authorize URL** | The endpoint where users see the login screen | | **Token URL** | The endpoint Plane uses to exchange authorization codes for tokens | | **Users' info URL** | The endpoint that returns user profile information | | **Logout URL** | *(Optional)* Where users go after signing out | 2. Click **Save changes** to activate OIDC authentication. ### SAML 2.0 SAML works well with traditional enterprise identity providers like Okta, Azure AD, and on-premise Active Directory. #### Get Plane connection details 1. Navigate to **Workspace Settings → Identity**. 2. Click **Configure** next to **Enable SAML**. 3. Click **Get setup details** and copy these values: * **Entity ID / Audience / Metadata information** * **SSO URL** * **SLO URL** #### Create a SAML application in your IdP 1. Sign in to your identity provider. 2. Create a new **SAML 2.0 Application**. 3. Configure the service provider settings: * **Entity ID / Audience**: Paste the Entity ID from Plane. * **ACS URL / SSO URL**: Paste the SSO URL from Plane. * **SLO URL**: Paste the SLO URL from Plane. 4. Configure attribute mapping to send the `email` attribute in the SAML assertion. Optionally map `firstName` and `lastName`. 5. Save and copy your IdP's SAML configuration: * **SSO URL** (sign-in endpoint) * **Entity ID** * **X.509 Certificate** #### Configure SAML in Plane ![Configure SAML](https://media.docs.plane.so/sso/configure-saml.webp#hero) 1. Return to Plane and enter the following details from your identity provider: | Field | Description | | --------------- | ----------------------------------------------------------- | | **Entity ID** | Your IdP's unique identifier | | **SSO URL** | The endpoint where Plane redirects users for authentication | | **Logout URL** | *(Optional)* Where users go after signing out | | **Certificate** | The X.509 certificate from your IdP | 2. Click **Configure and enable** to activate SAML authentication. ## How SSO works in Plane Once SSO is enabled: * When users visit your Plane workspace, they see the **Sign in with Single Sign-On** button. ![Sign in with SSO](https://media.docs.plane.so/sso/sign-in-with-sso.webp#hero) * Clicking it redirects them to your identity provider. * After authentication, they're signed in to Plane automatically. * Their Plane account is created automatically on first sign-in if it doesn't exist. --- --- url: 'https://docs.plane.so/authentication/group-sync.html' description: >- Automatically provision workspace roles, project memberships, and private collection access from your identity provider's groups. --- # IdP Group Sync :::info Availability Group syncing is currently available on the self-hosted Commercial and Airgapped Editions. ::: IdP Group Sync lets workspace admins map identity provider groups to access in Plane. When a user signs in through SSO, Plane reads the groups on their identity and automatically grants the matching access, then keeps it in sync as their group membership changes in your IdP. You can map groups to three things: * **Workspace roles** - the role a user gets in the workspace. * **Project access** - membership and role in specific projects, or in all projects. * **Private collection access** - view, comment, or edit access to private wiki collections. This removes manual onboarding and offboarding: access follows group membership in your identity provider. ## Supported providers Group sync works with all three SSO methods. One provider is active per workspace at a time. | Provider | Sync on login | Scheduled offline sync | | -------- | ------------- | ---------------------- | | **OIDC** | Yes | Yes | | **SAML** | Yes | No | | **LDAP** | Yes | Yes | SAML groups are only present in the login assertion, so SAML syncs at login only. It does not support the scheduled offline sync. OIDC and LDAP can fetch groups from the provider on a schedule as well as at login. ## Prerequisites * SSO configured and working with OIDC, SAML, or LDAP. * Your identity provider configured to send groups (as a claim for OIDC, an assertion attribute for SAML, or an attribute for LDAP). ## Turn on group syncing 1. Navigate to **Workspace Settings → Group syncing**. 2. Toggle on **Enable group syncing**. ![Group syncing](https://media.docs.plane.so/sso/enable-idp-group-sync.webp#hero) ## Configure sync settings Under **Configure group sync**, set how syncing behaves. | Setting | Description | Default | | -------------------------- | --------------------------------------------------------------------------------------------------------- | -------- | | **Sync on login** | Update the user's group membership and access when they sign in | Enabled | | **Offline sync** | Run a sync every two hours automatically, without waiting for users to log in (OIDC and LDAP only) | Disabled | | **Auto remove** | Remove users from the workspace and projects when no group matches | Disabled | | **Group attribute key** | The identity provider attribute that carries the user's groups | `groups` | | **Default workspace role** | The role assigned to users who are auto-added to the workspace but don't match any workspace role mapping | - | Set **Group attribute key** to match exactly what your IdP sends. Common values are `groups` (default), `roles`, `memberOf`, or `custom:groups`. ## Add group mappings Group syncing has three kinds of mapping, each in its own section on the page. Each mapping starts from an **IdP group name** and grants access when a user is in that group. A user in several matching groups always receives the **highest** role or access across them. ### Workspace role mapping Maps a group to a workspace role. 1. Under **Workspace role mapping**, click **Add group sync**. 2. Enter the **User group** name exactly as it appears in your IdP. 3. Select the **Workspace role**. 4. Click **Add**. If a user is auto-added to the workspace but matches no workspace role mapping, they get the **Default workspace role** from the settings above. ### Project role mapping Maps a group to one or more projects with a project role. 1. Under **Project role mapping**, click **Add group sync**. 2. Enter the **User group** name. 3. Choose the target: * Select a **Project**, or * Turn on **Apply to all projects** to map the group to every project in the workspace, including projects created later. 4. Choose the **Project role**: Admin, Member, or Guest. 5. Click **Add**. ### Private collection access mapping Maps a group to a private wiki collection with an access level. Collections group your workspace's wiki pages; only **private** collections have membership, so only private collections can be mapped. 1. Under **Private collection access mapping**, click **Add group sync**. 2. Enter the **User group** name. 3. Select the **Private collection**. 4. Choose the **Collection access**: View, Comment, or Edit. 5. Click **Add**. ## What happens on sync When a user signs in (or during an offline sync), Plane resolves their groups and applies access in order: workspace role first, then project access, then private collection access. | Situation | Result | | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | User is not in the workspace but matches a mapped group | Added to the workspace with the matching workspace role, or the default workspace role, then granted the mapped project and collection access | | User is in the workspace and matches a project or collection mapping | Granted or updated to the mapped access | | User matches several groups mapping to the same target | Receives the highest role or access across the matches | | User is in the workspace but matches no mapping | No access is added. With Auto remove on, synced access is revoked (see below) | ## When users leave groups Removal only happens when **Auto remove** is enabled. When a user no longer matches a mapping, Plane revokes the access that group sync granted, in this order: projects, private collections, and finally the workspace. Group sync only ever touches access it granted itself. The following are never changed or removed by syncing: * **Manually granted access.** Workspace roles, project memberships, and collection access that an admin assigned by hand are never modified or removed. Only access added by group sync is subject to auto-remove. * **The last admin.** A user is never removed if they are the last admin of the workspace or of a project. Manual roles are also never downgraded by syncing. If someone was manually made a project Admin, a group mapping for a lower role will not lower them. ## Sync behavior and safeguards * A user in multiple groups mapped to the same project, workspace, or collection gets the **highest** role or access among them. * **Manually assigned** roles and memberships are never overridden, downgraded, or auto-removed. * The **last admin** of a workspace or project is protected from removal. * A **workspace guest** cannot be granted a project Admin role through a mapping, even if a group maps to Admin. * Adding a paid workspace role through sync respects your seat limits. * **Sync errors never block sign-in.** If syncing fails, the user still logs in and the error is logged. ## Common use cases **New hire provisioning.** Map your `engineering` group to a Member role on all engineering projects (or use Apply to all projects). New engineers get access on their first sign-in with no admin action. **Department scoping.** Map `product-team`, `design-team`, and `marketing-team` to their respective projects so people only see what is relevant to them. **Workspace role assignment.** Map `leadership` to a higher workspace role and set a conservative Default workspace role, so most synced users land as Members while leads are elevated automatically. **Wiki access control.** Map `security-team` to a private "Security runbooks" collection with Edit access, and `all-staff` to the same collection with View, so the right people can read and the right people can maintain it. **Contractor offboarding.** Map `contractors` to projects with the Guest role and enable Auto remove. Access is revoked when they are removed from the IdP group, applied at their next login or at the next scheduled sync. --- --- url: 'https://docs.plane.so/workspaces-and-users/audit-logs.html' description: >- Track key actions across your workspace with a dedicated, tamper-evident audit log. View, filter, and export a record of authentication, membership, role, settings, integration, and security events. --- # Workspace Audit Logs The workspace audit log is a dedicated record of key actions taken across your workspace. It gives administrators an accountable, time-stamped history of who did what and when, covering sign-ins, membership changes, role changes, settings changes, integration activity, and security-sensitive events. The audit log is **append-only** and **tamper-evident**. Entries are written once and can never be edited or deleted, by anyone, including administrators. This makes the log suitable for compliance, security review, and incident investigation. :::info Access Only workspace **Admins** and **Owners** can view or export the audit log. It is not visible to members or guests. ::: ## Where to find it ![Audit logs](https://media.docs.plane.so/workspaces/audit-logs.webp#hero) Go to **Workspace settings → Audit logs**. The page shows the most recent events first, with filters and an export option at the top. ## What gets tracked Events are grouped into categories. The current set of tracked events is: | Category | Events tracked | | ---------------------- | ---------------------------------------------------------------------------- | | **Authentication** | Login success, login failure, logout | | **Member** | Member invited, member removed | | **Permission** | Member role changed | | **Workspace settings** | Workspace feature enabled, workspace feature disabled, plan changed | | **Webhooks** | Webhook created, webhook deleted | | **Security** | API token created, API token revoked, audit log searched, audit log exported | Reading and exporting the audit log are themselves recorded as events. This means every access to the log is accountable, which is a common compliance requirement. ## Read the log Each row in the table represents one event, with these columns: | Column | What it shows | | ---------------- | ------------------------------------------------------------------------------------------------------ | | **Timestamp** | The date and time the event occurred, in your local time | | **Actor** | Who performed the action. Shows the person's name or email. System-generated actions show as **Plane** | | **Event** | The action that took place, for example "Login success" or "Member role changed" | | **Event object** | The target the action was performed on, for example the affected member or token | | **Category** | The category the event belongs to, with an icon | Behind each entry, the log also captures additional context that appears in exports, including the actor type (user, API token, system, or anonymous), the outcome (success or failure), the IP address, the user agent, and, where relevant, the old and new values that changed. Actor identity is stored as a snapshot at the time of the event. If a user is later renamed or removed from the workspace, historical entries still show who they were when the action happened. ## Filter and search audit logs Use the filters at the top of the page to narrow the log: * **Category** - show only events in one or more categories * **Outcome** - show only successful or only failed events * **Actor** - show only events performed by a specific person * **Date range** - show only events within a start and end date * **Search** - free-text search across events Filters combine, so you can, for example, show only failed logins by a specific person within a date range. The filters you apply also determine what is included when you export. ## Export audit log You can export the audit log for offline review, archiving, or handing to auditors. 1. Apply any filters you want the export to respect. 2. Click the **Download** button. 3. Choose a format: **CSV**, **JSON**, or **Excel**. The export runs in the background. Large logs can take time to prepare. When the export is ready, you can download it from the export history, and the same download link is recorded there for later access. Because exporting reflects your current filters, you can produce a targeted export, for example only the Authentication events for a given month, rather than the entire log. ## Data integrity The audit log is designed so that it can be trusted as evidence. * **Append-only.** Entries cannot be modified or deleted after they are written. This is enforced both in the application and at the database level, so there is no path, even for an administrator, to alter history. * **Tamper-evident.** Each entry is cryptographically chained to the one before it within the workspace. If any entry were altered or removed, the chain would no longer validate. Chain verification is available through the audit log API for teams that want to confirm integrity programmatically. ## Notes and limits * The audit log records **workspace-level** actions. It is not an activity feed for individual work items. For the history of changes on a specific work item, use that work item's activity view. * Entries are permanent. There is no way to clear or prune the log. * The tracked event set is expanding over time. New event types are added to the existing categories as coverage grows. ## Frequently asked questions **Can an administrator delete an entry to hide an action?** No. The log is append-only and enforced at the database level. No one, including workspace owners, can edit or delete entries. **Are failed actions recorded, or only successful ones?** Both. Each entry has an outcome of success or failure. For example, both successful and failed logins are recorded. You can filter by outcome. **Does viewing the audit log show up in the audit log?** Yes. Searching and exporting the log are recorded as events, so access to the log is itself accountable. **Who can see the audit log?** Only workspace Admins and Owners. It is hidden from members and guests. --- --- url: 'https://docs.plane.so/workspaces-and-users/upgrade-plan.html' description: >- Upgrade to paid plans in Plane, activate license keys on self-hosted instances, manage seats, and handle subscription changes. --- # Upgrade plan You can upgrade from the Free plan to a paid plan to access premium features. 1. Click your workspace name on the sidebar and select **Settings**. ![Workspace settings](https://media.docs.plane.so/workspaces/workspace-settings.webp#hero-tl) 2. Navigate to the **Billing and plans** tab. ![Billing and plans](https://media.docs.plane.so/activate-license/billing-and-plans-cloud.webp#hero-tl) 3. Select the **Monthly** or **Yearly** tab to choose your billing cycle. 4. Click the **Upgrade** button. 5. This will redirect you to the Stripe payment page. Enter your payment info and click **Subscribe**. 6. If your transaction goes through, you will see a confirmation that your plan is now active. 7. If you're self-hosting Plane, see **[Activate license](/workspaces-and-users/manage-licenses#activate-license)** for instructions on activating your workspace with the license key. ::: info Still on the Business trial? New Cloud workspaces start on a 14-day Business trial and revert to the Free plan on their own if you never add a payment method. To end the trial before then, see [Cancel your trial early](/workspaces-and-users/billing-and-plans#cancel-your-trial-early). ::: --- --- url: 'https://docs.plane.so/workspaces-and-users/manage-licenses.html' description: >- Upgrade to paid plans in Plane, activate license keys on self-hosted instances, manage seats, and handle subscription changes. --- # Manage licenses ::: warning If you are on the self-hosted Community edition and want to upgrade to the Commercial Edition, see [Upgrade from Community](https://developers.plane.so/self-hosting/upgrade-from-community). ::: ## Activate license Activate a paid plan license on your self-hosted Plane instance using a license key from the Prime portal. 1. Login to the [Prime portal](https://prime.plane.so/licenses) with the same email address you used to purchase one of our paid plans. 2. Go to [Manage licenses](https://prime.plane.so/licenses). Copy the value of the **License key** for the license you want to activate. ![Manage licenses](https://media.docs.plane.so/activate-license/copy-license-key.webp#hero) ::: info Click the **Get more licenses** button as in the image above on the [Prime portal](https://prime.plane.so/licenses/plans) to buy more licenses. ::: 3. On the Plane app, navigate to **Workspace settings → Billing and plans**. 4. Click the **Activate this workspace** button. ![Activate workspace](https://media.docs.plane.so/activate-license/enter-license-key-selfhosted.webp#hero-tr) 5. Paste the license key in the **Enter license key** box. 6. Click **Activate**. You will see a confirmation. 7. That's it. To check your plan at any time and find additional details, just go to the **Billing and plans** tab in **Workspace settings**. ![Manage subscription](https://media.docs.plane.so/activate-license/pro-activated-cloud.webp#hero-tr) ## Sync plan If you've made changes to your subscription, like renewing your license, upgrading your plan, or adjusting seats, use **Sync plan** to pull those updates into your workspace. Syncing refreshes your workspace with the latest subscription information from the Prime server, including plan type, seat count, expiration dates, and feature access. **To sync your plan:** 1. Navigate to **Workspace settings → Billing and plans**. 2. Click **Sync plan**. 3. Wait for the sync to complete. You'll see a confirmation once your workspace is updated. Use this whenever you see a mismatch between what's in the Prime portal and what appears in your workspace, or after making any subscription changes externally. ## Delink license key Your license key is linked to both a workspace and an instance, meaning it can only be used on one workspace on one machine at a time. If you switch machines or reinstall the Commercial edition, you’ll need to reactivate your workspace. This helps prevent any misuse of the license on multiple machines or workspaces. To make it easier for you to move between machines or workspaces, we've added a Delink feature. This lets you free up your license from its current workspace, so you can reuse it on a new machine or workspace. ### In Workspace settings Here’s how to delink your license key from a workspace: 1. Head over to the **Billing and plans** screen of the workspace that's currently using the license. 2. Click **Delink license key**. This will release the license key, making it available for use on another machine or workspace. ![Delink license key](https://media.docs.plane.so/activate-license/delink-license-key.webp#hero-tl) 3. Restart the instance using `prime-cli restart`. 4. If you’re switching machines or reinstalling the Commercial edition, see [Move Plane instance to another server](https://developers.plane.so/self-hosting/manage/migrate-plane). 5. Ensure you are connected to the internet and reactivate the new workspace using the license key you delinked earlier. ### In Prime portal You can also delink a license key directly from the Prime portal without accessing the Plane instance. This is useful if you've lost access to the instance or can't reach Workspace settings. 1. Log in to the [Prime portal](https://prime.plane.so/licenses). 2. Click on the license you want to delink. 3. Click Delink license. ![Delink license key in Prime portal](https://media.docs.plane.so/activate-license/delink-license-prime-portal.webp#hero-tl) A confirmation dialog warns that your workspace will be disconnected and you'll lose access to paid features. Click Delink license to confirm. The license key is now released and available for reactivation on another workspace or instance. --- --- url: 'https://docs.plane.so/workspaces-and-users/add-remove-seats.html' description: Manage paid seats in your workspace --- # Add or remove seats Manage the number of paid seats in your workspace to control your subscription costs. Seats determine how many Admins and Members you can have. ::: info Guests don't count as paid seats. You get 5 Guest users per paid seat automatically. ::: ## Add seats Add seats when you need to invite more Admins or Members than your current seat count allows. 1. Navigate to **Workspace settings → Members**. ![Manage seats](https://media.docs.plane.so/activate-license/manage-seats.webp#hero-tr) 2. Click **Manage seats**. 3. Select **Add seats**. ![Add seats](https://media.docs.plane.so/activate-license/add-paid-seats.webp#hero) 4. Enter the number of seats to add. 5. Click **Change**. 6. Complete payment in Stripe. ::: info Billing impact * New seats are charged immediately. * Future bills include the full price of all seats. ::: ## Remove unused seats Remove unused seats to reduce your subscription cost. You can only remove seats that aren't currently assigned to members. ::: tip If you want to remove seats currently in use, remove the members first or change their role to Guest. See [Manage members](/core-concepts/workspaces/members), then remove the unused seats. ::: 1. Navigate to **Workspace settings → Members**. 2. Click **Manage seats**. 3. Select **Remove unused seats**. This removes all paid seats not currently assigned to Admins or Members. --- --- url: 'https://docs.plane.so/workspaces-and-users/billing-and-plans.html' description: >- Learn how Plane's per-seat billing works, and how billing cycles, upgrades, and payments are handled. --- # How billing works Plane uses a per-seat billing model for paid plans. You pay for the number of seats in your workspace, not the total number of users. Understanding this distinction helps you manage costs effectively while giving you the flexibility to map seats to your teams. ## Why per-seat instead of per-user Most SaaS tools charge per user. Every person who accesses the system counts toward your bill. Plane takes a different approach. **The per-seat model separates billing from user roles.** You purchase seats for users who need full access—Admins and Members—while users who need limited access—Guests—are not billed at all. This reflects how teams actually work. Not everyone needs the same level of access. For example, a typical workspace might have 20 Admins and Members and 100 Guests spanning non-participating stakeholders, clients, contractors, and other users. With per-seat pricing, you pay for 20 seats and get 5 Guest slots per paid seat for a total 100 Guest slots. Guests cost nothing extra. This model becomes more cost-effective as your Guest population grows. :::warning Guest allocation works differently on Enterprise Grid. Since Enterprise Grid includes Granular Access Control (GAC) where any role can have any permission, the preset system-defined roles don't apply. All users at the instance level are billable seats. ::: ## How seat-based billing works ### Pro and Business plans Billing happens per workspace. If you have multiple workspaces, each requires its own subscription. When you upgrade a workspace to a paid plan, you're charged for all seats, regardless of how those seats are distributed across projects. ### Enterprise Grid Billing happens at the instance or the tenant level. A single Enterprise Grid license covers the entire instance, including all workspaces within it. This means you can have multiple workspaces under one license. ### Seat allocation and usage **Seats are resources that you assign to users.** When you upgrade, you purchase a specific number of seats. Those seats form a pool that you allocate to users. For example, you might upgrade with 50 seats, assign 45 to current Admins and Members, and keep 5 available for the future. **The initial seat count matches your current team size.** When upgrading through Plane's interface, you automatically get as many seats as the number of Admins and Members currently in your workspace. On self-hosted instances upgrading through the Prime portal, you specify the seat count yourself. ![Add seats](https://media.docs.plane.so/activate-license/add-seats.webp#hero) ### Guest allocation On Pro and Business plans, every paid seat includes 5 Guest slots. These Guest slots are pooled at the workspace level, just like seats. If you have 20 paid seats, you get 100 Guest slots total (20 × 5). This does not apply to the Enterprise Grid. All users are billable seats at the instance level regardless of role. This is because Enterprise Grid will include Global Access Control, which lets you define custom permissions for any role. This means our preset system-defined roles no longer apply in the same way. Plus, your Enterprise Grid license isn't tied to a single workspace. You can have multiple workspaces with Enterprise features turned on. ## Managing seats over time ### Adding seats **You must add seats before adding new paid users.** If all your seats are assigned and you want to add another Admin or Member, you first [purchase additional seats](/workspaces-and-users/add-remove-seats#add-seats) from **Workspace settings → Members → Manage seats**. New seats are charged immediately to your card on file. The charge is prorated if you're mid-cycle or at full price if you're at the start of a cycle. See [How proration works](#how-proration-works) for more. :::warning If you don't have an online payment method on file or you have an offline subscription, you must contact [Plane support](/support/get-help) to adjust your seat count. The system can't automatically charge for new seats without payment information. ::: ### Removing seats **Removing members doesn't reduce your bill.** When you remove a user from your workspace, their seat becomes available in the pool. You can reassign it to someone else. Your seat count and billing remain unchanged. To actually reduce your billing, you must explicitly [remove seats](/workspaces-and-users/add-remove-seats#remove-unused-seats) from **Workspace settings → Members → Manage seats**. This action removes any seats that aren't currently assigned to users. When you remove seats, the prorated amount for the unused portion of the billing cycle is deducted from your next invoice. See [How proration works](#how-proration-works) for more. ### The seats-versus-members distinction This distinction causes confusion, so it's worth emphasizing: **Seats are billing units.** They represent capacity, the maximum number of paid users you can have. **Members are people.** They're the actual users in your workspace. Actions on members—adding, removing, changing roles—don't automatically affect your seat count or billing. Actions on seats—purchasing, removing—directly affect your billing. ### How proration works Proration ensures you only pay for what you use. Whenever you change your seat count mid-cycle, Plane calculates the charge or deduction based on how much of the billing cycle remains. **When you add seats mid-cycle**, you're charged immediately at the prorated price for the remaining days. If you add 10 seats halfway through a monthly billing cycle, you pay for 10 seats × the remaining 15 days, roughly half the monthly price per seat. Those seats then renew at full price in the next billing cycle. **When you remove seats mid-cycle**, the unused portion is deducted from your next invoice. If you remove 10 seats halfway through a monthly billing cycle, your next invoice is reduced by the value of 10 seats × the remaining 15 days. Proration applies to both monthly and annual billing cycles, calculated proportionally based on the number of days remaining in the cycle. ## Subscription lifecycle ### Automatic renewals Subscriptions renew automatically at the start of each billing cycle, monthly or annual, depending on what you selected. The renewal charge is processed through your payment method on file. Stripe, Plane's payment processor, handles the renewal. 1. An invoice is generated at the renewal date. 2. The charge is attempted on your payment method. 3. If successful, your subscription continues. 4. If unsuccessful, Stripe retries the payment 3-5 times over 14 days. 5. After 14 days of failed attempts, the subscription is automatically cancelled. You receive email alerts before each billing attempt and after failed payments. ### Mid-cycle changes **Billing frequency changes**—monthly to annual, or vice versa—take effect at your next billing cycle. You can request this change from **Workspace settings → Billing and plans → Manage subscription**. On Cloud, the change happens automatically. On self-hosted instances, you accept the change in the Stripe portal, then return to Plane and click [Sync plan](/workspaces-and-users/manage-licenses#sync-plan) from Workspace settings to apply the changes locally. **Plan upgrades** happen immediately. On Cloud, change the plan from **Manage subscription**. Any additional cost is prorated and charged immediately. If the new plan costs less per seat, the difference is deducted from your next invoice. On self-hosted instances, this currently requires purchasing a new license and activating it. This process will be simplified in future releases. ### Price stability Your subscription price doesn't change mid-cycle unless you add or remove seats. Monthly subscriptions renew at the same price each month. Annual subscriptions remain constant for the full year. **The exception**\ Limited-period discounts that some workspaces get during promotional periods expire according to their specific terms. If your workspace has a negotiated or promotional rate, note that the Stripe portal may show the standard list price rather than your discounted rate. The correct rate is applied at charge time and reflected on your invoice. ## Downgrade your plan You can downgrade from a higher plan to a lower one or cancel your subscription entirely to return to the Free plan. If your workspace is still on the 14-day Business trial, see [Cancel your trial early](#cancel-your-trial-early) instead. There's no subscription to cancel yet, so the steps below don't apply. ### Downgrade to a lower paid plan 1. Go to **Workspace settings → Billing and plans**. 2. Click **Manage subscription**. This opens the Stripe portal. 3. Click **Update subscription**. 4. Select the plan you want to downgrade to and click **Continue**. 5. Confirm the change. The downgrade takes effect at the end of your current billing cycle. You keep access to the higher plan's features until the cycle ends. The difference in cost is deducted from your next invoice. ### Cancel and return to the Free plan 1. Go to **Workspace settings → Billing and plans**. 2. Click **Manage subscription**. This opens the Stripe portal. 3. Click **Cancel subscription**. 4. Confirm the cancellation. Your workspace retains all paid features until the end of the current billing cycle. If your workspace exceeds the Free plan's seat limit when your subscription ends, the workspace enters a locked state. Everything except **Workspace settings** is blocked. Workspace Admins can either remove users to get under the limit or reactivate a paid subscription to regain full access. ## Manage your subscription All subscription management happens through the Stripe billing portal. Access it from **Workspace settings → Billing and plans → Manage subscription**. ![Manage subscription](https://media.docs.plane.so/billing/manage-subscription.webp#hero) The portal shows your current plan, seat count, and monthly or annual charge. From here you can: * Add or update your payment method * Update billing information (name, email, address, tax ID) * View and download past invoices :::info If your workspace has a negotiated or promotional rate, the portal may display the standard list price. Your actual charge will reflect the discounted rate. Confirm this on your invoice after billing. ::: ## Free plan and trial access ### Free trial for new workspaces When you create a new Plane workspace on our Cloud, you automatically start a 14-day free trial of the Business plan. This gives you full access to premium features without requiring payment information. The trial includes all Business plan features, full seat capacity for your team, and AI credits for Plane AI features. No payment method is required. While the trial runs, a banner on **Workspace settings → Billing and plans** and on the **Get started** page shows how many days are left. Add a payment method from there to convert to a paid Business subscription. After 14 days, your workspace automatically reverts to the Free plan if you haven't upgraded to a paid subscription, and you won’t be charged if a payment method was never added. ### Cancel your trial early If you already know the Business plan isn't for you, you don't have to wait out the 14 days. Workspace Owners and Admins can end the trial at any point and move the workspace to the Free plan straight away. The rest of the workspace can't—see [When the Manage trial link isn't there](#when-the-manage-trial-link-isn-t-there). Cancelling early doesn't save you anything—a trial is free either way, and a trial you leave alone expires to the Free plan on its own. It only changes when the workspace drops to Free. 1. Go to **Workspace settings → Billing and plans**. The same banner appears on the **Get started** page, and the flow works identically from there. 2. In the trial banner, click the **Manage trial** link at the end of the description. 3. The **Your trial is on us** window confirms that you're only ever charged if you choose to subscribe, and that the workspace becomes Free by itself once the trial ends. Click **Keep my trial** to stay on the trial, or **Downgrade to free plan** to carry on. 4. **What you'll miss out on** shows a side-by-side summary of what the workspace gives up: seats, epics and initiatives, workflows, dashboards, teamspaces and shared pages, and time tracking. It's a summary rather than a full feature list—the plan comparison further down the same page has the complete breakdown. 5. Click **Cancel Trial** to confirm, or **Keep Trial** to back out. ::: warning Cancelling a trial takes effect immediately Your workspace moves to the Free plan the moment you confirm. You don't keep Business features for the rest of the 14 days, and a workspace only gets one free trial, so you can't restart it from the app. If you just need more time to evaluate, email instead of cancelling. ::: Your projects, work items, pages, and members stay exactly where they are. Business features are switched off, not deleted. [Upgrade to a paid plan](/workspaces-and-users/upgrade-plan) at any time to turn them back on. The [Free plan seat limit](#free-plan-seat-limits) applies again once you're back on Free. Guests and pending invitations both count toward that limit, which they don't on a paid plan, so a workspace can be over it even when the Admin and Member count looks fine. Nobody is removed from the workspace, but you can't invite anyone new. While a workspace is over the limit, everyone is locked out of everything except Workspace settings until you remove enough people or start a paid subscription. #### When the Manage trial link isn't there **Manage trial** appears only for people who hold the [Manage billing](/roles-and-permissions/permissions-matrix#billing) permission—Workspace Owners and Admins by default. Everyone else in the workspace sees the trial banner without it. It also disappears once a payment method is added. The trial itself keeps running, but the workspace is now set to convert to a paid Business subscription when it ends. Stopping that goes through the Stripe portal instead—see [Cancel and return to the Free plan](#cancel-and-return-to-the-free-plan). Trials are a Plane Cloud feature. Self-hosted instances never show the trial banner or the **Manage trial** link. ### Free plan seat limits The Free plan supports up to 12 seats. **Grandfathered workspaces**\ Cloud workspaces on the Free tier before December 17th, 2024 were grandfathered at their current seat count. If you had 20 Admins and Members when the limit was introduced, your Free workspace retains 20 seats. Grandfathered workspaces keep their higher seat count until you manually remove seats. Once you drop to 12 seats, you lose grandfathered status and cannot add seats without upgrading. If you upgrade a grandfathered workspace to a paid plan, you're charged for all grandfathered seats. A workspace with 20 grandfathered seats would be billed for 20 seats on a paid plan. ## AI credits and usage Plane AI uses a separate credit-based system for AI features. Credits measure the computational work required for AI tasks, from quick queries to bulk automations. Each plan includes monthly AI credits per seat that pool at the workspace level. AI credits are separate from your seat-based subscription. You can run out of AI credits without affecting your paid seats, and vice versa. Learn more about [how AI credits work](/ai/plane-ai-credits) including consumption rates, rollover policies, and top-up options. ::: warning IMPORTANT AI credits apply only to Plane Cloud. On self-hosted instances, you use your own AI provider's API keys, and all AI usage and costs are managed directly through your provider. ::: ## Payment and invoicing ### Payment methods Plane requires a payment method on file for all paid subscriptions created through the standard upgrade flow. Stripe, Plane's payment processor, doesn't allow removing all payment methods once a subscription is active. You can update your payment method anytime from **Workspace settings → Billing and plans → Manage subscription**. ### Download invoices All invoices are available from **Workspace settings → Billing and plans → Manage subscription**. You can view and download past invoices from that screen. ### Failed payments When a payment fails, Stripe attempts to collect payment 3-5 times over 14 days. You receive email notifications after each failed attempt. If all payment attempts fail, Cloud workspaces are cancelled after 14 days. Self-hosted workspaces are cancelled 7 days after the failed payment cycle. ## Unpaid bills If you have an active subscription with unpaid invoices, you receive a 30-day notice to clear the balance. After 30 days, your workspace enters a restricted state where all members except Workspace Admins are locked out. Workspace Admins can access **Billing and plans** page, but no project work is accessible until bills are paid. Once you pay outstanding invoices, full workspace access is restored immediately. ## Cloud versus self-hosted billing differences Most billing mechanics work identically across Cloud and self-hosted instances, with a few key differences: **License activation**\ Self-hosted instances require [license key activation](https://developers.plane.so/self-hosting/manage/manage-licenses/activate-pro-and-business). On Pro and Business, each license key unlocks one workspace on one instance. On Enterprise, the license activates at the instance level, covering all workspaces within it. Cloud workspaces activate directly through the billing portal. There is no need to activate using a license key. **Plan changes**\ Cloud workspaces handle plan changes—upgrades, frequency changes—automatically. Self-hosted instances require using [Sync plan](/workspaces-and-users/manage-licenses#sync-plan) from Workspace settings after accepting changes in the billing portal. **License portability**\ On Pro and Business, license keys are tied to both a workspace and a machine. If you switch servers or workspaces, you must [delink your license key](https://developers.plane.so/self-hosting/manage/manage-licenses/activate-pro-and-business#delink-license-key) from the old workspace before reactivating it elsewhere. On Enterprise Grid, [license activation](https://developers.plane.so/self-hosting/manage/manage-licenses/activate-enterprise) and delinking happens at the instance level through [God mode](https://developers.plane.so/self-hosting/govern/instance-admin). ## Refund policy Plane doesn't offer refunds except in exceptional circumstances. Billing happens automatically with advance email notifications before each charge. If you believe you have an exceptional case warranting a refund, contact [Plane support](/support/get-help) with details about your situation. ## See also * [Upgrade to a paid plan](/workspaces-and-users/upgrade-plan) * [Add or remove seats](/workspaces-and-users/add-remove-seats) * [Manage licenses for self-hosted](/workspaces-and-users/manage-licenses) --- --- url: 'https://docs.plane.so/core-concepts/account/settings.html' description: >- Reference for personal account settings including profile, preferences, notifications, security, and activity. --- # Account settings Account settings control your personal profile, interface preferences, notification preferences, security options, and activity history. These settings apply across all workspaces you belong to. ## Access account settings 1. Click your profile picture in the sidebar. 2. Select **Settings** ![Profile dropdown](https://media.docs.plane.so/account/account-profile-dropdown.webp#hero-tl) ## Profile Manage your personal information and account visibility across workspaces. All profile information is visible to other members in your workspaces. **Profile picture and cover image** * Profile picture appears throughout Plane (work items, comments, assignments). * Cover image displays at the top of your profile page. * Click **Change cover** to upload a custom cover image. **Personal information** * **First name** - Your given name (required) * **Last name** - Your family name * **Display name** - Name shown in work items and mentions (required) * **Email** - Your account email address (required) **Account deactivation**\ You have the option to deactivate your account, which removes you from all the workspaces you are associated with. However, please note that deactivating your account will not delete the work items or any other entities created by you. ## Preferences Customize your interface appearance and behavior. ### Theme Your selected theme applies across all workspaces and devices where you're logged in. **Default:** Light theme **Theme options:** * **System** - Automatically matches your operating system's theme preference * **Light** - Light color scheme * **Dark** - Dark color scheme * **High contrast** - Enhanced contrast for better visibility * **Custom theme** - Create your own color scheme **Custom theme**\ When you select **Custom theme** from the theme dropdown, you can define your own color scheme by specifying hex color values for five interface elements: **Customizable colors:** * **Background color** - Sets the background for main content areas (dashboard, work items, pages, etc.) * **Text color** - Determines text color throughout the platform * **Primary (Theme) color** - Defines accent color for interactive elements * **Sidebar background color** - Sets the side navigation background * **Sidebar text color** - Specifies text color in side navigation Click **Set theme** to apply your custom color scheme. ### First day of the week Changes the starting day for all calendar displays throughout Plane, including: * Project timelines * Due date pickers * Calendar views * Date range selectors ### Smooth cursor Adds animation to cursor movement for a more fluid experience when navigating through editors. ### Timezone and language **Timezone:** * Sets display format for all times throughout Plane. * Affects notifications, activity logs, start dates, end dates, and timestamps. **Language:** * Controls interface language. * Supported languages: English, French, Spanish, Japanese, Simplified Chinese, Traditional Chinese, Russian, Italian, Czech, Slovak, German, Ukrainian, Polish, Korean, Brazilian Portuguese, Indonesian, Romanian, Vietnamese, Turkish ## Notifications Control email notification preferences for work item updates. Email notifications supplement in-app notifications visible in the [Inbox](/communication-and-collaboration/inbox) section. All notifications apply only to work items where you are the creator, assigned to, or explicitly subscribed. ### Notification types **Property changes** * Notifies when work item properties change (assignees, priority, estimates, etc.) * Applies to work items you created, are assigned to, or subscribed to **State change** * Notifies when work items move to different states * Applies to work items you created, are assigned to, or subscribed to **Work item completed** * Notifies only when work items reach completed state * Subset of state change notifications **Comments** * Notifies when someone adds a comment to work items you're involved with * Applies to work items you created, are assigned to, or subscribed to **Mentions** * Notifies when someone mentions you in comments or descriptions ## Security Manage account access credentials. Password must meet security criteria (minimum length, complexity requirements as configured by your instance). ### Change password * **Current password** - Your existing password (required) * **New password** - Your new password (required) * **Confirm password** - Re-enter new password (required) ## Activity View your recent actions and changes across all workspaces. Displays a chronological feed of your activities with timestamps. ## Connections Manage personal account connections on integrations with external services. ## Personal access tokens Generate secure API tokens for integrating Plane data with external systems and applications. --- --- url: 'https://docs.plane.so/core-concepts/projects/overview.html' description: >- Create and manage projects, configure settings, add team members, and enable features. --- # Manage projects Projects organize your team's work within a workspace. Each project contains work items, cycles, modules, pages, and other resources needed to accomplish your goals. ## Create a project **Quick access:** Press `N` then `P` from anywhere in Plane. 1. Navigate to **Work** on the siderail, then select **Projects** in the sidebar. 2. Click **Add Project**. 3. Fill in the project details (described below). 4. Click **Create project**. ![Create project](https://media.docs.plane.so/projects/create-project.webp#hero) **Project details:** * **Project name** (required)\ Give your project a clear and meaningful name that helps your team identify what it's for. * **Project identifier** (required)\ This is a unique code that gets attached to every work item in the project (for example, PROJ-123, DEV-456). The identifier makes it easier to track and reference work items across your workspace. You can update this identifier later in project settings if needed. * **Description** (optional)\ Provide a brief description to help your team understand what the project is about and what goals it serves. * **Access** (required)\ Choose whether the project is **Private** or **Public**. This determines who can see and join the project. See [Set project visibility](#set-project-visibility) below for details on each option. * **Lead** (optional)\ You can designate a lead for the project. This person will be the go-to for queries related to the project's execution and can help guide the team's work. Your new project appears in the sidebar and you're taken to the project dashboard. All project details can be edited later under the **General** tab in project settings. ## Set project visibility Choose who can access your project when creating it or change visibility later in settings. ### Public projects **Who can access:** * All workspace members (Admins and Members) * Guests cannot access public projects unless explicitly invited to them **Who can join:** * Any workspace member can discover and join public projects on their own * No invitation required for members to join **Best for:** * Company-wide initiatives where everyone should have visibility * Shared resources or documentation that benefits the entire team * Cross-team collaboration projects * Open projects where transparency and broad participation are valuable ### Private projects **Who can access:** * Only members who have been explicitly invited to the project * Workspace Admins automatically have access to all private projects **Who can join:** * Only Project Admins can add new members to the project * Members must receive an invitation and cannot join on their own **Best for:** * Confidential or sensitive work that needs restricted access * Client projects where only specific team members should have visibility * Small team projects where you want to control exactly who participates * Projects requiring tight access control for security or privacy reasons **Change visibility** 1. Open **Project Settings** (click **…** next to project name in sidebar). 2. Navigate to **General** tab. 3. Change **Access** setting to Public or Private. 4. Save changes. ::: warning When you change a project from Private to Public, it becomes visible to all workspace members immediately. Make sure this is what you want before making the change, as you cannot undo the visibility that members gained. ::: ## Configure project settings Access project settings to modify project details, manage members, and configure features. 1. Click the **…** icon next to your project name in the sidebar. 2. Select **Settings**. ![Project settings](https://media.docs.plane.so/projects/project-settings.webp#hero-bl) **Available settings tabs:** * **General** - Edit project name, identifier, description, visibility, lead, and timezone * **Members** - Manage project members, their roles, and invite new members * **Features** - Enable or disable project features like cycles, modules, pages * **States** - Configure work item states and workflows * **Labels** - Create and manage labels for organizing work items * **Estimates** - Set up your estimation system for work items * **Automations** - Configure automated actions and rules ## Set project timezone Each project can have its own timezone setting, which is independent of individual member timezone preferences. Only Project Admins can change the project timezone. 1. Navigate to **Project Settings**. 2. Go to **General** tab. 3. Select your desired timezone from the dropdown. 4. Save changes. **What the project timezone affects** * Cycle start and end dates and times * Project-level date displays in the interface **How timezone works for members**\ While the project has its own timezone, individual members will see cycle and module times converted to their personal timezone (set in their [Account preferences](/core-concepts/account/settings#timezone-and-language)). For example, if a cycle is set to end at 5:00 PM in the project timezone (Pacific), a member in Eastern timezone will see the cycle ending at 8:00 PM their time. This ensures everyone sees times in their local timezone while maintaining consistent scheduling across the project. ## Enable project features Control which features are available in your project based on how your team works. You can enable only the features you need and keep your project interface clean and focused. 1. Navigate to **Project Settings**. 2. Go to **Features** tab. 3. Toggle each feature on or off as needed. 4. Changes take effect immediately. ![Project features](https://media.docs.plane.so/projects/project-features.webp#hero) **Available features** * **Cycles**\ Timebox your work items into sprints or iterations. Cycles help you organize work into manageable time periods, track progress over defined intervals, and build momentum with regular delivery cadence. Perfect for agile teams running sprints. * **Modules**\ Group related work items together logically. Modules help you organize large projects into manageable components or features, making it easier to track progress on specific parts of your project. Useful for breaking down complex work into logical groupings. * **Views**\ Create custom filtered views of your work items and save them for quick access. Views let you define specific filters, sorts, and display options, then save them so you and your team can quickly access frequently-used perspectives on your work. * **Pages**\ Document project information, create guides, and build knowledge bases. Pages provide a space for your team to collaborate on documentation, meeting notes, specifications, and any other written content related to your project. * **Intake**\ Capture incoming requests from team members, stakeholders, or guests. The Intake feature provides a way to collect, review, and triage requests before adding them to your project backlog. Useful for managing feature requests, bug reports, and ad-hoc work requests. * **Time Tracking**\ Log time spent on work items and track effort across your project. Time tracking lets team members record hours worked on specific work items and provides reports on time spent. You can download worklog data for analysis or billing purposes. ## Archive a project Archive projects you're no longer actively working on but want to keep for reference or historical purposes. 1. Navigate to **Project Settings**. 2. Scroll to the bottom of the **General** tab. 3. Click **Archive project**. 4. Confirm the action. **What happens when you archive:** * The project is removed from your sidebar to reduce clutter. * The project remains fully accessible in the **Archived projects** section. * The project can be restored at any time with all data intact. * The project no longer appears in workspace search results or active project lists. ## Restore archived projects 1. Navigate to **Work** on the siderail, then select **Projects** in the sidebar. 2. Scroll to the bottom to find the **Archived projects** section. 3. Click **Restore project** on any archived project. 4. The project returns to your active project list in the sidebar ![Archived Projects](https://media.docs.plane.so/projects/archived-projects.webp#hero-bl) ## Delete a project Permanently remove a project and all its data from your workspace. Use this when you're certain you no longer need the project or any of its contents. ::: warning Deleting a project is permanent and cannot be undone. All work items, cycles, modules, views, pages, and other project data will be permanently deleted. Plane does not provide any way to recover a deleted project, so make sure you're certain before proceeding. ::: **Before deleting, consider:** * Exporting any data you might need to keep for records or future reference * Notifying all project members that the project will be deleted * Archiving the project instead if you might need it later **To delete a project:** 1. Navigate to **Project Settings**. 2. Scroll to the bottom of the **General** tab. 3. Click **Delete project**. 4. Confirm deletion by typing the exact project name as prompted. 5. Click the final **Delete** button. ## Troubleshooting ### Unable to create new projects When attempting to create a new project, the page auto-refreshes, but no project is created. This issue typically occurs in **self-hosted instances** when the Unsplash API key configured in your instance has expired or is invalid. Update the [Unsplash Access key](https://developers.plane.so/self-hosting/govern/instance-admin#images-in-plane) in God mode to resolve this issue. --- --- url: 'https://docs.plane.so/core-concepts/projects/manage-project-members.html' description: >- Add members to projects, assign roles, configure default assignee and project lead, manage subscribers, and understand how teamspace memberships interact with direct project access. --- # Manage project members Manage who has access to your project and what they can do by adding members and assigning roles. For background on the available roles, see [Member roles](/roles-and-permissions/member-roles). **Prerequisites:** * You must be a Project Admin or Workspace Admin to manage project members. * Users must be workspace members before they can be added to projects. ## Add members to a project Users must be workspace members before you can add them to a project. ![Project members and teamspaces](https://media.docs.plane.so/projects/project-members-teamspaces.webp#hero) **If the user isn't in your workspace yet:** 1. First, [invite them to the workspace](/core-concepts/workspaces/members#invite-members-to-your-workspace). 2. Once they accept the workspace invitation, proceed with adding them to the project. **Add existing workspace members to your project:** 1. Navigate to **Project Settings > Members & Teamspaces**. 2. Scroll to the **Members** section. 3. Click **Add member**. 4. Search for and select the workspace member. 5. Assign their role: **Admin**, **Contributor**, **Commenter**, or **Guest**. 6. Click **Add**. The member now has access to the project with the permissions defined by their role. ### Project roles * **Admin** — Full project access including settings, member management, and all features. * **Contributor** — Can create and manage work items, cycles, modules, pages, and views. Can delete content they created themselves. * **Commenter** — Can view all work items in the project and add comments and reactions. Can also create intake submissions. * **Guest** — Limited access. Can submit intake forms and view, edit, and delete intake issues they created. ::: info Renamed roles The role previously called **Member** is now called **Contributor**. Permissions are unchanged. The previous **Guest view access** toggle has been replaced by the **Commenter** role. To grant view access plus commenting, assign the Commenter role. ::: See [Permissions matrix](/roles-and-permissions/permissions-matrix) for the complete breakdown. ### Workspace Guest restriction If you're adding a workspace Guest to your project, you can only assign them the **Guest** or **Commenter** role. Attempting to assign Admin or Contributor returns an error. This guardrail prevents external collaborators from being accidentally over-privileged. ## Change a project member's role Update project member roles as responsibilities change. 1. Navigate to **Project Settings > Members & Teamspaces**. 2. Find the member in the **Members** list. 3. Click the **Role** dropdown next to their name. 4. Select the new role. The role change takes effect immediately. ## Remove a member from a project Remove members who no longer need project access. 1. Navigate to **Project Settings > Members & Teamspaces**. 2. Find the member in the **Members** list. 3. Click the three dots next to their name and select **Remove**. 4. Confirm the removal. The member loses access to the project immediately but remains in the workspace. **What happens when you remove a member:** * They can no longer access the project or its work items. * Work items they created remain in the project. * Their comments and activity history are preserved. * They remain a workspace member (unless removed separately). ::: info Removing workspace Owners and Admins Removing a workspace Owner or Admin from a project removes the project membership record but does not restrict their access — they retain access to all project content via their workspace role. ::: ## Default assignee Configure a default assignee to ensure all work items get assigned when created without an explicit assignee. 1. Navigate to **Project Settings > Members & Teamspaces**. 2. Find the **Default Assignee** setting. 3. Click the dropdown and select a project member. 4. The setting saves automatically. **How default assignee works:** * When someone creates a work item without selecting an assignee, the default assignee is automatically assigned. * This ensures no work items are left unassigned. * Useful for projects where a specific person triages new work items. * The creator can still manually assign work items to different members. **To disable:** Select **None** from the Default Assignee dropdown. ## Project lead Designate a project lead who serves as the primary point of contact for the project. 1. Navigate to **Project Settings > Members & Teamspaces**. 2. Find the **Project Lead** setting. 3. Click the dropdown and select a project member. 4. The setting saves automatically. **What a project lead does:** The project lead is the go-to person for questions about the project's execution, goals, and status. This is an informational role that helps team members know who to contact, not a permission level. **Project lead vs. Project Admin:** * Project lead is a designation that identifies a point of contact. * Project Admin is a role with specific permissions. * They can be the same person but don't have to be. ## Project subscribers Project subscribers receive notifications for all work items in the project — status changes, comments, and updates. This is useful for project leads, managers, or stakeholders who need visibility across the entire project without being subscribed to individual work items. ![Project subscribers](https://media.docs.plane.so/projects/project-subscribers.webp#hero) By default, members only receive notifications for work items they're assigned to, have created, or are subscribed to individually. Adding someone as a project subscriber ensures they stay informed about all project activity. To configure project subscribers: 1. Navigate to **Project Settings > Members**. 2. Under **Project subscribers**, click to open the member picker. 3. Select the members who should receive notifications for all work items. Only project admins can manage project subscribers. ## View project member activity ::: info The Enterprise plan is currently only available for self-hosted instances. If you're interested in Enterprise features for your self-hosted deployment, contact for pricing and licensing information. ::: Track member actions like additions, role changes, and removals to maintain visibility over project access management. **To view member activity:** 1. Navigate to **Project Settings → Members & Teamspaces**. 2. Click **Activity** in the top right corner of the Members section. The activity panel shows recent project member events: * **Member additions** — who added which members to the project and when. * **Role changes** — role updates with who made the change and when. * **Member removals** — who removed members from the project. Each activity entry shows the action taken, who performed the action, and when it happened (relative time like "6 days ago" or "3 days ago"). This audit trail helps project admins monitor membership changes and verify that access permissions are correct. Activity is retained for project history. ## Leave a project If you no longer need access to a project, you can leave it yourself. Click the … menu next to your own name in **Project Settings > Members & Teamspaces** and select **Leave**. You'll lose access to the project immediately but remain in the workspace. If you need to rejoin later, a Project Admin or Workspace Admin will need to add you again. ::: warning Last admin protection If you're the only Project Admin, you cannot leave the project. Promote another member to Admin first. ::: ## How users join projects Users can become project members in two different ways, and understanding both helps you manage your project team effectively. **Direct project membership** is when you specifically invite users to your project and assign them roles. These members have access only to the projects you've added them to, and you have full control over their permissions. **Teamspace-based membership** happens automatically when your project is linked to a [Teamspace](/core-concepts/workspaces/teamspaces). All members of that teamspace automatically receive the role assigned on the teamspace-to-project link, making it ideal for teams that collaborate across multiple projects. Users can have both types of access simultaneously. When this happens, Plane evaluates both grants — direct membership is checked first, and either source can grant the access. For example, if someone is a `Guest` on your project but joins a linked teamspace whose link grants `Contributor` access, they get Contributor access to the project through the teamspace. If they're already an `Admin`, they keep their `Admin` role through their direct membership. ## See also * [Manage workspace members](/core-concepts/workspaces/members) * [Member roles](/roles-and-permissions/member-roles) * [Permissions matrix](/roles-and-permissions/permissions-matrix) * [Teamspaces](/core-concepts/workspaces/teamspaces) --- --- url: 'https://docs.plane.so/core-concepts/deploy.html' description: >- Publish your projects as public boards with customizable layouts, commenting, and voting features. Share your roadmap with zero setup on a free domain. --- # Publish projects Any project you build in Plane can be turned into a public page, creating a fully navigable website. This makes it easy for your users and customers to see your latest features or when bug fixes roll out—no sign-up required. ## How to publish project Only Admins can publish a project in Plane. Here’s how: 1. Open your Plane workspace and navigate to the project you want to publish. 2. Click on the ellipsis **...** icon next to the project name to access the project settings menu. 3. Select **Publish** from the dropdown menu, which will open a modal dialog. 4. Configure your public board options in this modal. 5. Once ready, click **Publish**. You'll be instantly redirected to your new public board. ## Publish features ### Layout options You can publish your project in either **Kanban** or **List** layouts. Choose whichever view best fits your project, or turn on both to give viewers more flexibility. Soon, Gantt and Spreadsheet layouts will also be available. #### Attribute privacy **Visible attributes** * Project name * Project work items * Work item ID * Title * Description * State, due-date, priority * Comments * Reactions + `user_names` of users who reacted * Upvotes and downvotes + `user_names` of users who voted **Non-visible attributes** * Attachments * Work item links * Relations * Cycles * Modules * Project settings * Members ### Commenting options When turned on, users can sign up on the public board and add comments to work items—ideal for gathering feedback and showing progress. ### Upvotes and downvotes When turned on, users can upvote or downvote any work item on the deployed board. This helps project managers or owners prioritize which work items need attention. ### Work item reactions When this feature is on, users can react to work items on the public board using predefined emoticons. This provides a quick way for team members and the public to express their sentiments about specific work items, aiding in gauging overall opinion and urgency. ### Free domain hosting You can host your public board on a free domain, making it simple and accessible for anyone to check out your project. No additional setup or domain registration is required; simply choose this option during the publishing process, and your public board will be instantly accessible via the free domain. --- --- url: 'https://docs.plane.so/projects/project-audit-logs.html' description: >- Give project admins a tamper-evident record of who changed a project's configuration, membership, permissions, and settings, with filtering and export. --- # Project Audit Logs The project audit log is a focused record of security-relevant activity **within a single project**. It gives project admins an accountable, time-stamped history of who changed the project's configuration, membership, permissions, and settings. Like [Workspace Audit Logs](/workspaces-and-users/audit-logs), project audit entries are **append-only** and **tamper-evident**: they are written once and can never be edited or deleted, by anyone, including administrators. In fact, project and workspace audit entries are the same underlying records. The project audit log is the slice scoped to one project, so a project admin can review their own project's history without needing access to the whole workspace. ## Where to find it Go to **Project settings → Audit logs**. The page shows the most recent events first, with filters and an export option at the top. ## What gets tracked The project audit log records actions taken on this project: | Category | Events tracked | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Project** | Project settings updated; create, update, or delete of the project's states, labels, modules, cycles, views, workflows, and automations (including enabling or disabling an automation) | | **Member** | Member added to the project, member removed from the project | | **Role and permission** | Project member role changed | | **Security** | Audit log searched, exported, and export downloaded | Reading and exporting the project audit log are themselves recorded as events, so every access to the log is accountable. The project audit log deliberately covers only project-scoped activity. Workspace-wide events, such as sign-ins, plan changes, API tokens, and webhooks, are not shown here. Those belong to the [workspace audit log](/workspaces-and-users/audit-logs) and the instance-level logs. ## Read the log Each row represents one event, with these columns: | Column | What it shows | | ---------------- | ------------------------------------------------------------------------------------------------- | | **Timestamp** | The date and time the event occurred, in your local time | | **Actor** | Who performed the action, shown by name or email. System-generated actions show as **System** | | **Event** | The action that took place, for example "Project member role changed" | | **Event object** | The target the action was performed on, for example the affected member or the label that changed | | **Category** | The category the event belongs to, with an icon | Behind each entry, the log also captures additional context that appears in exports, including the actor type (user, API token, system, or anonymous), the outcome (success or failure), the IP address, the user agent, and, where relevant, the old and new values that changed. Actor identity is stored as a snapshot at the time of the event. If a member is later renamed or removed, historical entries still show who they were when the action happened. ## Filter and search Use the filters at the top of the page to narrow the log: * **Category** — Project, Member, Role & Permission, or Security * **Outcome** — successful or failed events * **Actor** — events performed by a specific person * **Date range** — events within a start and end date * **Search** — free-text search across events Filters combine, and the filters you apply also determine what is included when you export. ## Export the log You can export the project audit log for offline review, archiving, or handing to auditors. 1. Apply any filters you want the export to respect. 2. Click the **Download** button. 3. Choose a format: **CSV**, **JSON**, or **Excel (XLSX)**. The export runs in the background. When it is ready, download it from the **Previous exports** list, which records who exported, when, the format, and the status. Because exporting reflects your current filters, you can produce a targeted export, for example only this month's membership changes, rather than the entire log. ## Data integrity The project audit log is designed so it can be trusted as evidence: * **Append-only.** Entries cannot be modified or deleted after they are written. This is enforced in the application and at the database level, so there is no path, even for an administrator, to alter history. * **Tamper-evident.** Each entry is cryptographically chained to the one before it. If any entry were altered or removed, the chain would no longer validate. Programmatic chain verification is available through the audit log API at the workspace level. ## Notes and limits * Project audit entries are permanent. There is no way to clear or prune the log, and logs are retained indefinitely. * The project audit log is not an activity feed for individual work items. For the history of a specific work item, use that work item's activity view. * Project audit entries also appear in the [workspace audit log](/workspaces-and-users/audit-logs), which a workspace admin can use to review activity across every project at once. * The tracked event set expands over time as coverage grows. ## Frequently asked questions **Can a project admin delete an entry to hide an action?** No. The log is append-only and enforced at the database level. No one, including workspace owners, can edit or delete entries. **Do login events show up in the project audit log?** No. Sign-in and authentication events are recorded at the instance level, not in the project or workspace audit log. **Does viewing the project audit log show up in the log?** Yes. Searching and exporting the log are recorded as events, so access to the log is itself accountable. **Who can see the project audit log?** Project Admins, plus Workspace Admins and Owners. It is hidden from members and guests. --- --- url: 'https://docs.plane.so/core-concepts/projects/project-states.html' description: >- Use Project States to categorize and track project progress across your workspace. --- # Project States Project States allows you to track the overall progress of your projects. With this tool, you can categorize projects into different states, helping you quickly identify which projects need attention and which are on track. This feature provides a central view of all projects in your workspace, making it easier to manage priorities and understand progress. ## Enable Project States > **Role**: Workspace Admins 1. Navigate to **Workspace Settings > Project States**. ![Enable Project States](https://media.docs.plane.so/projects/enable-project-states.webp#hero) 2. Toggle the switch to turn on the feature. 3. There are default project state groups: * **Draft** * **Planning** * **Execution** * **Monitoring** * **Completed** * **Cancelled** ![Add or modify Project States](https://media.docs.plane.so/projects/add-modify-project-states.webp#hero) 4. **Modify state** 1. Click the pencil icon to edit the default state name and description. 2. Click **Update** to save changes. 5. **Add new state** 1. Use the **+** button to add a new state. 2. Provide a name and description for the new state. 3. Click **Create**. You’ll be able to apply these states to all projects in your workspace and begin tracking their progress. ## Modify Project properties 1. Navigate to **Work** on the siderail, then select **Projects** in the sidebar. ![Add or modify Project States](https://media.docs.plane.so/projects/modify-project-states.webp#hero) 2. In each project card, you'll see a bunch of project properties. * **State**: Set the project state. * **Priority**: Highlight high-priority projects. * **Lead**: Assign or change the project lead. * **Members**: Update the team members working on the project. * **Start and end Dates**: Add or adjust timelines. ## Why use Project States? * **Stay organized**\ Group projects based on their current stage, making it easier to prioritize and plan. * **Quick overview**\ Gain a snapshot of all projects from a single view. * **Customizable workflow**\ Adapt states to fit your team’s unique processes. --- --- url: 'https://docs.plane.so/core-concepts/projects/project-labels.html' description: Organize and categorize projects across your workspace with reusable labels. --- # Project Labels Project labels let you categorize projects across your workspace by team, function, priority, or any custom classification. Labels are defined at the workspace level and can be applied to any project. A project can have multiple labels. ## Create project labels 1. Go to **Workspace Settings → Projects**. 2. Click the **Project labels** tab. 3. Click **Add label**. 4. Enter a label name and choose a color. 5. Click **Add**. ![Project Labels](https://media.docs.plane.so/projects/project-labels.webp#hero) You can also create labels directly from the label picker when assigning them to a project. ## Group projects by labels In Board and List layouts, you can group projects by their labels: * Each label appears as its own column or group. * Projects appear under their assigned labels. * Projects without labels appear in a **No Label** group. This makes it easier to scan and manage projects by custom categories. ## Edit and delete labels **Edit a label:** 1. Go to **Workspace Settings → Projects → Project labels**. 2. Click the **…** icon on the label and select **Edit label**. 3. Update the name or color and click **Update**. **Delete a label:** 1. Click the **…** icon on the label and select **Delete**. ::: warning Deleting a label removes it from all projects that had it assigned. ::: --- --- url: 'https://docs.plane.so/core-concepts/projects/project-overview.html' description: >- Track metrics, share status updates, and monitor overall project health from a centralized dashboard for better team alignment. --- # Project Overview Without a centralized project view, teams often face challenges like fragmented information, inefficient progress tracking, and communication gaps. Project Overview offers a centralized space for teams to monitor project health, track progress, and collaborate effectively. It consolidates key project metrics, updates, and collaboration tools into a single view. Whether you're a project lead, team member, or stakeholder, this feature provides the visibility you need to stay informed and aligned. ## Access project overview Navigate to **Work items** under your project and click **Overview** on the top bar. Alternatively, click the project name at the top left when working within other sections like Cycles or Pages. ![Access Project Overview](https://media.docs.plane.so/projects/access-project-overview.webp#hero) ## Project header The header includes the project details and quick access to essential actions. * Add a custom banner and project icon to personalize your dashboard. * Write key details about your project plan, goals, and success metrics, helping your team stay aligned and focused. * Attach links or resources directly to the dashboard. ![Project header](https://media.docs.plane.so/projects/project-header.webp#hero) ## Project metrics You can view overall project completion percentages. Metrics are displayed visually with status bars to help identify bottlenecks. ![Project Progress](https://media.docs.plane.so/projects/project-progress.webp#hero) This helps to identify overdue tasks and track progress over time. Task status breakdown: * **Backlog**: Tasks that are planned but not yet prioritized. * **Unstarted**: Tasks yet to begin. * **Started**: Tasks currently in progress. * **Completed**: Tasks that are done. ## Project properties ![Project properties](https://media.docs.plane.so/projects/project-properties.webp#hero) Quickly view and edit project properties in the info icon tab on the side panel. * **State**: Displays the current state of the project (e.g., Execution). * **Priority**: Shows the priority level (e.g., Urgent, High, Medium, Low, or None). * **Team composition**: See the number of **Members** involved and the assigned Project **Lead**. * **Timeline**: Manage and monitor **Start date** and **Due date** for the project. ## Project updates Communicate project status without meetings. Post updates with status indicators to keep your team aligned and create a historical record of progress. See **[Project updates](/communication-and-collaboration/project-updates)** for details. ![Add project updates](https://media.docs.plane.so/projects/add-project-updates.webp#hero) ## Activity feed Get real-time updates on project activities, such as task progress, state changes, and new members. Updates are listed chronologically, making it easy to follow the project’s history. ![View activity feed](https://media.docs.plane.so/projects/activity-feed.webp#hero) ## See also * [Project updates](/communication-and-collaboration/project-updates) --- --- url: 'https://docs.plane.so/templates/project-templates.html' description: >- Create and use Project Templates to standardize projects, save setup time, and ensure consistency across your workspace with predefined settings. --- # Project Templates Project Templates help you standardize and streamline your workflow by providing reusable structures for common project types. Instead of manually configuring similar projects from scratch, templates allow you to quickly apply predefined settings, saving time and ensuring consistency across your workspace. Templates are perfect for teams who: * Launch similar projects on a regular basis * Need to maintain consistency across multiple projects * Want to reduce setup time for new projects * Need to ensure all projects follow team standards and best practices ## Create project template 1. Navigate to [Workspace Settings](https://docs.plane.so/core-concepts/workspaces/overview#access-workspace-settings). ![Create project template](https://media.docs.plane.so/templates/create-project-template.webp#hero-tr) 2. Select the **Templates** tab on the right pane. 3. Click the **Create template** button in the top-right corner. 4. Select **Project template** from the options. 5. Fill in the template details: ![Project template details](https://media.docs.plane.so/templates/project-template-details.webp#hero) * Give your template a clear, descriptive name. * Add a description explaining when and how to use this template. * Upload a cover image that represents the template. * Configure project properties like visibility, lead, and dates. * Set up optional features like **States**, **Labels**, and **Work item types**. ![Configure project template](https://media.docs.plane.so/templates/configure-project-template.webp#hero) * You can optionally define initial work items that will automatically create when teams start new projects, helping them get up and running faster with pre-structured tasks. 6. Click **Create project template** to save. ## Use project templates Once you've created templates, you can use them whenever you create a new project. ![Use Template when creating projects](https://media.docs.plane.so/templates/use-template-projects.webp#hero) 1. Navigate to **Work** on the siderail, then click the **+** button next to **Projects** in the sidebar. 2. Select **Pick a project template** on the top-left corner of the modal. 3. Choose from available templates. 4. Your new project will be pre-configured with all the template settings. 5. Make any necessary adjustments to customize the project. 6. Click **Create**. Alternatively, from the Templates settings page: ![Use template in workspace settings](https://media.docs.plane.so/templates/use-template.webp#hero) 1. Find your template in the list. 2. Click the **Use template** button. 3. This will immediately open the new project creation form with all template settings pre-filled. ## Manage templates All your templates are accessible from **Workspace Settings > Templates**. From here you can: * View all existing templates * Create new templates * Use existing templates * Edit or delete templates --- --- url: 'https://docs.plane.so/core-concepts/issues/overview.html' description: >- Create, manage and organize work items in Plane with sub-tasks, relations, file attachments, automations, and activity tracking for efficient project management --- # Manage work items A work item is the fundamental unit of work — a task, bug, feature, or any piece of work your team needs to track. Work items are assignable, trackable, and connected to the rest of your project through properties, relations, and project structure. ## Create work item The quickest way to add a new work item is to press `N` then `I` on your keyboard. The work item defaults to the project you're currently viewing or the one you last visited. You can also navigate to the **Work items** tab in the sidebar under your project and click **Add Work item** at the top right. ![Create work item](https://media.docs.plane.so/work-items/create-work-item.webp#hero) In the **Create new work item** modal, define the work item's attributes — title, description, assignees, state, priority, labels, dates, and more. The project's default work item type is pre-selected, and you can switch to a different type from the dropdown at the top left. Turn on **Create more** to add multiple work items in sequence without closing the modal. When you create a work item, Plane assigns it a sequential identifier based on your project (e.g., PROJ-1). ::: tip Plane automatically saves half-written work items to [Drafts](/core-concepts/drafts), so you can access them later if you close the modal before finishing. ::: ### Quick add work items For quick capture without opening the full modal, use the inline quick-add row available in the List and Board layouts. Type a title and press Enter — the work item is created immediately with default properties, and you can refine it later. ![Quick add work item](https://media.docs.plane.so/work-items/quick-add-work-item.webp#hero-bl) ## View work item details Click any work item to open its detail view. The detail view is your workspace for everything about a single work item — editing its description, setting properties, managing sub-work items, tracking activity, and collaborating with your team. ![work item details](https://media.docs.plane.so/work-items/work-item-detail.webp#hero) ### Layout options The detail view opens in **peek overview** mode by default, which lets you browse work items without losing your list context. You can switch between three styles: * **Side peek** (default) — opens as a panel alongside your list. * **Modal** — opens as a centered overlay. * **Full screen** — takes over the entire view. ![Work item side peek](https://media.docs.plane.so/work-items/work-item-side-peek.webp#hero) ### Header The header shows the work item's breadcrumb path (Project > Work Items > ID), the work item type badge, and several quick actions: * **Approval status** — shows "Approval pending" when the work item is awaiting approval. * **Upvote / downvote** — vote on work items to signal priority to your team. Counts are shown in the header. * **Subscriber avatars** — shows who's subscribed to updates. Click **Unsubscribe** to stop receiving notifications for this work item. ### Parent work item When a work item has a parent, the parent appears as a breadcrumb above the title with its type badge and ID. Click the **…** menu on the parent to: * **View sibling work items** — see other sub-work items under the same parent. * **Remove parent work item** — detach this work item from its parent. ![Parent and child work items](https://media.docs.plane.so/work-items/parent-child-work-items.webp#hero) ### Properties panel The right-side properties panel is organized into collapsible sections: * **Details** — state, priority, assignees, labels, start/due dates, estimate, tracked time. * **Project structure** — cycle, modules, customers, milestone, releases. * **Custom properties** — any custom fields defined for this work item type. Metadata (created by, created on, updated on) appears at the bottom. For a full reference of every property, see [Work item properties](/core-concepts/issues/properties). ### Toolbar Below the description, a toolbar provides quick access to: * **Add sub-work item** — create or link sub-tasks. * **Relations and dependencies** — connect this work item to others. * **Links** — add external URLs. * **Attachments** — upload files. * **Pages** — link project or wiki pages. ## Set work item properties You can set various properties for a work item, including its state, assignees, priority, start date, and due date. For a complete list of all available properties, check out the [Properties](/core-concepts/issues/properties) page. ## Create sub-work items Break down larger tasks into smaller, manageable components by creating sub-work items. Sub-work items can be either newly created or linked to existing work items, giving you flexibility in organizing work. ![Sub-work items](https://media.docs.plane.so/work-items/sub-work-items.webp#hero) **Cross-project sub-work items**\ A work item in Project A can be a sub-work item of a work item in Project B. The parent picker searches across the entire workspace. ## Duplicate work items Use **Make a copy** to replicate a work item — either in its own project or in another project in the workspace. It's a quick way to spin up recurring tasks, reuse a well-structured work item as a template, or hand work off to another team. Click the **•••** menu in the work item header and select **Make a copy**. In the modal, pick the destination project — it defaults to the current one — and confirm. The copy always gets a fresh ID from the destination project's sequence. ### What gets copied How much of the original carries over depends on whether you copy in place or into a different project. Labels, modules, cycles, and estimates belong to a single project, so they can't follow a work item across the boundary. | Property | Same project | Different project | | --------------------- | ---------------- | ----------------------------------- | | Title | ` (Copy)` | Unchanged | | Work item type | Retained | Destination project's default type | | State | Retained | Destination project's default state | | Priority | Retained | Retained | | Start and due dates | Retained | Retained | | Description | Copied | Copied | | Links and attachments | Copied | Copied | | Assignees | Retained | Cleared | | Labels | Retained | Cleared | | Modules | Retained | Cleared | | Cycle | Retained | Cleared | | Estimate | Retained | Cleared | | Custom properties | Retained | Appended to the description as text | | Releases | Retained | Retained | | Sub-work items | Not copied | Not copied | | Customer requests | Not copied | Not copied | The copy is also linked back to the original with a **Duplicate of** relation, so you can always trace where it came from. ::: tip Custom property values are project-specific, so they can't be carried into another project's properties. Instead of dropping them, Plane writes them into the bottom of the copied work item's description — nothing is lost, but you'll need to re-enter them against the destination project's own properties if you want them as structured values. ::: ### Notes and limits * **Epics** copied into a different project need an Epic type in the destination — that is, the destination project must have [Work item types](/core-concepts/issues/epics) enabled. If it doesn't, Plane refuses the copy with an error instead of demoting the epic to a regular work item. Copying an epic within its own project always works. * **Archived work items** are copied as active work items, not as archived ones. * You can copy work items in bulk, too. The field rules above apply there as well — see [Copy work items](/core-concepts/issues/bulk-ops#copy-work-items) for the selection limit, permissions, and how epics in a mixed selection are handled. ## Add dependencies Set up scheduling dependencies between work items using the **Add dependency** button. Dependencies control the order in which work happens and are visualized as connectors in the [Timeline layout](/core-concepts/issues/timeline-dependency). * **Blocked by** — this work item cannot proceed until the other work item is completed. * **Blocking** — this work item must be completed before the other work item can proceed. * **Starts Before** — this work item must start before the other work item starts. * **Starts After** — this work item can only start after the other work item starts. * **Finishes Before** — this work item must finish before the other work item finishes. * **Finishes After** — this work item can only finish after the other work item finishes. When both work items have start and due dates set, dependencies appear as visual connectors in the Timeline layout. Violated dependencies — where the dates conflict with the dependency type — are shown as red lines. ## Add relations Link work items that are logically connected using the **Add relation** button. Relations describe how work items relate to each other but don't enforce scheduling constraints. * **Relates To** — the two work items are connected by context but don't directly affect each other's completion. * **Duplicate** — this work item is a duplicate of another. The original remains active while the duplicate is typically closed. * **Implements** — this work item implements or fulfills the other work item. To create custom relation types for your workspace, see [Custom relations](/work-items/custom-relations). ## Add links and attachments You can easily add links and upload attachments to work items in Plane to provide additional context or resources. ![Add links and attachments](https://media.docs.plane.so/issues/links-and-attachments.webp#hero) You can link to external resources, documentation, or related work items by adding URLs in the **Add link** modal. This helps in providing quick access to important references without cluttering the work item itself. Plane allows you to upload different file types directly to the work item. Use the **Attach** button to upload attachments. ### Supported file types * **Images**\ JPEG, PNG, GIF, SVG, WebP, TIFF, BMP * **Documents**\ PDF, Microsoft Word, Microsoft Excel, Microsoft PowerPoint, Plain Text, Rich Text Format (RTF), Markdown, OpenDocument Spreadsheet, OpenDocument Text, OpenDocument Presentation, OpenDocument Graphics * **Audio**\ MP3, WAV, OGG, MIDI, AAC, FLAC, M4A * **Video**\ MP4, MPEG, OGG Video, WebM, QuickTime, AVI, WMV * **Archives**\ ZIP, RAR, TAR, GZIP * **Microsoft Visio**\ Visio Files * **Netpbm formats**\ Portable Graymap, Portable Bitmap, Portable Pixmap * **OpenOffice Base**\ Database files * **3D models**\ GLTF Binary, GLTF JSON, OBJ * **Fonts**\ TrueType, OpenType, WOFF, WOFF2 * **Other**\ CSS, JavaScript, JSON, XML, CSV, SQL ## Link pages to work items Connect relevant project pages and wiki documentation to your work items to provide instant access to related context, specifications, or reference materials. 1. Use the **Link pages** button in the work item to open the page linking modal. 2. You can search through your project pages and use the **Show Wiki pages** toggle to include wiki documentation in your search results. 3. Select multiple pages by checking the boxes next to the pages you want to link, then click **Confirm** to establish the connections. Linked pages appear directly in the work item, making it easy for team members to access relevant documentation without leaving the context of their current task. ## Work item updates Updates let you post a status snapshot on any work item. Each update carries a status indicator — On Track, At Risk, or Off Track — alongside a message. **Post an update:** 1. Open the work item. 2. Click the **Updates** tab in the side panel. 3. Click **Add Update**. 4. Select a status: * **On Track** — progressing as planned * **At Risk** — potential blockers that need attention * **Off Track** — significant blockers or delays 5. Add your message. 6. Click **Add update**. Updates roll up to any initiative the work item is linked to. ## Change a work item's type To change a work item to an Epic or any other type - use **Switch work item type**. Open the work item, hover next to the work item ID, and click **Switch work item type**. Select the new type from the dropdown and click **Update**. See [Work Item Types](/work-items/project-work-item-types#switch-work-item-types) for full details. ## Activity and collaboration The bottom section of the work item detail view contains tabs for tracking everything that happens on the work item. ### All Shows a unified feed combining comments, system activity, worklogs, transitions, and history in chronological order. Use this for a complete picture of the work item's lifecycle. ### Activity Shows system-generated events: state changes, assignee updates, priority changes, label additions, cycle/module assignments, date modifications, estimate changes, custom property value changes, and relation changes. Bot-initiated actions (such as cycle automations) also appear here, attributed to the automation that triggered them. ### Comments Shows only comments posted by team members. Add a comment using the rich text editor at the top — it supports formatting, mentions (`@username`), images, code blocks, and attachments. Comments support threaded replies. Click the **…** menu on any comment and select **Reply** to start a nested conversation. Team members are notified when you reply to their comments. For full details on commenting, see [Work item comments](/communication-and-collaboration/comments-and-activity). ### Worklogs Shows time entries logged against this work item. Click **+ Log work** to add a new entry with hours, minutes, and an optional description. For full details, see [Time tracking](/core-concepts/issues/time-tracking). ### Transition Shows every state transition the work item has gone through — from when it was created to its current state. Each entry shows who changed the state, when, and the from→to states with color-coded status icons. Between transitions, a **time-in-state badge** shows how long the work item stayed in the previous state (e.g., "54m", "1m"). This makes it easy to spot bottlenecks — if a work item sat in "In Review" for 3 days but only spent 10 minutes in "QA", you know where the delay was. ### History Shows a detailed changelog of every property modification made to the work item. Each entry shows the property that changed, the before→after values with matching icons, who made the change, and when. Unlike the Activity tab which shows summary text, History shows the full structured before→after for each change. History tracks all property types including state changes, cycle assignments, estimate changes, label additions, custom property value changes, and actions performed by automation bots (e.g., "Cycle Automation Bot set the cycle to Cycle 1"). Use History to audit specific changes, trace when a due date was moved, or understand who changed an assignee. ### Filter and sort activity Click **Filters** in the activity area to show only specific types of activity. Use the sort toggle to switch between newest-first (default) and oldest-first ordering. ## Subscribe to notifications You’ll automatically receive email notifications for updates on work items that you’ve created or are assigned to. You can also view these notifications directly in **Inbox** on the sidebar. If you'd like to start receiving notifications for a work item you’re interested in, click **Subscribe** at the top right of the work item detail page. If you no longer want to receive updates, simply click **Unsubscribe** to stop the notifications. You can subscribe other users to the work item by mentioning them using `@username` in the comments or the work item description. This ensures they’re notified about the updates and stay in the loop. ## Copy branch name When working with Git, you can copy a pre-formatted branch name directly from a work item. Click the Copy branch name button in the work item header toolbar. Plane generates a branch name from your username and the work item ID (e.g., sarah/DOCSW-606) and copies it to your clipboard. This keeps branch naming consistent across your team when creating PRs. ## View description edit history The work item editor now features an edit history viewer that tracks changes to work item descriptions. ![Description edit history](https://media.docs.plane.so/issues/description-edit-history.webp#hero) Clicking on the last edited timestamp reveals a dropdown panel showing the complete editing history, including: * Who last edited the description * When edits occurred * A dropdown panel showing previous editors and timestamps This addition improves transparency in collaborative projects by making it easy to see how work items evolve over time and who contributed specific changes. ## Export work items You can export your work items to access and analyze your data outside of Plane. Exports support CSV and JSON formats, and you can filter exactly which work items to include. This is useful when you need to create reports, perform external analysis, or share data with stakeholders who don't use Plane. Learn more about [custom exports](/core-concepts/export#custom-exports). ## Archive work items Completed or canceled work items can be archived, and automations can be set up to archive such work items. Archived work items can be found under the three dots menu next to your project name. ![archived-work items](https://media.docs.plane.so/issues/archived-issues.webp#hero) ## Delete work items You can delete work items that were created accidentally or are no longer relevant to the project. Deleted work items cannot be recovered, so be sure to review them carefully before removal. Once deleted, the work item is permanently removed from the project. --- --- url: 'https://docs.plane.so/core-concepts/issues/properties.html' description: >- Explore all available work item properties in Plane including states, priorities, dates, relationships, and more. A comprehensive guide to configuring your tasks effectively. --- # Work Item Properties A breakdown of all the properties available in work items for members to update. | Property | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | Title | Title of the work item or a summary of the work item. This is the only mandatory field to create a work item. | | Description | A brief about the work item which can contain more information, detailed steps etc. | | State | State of the work item in the workflow of the project. When no state is added, the work item is created in the default backlog state. | | Priority | Priority of the work item when compared to other work items in the project. Priority can be urgent, high, medium, low, or none. | | Assignees | Members responsible to work on the work item. Guests cannot be assigned to a work item. | | Labels | Categorize your work item with labels created within the project. | | Start date | Date when the assignee will start working on the work item. | | Due date | Date when the assignee is supposed to close the work item. | | Cycle | If cycles are turned on in your project, you can select the cycle you want the work item to be added in. | | Modules | If modules are turned on in your project, you can select the modules you want to link to the work item. | | Links | External links for the work item. | | Parent | Mark a parent work item for the work item you are creating. | | Blocking | Can be linked to work items which are being blocked by the current work item. | | Blocked by | Can be linked to work items which block the current work item. | | Relates to | Can be linked to work items which are closely related to the current work item. | | Duplicate of | Can be linked to work items which are duplicates of the current work item. | --- --- url: 'https://docs.plane.so/core-concepts/issues/work-item-url.html' description: >- Use a URL to trigger the creation of a new work item in Plane and pre-fill fields using query parameters. --- # Create work items via URL Plane provides a special URL that triggers the creation of a new work item in any browser. You can add query parameters to this URL to pre-fill work item fields, making it easy to create work items from external tools, bookmarks, or shared links. ## Base URL **For Plane Cloud**\ `https://app.plane.so/work-items/new`. For self-hosted instances, replace `app.plane.so` with your domain, e.g., `https://plane.yourdomain.com/work-items/new`. When you visit this URL, Plane authenticates you, redirects to your last active workspace, and opens the work item creation modal. Any query parameters you include will pre-fill the corresponding fields. ## Build a URL with parameters Start with the base URL, add `?`, then append parameters in `name=value` format. Separate multiple parameters with `&`. ```bash https://app.plane.so/work-items/new?title=Fix+bug&priority=high&assignee=me ``` A few formatting rules: * Use `+` or `%20` for spaces in text values. * URL-encode special characters in descriptions. * Separate multiple values (like assignees) with commas. ## Query parameters reference ### workspace Overrides the default behavior of redirecting to your last active workspace. Pass a workspace slug to land in a specific workspace instead. ``` https://app.plane.so/work-items/new?workspace=plane ``` ### title Sets the work item title. Replace spaces with `+` or `%20`. ``` https://app.plane.so/work-items/new?title=Fix+login+bug ``` ``` https://app.plane.so/work-items/new?title=Implement%20new%20feature ``` ### description Sets the work item description. For anything beyond simple text, URL-encode the content to handle special characters and line breaks. ``` https://app.plane.so/work-items/new?description=This+is+a+bug+description ``` Combined with a title: ``` https://app.plane.so/work-items/new?title=Bug+Report&description=Steps+to+reproduce ``` ### project Assigns the work item to a project. You can use either the project identifier (the short code like `WEB` or `MOBILE`) or the project's UUID. ``` https://app.plane.so/work-items/new?project=WEB ``` ``` https://app.plane.so/work-items/new?project=MOBILE&title=New+feature ``` ### priority Sets the priority level. Accepts `urgent`, `high`, `medium`, `low`, or `none`. Values are case-insensitive, so `High`, `HIGH`, and `high` all work. ``` https://app.plane.so/work-items/new?priority=urgent ``` ``` https://app.plane.so/work-items/new?priority=high&title=Critical+fix ``` ``` https://app.plane.so/work-items/new?priority=Medium ``` ### assignee Assigns one or more team members to the work item. You can specify assignees by UUID, display name, or use `me` to assign to whoever opens the URL. For names with spaces, use `+` or `%20`. To assign multiple people, separate values with commas. Assign to yourself: ``` https://app.plane.so/work-items/new?assignee=me ``` Assign by display name: ``` https://app.plane.so/work-items/new?assignee=john ``` Assign by full name: ``` https://app.plane.so/work-items/new?assignee=Erin+Baker ``` Assign multiple people: ``` https://app.plane.so/work-items/new?assignee=me,john,jane ``` ### start\_date Sets the start date. Use `YYYY-MM-DD` or ISO 8601 format for consistency, though any format that JavaScript's `Date` can parse will work. ``` https://app.plane.so/work-items/new?start_date=2024-03-15 ``` ### due\_date Sets the due date (also called target date). Same format rules as `start_date`. ``` https://app.plane.so/work-items/new?due_date=2024-03-30 ``` ## Examples **Bug report with title and description:** ``` https://app.plane.so/work-items/new?title=Login+button+not+working&description=Users+cannot+click+the+login+button+on+mobile ``` **High-priority task assigned to yourself:** ``` https://app.plane.so/work-items/new?project=WEB&priority=high&assignee=me&title=Fix+authentication+bug ``` **Fully populated work item:** ``` https://app.plane.so/work-items/new?title=Implement+dark+mode&description=Add+dark+mode+support+to+the+dashboard&project=FRONTEND&priority=medium&assignee=me,john&start_date=2024-03-15&due_date=2024-03-30 ``` ## Things to know * **Authentication required**\ Users must be logged in. If they're not, Plane redirects them to sign in first, then continues to the work item modal. * **Invalid values are ignored**\ If a project identifier or display name doesn't match an existing record, Plane skips that parameter and processes the rest. * **Case doesn't matter**\ Values like priority and project identifier are case-insensitive. * **Users can still edit**\ Pre-filled values aren't locked. After the modal opens, users can change any field before creating the work item. --- --- url: 'https://docs.plane.so/core-concepts/drafts.html' description: >- Drafts feature automatically saves your work item progress. Create, edit, copy, and move drafts to projects when ready, with no risk of losing your work. --- # Save draft work items We've all been there—clicking outside a modal or navigating away from a page, only to lose all our progress. With Drafts, you don’t have to worry about that anymore. If you're interrupted when writing a work item or a comment or accidentally click away, Plane automatically saves your half-written text so you can pick up right where you left off. ## How drafts work ::: info Drafts remain private and won't be visible to team members until you move them to project work items. ::: As soon as you start writing a work item, Plane auto-saves it for you. Should you stop midway or click away to a notification, all your work items, and soon, comments, are available in **Drafts** accessible from the sidebar. Find your draft from the preview text, edit it, delete it, or move the draft to a project when you're ready. ![Drafts section](https://media.docs.plane.so/drafts/drafts-section.webp#hero) Additionally, if you try to close the **Create work item** modal, you’ll see a confirmation box offering you the option to save it to Drafts. ![Save to drafts](https://media.docs.plane.so/drafts/save-to-drafts.webp#hero) ## Create drafts manually Just click **Draft a work item** at the top right of your **Drafts** screen, and write out a draft that you will pick up later. ![Create drafts](https://media.docs.plane.so/drafts/create-draft.webp#hero) ## Manage your drafts To manage your drafts, click the ellipsis (•••) next to any draft and choose one of several options. ![Manage drafts](https://media.docs.plane.so/drafts/manage-drafts.webp#hero-tr) * **Edit**\ Select **Edit** to make changes to your draft as you would with a regular work item. Once you're done, just save your updates. * **Make a copy**\ Need a duplicate? Simply select **Make a copy** to clone your draft. * **Move to project**\ Ready to finalize your draft? Click **Move to project** to publish it as a regular work item. A confirmation modal will appear, giving you a chance to review it one last time. Assignees and team members will be notified only once the draft is moved to the project. * **Delete**\ Created a draft you no longer need? Deleting it is easy. Click **Delete**, confirm, and it’s gone. A toast message will appear confirming the deletion. ::: caution Keep in mind, deleted drafts cannot be recovered. You'll always see a confirmation modal to prevent accidental deletions. ::: --- --- url: 'https://docs.plane.so/work-items/project-work-item-types.html' description: >- Create specialized work item types in Plane with custom properties, icons, and colors for different teams and workflows to streamline project management. --- # Project Work Item Types Every work item in Plane has a type. When you enable Work Item Types, Plane creates two types for your project automatically: **Task** (the default) and **Epic**. Work Item Types let you go further by creating named types like Bug, Story, or Feature Request with the exact custom properties each type needs. A Bug might need Version, Environment, and Steps to reproduce. A Content Request might need Channel, Reviewer, and Go-live date. A Feature Request might need Business value and Customer impact. Once you define a type, those properties appear automatically on every work item of that type. :::info On the Enterprise Grid, types are managed at the workspace level rather than at the project level. See [Workspace Work Item Types](/work-items/workspace-work-item-types) for that configuration. ::: ## Create work item types ::: warning **Work Item Types cannot be disabled once turned on for a project.** The feature itself is irreversible, though individual types can be disabled at any time. ::: > **Role**: Project Admins ![Work item types](https://media.docs.plane.so/work-item-types/work-item-types.webp#hero) 1. Click the … icon next to your project name on the sidebar and click **Settings**. 2. Select **Work item Types** in the settings panel. If Work Item Types haven't been enabled yet, you'll see the option to turn them on. 3. Click **Enable**. A confirmation prompt reminds you that this cannot be reversed. Confirm to proceed. 4. Two types appear in the list - the default **Task** type and an **Epic** type. You can now create additional types. 5. Click the **Add Work item Type** button to create a new work item type. 6. In the **Create work item type** modal, type name, and description, and choose a background color and an icon to represent the work item type. Click the **Create work item type** button. 7. Switch on the toggle button to allow users to select the work item type when creating work items and sub-work items. ### Examples of work item types * *IT development teams*\ `Bug` `Improvement` `Epic` `Story` * *IT support teams*\ `Incident` `Change` `Service request` `New feature` * *Product management*\ `Product launches` `User research` `Feature development` `Market analysis` * *Production units (automobile)*\ `Production planning`, `Material procurement`, `Quality control`, `Inventory management` * *Design agencies*\ `Revision requests` `Design drafting` `Client presentation` `Quality assurance` ## Add custom properties > **Role**: Project Admins You can add custom properties to all your work item types. 1. Under the work item type, click **Add New Property** to create custom fields. ![Add new property](https://media.docs.plane.so/work-item-types/add-new-property.webp#hero) 2. Specify values for **Title**, **Description** and **Property type** of the new property. 3. Select the **Mandatory property** checkbox if it's a required field. Select the **Active** checkbox to make the property visible in work items. 4. Click **Create** to add the property to the work item type. ::: warning Before you delete properties, switch off the **Active** toggle button to avoid data loss. ::: ## Property types ### Text A freeform text field. When you add a text property, you choose one of three formats: * **Single line:** A compact input for short values like names, codes, or labels. * **Paragraph:** A multi-line input for longer freeform content. * **Read-only:** A fixed text display. You enter the text when setting up the property, and members see it on every work item but cannot edit it. Read-only text properties cannot be marked as mandatory. ### Number A numeric field that accepts decimal values. You can optionally set a default value that pre-fills when a work item is created. ### Dropdown A selection field backed by a list of options you define. When setting up the property, add your options under **Add options**. Each option can have a name and an icon. Choose **Single select** to let members pick one option at a time, or **Multi select** to allow multiple selections. ### Boolean A true/false toggle. The default state is false. Because it already represents a complete two-state answer, boolean properties cannot be marked as mandatory. ### Date A date picker field. You choose a display format for dates across this property: * `Jan 15, 2025` * `15/01/2025` * `01/15/2025` * `2025/01/15` The format you pick applies consistently to all work items using this property. ### Rich text A full document editor field. Unlike a plain text property, rich text supports formatting: headings, lists, code blocks, inline code, bold, italic, and embedded images. Each work item stores its own content for the field, and that content is versioned and searchable. ### Member picker A people-selection field that lists all members of the project. Choose **Single select** to allow one member, or **Multi select** to allow several. Members selected through a member picker property are automatically added as subscribers to that work item, so they receive notifications for updates, comments, and status changes. ### Release picker A field for linking a work item to one or more [releases](https://docs.plane.so/releases) in the project. Supports multi-select. ### URL A field for a single URL. Members enter a link to an external resource, like a design file, a document, or a ticket in another tool, and it renders as a clickable link on the work item. ## Use work item types Once the project Admin sets up the work item types any project member can use them when creating work items or sub-work items. * In the **Create new work item** modal, the user can choose the desired work item type from the list at the top left corner. By default, the work item type `Task` is selected displaying both system-defined and custom properties. * Changing the work item type will update the modal to display the relevant properties for that type. * When a member picker property is filled in, the selected members are automatically subscribed to the work item. This means reviewers, stakeholders, or anyone added through a member picker stay informed without needing to be manually subscribed. * The system ensures that all properties marked as mandatory are filled before creating the work item. ![Use work item types](https://media.docs.plane.so/work-item-types/use-issue-types.webp#hero) When viewing work items, the work item type is displayed with an icon near the title for easy identification. Any custom properties added will also appear in the list of properties, and changes to these values are tracked in the work item's activity trail. ### Switch work item types You can easily switch the work item's type at any time. Just follow these steps: 1. Open the work item you’d like to update. 2. Hover over to the right of the work item ID and click **Switch work item type**. Alternatively, you can click **Edit** from the work item's ellipsis (•••) menu to open the **Update work item** modal directly. ![Switch work item type](https://media.docs.plane.so/work-item-types/switch-issue-type.webp#hero-tl) 3. Choose the new work item type from the dropdown next to your project name. 4. Click **Update** to save your changes. ### Bulk update work item types You can change the work item types for several work items at once. Here’s how: 1. Switch to the **Table** layout in the Work Items page. 2. Select the work items you want to update. A bulk operations bar appears at the bottom of the screen. 3. Select the new type. An **Update** button appears. 4. Click **Update**. ## Set the default work item type The default work item type is pre-selected whenever someone creates a new work item. Initially this is set to the built-in `Task` type, but you can change it to any active work item type. 1. Navigate to **Project Settings → Work item Types**. 2. Click the **…** menu next to the work item type you want to make the default. 3. Select **Set as default**. The selected type now shows a **Default** badge and is automatically pre-selected in the Create new work item modal. You can change the default at any time by repeating these steps for a different type. ## Edit or delete work item types To modify an existing work item type, click the **…** menu next to it and select **Edit**. You can update the name, description, icon, and background color. To remove a work item type, click the **…** menu and select **Delete**. Existing work items of that type are not deleted — they retain the type until individually changed. ## Disable work item types Disabling a type hides it from the type selector when creating new work items. Existing work items of that type are not affected. 1. Go to **Project Settings → Work item Types**. 2. Find the type you want to pause. 3. Toggle off the **Active** switch next to it. To re-enable, toggle it back on. :::info The default type cannot be disabled. ::: --- --- url: 'https://docs.plane.so/work-items/workspace-work-item-types.html' description: >- Define work item types and custom properties at the workspace level, then import them into projects for consistent tracking across your organization. --- # Workspace Work Item Types On the Enterprise Grid, work item types are defined at the workspace level by Workspace Admins and imported into projects. This ensures consistency — a "Bug" in one project has the same properties and structure as a "Bug" in another — while keeping centralized governance over how work is tracked across your organization. :::info On Pro and Business plans, work item types are managed at the project level. See [Project Work Item Types](/work-items/project-work-item-types). ::: ## How workspace work item types work Every workspace starts with a default type called **Task**. This is the base type for all work items and cannot be deleted. You can add custom properties to it, but it's always available as a fallback. When you create additional types at the workspace level, they don't automatically appear in projects. Project Admins import the types they need from the workspace library, making only the relevant types available in their project. This keeps projects focused while maintaining centralized governance. The type assigned to a work item determines its available properties and its behavior across workflows. Changes made to a type at the workspace level reflect across all projects using that type — there's no duplication. :::tip If you had work item types configured at the project level before upgrading to the Enterprise Grid, they've been rolled up to the workspace level. Project Admins can no longer create or edit types directly — that's now handled by Workspace Admins. Your existing types and properties are preserved and available in the workspace library. ::: ## Activate workspace work item types :::warning Work item types cannot be disabled once enabled for a workspace. ::: > **Role**: Workspace Admin 1. Go to **Workspace Settings > Work item Types**. 2. Toggle on **Turn on Work item types for this workspace**. Once enabled, you'll see the **Work item Types** and **Properties** tabs. The default **Task** type is already listed. ![Work item types page](https://media.docs.plane.so/workspaces/work-item-types.webp#hero) ## Create workspace work item type > **Role**: Workspace Admin 1. On the **Work item Types** tab, click **Add work item type**. 2. In the modal, enter a unique name and a description that explains what this type is for and when to use it. 3. Click the icon to the left of the name to choose a custom icon and color. 4. Click **Add work item type**. ![Create work item type](https://media.docs.plane.so/workspaces/create-work-item-type.webp#hero) The new type appears in the list. Use the toggle next to it to control whether project members can select it when creating work items. The type name must be **unique across the workspace**. A newly created type starts **inactive** until you turn it on with the toggle. ## How a type reaches projects Creating a type at the workspace level makes it available in the workspace library, but it does not put the type into every project by itself. How a type reaches a project depends on its rollout setting: | Rollout | Behavior | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Import** (default) | The type is added to a project only when a Project Admin imports it from the workspace library. See [Import types into a project](#import-types-into-a-project). | | **Mandatory** | The type is present in **every** project and cannot be removed by a Project Admin. Marking a type Mandatory adds it to all existing projects immediately. | :::warning Marking a type **Mandatory** adds it to every project right away, and a mandatory type cannot be deactivated or removed at the project level. Changing it back to Import later does **not** remove it from projects that already have it. ::: The default **Task** type behaves like a workspace-wide type: it is present in every project and cannot be deleted or made inactive. ## Create workspace custom properties > **Role**: Workspace Admin Custom properties are fields you define at the workspace level and attach to one or more work item types. A property like "Severity" can be used across both "Bug" and "Incident" types without duplicating it. Properties are not automatically applied to all types — you explicitly choose which properties belong to which type. ### Create a property 1. Switch to the **Properties** tab. 2. Click **Add new property**. 3. Fill in the **Title** and **Description**. 4. Select a **Property type** from the dropdown. 5. Check **Mandatory property** if this field should be required when creating a work item of the linked type. 6. Click **Create**. ![Create custom property](https://media.docs.plane.so/workspaces/create-custom-property.webp#hero) The property is now available to attach to any work item type. ### Attach properties to a type 1. Switch to the **Work item Types** tab. 2. Expand the type you want to add properties to by clicking its arrow. 3. Click **+ Add properties**. 4. In the modal, select the properties you want to attach and click **Add**. ![Add properties to type](https://media.docs.plane.so/workspaces/add-properties-to-type.webp#hero) If the modal shows "No properties available," either all existing properties are already linked to that type, or no custom properties have been created at the workspace level yet. Create new properties from the **Properties** tab first. ## Property settings Every property, regardless of its type, shares a common set of settings. **Title** (required) The label members see on the work item. It must be unique within the type, and cannot reuse one of the reserved field names **state**, **due date**, **cycle**, or **modules**. Plane derives an internal name from the title automatically, which is what [formulas](#formula) and the API use to reference the field. **Description** Optional helper text explaining what the property is for. **Icon** An icon shown next to the property. Each property type has a sensible default. **Mandatory** When on, the value cannot be left empty and the work item cannot be created or saved without it. Marking a property mandatory **clears any default value**. Boolean, Formula, and read-only Text properties cannot be made mandatory. **Active** Properties are active by default. Turn a property off to hide it without deleting it, and without losing values already entered on existing work items. **Default value** A value pre-filled on new work items. Most property types support a default; Formula properties do not, and a mandatory property cannot carry a default. **Single or multi select** For Dropdown, Member picker, and Release picker properties, whether members can select one value or several. **Display order** New properties are added to the end of the type and can be reordered. The order set here is the order members see on the work item. Several of these settings can be **overridden per context**, so the same property can be mandatory in one project or type and optional in another. See [Scope properties with contexts](#scope-properties-with-contexts). ## Property types ### Text A freeform text field. When you add a text property, you choose one of three formats: * **Single line:** A compact input for short values like names, codes, or labels. * **Paragraph:** A multi-line input for longer freeform content. * **Read-only:** A fixed text display. You enter the text when setting up the property, and members see it on every work item but cannot edit it. Read-only text properties cannot be marked as mandatory. The format is chosen when the property is created and cannot be changed afterward. ### Number A numeric field that accepts decimal values. You can optionally set a default value that pre-fills when a work item is created. ### Dropdown A selection field backed by a list of options you define. When setting up the property, add your options under **Add options**. Each option can have a name and an icon, and options can be nested under a parent option. At least one option is required. Choose **Single select** to let members pick one option at a time, or **Multi select** to allow multiple selections. You can mark one or more options as the default (a single-select property can have only one default, and a mandatory property cannot carry a default). ### Boolean A true/false toggle. The default state is false. Because it already represents a complete two-state answer, boolean properties cannot be marked as mandatory. ### Date A date picker field. You choose a display format for dates across this property: * `Jan 15, 2025` * `15/01/2025` * `01/15/2025` * `2025/01/15` The format you pick applies consistently to all work items using this property, and can be changed at any time. ### Member picker A people-selection field that lists the **members of the workspace**. Choose **Single select** to allow one member, or **Multi select** to allow several. Members selected through a member picker property are automatically added as subscribers to that work item, so they receive notifications for updates, comments, and status changes. ### Release picker A field for linking a work item to one or more [releases](/releases) in the project. Supports multi-select. ### Rich text A full document editor field. Unlike a plain text property, rich text supports formatting: headings, lists, code blocks, inline code, bold, italic, and embedded images. Each work item stores its own content for the field, and that content is versioned and searchable. Content is sanitized on save, so scripts and unsafe HTML are removed. Rich text properties cannot be used to filter or group work items. ### URL A field for a single URL. Members enter a link to an external resource, like a design file, a document, or a ticket in another tool, and it renders as a clickable link on the work item. ### Formula A computed, read-only field. You write an expression when setting up the property, and Plane evaluates it automatically for each work item. Members cannot edit the value directly; it always reflects the formula result. **Referencing fields.** Reference another property with double curly braces: `\{\{field_name\}\}`. Field names are matched case-insensitively and ignore spaces versus underscores, so `\{\{start_date\}\}`, `\{\{Start Date\}\}`, and `\{\{START_DATE\}\}` all resolve to the same field. A formula can reference Text, Number, Date, and Boolean properties on the same work item type, and cannot reference itself. **Result types.** A formula evaluates to a Number, Text, Date, or Boolean. **Operators.** * Arithmetic on numbers: `+ - * /` * Dates: `\{\{end\}\} - \{\{start\}\}` gives the number of days; `\{\{date\}\} + 30` and `\{\{date\}\} - 7` shift a date. * Text concatenation: `&` (numbers, dates, and booleans are converted to text automatically). * Comparisons: `= != < <= > >=` (these return a Boolean). **Functions.** `IF(condition, true_value, false_value)`, `ROUND`, `ABS`, `UPPER`, `LOWER`, `LEN`, `CONCAT`, `TODAY()`, `NOW()`. **Examples.** Categorize by estimate size: ``` IF(\{\{estimate_point\}\} > 5, "Large", "Small") ``` Flag high-priority items: ``` IF(\{\{priority\}\} = "HIGH", "Urgent: " & \{\{name\}\}, \{\{name\}\}) ``` Days remaining until a deadline: ``` IF((\{\{due_date\}\} - TODAY()) < 0, "OVERDUE", (\{\{due_date\}\} - TODAY()) & " days remaining") ``` **Behavior.** If any referenced value is empty, the result is empty (an `IF()` branch that is not taken can still reference an empty field safely). A runtime error, such as dividing by zero, shows an error state rather than a value. Because the value is always derived, formula properties cannot be marked as mandatory. ## Scope properties with contexts By default, a property applies everywhere it is attached. **Contexts** let you narrow a property to specific projects and work item types, each with its own configuration, so the same property can behave differently depending on where it is used. When you first create a property, Plane creates a **default context** covering all projects and all types, so the property is visible everywhere it's attached. You then add more specific contexts as needed. With contexts you can, for example, make a "Severity" dropdown **mandatory** on the Bug type in one project but **optional** on the same type in another. For any work item, Plane resolves the effective setting from the **most specific matching context**, falling back to the property's own base setting when no context matches. Manage these from the property's **Manage contexts** option on the **Properties** tab. ## Edit and delete a property ### Edit a property > **Role**: Workspace Admin You can change a property's title, description, icon, mandatory state, active state, and default value at any time. :::warning Some changes lock once values exist Once any work item has a value for the property, you **cannot change its property type, its single/multi-select setting, or its type-specific settings** (such as a dropdown's options). Those are only editable while no work item has used the property yet. Attempting to change them afterward is rejected. ::: Making a property mandatory later is allowed (except for the types that can't be mandatory). Existing work items that are missing the value will need it filled in the next time they are edited. ### Delete a property > **Role**: Workspace Admin Deleting a property that already has values gives you a choice: * **Save values to work item descriptions** (recommended) — each affected work item keeps its value by appending it to the work item's description, with an activity entry recording the change, before the property is removed. * **Delete the property and all its values** — removes the values along with the definition. This cannot be undone. The delete dialog shows how many work items, work item types, and projects across the workspace are affected. If you only want to stop using a property temporarily, turn it **inactive** instead of deleting it. ## Import types into a project > **Role**: Project Admin Projects don't create their own types — they import what's defined at the workspace level. Imported types are linked to the workspace definition, so updates made by Workspace Admins are reflected automatically. 1. Go to **Project Settings > Work item Types**. 2. Click **Import from workspace**. 3. In the modal, select the types you want to bring into this project from the workspace library. 4. Click **Add**. ![Import from workspace](https://media.docs.plane.so/workspaces/import-from-workspace.webp#hero) The imported types now appear in the project's type list alongside the default **Task** type. Project members can select them when creating work items. Only types that have been imported into a project are available when creating or editing work items in that project. ## Use workspace work item types Once types are available in a project, any project member can use them. When creating a new work item, select the type from the dropdown at the top-left of the create modal. The modal updates to show the properties associated with that type. Any mandatory properties must be filled before the work item can be created. ![Choose work item type](https://media.docs.plane.so/workspaces/choose-work-item-type.webp#hero) When viewing work items, the type is displayed with its icon next to the work item title. Custom properties appear in the properties panel, and changes to property values are tracked in the work item's activity trail. ### Switch a work item's type 1. Open the work item. 2. Hover to the right of the work item ID and click **Switch work item type**. Alternatively, click **Edit** from the work item's three-dot menu. 3. Choose the new type from the dropdown. 4. Click **Update**. ### Bulk update types 1. Switch to the **Spreadsheet** layout on the Work items page. 2. Select the work items you want to update. 3. Open the **Work item type** dropdown at the bottom of the screen and pick the new type. 4. Click **Update**. ## Disable a workspace work item type > **Role**: Workspace Admin You can temporarily prevent new work items from being created with a specific type without affecting existing ones. On the **Work item Types** tab, toggle off the switch next to the type you want to disable. Existing work items of that type are unaffected — they retain their type and properties. The type simply won't appear as an option when creating new work items. ## Delete a workspace work item type > **Role**: Workspace Admin Deleting a type removes it from the workspace library and from every project that imported it. Existing work items of that type will need to be reassigned to another type. Before deleting, consider whether disabling the type would be a better option — it preserves existing work items while preventing new ones from being created. ## Hierarchy Hierarchy lets you define structured parent-child relationships between work item types at the workspace level. Once configured, it controls which types can be nested under which — ensuring that work is organized consistently across every project in the workspace. Without hierarchy, any work item can be a sub-work item of any other, regardless of type. With hierarchy enabled, Plane enforces the rules you define: an Epic can only contain Stories and Tasks, a Campaign can only contain Deliverables, and so on. Invalid nesting is blocked throughout the product. ### Why use hierarchy Hierarchy is useful when your organization has a clear structure for how work breaks down and you want to enforce it consistently. It prevents ad hoc nesting that doesn't match your process, keeps reporting and rollups meaningful, and makes it clear to everyone on the team what "level" of work they're looking at. ### How hierarchy levels work Hierarchy is organized as numbered levels, where higher numbers represent broader work and lower numbers represent more granular tasks. Each level can contain one or more work item types, and each level defines a parent relationship with the level directly above it and a child relationship with the level directly below it. Level 0 is the default — types that sit here are leaf-level work items with no children defined in the hierarchy. Types not assigned to any level remain at Level 0. For example, a product engineering team might define: | Level | Types | Role in the hierarchy | | ----- | ----------- | ---------------------------- | | 2 | Epic | Major feature or deliverable | | 1 | Story, Bug | Individual units of work | | 0 | Task, Spike | Leaf-level execution items | In this setup, an Epic can contain Stories and Bugs, and a Story can contain Tasks and Spikes. But a Task cannot contain an Epic — the hierarchy enforces the defined structure. ### Activate hierarchy :::warning Hierarchy cannot be disabled once enabled for a workspace. ::: > **Role**: Workspace Admin Hierarchy requires [work item types to be activated](/work-items/workspace-work-item-types#activate-workspace-work-item-types) and defined first. Once enabled, you'll see all your work item types listed at Level 0 (Default), with a drop zone above for building levels. ### Configure hierarchy levels 1. **Drag and drop** a type from Level 0 up into a new level to create the hierarchy. Each type you drag creates or joins a level. 2. Levels are numbered automatically — higher numbers sit at the top of the hierarchy. 3. Multiple types can sit at the same level. For example, Bug and Customer feedback can both be Level 2 types, meaning both can serve as parents to Level 1 types. 4. Use the **…** menu on a level to set it as default. 5. Click **Save changes** when you're done. Click **Discard** to revert unsaved changes. The hierarchy builder shows the parent→child flow with arrow connectors between levels, making it easy to visualize the structure. ### What hierarchy enforces Once hierarchy is enabled and configured, the following rules are enforced across the workspace: **Work item creation.** When creating a new work item, the type dropdown reflects hierarchy rules. **Sub-work item creation.** When adding a sub-work item to a parent, only types from the level directly below the parent's level are shown. Disallowed types are automatically hidden from the picker. **Type changes.** If a work item already has parent or child relationships, changing its type is only allowed if the new type is valid within the existing hierarchy. If the change would create an invalid relationship, it's blocked. **Data integrity.** Hierarchy prevents invalid parent-child mappings from being created through any surface — the UI, bulk operations, or imports. Existing relationships that were created before hierarchy was enabled remain intact, but new invalid relationships cannot be added. --- --- url: 'https://docs.plane.so/core-concepts/issues/states.html' description: >- Manage work item progress with customizable states in Plane. Organize tasks through backlog, unstarted, started, completed, and cancelled state groups. --- # Work Item States Managing work items effectively is at the heart of every project, and Plane provides a robust system for organizing them into states that represent the stages of a work item's lifecycle. As work items transition through these states—from backlog to completion—they reflect the progression of work in your project, forming a clear and efficient workflow for your team. ## Where to configure states Each project defines its own states, managed by a **project admin** under **Settings → (project) → States**. This is the default. **Enterprise Grid - workspace level**\ With [workspace governance](/workspace-administration/workspace-governance) enabled, states become a single shared set for the whole workspace, managed by a **workspace admin** under **Workspace Settings → States**, then applied to every project. Project admins use the shared set but can't edit it. See [Under Enterprise Grid governance](#under-enterprise-grid-governance). The concept and most mechanics are identical either way; only where you configure them, who can, and a few behaviors differ. ## State groups Every state belongs to one of five groups. The group is the meaning Plane attaches to the state; the name is your label for it. ![Work item states](https://media.docs.plane.so/projects/issue-states.webp#hero) Plane organizes work item states into five primary groups, each serving a distinct purpose in your project’s workflow: * **Backlog**\ Use this group for work items that aren’t ready to be prioritized yet. They might need more discussions or preparation before moving forward. By default, Plane creates a state called **Backlog** in this group. * **Unstarted**\ This group represents work items that are planned but not yet in progress. They’re essentially your team’s to-do list. The default state in this group is **Todo**. * **Started**\ Work items in this group are actively being worked on. They represent ongoing tasks and are crucial for tracking current progress. Plane creates a default state called **In Progress** here. * **Completed**\ These states are for work items that your team has successfully finished. By default, Plane includes a **Done** state in this group. * **Cancelled**: Use this group for work items that are no longer relevant or actionable. Plane provides a default state called **Cancelled** for this purpose. ### What groups drive The group, not the state name, determines behavior across Plane: * **Completion and progress** - only work items in the **Completed** group count as done. Cycle and module progress, burndown, and analytics bucket work items by group. * **Archiving** - only work items in **Completed** or **Cancelled** states are eligible for automatic archiving. * **Ordering** - states sort by group first, then by position within the group. Because of this, **changing a state's group changes how its work items are counted**. Moving a state into Completed, for example, makes its work items count as done in every chart and progress bar. ## The default state Exactly one state is the **default** - the state new work items get when none is chosen. New projects start with Backlog as the default. To change it, open a state and choose **Mark as default**. The previous default is cleared automatically; there is always exactly one. ::: info **Enterprise Grid** The default is not a flag on the state and there is no "Mark as default." The default is the **starting state of the workflow**, set on the [Workflows](/workflows-and-approvals/workflows) page. A governed workspace's default workflow starts at **Todo**. ::: ## Triage state Triage is a special, system-managed state used as the holding area for [intake](#) submissions - items land in Triage before being accepted into the project's normal flow. * There is **one triage state per project**, or **one per workspace** under governance. * **"Triage" is a reserved name** - you cannot name a state Triage. * You **cannot create** a state in the Triage group, and you **cannot delete** the triage state. * Triage is kept out of normal state lists and excluded from analytics. ## Manage states States are shown grouped. Use the **+** on a group to add a state to it. **Create** - set a **name**, a **color**, and an optional **description**. The group is determined by which group you add the state under. A duplicate name is rejected. ::: info **Enterprise Grid:** State names must be unique across the **whole workspace**, and the check is **case-insensitive** - "Todo" and "todo" are treated as the same. (When governance is first enabled, same-named states from different projects are merged into one.) ::: **Edit** - change the name, color, or description at any time. To change a state's group, drag it into another group. **Reorder and regroup** - drag a state to reorder it within its group, or drag it into a different group to reassign it. You **cannot drag away the last state in a group** - every group must keep at least one state. **Delete** - remove a state, subject to these rules: * The **default state cannot be deleted**. Set a different default first. * A state with **work items cannot be deleted** - there is no automatic reassignment. Move its work items to another state first, then delete it. * The **triage state cannot be deleted**. * A group's **last remaining state cannot be deleted**. Deleting a state is permanent. :::info **Enterprise Grid** A state also **cannot be deleted while a workflow uses it** - the error names the workflows. Remove the state from those workflows first. Project admins cannot create, edit, or delete states at all; state management happens at the workspace level. ::: ## Restricting work item creation in a state Whether work items can be created directly in a given state is a **workflow** setting, not a property of the state itself. In a workflow, each state has an **allow work item creation** toggle; turn it off for states that should only be reached by moving an existing work item (like "Done"). See [Workflows](/workflows-and-approvals/workflows). *** ## Under workspace governance When governance is on, states are a single **shared catalog** for the whole workspace: * One shared set that every governed project draws from. A project's visible states are the ones used by the workflows its work item types resolve to. * Names are unique across the workspace, case-insensitive. * One workspace triage state. * The default concept moves to the workflow's starting state. * Project admins cannot edit states; deleting a catalog state is blocked while a workflow references it. See [Workspace governance](/workspace-administration/workspace-governance) for how governance works overall. ## Warnings and limitations * **The default state cannot be deleted** - reassign the default first. * **A state with work items cannot be deleted** - move those work items first; there is no automatic reassignment. * **Every group must keep at least one state.** * **"Triage" is reserved** and cannot be created as a group or deleted. * **State names must be unique** - within the project, or across the workspace (case-insensitive) under governance. * **Changing a state's group re-buckets its work items** for progress, analytics, and archiving. * **Under governance**, a catalog state can't be deleted while a workflow references it, and project admins can no longer edit states. --- --- url: 'https://docs.plane.so/core-concepts/issues/labels.html' description: >- Use labels to categorize work items, simplify filtering, and organize tasks by component, feature, or custom attributes beyond standard properties. --- # Work Item Labels Labels are colored tags you assign to work items to categorize and differentiate them within a project. They are ideal for tracking components, features, or other classifications that don't fit the standard work item properties like state, priority, or assignee. Once labels exist, you can apply several to a single work item, then filter, group, and sort your work items by them across every layout. A label belongs to one project, so each project keeps its own set. ## Manage labels Labels are managed in a project's settings, and the two actions have different permission levels: * **Managing the label set** (create, edit, delete, reorder, and group labels) requires **Project Admin** access. Contributors, commenters, and guests can see labels but cannot change the set. * **Applying an existing label** to a work item is part of editing that work item, so anyone who can edit a work item can add or remove its labels, even if they cannot manage the label set. ![Project labels](https://media.docs.plane.so/issues/work-item-labels.webp#hero) You can manage your labels in the **Labels** tab in your project settings. From here, you can create, edit, and delete labels. Open **Project settings → Labels** to create, edit, group, reorder, and delete your project's labels. If the project has none yet, you'll see a prompt to create your first one. ### Create a label 1. Click **Add label**. 2. Enter a name and pick a color. Plane pre-selects a random color from a preset palette; you can choose a different one. 3. Click **Add**. A few rules to know: * The **name is required** and can be up to **255 characters**. * Names must be **unique within the project** (case-insensitive). If you reuse a name, Plane tells you the label already exists. * In the app, a label has a **name and a color** only. The color picker offers a fixed palette of preset colors. You can also create a label on the fly while working, without opening settings. From a work item's label picker, type a new name and create it inline. Newly created labels there are given a color from the palette automatically. ![Create labels in a work item](https://media.docs.plane.so/issues/create-label-in-work-item.webp#hero-br) When you create a work item, Plane can also [**suggest labels**](/ai/plane-ai#label-prediction) based on its title and description, so you can apply relevant labels (or create suggested ones) in a click. ### Edit a label 1. Open the label's menu and choose **Edit label**. 2. Update the name or color. 3. Click **Update**. Editing is inline, the same form used to create a label, so you can change the name and color but nothing else. ### Group labels You can nest related labels under a parent to keep a long list organized, for example grouping "Frontend," "Backend," and "Infra" under a parent called "Area." * To create a group, **drag one label onto another** in the Labels list. The dragged label becomes a child of the one you drop it on, and the parent becomes a collapsible group. * Grouping is done entirely by drag-and-drop. There is no separate "create group" button and no parent field in the create form. * **Nesting is one level deep.** A label can be a parent or a child, but you cannot nest groups inside other groups. * A group shows as a collapsible section with its child labels indented underneath. ### Reorder labels Drag labels up or down in the list to set their order. The order you set is the order labels appear in pickers and filters. Reordering, like grouping, requires Project Admin access. ### Delete a label 1. Open the label's menu and choose to delete it. 2. Confirm in the dialog. When you delete a label, Plane removes it from every work item that had it and from any views that were filtering on it. The work items themselves are not affected beyond losing that one label. :::warning Deleting a group deletes its children Deleting a parent label also deletes all of the labels nested under it, and removes those labels from their work items too. If you want to keep the child labels, drag them out of the group first. ::: ## Apply labels to work items Labels are applied from wherever you edit a work item, and a work item can carry **as many labels as you need**. * **From a work item:** open it and use the label field to add or remove labels. You can create a new label inline from the same picker. * **From the create dialog:** set labels while creating the work item, or accept Plane's label suggestions. * **In bulk:** select multiple work items in the List layout, and apply labels to all of them at once. ## Where labels help you across the project Once your work items are labeled, labels power several parts of the product: * **Filtering.** Filter any work item list by one or more labels, in every layout. * **Grouping.** Group work items by label in the board, list, and spreadsheet layouts. On the board you can drag a work item from one label group to another to relabel it. * **Sorting.** Order a list by label name. * **Display.** Show labels directly on cards and as a spreadsheet column. * **Queries (PQL).** Filter with the `label` field (for example `label IN (Bug, Regression)`) and the `hasNoLabel()` function to find unlabeled work. See [Plane Query Language](/core-concepts/issues/plane-query-language). * **Automations.** Use labels as a condition (only act on work items with certain labels) and as an action (add, remove, or replace labels when a rule fires). See [Automations](/automations/custom-automations). * **Views and workspace views.** Labels are available as a filter in saved project views and in workspace-level views that span projects. * **Templates.** Project templates can carry a predefined set of labels so new projects start with your standard taxonomy. ## Import labels from a CSV Instead of adding labels one at a time, you can bulk-create them from a CSV file. This is useful when setting up a new project or migrating a label taxonomy from another tool. 1. In **Project settings → Labels**, click **Import**. 2. Upload a CSV file. Use **Download sample CSV** to get the correct format. 3. Plane validates and processes the file, then shows a summary. ### CSV format The file has three columns: | Column | Required | Notes | | ------------- | -------- | ----------------------------------------------------------------------------------- | | `name` | Yes | The label name. Blank names are reported as errors. | | `description` | No | Stored on the label. | | `color` | No | A hex color such as `#0693E3`. Invalid or blank colors get a random color assigned. | ### What the import does * **Creates new labels only.** It never updates or links to existing labels. * **Skips duplicates.** A row whose name already exists in the project (case-insensitive), or repeats a name from earlier in the same file, is skipped rather than merged or renamed. * **Does not create groups.** Imported labels are flat; parent/child grouping is not carried by the CSV. You can group them afterward by drag-and-drop. * **Runs in the background** and reports a summary of how many labels were **Created**, **Skipped**, and **Failed**. If any rows failed, you can download an error report showing which rows and why. ## Things to know * **A label belongs to one project.** To use the same taxonomy in another project, recreate the labels there, import them from a CSV, or start the project from a template that includes them. * **The app shows name and color only.** A `description` field exists and can be set through the CSV import and the API, but it is not shown or editable in the app today. * **No limits** are enforced on how many labels a project can have or how many labels a single work item can carry. * **Reusing a deleted label's name is allowed.** Once a label is deleted, its name is free to use again. --- --- url: 'https://docs.plane.so/templates/work-item-templates.html' description: >- Create and use Work Item Templates to standardize recurring tasks, save setup time, and ensure consistency with predefined fields and properties. --- # Work Item Templates Work Item Templates help you standardize and streamline your workflow by providing reusable templates for common tasks. Instead of manually recreating similar work items, templates allow you to quickly apply predefined structures, saving time and ensuring consistency. Templates are perfect for teams who: * Handle recurring tasks with similar structures * Need to maintain consistency across work items * Want to reduce setup time for new tasks * Need to ensure team members include all required information ## Create work item template 1. Navigate to [Project Settings](https://docs.plane.so/core-concepts/projects/overview#configure-project-settings). 2. Select the **Templates** tab on the right pane. ![Create work item template](https://media.docs.plane.so/templates/create-work-item-template.webp#hero-bl) 3. Click the **Create template** button in the top-right corner. 4. Select **Work Item template** from the options. ![Add template details](https://media.docs.plane.so/templates/add-template-details.webp#hero) 5. Fill in the template details: * Give your template a clear, descriptive name. * Add a description explaining when and how to use this template. * Fill in any default fields you want pre-populated (title format, description,..) * Configure properties like Labels, Assignees, and Modules. * You can optionally define sub-work items that will automatically create along with the main work item, helping structure complex tasks from the start. 6. Click **Create work item template** to save. ## Use work item templates Once you've created templates, you can use them whenever you create a new work item: ![Use Template when creating work items](https://media.docs.plane.so/templates/use-template-work-items.webp#hero-tr) 1. Navigate to **Work Items** under your project. 2. Click the **+** button to create a new work item. 3. Select the work item type. 4. Click the templates icon and choose and from available templates in the dropdown menu. 5. Your new work item will be pre-populated with all the template information. 6. Make any necessary adjustments to the work item. 7. Click **Save**. Alternatively, from the Templates settings page: ![Use Template in project settings](https://media.docs.plane.so/templates/use-template-in-settings.webp#hero-tr) 1. Find your template in the list. 2. Click the **Use template** button. 3. This will immediately open the new work item creation form with all template fields pre-filled. ## Manage templates You can manage your templates from two locations: * **Workspace-level templates**: Access from **Workspace Settings > Templates** * **Project-level templates**: Access from **Project Settings > Templates** From either location you can: From here you can: * View all existing templates * Create new templates * Use existing templates * Edit or delete templates --- --- url: 'https://docs.plane.so/core-concepts/projects/recurring-work-items.html' description: >- Learn how to set up recurring work items to automatically create repetitive tasks, maintenance schedules, and routine work on a predefined schedule. --- # Recurring Work Items Keep your team on track with repetitive tasks by setting them up once and letting them automatically repeat on your schedule. ## Overview Recurring work items are templates that automatically create new tasks based on a schedule you define. Instead of manually creating the same maintenance check, weekly report, or team standup every time, you set it up once and let the system handle the repetition. Think of it like setting a recurring calendar appointment, but for your project work. You define what needs to be done, how often it should happen, and who should do it - then the system takes care of creating these items automatically. ## Set up recurring tasks ![Recurring work items](https://media.docs.plane.so/projects/recurring-work-items.webp#hero) 1. Navigate to your [Project Settings](/core-concepts/projects/overview#configure-project-settings). 2. In the left pane, select **Recurring work items**. 3. Click **Create recurring work item**. ![Create recurring work items](https://media.docs.plane.so/projects/create-recurring-work-items.webp#hero) 4. Fill out your recurring work item just like any regular task - add a title, description, assignees, and any custom properties your team uses. This becomes your template that gets copied each time a new instance is created. 5. In the **Schedule** section, you'll configure when and how often your work item repeats: * **Start and end dates**\ When the recurring pattern begins and optionally when it should stop. * **Frequency**\ Choose from daily, weekly, monthly, or yearly patterns. The system will continue creating items based on your frequency until the end date you specify, or indefinitely if you don't set an end date. 6. Click **Create recurring work item**. ## Manage recurring tasks All your recurring work items appear in the Recurring work items section of your Project settings. Here you can: * See all your recurring patterns with their repeat frequency (like "repeats every week"). * Edit the template or schedule for future instances by clicking the three-dot menu. * Delete recurring patterns you no longer need. When you edit a recurring work item, your changes only affect future instances. Work items that have already been created remain unchanged. *** Recurring work items help ensure nothing falls through the cracks while reducing the administrative burden on your team. Set them up once, and focus your energy on the work that matters most. --- --- url: 'https://docs.plane.so/core-concepts/cycles.html' description: >- Create and manage sprints using Cycles in Plane. Track progress, transfer incomplete tasks, and monitor active cycles across projects for efficient Agile workflows. --- # Cycles A Cycle is a set period of time where your team focuses on completing specific tasks or work items, similar to sprints in Agile. Each Cycle is flexible, allowing you to prioritize and tackle backlog items at your own pace. Using Cycles, your team stays organized, meets deadlines, and keeps moving forward efficiently. It’s all about getting things done without the overwhelm! ## Turn on cycles By default, Cycles are automatically turned on when you create a new project. If you ever want to switch them off or back on, you can easily do that by navigating to **Settings > Features** in your project's ellipsis (…) menu. ## Create cycles :::warning By default, two cycles cannot have overlapping dates. If you need overlapping cycles, see [Parallel cycles](/core-concepts/cycles#parallel-cycles). ::: To create a new Cycle, just press `Q` from anywhere in your project. Or, you can head to the **Cycles** page under your project in the sidebar and click the **Add Cycle** button. You’ll need to give it a name and set the start and due dates. If you want, you can also add a description—either right away or later on! ![Create cycle](https://media.docs.plane.so/cycles/create-cycles.webp#hero) ::: warning Timezone settings If the Project Admin sets the **Timezone** in [Project settings](/core-concepts/projects/overview#configure-project-settings), the Cycle schedules (start and end) will align with it. However, Members will view Cycles starting and stopping based on the timezone set in their [profile settings](/core-concepts/account/settings#timezone-and-language). ::: ## Add work items to cycles * After you create a cycle, you can start adding new work items or bringing in existing work items right in the Cycle page. ![Empty cycle](https://media.docs.plane.so/cycles/cycle-empty-state.webp#hero) * You can also link a Cycle directly as a property within any work item. ![Cycle property](https://media.docs.plane.so/cycles/cycle-property.webp#hero-br) ## Cycle states * **Active cycle**\ An active cycle is the current, ongoing cycle (the current date falls within the cycle's start and due dates) in which a team is working to complete a set of tasks or user stories within a defined time period. By default, only one cycle can be active at a time. To run multiple active cycles simultaneously, see [Parallel cycles](/core-concepts/cycles#parallel-cycles). * **Upcoming cycle**\ A cycle with a start date in the future is considered upcoming. This allows teams to plan their next phase of work in advance, ensuring a seamless transition from the current active cycle to the next, with everything lined up and ready to go. * **Completed cycle**\ When a cycle’s due date has passed, it moves into the completed state. This reflects that the work scheduled during that cycle is finished, and the team can move on to review, wrap-up, and start planning for future cycles. Completed cycles are not editable, however you can transfer work items that are incomplete to an active or upcoming cycle. ::: tip You can modify the name, description, start and due dates of active and upcoming cycles at any time. ::: ## Manually start and stop cycles While Cycles typically run for their set duration, sometimes you need more flexibility in managing your work periods. You can manually control when a Cycle begins or ends using the interface controls. To start a Cycle, simply click the **Start Cycle** button next to your upcoming Cycle. This is particularly useful when you want to begin a planned Cycle earlier than its scheduled start date or if you need to start a fresh Cycle immediately. ::: tip By default, you can't start a new Cycle while another is in progress — you'll need to stop the active one first. With [parallel cycles](/core-concepts/cycles#parallel-cycles) enabled, this restriction is removed and multiple cycles can run simultaneously. ::: ![Start Cycle](https://media.docs.plane.so/cycles/start-cycle.webp#hero-br) To end a Cycle before its scheduled completion date, you can: 1. Click the three-dot menu (⋯) on the active Cycle. 2. Select **End Cycle** from the three dots menu to the right of the active cycle. ::: warning You can't restart a Cycle after it's been manually ended. ::: 3. Once you end a Cycle, it will be marked as completed and move to your **Completed cycle** section. ![End Cycle](https://media.docs.plane.so/cycles/end-cycle.webp#hero-tr) Any unfinished work items in the ended Cycle will remain in their current state. The burn-down chart and progress metrics will be finalized based on the completion status at the time you end the Cycle. This manual control gives you the flexibility to adapt your Cycles to your team's actual work rhythm, rather than being strictly bound to predetermined dates. ## Override scheduled cycles Cycles start and end automatically when their scheduled dates arrive. With this feature, a cycle's dates no longer trigger state changes on their own. The admin decides when each cycle actually starts and ends. So if a cycle is scheduled to start on July 5, it stays upcoming past that date until the admin clicks **Start cycle**. If it's set to end on July 5, it keeps running until the admin clicks **End cycle**. To enable this feature: 1. Go to **Settings → Features → Cycles** inside the project. 2. Find **Manually start and end cycles** and toggle it on. When ending a cycle, if there are incomplete work items, you'll be asked whether to leave them in place or transfer them to another cycle before confirming. > Turning this off does not affect any cycle already in progress, it only restores automatic scheduling going forward. ## Parallel cycles By default, only one cycle can be active at a time, and cycles cannot have overlapping dates. With parallel cycles enabled, you can run multiple cycles simultaneously with overlapping date ranges. This is useful when your team manages parallel workstreams — for example, a two-week sprint running alongside a longer release cycle. ### Turn on parallel cycles 1. Go to **Project Settings > Features > Cycles**. 2. Toggle on **Parallel cycles**. ![Parallel cycles setting](https://media.docs.plane.so/cycles/parallel-cycles-setting.webp#hero) Once enabled, you can create cycles with overlapping dates and start multiple cycles at the same time. Each active cycle appears independently in the Cycles page with its own progress breakdown and burn-down chart. ![Multiple active cycles](https://media.docs.plane.so/cycles/multiple-active-cycles.webp#hero) ### How parallel cycles work Even with parallel cycles enabled, a work item can only belong to one cycle at a time. This prevents duplicate tracking and keeps cycle metrics accurate. If you try to add a work item that already belongs to another cycle, the system will block the action. When you end a parallel cycle, you're prompted to choose what happens to incomplete work items — leave them in the ended cycle or transfer them to an upcoming cycle. Parallel cycles also appear in the workspace-level Active Cycles view and in any connected Teamspace Cycles view, so managers can track overlapping cycles across projects. ### Turn off parallel cycles If you turn off the parallel cycles toggle after overlapping cycles already exist, those cycles continue to run normally. You just won't be able to create new overlapping cycles going forward. No existing data is disrupted. ## Transfer work items Once the due date of an active Cycle passes, it’s automatically marked as completed. After that, you can easily transfer any unfinished work items to an active or upcoming cycle, making it simple to move any leftover tasks to the next cycle. ![Transfer work items](https://media.docs.plane.so/cycles/transfer-issues.webp#hero-tr) ## Auto-schedule cycles Automate the creation and management of cycles according to predefined configurations, eliminating manual setup while ensuring consistent cycle planning and team predictability. ![Autoschedule cycles](https://media.docs.plane.so/cycles/auto-schedule-cycles.webp#hero-br) #### Benefits * Maintain regular cycle rhythms automatically without manual intervention. * Keep future cycles pre-scheduled so teams can plan ahead with confidence. * Eliminate repetitive administrative work from cycle creation. * Ensure reliable, consistent sprint schedules across projects. #### Configuration 1. Navigate to **Project Settings → Features → Cycles**. 2. Turn on the **Auto-schedule cycles** toggle and configure: * Cycle Title — Set a base name for automatically created cycles. Each cycle gets a numerical suffix appended automatically (e.g., if you set the title to "Sprint", cycles are created as "Sprint 1", "Sprint 2", "Sprint 3", and so on). * Cycle Duration — Define the length of each cycle in weeks (e.g., 1 week, 2 weeks). * Cooldown Period — Add an optional buffer between cycles in days for planning and retrospectives. * Cycle starts day — Choose the start date for the first auto-scheduled cycle. * Number of future cycles — Specify how many upcoming cycles to keep pre-scheduled. * Auto-rollover work items — Enable to automatically move incomplete work items from one cycle to the next. Once enabled, the system automatically: * Generates the configured number of future cycles based on your settings. * Creates a new cycle when the current one concludes to maintain the specified schedule. * Numbers each new cycle sequentially, continuing from the last created cycle. * Ensures cycles don't overlap and follow the defined cadence. * Applies consistent naming conventions and durations across all cycles. All auto-scheduled cycles appear in your Cycles view with clear dates and durations. Admins can update configuration settings anytime to adjust the schedule, and the system will adapt future cycles accordingly. ## Track active cycle Once a cycle is active and contains work items, you can monitor its progress, assess the team's productivity, and review the breakdown of priorities in the Cycles page of the project. This section also allows you to investigate any discrepancies if the cycle is not proceeding as expected. ![Track cycle progress](https://media.docs.plane.so/cycles/track-cycle-progress.webp#hero) ## Cycle progress charts This feature provides powerful visualization tools to help you track project cycles more effectively. With real-time insights, you can see exactly how your cycle is performing against the planned progress, making it easier to stay on top of deadlines and adjust as needed. ![Cycle progress charts](https://media.docs.plane.so/cycles/cycle-progress-charts.webp#hero) ### Cycle summary At the top of the cycle view, you’ll see the overall progress percentage. Hover over it to get a breakdown of completed and pending work items, along with the number of days left in the cycle. To the left, there’s a color-coded summary that shows if the cycle is leading or trailing based on the burn-down and build-up. This gives you instant feedback about how things are going and highlights risks so you can make quick decisions and ensure nothing slips through the cracks. The burn-down and build-up charts are straightforward ways to gauge your cycle’s momentum. You can customize them to show progress based on the **count of work items** or **point estimates** for each task, giving you the flexibility to use the metrics that work best for your team. ![Scope](https://media.docs.plane.so/cycles/scope-change.webp#hero) * **Scope**\ This is the total number of work items planned for the current cycle. * **Unstarted**\ The work items that haven't begun yet * **Backlog**\ All work items in an unstarted state The other metrics are detailed below, tailored to each chart type. ### Burn-down chart The burn-down chart gives you a clear visual of how much work remains in your cycle. It's designed to show the ideal pace of progress compared to what’s actually happening. * **Today's ideal pending**\ This shows how many tasks should be left based on the ideal progress for today. * **Pending**\ This is the total number of unfinished tasks, calculated by subtracting completed ones from the total planned for the cycle. The chart tracks the days left, so you can see what should be done by now versus what actually is done. * **Leading**\ If your team is ahead of schedule, meaning you have fewer pending tasks than expected, the chart will show a green upward trend. The area between the ideal and pending lines is filled with light green, indicating strong progress. * **Trailing**\ If progress is behind schedule and there are more pending tasks than expected, the chart displays a red downward trend. A light red fill appears between the ideal progress and the pending lines, signaling the need to catch up. ### Build-up chart The build-up chart helps track how much work has already been completed in the cycle. * **Today's ideal done**\ This shows how many work items should be completed by today based on the ideal pace. * **Done**\ This is the total number of tasks your team has completed so far. * **Leading**\ If you’ve completed more tasks than planned, the chart will show a green upward trend. The area between the ideal and completed lines is filled with light green, visually highlighting that you’re ahead of schedule. * **Trailing**\ If fewer tasks are completed than expected, the chart shows a red downward trend, with a light red fill between the ideal and actual lines, indicating the need to speed up progress. ## Active cycles across projects If you have multiple projects with Cycles running at the same time, you can easily track the progress of all active cycles in the **Cycles** section under the **Workspace** section in the sidebar. This gives you a quick overview of each project’s progress and helps you spot any potential issues early on. Each cycle displays its status—whether it’s ahead of schedule or falling behind—based on the burn-down and build-up metrics. ![Active cycles](https://media.docs.plane.so/cycles/active-cycles-projects.webp#hero) ## Archive cycles You can archive completed cycles, allowing you to conceal significantly older cycles from your views. ## Delete cycles You can delete a Cycle to remove it entirely. When you do, all associated analytics and progress reports will be erased. Any work items linked to that Cycle will also be automatically unlinked. ## Export cycles You can export cycle data to analyze sprint performance, create reports, or share progress with stakeholders outside of Plane. Exports include all work items within the cycle along with their key details. Learn more about [custom exports](/core-concepts/export#custom-exports). --- --- url: 'https://docs.plane.so/core-concepts/modules.html' description: >- Use Modules to organize work items, track feature development, and break down projects into manageable components with progress tracking and multiple layouts. --- # Modules Modules are smaller, focused projects that help users group and organize work items within specific time frames. They allow teams to break down their work into manageable chunks and track progress towards specific goals or objectives. They can serve various purposes: tracking progress on a new feature, managing a milestone like a marketing campaign, or representing discrete pieces of your software architecture such as a microservice. ## Turn on Modules By default, Modules are turned on for all new projects. If you need to turn them on or off later, head to [Project settings](/core-concepts/projects/overview#configure-project-settings) and toggle the Modules feature as needed. ## Create Module To create a new Module: 1. Press `M` from anywhere in the project or navigate to the Modules page on the sidebar and click **Add Module**. 2. Provide a name for the Module. 3. Optionally, add a description, state, designate a lead, and set start and due dates (these can also be added later). ![Create module](https://media.docs.plane.so/modules/create-module.webp#hero) ::: info You can add Members to the Module irrespective of whether they are the assignees in the work items present in the Module. ::: ## Add work items to Module Once your Module is created, you can populate it with work items: * Add new or existing work items directly from the Module page. ![Add work items to module](https://media.docs.plane.so/modules/add-issues-to-module.webp#hero) * Assign multiple Modules to a work item from its properties. For instance, a work item can belong to both a Feature module and a Release module simultaneously. ![Work item module property](https://media.docs.plane.so/modules/issue-module-property.webp#hero) ## Module states Modules can be in one of the following states: * **Backlog** - Newly created Modules start here by default. * **Planned** - Indicating that the Module has been scheduled. * **In Progress** - Work on the Module has started. * **Paused** - Temporarily on hold. * **Completed** - All work items in the Module are in the Done state. * **Cancelled** - The Module has been discontinued. These states provide a clear picture of where each Module stands in your project timeline. Users can plan their Modules with these statuses, offering clarity about the progress and current stage of each Module. ## Module progress Module progress is calculated based on the number of completed work items within the Module. This offers a quick overview of how much work remains before the Module can be closed. Each Module comes with analytics and metrics, empowering teams to assess performance and the success of their goals. ![Module progress](https://media.docs.plane.so/modules/module-progress.webp#hero) ## View Module details * To view the work items within a module, simply click on the module itself. * For detailed information about the module, click the info icon next to the module name. This will display the following details: * Name, description, Members, and assigned lead * Start and due dates * Work items in the Module and their statuses * Progress indicators * Additional properties like assignees, labels and states ![View Module details](https://media.docs.plane.so/modules/view-module-details.webp#hero-tr) ## Search, sort, and filter Modules Quickly locate specific Modules using the search, sorting, and filtering options. You can sort Modules by name, state, or due date, and apply filters to focus on relevant Modules. ## Module layouts Visualize your Modules in different layouts: * **List layout** – For simple ordered list of Modules in the project. * **Gallery layout** – Displays Modules as cards, with a clear breakdown of work item counts by state for better visibility. * **Timeline layout** – Displays the sequence of goals and their progress, helping you ensure your project is on track. ![Module layout](https://media.docs.plane.so/modules/module-gallery.webp#hero) ::: info Easily share a Module by copying its link. Mark frequently used Modules as favorites for quick access. ::: ## Archive Module Archive completed Modules to declutter your views while preserving historical data. This feature is ideal for concealing older, no-longer-active Modules. You can access them in the project's **Archives** option. ## Delete Module If a Module is no longer needed, you can delete it. Deleting a Module removes its progress analytics and de-links all associated work items. ## Export modules You can export module data to track progress, create reports, or share module updates with stakeholders outside of Plane. Exports include all work items within the module along with their key details. Learn more about [custom exports](/core-concepts/export#custom-exports). --- --- url: 'https://docs.plane.so/core-concepts/issues/epics.html' description: >- Epics are now a work item type in Plane. Learn what changed, what stayed the same, and where to go next. --- # Epics Epics in Plane have moved. They're now a [**work item type**](/work-items/project-work-item-types), living in the same Work Items list as other types your team tracks. If you've been using Epics, this page explains what changed, what stayed the same, and where everything is now. ## What changed Previously, Epics had their own dedicated tab in the project sidebar. You managed them separately from work items, and they had their own filtered view, their own settings toggle, and their own sidebar entry. That separate layer is gone. Epic is now a **work item type** and is treated exactly like any other type. You filter, group, sort, and manage Epics the same way you work with any other work item. The creation form, the detail view, the bulk editor, the filters, all of it is shared. What this means in practice: * **The Epics tab in the sidebar is removed.** Epics live in **Work Items**, filterable by type. * **The Epics toggle in Project Settings is gone.** Epic is now managed under **Work item Types** settings. If Work Item Types are enabled for your project, Epic is there. * **Epic is created automatically.** When you enable Work Item Types for a project, Plane creates two types: the default **Task** type and an **Epic** type. You don't set them up manually. * **Work Item Updates - On Track, At Risk, Off Track - are no longer exclusive to epics.** They're now available on every work item of every type. The levels aren't arbitrary. Task is created at level 0 and Epic at level 1 - this is the default hierarchy structure built into the product. If your workspace has the Hierarchy feature enabled, that structure is enforced automatically: Epics sit above Tasks, Tasks can be sub-items of Epics, and Tasks cannot contain Epics. You don't configure this; it's there by default the moment Work Item Types are enabled. ## What stayed the same The data is fully intact. Every comment, every activity log entry, every update, every sub-work item relationship, and every initiative link on your existing epics carried over. Nothing was lost. The way Epics work conceptually hasn't changed either. An epic is still the parent layer above individual work items. Work items still link to an epic through the **Parent** field. Updates from epics still feed into initiative streams as for all work items. ## Where to find your epics now Open **Work Items** in your project. Click **Filters**, add a **Type** filter, and select **Epic**. Your epics are there, exactly as you left them. You can also group your Work Items view by **Type** to see epics and other types side by side. --- --- url: 'https://docs.plane.so/core-concepts/issues/timeline-dependency.html' description: Create and manage visual task dependencies in Plane with timeline connectors. --- # Dependencies in Timeline With dependencies, managing connected tasks has never been easier. This feature provides a clear, high-level view of task relationships, allowing you to quickly see which tasks depend on each other. It helps you plan tasks more efficiently, optimize resource allocation, and stay on top of critical tasks. By tracking dependencies, you can spot bottlenecks, prevent delays, and keep everything on track. ## Timeline connectors ::: info You need to set the Start date and Due date on work items for dependencies to appear in the Timeline layout. ::: In the Timeline layout, you can easily set up dependencies by dragging connectors from one task to another. Once the dependency is established, a line appears between the tasks to visually represent the connection. Violated dependencies are shown as red lines, making it simple to spot any misaligned timelines. ![Timeline dependencies](https://media.docs.plane.so/issues/timeline-dependencies.webp#hero) ::: tip When you drag tasks along the timeline, dependent tasks will adjust automatically to stay in sync. ::: Plane supports three main types of dependencies: * **Finish-to-Start (FS)**\ Task B can’t start until Task A finishes. This is shown by the relations Blocking (Task A is blocking Task B) or Blocked by (Task B is blocked by Task A). If Task B’s start date is earlier than Task A’s due date, the connecting line will turn red to indicate a conflict. ![Finish to start](https://media.docs.plane.so/issues/finish-to-start.webp#hero) * **Start-to-Start (SS)**\ With this dependency, Task B can’t start until Task A begins, but both tasks can proceed simultaneously from that point onward. This is shown by the relations Starts before (Task A starts before Task B) or Starts after (Task B starts after Task A). If Task B’s start date is earlier than Task A’s start date, the connecting line will turn red to indicate a conflict. ![Start to start](https://media.docs.plane.so/issues/start-to-start.webp#hero) * **Finish-to-Finish (FF)**\ Task B cannot be completed until Task A is finished, though both can be worked on simultaneously. This is shown by the relations Finishes Before (Task A finishes before Task B) or Finishes After (Task B finishes after Task A). If Task B’s due date is earlier than Task A’s, the connecting line will turn red to indicate a conflict. ![Finish to finish](https://media.docs.plane.so/issues/finish-to-finish.webp#hero) ## Dependency relations You can also set up dependencies between work items using the **Add dependency** button. However, for the connectors to show up in the Timeline layout, you'll need to set the **Start date** and **Due date** for the work items. See [Add dependencies](/core-concepts/issues/overview#add-dependencies) for more information. --- --- url: 'https://docs.plane.so/core-concepts/projects/initiatives.html' description: >- Create and manage Initiatives to align multiple projects with strategic goals, track cross-project work items, and monitor aggregated progress. --- # Initiatives Initiatives helps you manage and track progress across multiple related projects under a unified objective. Use it when you need a high-level view of how various projects and work items align with strategic goals. Use Initiatives when you need to: * Align multiple projects with a broader organizational goal. * Manage and monitor groups of related projects efficiently. * Provide stakeholders with an aggregated view of progress and status. ## Activate Initiatives To start using Initiatives, you'll need to enable the feature: 1. Go to [Workspace settings](/core-concepts/workspaces/overview#access-workspace-settings). 2. Select the **Initiatives** tab on the right pane. 3. Toggle on the **Enable Initiatives** option. ![Enable Initiatives](https://media.docs.plane.so/initiatives/enable-initiatives.webp#hero) Once enabled, you'll see an **Initiatives** option in the sidebar under **Workspace** section. ## Create an initiative ![Create Initiatives](https://media.docs.plane.so/initiatives/create-initiatives.webp#hero) Follow these steps to set up an Initiative: 1. Navigate to the **Initiatives** section in the sidebar. 2. Click the **Add Initiative** button on the top right of the screen. 3. Provide the following details: * **Title**: Name your Initiative. * **Description**: Add context about the goal of the Initiative. * **State**: Set the initial state (Drafts, Planned, Active, Completed, or Closed). By default, new Initiatives are set to "Drafts". * **Start and End Dates**: Define the timeline for the Initiative. * **Lead**: Assign a person responsible for the Initiative. * **Labels**: Add custom labels to categorize the Initiative (labels must be set up in workspace settings first). 4. Click **Create Initiative**. ## View and manage initiatives Once created, you can view all Initiatives in the **Initiatives** section on the sidebar. ![View Initiatives](https://media.docs.plane.so/initiatives/view-initiatives.webp#hero) Selecting an Initiative opens its detailed view. ![Initiative overview](https://media.docs.plane.so/initiatives/initiative-overview.webp#hero) Initiatives now offer two distinct views to help you track progress and manage scope effectively. Use the dropdown in the top navigation to switch between Overview and Scope views depending on whether you need high-level progress insights or detailed scope management. ### Initiative layouts Initiatives offers three distinct layouts to help you visualize and manage your strategic goals. Use the layout selector in the top navigation bar to switch between views. ![Initiative layouts](https://media.docs.plane.so/initiatives/initiative-layouts.webp#hero) #### List layout The default view that displays Initiatives in a structured list format, showing key details like progress status, dates, connected projects and work items, leads, and states at a glance. This layout is ideal for quickly scanning through multiple Initiatives and comparing their high-level status. #### Board layout Organizes Initiatives into columns based on grouping criteria, providing a kanban-style view of your strategic work. This layout works well for tracking Initiatives through different stages or when you want to see how work is distributed across teams or states. #### Timeline layout Visualizes Initiative timelines on a gantt view, making it easy to see duration, overlaps, and scheduling across your strategic portfolio. Switch between Week, Month, Quarter, and Today views to adjust your time horizon. This layout is perfect for identifying timeline conflicts and understanding how Initiatives are sequenced over time. All three layouts support filtering and grouping in the top navigation. ### Initiative overview The **Overview** gives you a bird's-eye view of your Initiative's progress. You'll see a comprehensive scope breakdown that tracks both projects and work items within your initiative, showing completion percentages and recent updates at a glance. The progress visualization at the bottom provides an instant snapshot of work distribution across different states - from backlog items to completed work. The percentages and counts for each category are automatically calculated based on the associated projects. This makes it easy to understand where your initiative stands and identify any bottlenecks in your workflow. ::: tip Use Initiatives for a top-down view of progress. For detailed updates, navigate to individual projects. ::: ### Initiative scope ![Initiative scope](https://media.docs.plane.so/initiatives/initiative-scope.webp#hero) Use the dropdown in the top navigation to switch to the **Scope** view to see all the building blocks of your initiative. Here you'll find detailed lists of: **Work items**\ You can bring together work items from different projects into a single, high-level view under one initiative. This gives you a centralized picture of how everything is moving forward across workstreams. Any work item type can be added to an initiative — Tasks, Bugs, Features, Epics, or any custom type your workspace uses. You are not limited to a single type. Adding work items to an initiative lets you: * Group related work from different projects under one goal. * Track progress, dependencies, and blockers across multiple projects in one place. * Monitor overall progress and update statuses without switching between projects. **Projects**\ Connected projects showing completion rates and key details like execution status, leads, and timelines. Each item shows its current progress, making it simple to drill down into specific areas that need attention or are ready for the next phase. Use the **Add scope** button in the top-right corner to expand your initiative by connecting additional work items and projects. This makes it easy to grow your initiative as new work streams emerge or when you need to link existing work to your strategic goals. ### Initiative states Every Initiative has a state that reflects its current phase. Use the **State** property to update its status: * **Drafts**\ Initiatives in the planning phase that aren't ready to start * **Planned**\ Initiatives that are defined and scheduled but not yet active * **Active**\ Currently ongoing Initiatives that teams are working on * **Completed**\ Successfully finished Initiatives that have met their goals * **Closed**\ Initiatives that have been archived or discontinued You can filter Initiatives by state using the **Display** dropdown in the Initiatives list view, making it easy to focus on active work or review completed efforts. ### Initiative labels Labels help you categorize and organize Initiatives across your workspace. Before you can use labels on Initiatives, you need to set them up in your [workspace settings](/core-concepts/workspaces/overview#access-workspace-settings). 1. Go to **Workspace settings**. 2. Navigate to the **Initiatives** tab in the left sidebar. 3. Scroll to the **Labels** section. 4. Click **Add label** or **Create your first label**. 5. Define your label name and color. Once labels are created, you can assign them to any Initiative through the **Labels** property in the Initiative's properties panel. Multiple labels can be applied to a single Initiative, allowing for flexible categorization. ## Initiative updates ![Initiative updates](https://media.docs.plane.so/initiatives/initiative-updates.webp#hero-tl) The Initiative updates stream displays all project and work item updates in a chronological feed at the top of the Initiative view. Each update card shows: * Status indicators (On Track, At Risk, Off Track) * Source project or work item name * Post date and author * Complete update content This consolidated view enables Initiative owners to monitor progress across all connected work without navigating to individual items. The stream combines qualitative context with the initiative's quantitative metrics, providing real-time visibility into progress and potential risks across all contributing workstreams. ## Properties, comments, and activity * The Info tab on the side panel of an Initiative provides a quick snapshot of key properties and metadata associated with the Initiative. * **State**: Track the Initiative's lifecycle phase (Drafts, Planned, Active, Completed, Closed) * **Projects**: Number of connected projects * **Work items**: Number of associated work items * **Lead**: Person responsible for the Initiative * **Start date**: When the Initiative begins * **Due date**: Target completion date * **Created by**: Initiative creator * **Labels**: Custom categorization tags for organization ![Initiative properties](https://media.docs.plane.so/initiatives/properties.webp#hero-tr) * Add comments to discuss updates or highlight issues. ![Initiative comments](https://media.docs.plane.so/initiatives/comments.webp#hero-tr) * View the activity log for all updates related to the Initiative. ![Initiative activity](https://media.docs.plane.so/initiatives/activity.webp#hero-tr) ## Sort and filter initiatives To make managing initiatives easier, Plane provides comprehensive options to filter, group, and sort them based on various criteria. ### Filter initiatives Use the filter icon in the top navigation to apply filters: * **Lead**: Filter by the assigned lead with options to select multiple leads or search for a specific person. * **Start date**: Filter based on Initiative start dates with quick options like "1 week from now," "2 weeks from now," "1 month from now," or use a custom date selector. * **End date**: Filter based on target completion dates, similar to the start date options. * **State**: Filter Initiatives by their lifecycle phase (Drafts, Planned, Active, Completed, Closed). * **Labels**: Filter by custom labels to find Initiatives in specific categories. ### Display options Click the **Display** dropdown in the top navigation to customize how Initiatives are organized and sorted: **Group by** * **Lead**: Group Initiatives by the person responsible for them * **Created By**: Group by the person who created the Initiative * **States**: Group by lifecycle phase (Drafts, Planned, Active, Completed, Closed) * **Labels**: Group by assigned labels * **None**: View all Initiatives in a flat list without grouping **Order by** * **Manual**: Drag and drop to arrange Initiatives in your preferred order * **Last Created**: Sort by creation date, showing newest Initiatives first * **Last Updated**: Sort by last modification date, showing recently updated Initiatives first These filtering, grouping, and sorting tools make it easier to focus on specific Initiatives or prioritize your view based on team needs and workflow preferences. --- --- url: 'https://docs.plane.so/core-concepts/workspaces/teamspaces.html' description: >- Organize team members across projects, track team-specific work items, and create dedicated spaces for team knowledge and collaboration. --- # Teamspaces With Teamspaces, you can mirror your real-world teams of any kind and track work separately from a project. See your team's work automatically filtered across projects, and house your team's knowledge separate from anything else in Plane. ## What is Teamspaces? Teamspaces brings together people and projects in a neat space tucked away from all else in Plane, offering you an overview of your teams' work. Track work items across projects, manage multiple cycles, share views and pages, and chat with team members—all without jumping around from one screen to another. ## Turn on Teamspaces ::: warning Once on, the feature cannot be turned off in a workspace. ::: To start using Teamspaces, turn on the feature for your workspace: ![Enable Teamspaces](https://media.docs.plane.so/teams/enable-teamspaces.webp#hero) 1. Navigate to [Workspace Settings](/core-concepts/workspaces/overview#access-workspace-settings). 2. Select the **Teamspaces** tab on the left pane. 3. Toggle on the **Turn on Teamspaces for this workspace** option. Once turned on, the **Teamspaces** option will appear in the sidebar under **Workspaces**, giving you quick access to create and manage teams. ## Create Teamspaces ![Create Teams](https://media.docs.plane.so/teams/create-teamspace.webp#hero) Creating a Teamspace is quick and easy. Here's how: 1. Navigate to the **Teamspaces** section from the sidebar. 2. Click the **New Teamspace** button located at the top-right corner of the screen. 3. Fill in the required details: * **Name**: Provide a name that clearly represents the team. * **Team lead**: Assign a team lead. * **Team members**: Add members by selecting from the list of available users. 4. Once all details are filled, click **Create Teamspace**. After creating a teamspace, you can view and manage all your teams in one place. ![Teams page](https://media.docs.plane.so/teams/view-all-teamspaces.webp#hero) ### Teamspaces and project access When you link a Teamspace to projects, it automatically affects how your team members access those projects. Understanding this relationship helps you manage permissions effectively across your organization. * All members of a teamspace automatically receive `Member` access to any projects linked to that teamspace. This means when you add someone to a teamspace, they immediately gain access to all associated projects without needing separate invitations. * Team members can have both direct project access and teamspace-based access simultaneously. When this happens, Plane applies whichever role gives them higher permissions. For example, if someone is a `Guest` on a project but joins a linked teamspace, they're automatically upgraded to `Member` access. If they're already an `Admin`, they keep their `Admin` role. * Removing someone from a project won't affect their access if they're still in the linked teamspace - they'll retain `Member` access through the teamspace connection. Similarly, removing someone from a teamspace only affects their teamspace-based access; any direct project roles they have remain unchanged. * If you unlink a teamspace from a project, members who had access only through the teamspace will lose access to that project, while those who were directly added to the project will keep their original roles. ## Teamspaces Overview When you click on a Teamspace, you'll see a comprehensive dashboard that gives you visibility into all activities across your team's projects. The **Jump into** section serves as your navigation hub, providing quick access to your team's Work items, Cycles, Views and Pages. ![Jump into section](https://media.docs.plane.so/teams/jump-into-section.webp#hero) ### Teamspace Work Items The Work Items screen gives you a bird's-eye view of everything your team is working on across all projects. You'll see all work items assigned to your team members in one place, making it easy to track progress and understand what everyone's focused on without jumping between different projects. ### Teamspace Cycles The Cycles screen brings together all your team's cycles from every project into one consolidated view. Whether you're looking at active cycles currently in progress, planning upcoming work, or reviewing what you've completed in the past, this screen helps you monitor project timelines and delivery schedules across your entire team's portfolio. ### Teamspace Views Views let you create custom ways of organizing and viewing work that make sense for how your team collaborates. These views exist at the team level, so they're independent of individual projects and can pull together information in ways that work best for your team's workflow and processes. ### Teamspace Pages The Pages screen is your team's documentation hub, where you can create and maintain knowledge that lives at the team level rather than within specific projects. It's perfect for building process documentation, team guidelines, and collaborative resources that everyone can access and contribute to. ## Team progress This section provides a visual representation and summary of the team's current workload and performance, helping managers track progress effectively. It highlights overdue work items, incomplete tasks, and pending actions, ensuring teams stay on top of their responsibilities. ![Team progress](https://media.docs.plane.so/teams/team-progress.webp#hero) Here's a breakdown of its components: * **Overdue work items**\ A red-highlighted banner at the top shows the count of overdue work items, emphasizing the urgency to address them. This feature encourages timely action to meet deadlines and reduce project delays. * **Progress chart**\ A bar chart displays the progress of work items categorized by selected criteria, such as Priority, Due date, or Start date. Users can toggle between these views using the dropdown menu to focus on specific aspects of the team's work. Each bar is segmented to show the percentage of completed and pending work items, offering a quick comparison. * **Summary of team's work items**\ A summary panel on the right provides a detailed breakdown of work item states. It displays counts for Pending and Completed work items and includes additional states like Backlog and Cancelled, ensuring all work items are accounted for. It also highlights work items without due dates, helping team leads prioritize and assign deadlines. ## Team relations The Relations feature allows team members to track dependencies between work items. It has two main tabs - **Blocking** and **Blocked**. ![Team relations](https://media.docs.plane.so/teams/team-relations.webp#hero) **Blocking**\ This tab displays work items that are currently blocking other tasks, potentially causing delays in your team’s workflow. **Blocked**\ This tab would display work items that are blocked by others. It helps in identifying bottlenecks and ensuring timely resolution to keep tasks moving. ## Team stats This section provides a high-level view of tasks across multiple projects or teams. It visualizes work items in a treemap format, where each section represents a project, and the size of each block is proportional to the number of work items. ![Team stats](https://media.docs.plane.so/teams/teamspace-stats.webp#hero) You can group the stats based on filters like Projects, Members, State Groups, Dependency, and Due By to focus on specific areas of work. A legend at the bottom categorizes work items by their state or priority, making it easier to understand their progress. This feature helps you quickly assess the distribution of workload, identify where resources are focused, and monitor the health of ongoing efforts. ## Team info The Info tab on the right serves as a centralized space to view key details and linked entities. ![Teams info](https://media.docs.plane.so/teams/teamspace-info.webp#hero) * **Properties**\ Displays primary details about the entity. For example, the lead or owner of the team is listed here. * **Linked entities**\ Provides a breakdown of related elements associated with the entity, including number of work items and cycles . * **Team's entities** Displays the count of views and pages created at the team level. ## Team members The Members tab displays all members currently associated with the team. Clicking the **Add new member** button allows you to onboard teammates. You can remove team members through the menu (represented by the three dots) next to the member name. ![Teams members](https://media.docs.plane.so/teams/team-members.webp#hero-tr) ## Team comments Add comments to collaborate with your team and to discuss progress, blockers, or updates. ![Teams info](https://media.docs.plane.so/teams/team-comments.webp#hero-tr) ## Team activity feed Access the activity log for a history of changes made to the team, ensuring transparency and accountability. ![Teams info](https://media.docs.plane.so/teams/team-activity.webp#hero-tr) *** Teamspaces is your answer to scattered collaboration. It's where your team members and their work come together in perfect harmony. No more switching between multiple views or losing track of who's doing what – everything your team needs is right here in one organized space. --- --- url: 'https://docs.plane.so/core-concepts/projects/milestones.html' description: >- Align work items toward shared completion dates with milestones. Track progress on quarterly objectives, product launches, and strategic initiatives in Plane. --- # Milestones Milestones provide a layer to align work items toward shared completion dates, helping teams focus on strategic objectives and critical deliverables. Whether tracking quarterly goals, product launches, or major feature releases, milestones give you visibility into progress and ensure teams stay on track. ## Set up milestones Workspace and project admins can turn on the Milestones feature in the project. ![Enable Milestones](https://media.docs.plane.so/milestones/set-up-milestones.webp#hero) To enable milestones in your project: 1. Go to **Project Settings → Features**. 2. Toggle on **Milestones** under the **Work management** section. 3. A **Milestones** section will appear in your project's Overview page. ## Create a milestone ![Create Milestones](https://media.docs.plane.so/milestones/create-milestone.webp#hero) From your project's Overview page: 1. Scroll down to the **Milestones** section. 2. Click **Create** or the **+** icon to add a new milestone. 3. Enter the milestone details: * Title: Name your milestone (e.g., "Q4 Launch", "MVP Release"). * Description: Add context about the milestone's purpose and goals. * Target date: Set the completion deadline. * Link work items: Associate relevant work with the milestone. 4. Click **Create** to save your milestone. ## Manage milestones ### Track progress ![Manage Milestones](https://media.docs.plane.so/milestones/manage-milestone.webp#hero) Each milestone displays: * Completion percentage: Based on linked work items. * Target date: Deadline with visual indicators for approaching or overdue milestones Click on a milestone to expand and see all linked work items. The progress bar updates automatically as work items are completed or cancelled. ### View milestones in Timeline layout Milestones appear in the Timeline layout as vertical dashed lines at their due date. Hover over it to reveal a diamond marker with the milestone name, progress percentage, and linked work item count. ![Milestone indicator in Timeline](https://media.docs.plane.so/milestones/milestone-indicator.webp#hero) This helps you quickly identify whether work is on track to meet milestone deadlines and spot potential scheduling conflicts. ### Link work items You can link work items to milestones in two ways: **From the milestone**\ Click **Link work items** and select work items from your project. **From the work item**\ Open any work item and assign it to a milestone from the properties panel. ![Link work items](https://media.docs.plane.so/milestones/link-work-items.webp#hero) ### Edit or delete milestones Update milestone details anytime: * Modify the title, description, or target date. * Adjust linked work items. * Track metrics and progress indicators. * Click the ⋯ menu for additional options. --- --- url: 'https://docs.plane.so/releases.html' description: >- Group work items under named versions, track delivery progress, and publish changelogs to keep your team aligned on what ships and when. --- # Workspace Releases A release is how you communicate what your team is shipping and when. It groups work items from across your workspace into a named, versioned deliverable — with a target date, a lead, a changelog, and a clear status that tells everyone whether this version is in progress, out the door, or cancelled. ![Enable releases](https://media.docs.plane.so/releases/enable-releases.webp#hero) These workspace releases live at the workspace level, so a single release can pull in work items from multiple projects. A release for "v2.3.0" might include a backend fix from your API project, a UI change from your web project, and a docs update from your content project, all tracked together in one place. Plane also offers **project releases**, a version of the same feature scoped to a single project and enabled per project. If you want to group and ship one project's work on its own, see [Project releases](/projects/project-releases). Everything on this page about creating, scoping, and shipping a release applies to both; the difference is only their scope. This is the key distinction between releases and cycles. Cycles are sprint containers - time-boxed, project-scoped, for managing ongoing development. Releases are version containers - for grouping and communicating deliverables across projects, regardless of which cycle the work was done in. ## Set up releases for your workspace Releases must be enabled at the workspace level before anyone can use them. 1. Go to **Workspace Settings → Releases**. 2. Toggle on **Enable Releases**. Once enabled, workspace members have view access to releases in the sidebar. Owners and Admins can create, edit, and delete them. ### Manage release tags Tags are version identifiers shared across all releases in the workspace. Create them before you start creating releases, or add them as needed. **To create a tag:** 1. Go to **Workspace Settings → Releases → Release tags**. 2. Click **Add Tag**. 3. Enter a version string (e.g., `v2.3.0`). 4. Save. **To edit or delete a tag:** 1. Go to **Workspace Settings → Releases → Release tags**. 2. Click **···** on the tag row and select **Edit tag** or **Delete tag**. Deleting a tag removes it from any releases it was assigned to. ### Manage labels Labels let you categorize releases across the workspace - for example by team, platform, or release type. **To create a label:** 1. Go to **Workspace Settings → Releases → Labels**. 2. Click **Add Label**. 3. Enter a name and choose a color. 4. Save. **To reorder labels:** Drag the label rows into the order you want. **To edit or delete a label:** 1. Go to **Workspace Settings → Releases → Labels**. 2. Click **···** on the label row and select **Edit label** or **Delete label**. ## Create a release ![Create Releases](https://media.docs.plane.so/releases/create-releases.webp#hero) 1. Go to **Releases** in the workspace sidebar. 2. Click **Add Release**. 3. Fill in the release details: | Field | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | Identifies the release in the list and throughout the workspace. Release names must be unique within the workspace. | | **Description** | A rich text field for context - background, goals, or any notes the team needs before the work starts. | | **Status** | Tracks where the release is in its lifecycle. Values: Unreleased (default), Released, or Cancelled. | | **Tag** | A version identifier - for example, `v2.3.0` or `2024-Q4`. Tags are shared across all releases in the workspace. A release can have one tag. | | **Labels** | Let you categorize and organize releases. A release can have multiple labels. | | **Target date** | The planned release date - when you intend to ship. This is separate from the actual release date, which you can record once the work is done. | | **Lead** | The person responsible for the release. One user, visible in the release list. | 4. Click **Create Release**. You'll land on the release detail page, where you can start adding scope and writing the changelog. ## Work with a release Each release has three tabs: **Overview**, **Scope**, and **Changelog**. ### Overview The Overview tab shows the release description, all selected properties, and a live progress tracker. The progress bar fills proportionally as work items in the release are completed. Counters display completed work items (e.g., 18/22 - 82%), pending work items, and cancelled work items. Click any property chip - Tag, Label, Lead, or Target date - to edit it inline. Click **Click to add description** to write or update the release description. ![Release overview](https://media.docs.plane.so/releases/release-overview.webp#hero) #### Track progress Plane tracks three counts for every release based on the current state of linked work items: * **Completed work items** - work items whose state group is Completed * **Cancelled work items** - work items whose state group is Cancelled * **Pending work items** - everything else (Backlog, Unstarted, Started) These update automatically as your team moves work items through states. The progress indicator in the release list and on the Overview tab reflects the completed count against the total. Plane does not automatically change a release's status when all work items are completed. You mark the release as Released manually when you're ready. #### Release status A release moves through three statuses that reflect where it is in its lifecycle: * **Unreleased** - the default status when a release is created. Work is still in progress, and the scope and changelog are being built out. * **Released** - the release has shipped. Use this to mark the release as complete and signal to your team that it's out. * **Cancelled** - the release was abandoned. Use this when a planned release is no longer going forward, so the scope and history are preserved without cluttering your active releases. Click the status chip on the Overview tab to change it. The Releases list groups releases by their status, so updating this keeps your list organized and makes it easy to see what's active, shipped, or cancelled. You can also set the actual release date here to record when the version shipped. Cancelled releases remain in the list and all their data is preserved. Work items linked to a cancelled release are not affected. ### Scope The scope of a release is the set of work items it contains - everything your team needs to ship for this version. Work items come from any project in the workspace. There is no restriction to a single project. ![Release scope](https://media.docs.plane.so/releases/release-scope.webp#hero) Click **Add work items** to search and attach items by title or ID. Work items from any project in the workspace can be scoped to a release. To remove an item, hover over it and click the remove icon. #### Add work items to a release 1. Open the release and go to the **Scope** tab. 2. Click **Add work items**. 3. Search for work items by name or identifier. 4. Select the items you want to include. 5. Click **Add selected work items**. You can add work items from any project in the workspace. #### Remove a work item from a release 1. Open the release and go to the **Scope** tab. 2. Find the work item you want to remove. 3. Click the **···** menu on the work item row and select **Remove from release**. The work item remains in its project - only the link to the release is removed. A work item's existing state drives the progress calculation automatically - you don't need to mark anything as "done in release" separately. Adding a work item to a release does not move it, reassign it, or change its state. It creates a link. The work item stays in its project, continues through its normal workflow, and appears in the release's Scope view alongside everything else you're tracking for this version. Removing a work item from a release removes the link only. The work item remains in its project. ### Changelog The **Changelog** tab is a separate rich text document for recording what changed in this version - new features, fixes, breaking changes, anything you want to communicate to users or stakeholders. It's independent from the description and intended as the outward-facing record of the release. Edit it any time before or after shipping. The changelog is blank by default. ![Release changelog](https://media.docs.plane.so/releases/release-changelog.webp#hero) The editor supports all the same [blocks](/core-concepts/pages/editor-blocks) available in Pages and Wiki. Changes save automatically as you type, and the changelog is visible to all workspace members who can access the release. :::tip Use the Scope tab to audit completed work items, then use the Changelog tab to write polished, user-facing notes based on that list. ::: ## Work with releases from a work item ### The Releases property Every work item has a **Releases** property in its detail panel, in the same section as Cycle and Module. It works in both directions - you can link a work item to a release from the work item itself, not just from the Releases page. Whatever you do from either side produces the same result: a link between the work item and the release. A work item can belong to more than one release. If you're shipping the same fix in both `v2.3.1` (a patch) and `v3.0.0` (the next major), you can add both releases to the same work item. The work item appears in the scope of each release and counts toward the progress of each. The Releases property is only visible when releases are enabled for your workspace. If you don't see it in the detail panel, check that releases have been turned on in **Workspace Settings → Releases**. #### Assign a release from the work item detail panel 1. Open the work item. 2. In the sidebar, find the **Releases** property under the project structure section. 3. Click the property to open the release picker. 4. Search for or select the release you want to link. 5. The link is saved immediately. To link multiple releases, open the picker again and select another release. Each selection adds to the list without removing the previous ones. #### Remove a release from the work item detail panel 1. Open the work item. 2. In the sidebar, find the **Releases** property. 3. Click on the release you want to remove. 4. Deselect it from the picker. Removing the release from the work item is the same as removing the work item from the release's Scope tab - the work item remains in its project, unchanged. #### Assign a release inline from list, board, and table layouts You do not need to open the detail panel to assign a release. In any project view, you can update the Releases property directly on the work item row or card. **In list layout**: Click the Releases property on the work item row. If the column is not visible, enable it from **Display → Properties → Releases**. **In table layout**: Click the Releases cell in the work item row. The release picker opens inline. Add or remove releases without leaving the spreadsheet. **In board (kanban) layout**: Click the Releases indicator on the work item card. If releases are not showing on cards, enable them from **Display → Properties → Releases**. ### The Release picker custom property There is a second, separate way releases can appear on a work item: as a **Release picker** custom property added to a work item type. When a workspace admin adds a Release picker property to a work item type in **Workspace Settings → Work Item Types**, work items of that type get a multi-select field for picking one or more releases. It looks and behaves like the built-in Releases property - searchable dropdown, multi-select - but it is a custom field, not a system field. For how to create a Release picker property on a work item type, see [Work item types](/work-items/project-work-item-types#add-custom-properties). ## Manage releases ### Edit a release 1. Go to **Releases** in the workspace sidebar. 2. Click **···** on the release row and select **Edit**, or open the release and update properties directly from the **Overview** tab. 3. Change name, status, dates, lead, tag, labels, or description as needed. ### Delete a release 1. Go to **Releases** in the workspace sidebar. 2. Click **···** on the release row and select **Delete**. 3. Confirm. Deleting a release removes it permanently. Work items that were linked to the release are not deleted - they remain in their projects. --- --- url: 'https://docs.plane.so/projects/project-releases.html' description: >- Group a single project's work items into named versions, track delivery progress, and publish a changelog, all within the project. --- # Project Releases Project releases let you group work items from **one project** into a named, versioned deliverable, track its progress, and publish a changelog. They are the project-scoped version of Plane's [Releases](/releases) feature: the same release model, but each release belongs to a single project and is managed from within that project. Use project releases when a project ships on its own cadence and you want its versions kept inside the project, rather than as workspace-wide releases that span several projects. ## Project releases vs workspace releases Both work the same way. The only difference is scope and where they live. | | Project releases | Workspace releases | | -------------------------------- | --------------------------------- | ------------------------------------- | | Scope | One project | The whole workspace | | Work items a release can contain | Only work items from that project | Work items from any project | | Where you manage them | The project's **Releases** tab | **Releases** in the workspace sidebar | | Enabled | Per project, in project settings | Per workspace, in workspace settings | If you need a single release to pull work from several projects at once, use [workspace releases](/releases) instead. ## Enable releases for a project Project releases are off until an admin turns them on for the project. 1. Go to **Project settings → Features**. 2. Find **Releases** and toggle it on ("Create releases in this project, add work items to them, and ship them together"). Once enabled, a **Releases** tab appears in the project, and work items in the project gain a Releases property. ## Where to find them Open the project and select the **Releases** tab. Releases are listed and grouped by status (Unreleased, Released, Cancelled). From here you create a release and open any release to work on it. ## Create and work with a release Creating a release, its **Unreleased / Released / Cancelled** lifecycle, the **Overview**, **Scope**, and **Changelog** tabs, the progress rollup, and the manually written changelog all behave exactly as they do for workspace releases. See [Releases](/releases) for the full walkthrough. A quick summary: * **Create** a release with a name, description, status, tag, labels, target date, and lead. Names are unique across the workspace. * **Overview** shows the release's properties and a live progress bar (completed, pending, and cancelled counts based on each work item's state). * **Scope** is the set of work items in the release. * **Changelog** is a separate rich-text document for your outward-facing release notes. It starts blank and is written by hand; Plane does not generate it from the work items. * **Status** is set manually. Marking a release **Released** does not happen automatically when all work is done, and you can record the actual release date at that point. ## Add work items (the key difference) A project release can only contain work items from its **own project**. When you open the release's **Scope** tab and click **Add work items**, the search is limited to that project. Trying to add a work item from another project is rejected. This is the one behavioral difference from workspace releases, which can pull work items from any project. Everything else about adding and removing scope is the same: adding a work item creates a link without moving or changing it, and removing it only removes the link. ## Link releases from a work item Work items in a release-enabled project have a **Releases** property in their detail panel, next to Cycle and Module, and as a column in the spreadsheet and board layouts. You can link a release from the work item instead of from the Scope tab, and a work item can belong to more than one release. In the release picker, releases are grouped into **Project releases** and **Workspace releases**, so you can tell which scope each one belongs to. For the full behavior of the Releases property, the separate **Release picker** custom property, and filtering work items by release including in [PQL](/core-concepts/issues/plane-query-language), see [Releases](/releases). ## Availability and permissions * Project releases require the project releases entitlement on your plan, and the per-project **Releases** feature toggle must be on. This entitlement is separate from workspace releases, so a workspace can have one, the other, or both. * Managing releases (create, edit, delete, change scope) follows your project role. Members with the release permissions in the project can manage them; others can view. --- --- url: 'https://docs.plane.so/core-concepts/stickies.html' description: >- Use Stickies in Plane to capture quick ideas, reminders, and notes without leaving your workspace. --- # Stickies Imagine having a digital bulletin board that follows you through every project and task. Stickies is your personal memo pad, seamlessly integrated into the Plane interface, ensuring that no brilliant idea or critical reminder ever gets lost in the shuffle. ![Stickies](https://media.docs.plane.so/stickies/stickies.webp#hero) ## Use Stickies You'll find the sticky note icon at the bottom right of your screen. Adding a new sticky note is incredibly straightforward. Click the **Add Sticky** button on the floating bar, and you're presented with a blank canvas ready to capture whatever is on your mind. Whether it's a quick task reminder, a project insight, or a creative concept, Stickies provides the perfect space to record it. The floating bar also shows your most recent sticky note, allowing instant recall. The **All stickies** button opens a modal with every sticky note you've created, so you can organize, review, and manage your collection with ease. ## Customize your notes Each sticky note offers basic customization options: * Color-coding to visually categorize or prioritize * Formatting options to emphasize key points * A clean, intuitive interface that adapts to your personal style *** Stickies is more than just a note-taking tool—it's your personal productivity partner, designed to keep your ideas visible, your reminders prominent, and your workflow smooth. --- --- url: 'https://docs.plane.so/core-concepts/issues/layouts.html' description: >- Use layouts to visualize, organize, and manage your work items based on your team's workflow preferences. --- # Layouts Plane provides five flexible layouts to view and manage your work items, tailored to suit different workflows. Each layout offers unique benefits, so you can easily switch perspectives and optimize your team’s productivity. ## List layout The List layout is a straightforward, text-based view ideal for scanning and organizing tasks. It displays all your work items in an ordered list, which can be grouped by properties like priority, assignee, or labels. You can also drag and drop tasks to adjust their positions. This layout is particularly useful for getting a quick snapshot of all project activities. ### Key features * **Grouping**: Group work items by properties such as priority or assignee. * **Hierarchy**: View parent-child work item relationships. * **Drag and Drop**: Rearrange tasks directly within the list. ## Board layout The Board layout resembles a Kanban board, with work items represented as cards in vertical columns. It’s perfect for visualizing work stages like Backlog, In Progress, or Done. ### Key features * **Column organization**: Define stages for workflows. * **Subgroups**: Subgroup tasks to add finer categorizations. * **Status updates**: Drag and drop cards between columns to reflect progress. ## Calendar layout The Calendar layout maps out your work items by their due dates. It's perfect for tracking deadlines and planning ahead. Only tasks with defined due dates are displayed, allowing you to focus on what’s due and when. ### Key features * **Date-based planning**: Displays work items based on their end dates. * **Drag and Drop**: Adjust due dates by moving tasks across the calendar. ## Table layout The Table layout offers a spreadsheet-like interface, great for bulk editing and analyzing detailed work item data. Each row represents a work item, and columns display attributes like assignee, priority, and dates. ### Key features * **Keyboard navigation**: Quickly update task properties. * **Bulk edits**: Modify multiple rows at once. ## Timeline layout The Timeline layout, similar to a Gantt chart, shows your project's progress over time. You can see how long tasks take, when they start and finish, and how they connect to each other. Tasks with start and end dates appear as bars, giving a clear picture of how work fits together. ### Key features * **Drag and drop**: Adjust start and end dates directly. * **Critical path visualization**: Identify crucial tasks that could impact deadlines. * **Dependencies**: Link tasks to define order and precedence. See [Dependencies in Timeline](/core-concepts/issues/timeline-dependency) for more info. ## Choose the right layout Each layout offers a different lens to view your work. Switch between them to find the perspective that helps your team work best. * Use **List** for simplicity and quick overviews. * Choose **Board** for workflows that need a visual pipeline. * Try **Calendar** for deadline-focused planning. * Opt for **Table** when handling detailed data or performing bulk updates. * Go for **Timeline** when managing dependencies or seeing the big picture. --- --- url: 'https://docs.plane.so/core-concepts/issues/visualise_filter.html' description: Learn how to filter work items in Plane. --- # Work Item Filters Filters help you find exactly the work items you need by applying conditions across multiple fields. Whether you're looking for overdue tasks assigned to your team or tracking items in specific states, filters give you the control to slice through your work items with precision. With rich filters, you can now choose from different operators for each field type, giving you even more control over how you filter your work items. ![Filter work items](https://media.docs.plane.so/issues/filter-work-items.webp#hero) ## How to use filters Filters live in their own dedicated row below the main toolbar, making them always accessible while you work with your work items. ### Basic filtering To start filtering your work items: 1. Click the Filters icon button to open a dropdown with all the fields. 2. Select any field (State, Priority, Assignee, etc.) to add a filter condition. 3. Choose your operator from the dropdown (like "is", "is not", "after", etc.). 4. Select one or more values you want to filter the field by. 5. Your work items update instantly to match your criteria. ### Build complex filters You can combine multiple filters to create powerful queries: **Find urgent items for your team:** * Set **Priority** → **is** → `High` * Add **Assignee** → **in** → \[Select team members] * Add **State** → **is not** → `Done` **Track overdue work:** * Set **Target date** → **before** → \[Select date] * Add **State group** → **is not** → `Completed` **Review items without assignments:** * Set **Assignee** → is → \[Leave empty] * Add State → in → \[Backlog, To Do] ### Work with date filters Date filters are particularly powerful for project management: **This week's deliverables:** * Set **Target date** → **between** → \[\[Select date range] **Items starting soon:** * Set **Start Date** → **after or on** → \[Select date] * Add **Start Date** → **before or on** → \[Select date] **Overdue items:** * Set **Target date** → **before** → \[Select date] * Add **State group** → **is not** → \[Completed] ## Manage your filters * **Clear specific filters:**\ Click the **X** next to any filter condition to remove just that filter. * **Clear all filters:**\ Use the **Clear all** button to start fresh. * **Save your view:**\ Once you've built the perfect filter combination, use **Save view** to preserve your configuration as a custom view for easy access in the future. Views allow you to quickly switch between different perspectives, such as a high-priority tasks dashboard or a specific team’s workload. See [Views](/core-concepts/views) for more details. ## Filter operators reference Each field supports different operators to give you precise control over your filtering. ::: info Operator availability **Free plan**\ You get essential filtering with the `is` operator, plus `between` for date fields. This covers the most common filtering needs. **Paid plans**\ Unlock advanced filtering with additional operators including `is not`, `is not any of`, `after`, `before`, and more specialized conditions. We will be adding more conditions here such as `not in`, `contains`, `is empty`, etc. . ::: ### Title Filter work items by their title text to find specific work items. | Operator | Description | Use case | | ------------------ | --------------------------- | ----------------------------------- | | `is` | Exact title match | Title is exactly "Login bug" | | `is not` | Not exact title match | Title is not "Login bug" | | `contains` | Title contains text | Title contains "authentication" | | `does not contain` | Title does not contain text | Title does not contain "deprecated" | ### Milestone Filter work items by their associated milestone to track progress toward major goals or releases. | Operator | Description | Use case | | --------------- | ------------------------------ | -------------------------------- | | `is` | Exactly this milestone | Items in Q1 Launch milestone | | `is any of` | Any of these milestones | In Q1 Launch or Beta Release | | `is not` | Not this specific milestone | Not in Q1 Launch | | `is not any of` | Not in any of these milestones | Not in Q1 Launch or Beta Release | | `is empty` | No milestone assigned | Items without any milestone | ### Type Filter by custom work item types, such as Bug, Feature, or Task. | Operator | Description | Use case | | --------------- | ---------------------------- | ------------------------------------ | | `is` | Exactly matches one type | Show only work items with type *Bug* | | `is any of` | Matches any of several types | Bugs or Tasks only | | `is not` | Excludes one type | Everything except Bug | | `is not any of` | Excludes several types | Not Bugs or Tasks | ### State View work items based on their current state, such as Todo, In Progress, or Done. | Operator | Description | Use case | | --------------- | ----------------------------- | ---------------------- | | `is` | Exactly matches one state | Only items In Progress | | `is any of` | Matches any of several states | Todo or In Progress | | `is not` | Excludes one state | Everything except Done | | `is not any of` | Excludes several states | Not Done or Cancelled | ### State Group View all, active or backlog work items. | Operator | Description | Use case | | --------------- | ----------------------------- | ---------------------------- | | `is` | Exactly matches one group | Show only Started work items | | `is any of` | Matches any of several groups | Backlog or Unstarted | | `is not` | Excludes one group | Everything except Backlog | | `is not any of` | Excludes several groups | Not Backlog or Cancelled | ### Assignees Focus on work items assigned to specific team members to track workloads or identify pending tasks. | Operator | Description | Use case | | --------------- | ------------------------------ | ------------------------------- | | `is` | Exactly matches one person | Find work assigned to Sarah | | `is any of` | Matches any of multiple people | Show work for the frontend team | | `is not` | Excludes one person | Hide items assigned to John | | `is not any of` | Excludes multiple people | Not assigned to John or Sarah | | `is empty` | No assignee | Unassigned work items | ### Priority Filter work items by their priority level (e.g., Urgent, High, Medium, Low) to focus on the most critical tasks. | Operator | Description | Use case | | --------------- | --------------------------------- | ------------------------------ | | `is` | Exactly matches one priority | Only high priority items | | `is any of` | Matches any of several priorities | High or medium priority | | `is not` | Excludes one priority | Everything except low priority | | `is not any of` | Excludes several priorities | Not low or none priority | ### Mentions Filter tasks where you or another team member has been mentioned to ensure no critical tasks are missed. | Operator | Description | Use case | | --------------- | ------------------------------ | ---------------------------- | | `is` | Exactly matches one person | Items mentioning Sarah | | `is any of` | Matches any of multiple people | Mentioning team leads | | `is not` | Excludes one person | Not mentioning John | | `is not any of` | Excludes multiple people | Not mentioning John or Sarah | | `is empty` | No mentions | Items with no mentions | ### Label Filter work items based on custom tags, such as "Frontend", or "Marketing". | Operator | Description | Use case | | --------------- | ------------------------- | ------------------------ | | `is` | Exact label match | Label exactly "bug" | | `is any of` | Matches any of the Labels | frontend or backend | | `is not` | Not exact label match | Label not exactly "bug" | | `is not any of` | Excludes several labels | Not frontend or backend | | `is empty` | No labels | Items without any labels | ### Cycle View work items tied to specific cycles to monitor progress within a timeframe. | Operator | Description | Use case | | --------------- | -------------------------- | ---------------------- | | `is` | Exactly this cycle | Items in Sprint 23 | | `is any of` | Any of these cycles | In Sprint 23 or 24 | | `is not` | Not this specific cycle | Not in Sprint 23 | | `is not any of` | Not in any of these cycles | Not in Sprint 23 or 24 | | `is empty` | No cycle assigned | Items not in any cycle | ### Module Filter work items by their associated module to analyze related tasks together. | Operator | Description | Use case | | --------------- | --------------------------- | --------------------------------------------- | | `is` | Exactly this module | Items in Authentication module | | `is any of` | Any of these modules | In API development or Data management modules | | `is not` | Not this specific module | Not in Authentication module | | `is not any of` | Not in any of these modules | Not in API or Data management | | `is empty` | No module assigned | Items not in any module | ### Start date, Due date, Created at, and Updated at Filter work items by start dates to view tasks that are planned or already in progress, and by target dates to track upcoming deadlines or overdue tasks. For even more flexibility, you can specify a custom date range to focus on a specific timeframe. | Operator | Description | Use case | | ------------------ | ---------------------- | -------------------------------------------- | | `is` | Exactly this date | Items due today | | `is not` | Not this specific date | Not due today | | `before` | Earlier than this date | Due before Monday | | `not before` | This date or later | Not due before Monday (due Monday or later) | | `before or on` | This date or earlier | Due Monday or earlier | | `not before or on` | Later than this date | Not due Monday or earlier (due after Monday) | | `after` | Later than this date | Due after Friday | | `not after` | This date or earlier | Not due after Friday (due Friday or earlier) | | `after or on` | This date or later | Due Friday or later | | `not after or on` | Earlier than this date | Not due Friday or later (due before Friday) | | `between` | Within date range | Due this week | | `not between` | Outside date range | Not due this week | | `is empty` | No date set | Items without start date or target date | ### Created by Identify work items created by specific individuals. | Operator | Description | Use case | | --------------- | ------------------------------ | ------------------------------- | | `is` | Exactly matches one person | Items created by Sarah | | `is any of` | Matches any of multiple people | Show work for the frontend team | | `is not` | Excludes one person | Not created by John | | `is not any of` | Excludes multiple people | Not created by John or Sarah | ### Custom properties Filter work items by any custom properties defined for each work item type in your project. The available operators depend on the property type. **Text properties** | Operator | Description | Use case | |----------|-------------|----------| | `is` | Exact text match | Name is exactly "Login feature" | | `is not` | Not exact text match | Name is not "Login feature" | | `contains` | Text contains value | Description contains "authentication" | | `does not contain` | Text does not contain value | Description does not contain "deprecated" | | `is empty` | No text entered | Items with empty description field | **Number properties** | Operator | Description | Use case | |----------|-------------|----------| | `is` | Exactly this number | Story points is 8 | | `is not` | Not this number | Estimated hours is not 5 | | `less than` | Below this value | Priority score less than 50 | | `not less than` | This value or above | Complexity not less than 3 | | `less than or equal` | This value or below | Effort less than or equal 10 | | `not less than or equal` | Above this value | Risk level not less than or equal 5 | | `greater than` | Above this value | Technical complexity greater than 3 | | `not greater than` | This value or below | Customer impact not greater than 7 | | `greater than or equal` | This value or above | Business value greater than or equal 50 | | `not greater than or equal` | Below this value | Severity not greater than or equal 8 | | `between` | Within numeric range | Estimated hours between 5 and 10 | | `not between` | Outside numeric range | Priority score not between 20 and 40 | | `is empty` | No number entered | Items without impact score | **Dropdown properties** | Operator | Description | Use case | |----------|-------------|----------| | `is` | Exactly this option | Severity is Critical | | `is any of` | Any of these options | Status is Approved or Pending | | `is not` | Not this option | Category is not Bug | | `is not any of` | Not any of these options | Environment not Staging or Development | | `is empty` | No option selected | Items without severity set | **Boolean properties** | Operator | Description | Use case | |----------|-------------|----------| | `is` | Matches boolean value | Is blocking is True | | `is not` | Does not match boolean value | Requires review is not False | **Date properties** | Operator | Description | Use case | |----------|-------------|----------| | `is` | Exactly this date | Review date is today | | `is not` | Not this specific date | Launch date is not tomorrow | | `before` | Earlier than this date | Deadline before next Monday | | `not before` | This date or later | Start date not before January 1 | | `before or on` | This date or earlier | Due date before or on Friday | | `not before or on` | Later than this date | Planned date not before or on March 15 | | `after` | Later than this date | Completion date after Q1 end | | `not after` | This date or earlier | Target date not after June 30 | | `after or on` | This date or later | Delivery date after or on release day | | `not after or on` | Earlier than this date | Milestone not after or on sprint end | | `between` | Within date range | Review period between Jan 1 and Jan 31 | | `not between` | Outside date range | Availability not between holidays | | `is empty` | No date set | Items without start date or target date | **Member picker properties** | Operator | Description | Use case | |----------|-------------|----------| | `is` | Exactly this member | Reviewer is Sarah | | `is any of` | Any of these members | Code owner is John or Emily | | `is not` | Not this member | Quality checker is not Mike | | `is not any of` | Not any of these members | Approver not John or Sarah | | `is empty` | No member selected | Items without reviewers assigned | **URL properties** | Operator | Description | Use case | |----------|-------------|----------| | `is` | Exact URL match | Design link is exactly \[URL] | | `is not` | Not this exact URL | Documentation link is not \[URL] | | `contains` | URL contains text | Reference URL contains "figma.com" | | `does not contain` | URL does not contain text | External link does not contain "staging" | --- --- url: 'https://docs.plane.so/core-concepts/issues/plane-query-language.html' description: Filter work items using text-based queries with Plane Query Language (PQL). --- # Plane Query Language (PQL) Plane Query Language (PQL) lets you filter work items using text-based queries. Write structured expressions to quickly find exactly what you need, combine conditions with logic, call built-in functions, and sort and limit the results. ![PQL editor](https://media.docs.plane.so/issues/pql-editor.webp#hero) ## Use the PQL editor Plane includes an interactive editor that helps you build queries. To switch to PQL mode, click **PQL** in the filter bar. When you start typing in the PQL field: 1. A dropdown shows available **fields** and **functions** 2. After selecting a field, you see **operators** 3. Then you choose or type **values** 4. Continue building your query using **AND** or **OR** This guided experience lets you construct queries without memorizing syntax. ## Generate a filter with AI Instead of writing PQL by hand, you can describe the filter you want in plain language and let Plane AI translate it into a PQL query for you. In the advanced (PQL) filter view, look for the AI filter input with the prompt **"Describe your filter in plain language..."** 1. Type what you want in natural language, for example "high priority bugs assigned to me that are overdue." 2. Press **Enter**, or click the submit button. 3. Plane AI generates the matching PQL query, fills it into the PQL editor, and applies it. The generated query appears in the PQL editor as normal PQL, so you can review it, tweak it by hand, and save it as a view like any other query. ### Examples | You type | Plane AI produces a query like | | ----------------------------------------------- | ---------------------------------------------------------------------------- | | "urgent items with no assignee" | `priority = Urgent AND hasNoAssignee()` | | "everything due this week in the current cycle" | `dueDate BETWEEN startOfWeek() AND endOfWeek() AND cycle IN (activeCycle())` | | "bugs Priya is working on that aren't done" | `type = Bug AND assignee = Priya AND stateGroup IN (openStates())` | When your description names people, cycles, labels, or other entities, Plane AI resolves them to the actual items in your workspace so the query filters correctly and reads with their real names. If you are filtering inside a project, the AI scopes the query to that project. Otherwise it generates a workspace-level query. If your description is too ambiguous or can't be turned into a valid filter, you'll see "Could not generate a PQL query from the given input." Try rephrasing with more specific terms, or build the filter manually. Generating filters with AI requires [Plane AI to be enabled](/ai/plane-ai#enable-plane-ai-for-a-workspace) for your workspace. ## Query structure PQL queries follow a simple pattern: ``` Field Operator Value ``` Example: ``` priority = High ``` This returns all work items where priority is High. You can also combine multiple conditions using the logical operators `AND`, `OR`, and `NOT`. **Using AND** ``` type = Bug AND priority = High ``` This returns work items that match both conditions. **Using OR** ``` state = Todo OR state = In Progress ``` This returns work items that match either condition. **Using NOT** ``` NOT hasNoAssignee() ``` This returns work items that do have an assignee. **Combined:** ``` (priority = High AND state in (Backlog, In Progress, Todo)) OR (type in (Bug, Task, Improvements) AND assignee in (Ethan, Parker, Amanda)) ``` ## Sort and limit results You can sort results and cap how many are returned by adding `ORDER BY` and `LIMIT` clauses to the end of a query. ``` priority = High ORDER BY dueDate ASC LIMIT 20 ``` * **ORDER BY** sorts the results by a field. Add `ASC` (ascending, the default) or `DESC` (descending). * **LIMIT** caps the number of results returned. The maximum is 1000. Fields you can sort by: `priority`, `state`, `title`, `assignee`, `label`, `module`, `startDate`, `dueDate`, `createdAt`, `updatedAt`, `sortOrder`, `rank`. ## Save as view Once you've built your query, click **Save view** to preserve it for quick access later. See [Views](/core-concepts/views) for details. ## Where PQL works PQL is available wherever work items are listed: * Work items * Cycles * Modules * Views * Teamspace work items * Workspace views The exact fields available in the editor depend on what is enabled for the project or workspace you are filtering. For example, `cycle` and `module` appear where those features are on, and custom properties appear when your work item types define them. ## Fields reference ### Text search | Field | What it searches | | ------- | ----------------------------------------------------------------------- | | `title` | The work item title (name) only | | `text` | The work item title **and** description together, in a single condition | Use `text` when you want to match a term whether it appears in the title or the body of a work item. For example, `text ~ "login"` returns work items with "login" in the title or the description. ### Common fields | Field | Filters on | | ------------ | --------------------------------------------------------------- | | `type` | Work item type | | `state` | Workflow state | | `stateGroup` | State group (Backlog, Unstarted, Started, Completed, Cancelled) | | `priority` | Priority (Urgent, High, Medium, Low, None) | | `assignee` | Assigned members | | `label` | Labels applied | | `cycle` | Cycle membership | | `module` | Module membership | | `release` | Release the work item is linked to | | `milestone` | Milestone | | `mention` | Members mentioned in the work item | | `createdBy` | Who created the work item | | `project` | Project the work item belongs to | | `startDate` | Start date | | `dueDate` | Due date | | `createdAt` | Creation date | | `updatedAt` | Last updated date | ## Operators reference Each field supports different operators. The available operators depend on the field type. All operators available in PQL: | Operator | Meaning | | ------------- | -------------------------------------- | | `=` | Matches exactly | | `!=` | Does not match | | `~` | Contains the text | | `IN` | Matches any value in a set | | `NOT IN` | Matches none of the values in a set | | `<` | Less than / before | | `<=` | Less than or equal to / on or before | | `>` | Greater than / after | | `>=` | Greater than or equal to / on or after | | `BETWEEN` | Within a range | | `IS NULL` | The field has no value | | `IS NOT NULL` | The field has a value | The tables below show which operators apply to each field. ### id The `id` field matches a work item by its identifier (like `WEB-11`) or by its sequence number, and it supports comparisons as well as exact matches. | Operator | Description | | ----------------- | ------------------------------------------------- | | `=` | ID matches exactly | | `!=` | ID does not match | | `~` | Identifier contains text (partial match) | | `<` `<=` `>` `>=` | Sequence comparison | | `BETWEEN` | Sequence within a range | | `IN` | Any of the listed identifiers or sequence numbers | The value can take several forms: | Form | Meaning | Example | | --------------------- | --------------------------------------------- | ----------------------------------------------------------------- | | Identifier equality | Exact work item key | `id = "WEB-11"` | | Identifier comparison | Project-scoped sequence comparison | `id >= "WEB-11"` matches project `WEB` with sequence 11 or higher | | Bare integer | Sequence number only, in any project in scope | `id >= 10`, `id IN (1, 2, 3)` | | Contains | Partial identifier match | `id ~ "WEB"` | ### title | Operator | Description | | -------- | --------------------- | | `=` | Title matches exactly | | `!=` | Title does not match | | `~` | Title contains text | ### text | Operator | Description | | -------- | -------------------------------------------- | | `=` | Title or description matches the text | | `!=` | Title or description does not match the text | | `~` | Title or description contains the text | ### type | Operator | Description | | -------- | --------------------------------------- | | `IN` | Type is any of the specified values | | `NOT IN` | Type is not any of the specified values | | `=` | Type matches exactly | | `!=` | Type does not match | ### state | Operator | Description | | -------- | ---------------------------------------- | | `IN` | State is any of the specified values | | `NOT IN` | State is not any of the specified values | | `=` | State matches exactly | | `!=` | State does not match | ### stateGroup | Operator | Description | | -------- | ---------------------------------------------- | | `IN` | State group is any of the specified values | | `NOT IN` | State group is not any of the specified values | | `=` | State group matches exactly | | `!=` | State group does not match | ### assignee | Operator | Description | | ------------- | -------------------------------------------- | | `IN` | Assigned to any of the specified members | | `NOT IN` | Not assigned to any of the specified members | | `=` | Assigned to this member | | `!=` | Not assigned to this member | | `IS NULL` | No assignee | | `IS NOT NULL` | Has an assignee | ### priority | Operator | Description | | -------- | ------------------------------------------- | | `IN` | Priority is any of the specified values | | `NOT IN` | Priority is not any of the specified values | | `=` | Priority matches exactly | | `!=` | Priority does not match | ### mention | Operator | Description | | ------------- | --------------------------------------------- | | `IN` | Mentions any of the specified members | | `NOT IN` | Does not mention any of the specified members | | `=` | Mentions this member | | `!=` | Does not mention this member | | `IS NULL` | No mentions | | `IS NOT NULL` | Has mentions | ### label | Operator | Description | | ------------- | ----------------------------------------- | | `IN` | Has any of the specified labels | | `NOT IN` | Does not have any of the specified labels | | `=` | Has this label | | `!=` | Does not have this label | | `IS NULL` | No labels | | `IS NOT NULL` | Has at least one label | ### cycle | Operator | Description | | ------------- | ---------------------------------- | | `IN` | In any of the specified cycles | | `NOT IN` | Not in any of the specified cycles | | `=` | In this cycle | | `!=` | Not in this cycle | | `IS NULL` | Not in any cycle | | `IS NOT NULL` | In a cycle | ### module | Operator | Description | | ------------- | ----------------------------------- | | `IN` | In any of the specified modules | | `NOT IN` | Not in any of the specified modules | | `=` | In this module | | `!=` | Not in this module | | `IS NULL` | Not in any module | | `IS NOT NULL` | In a module | ### release | Operator | Description | | ------------- | ------------------------------------------- | | `IN` | Linked to any of the specified releases | | `NOT IN` | Not linked to any of the specified releases | | `=` | Linked to this release | | `!=` | Not linked to this release | | `IS NULL` | Not linked to any release | | `IS NOT NULL` | Linked to a release | The `release` field is available where the releases feature is enabled. Use it with the [`earliestUnreleasedRelease()`](#release-functions) value function, for example `release = earliestUnreleasedRelease()`. ### milestone | Operator | Description | | ------------- | -------------------------------------- | | `IN` | In any of the specified milestones | | `NOT IN` | Not in any of the specified milestones | | `=` | In this milestone | | `!=` | Not in this milestone | | `IS NULL` | No milestone | | `IS NOT NULL` | Has a milestone | ### startDate, dueDate, createdAt, updatedAt Date fields all support the same operators. | Operator | Description | | ------------- | -------------------------- | | `=` | Is this date | | `!=` | Is not this date | | `<` | Before this date | | `<=` | On or before this date | | `>` | After this date | | `>=` | On or after this date | | `BETWEEN` | Within the specified range | | `IS NULL` | No date set | | `IS NOT NULL` | A date is set | Date values can be literal dates or [date functions](#date-functions), for example `dueDate < today()` or `createdAt >= daysAgo(7)`. ### createdBy | Operator | Description | | -------- | ------------------------------------------- | | `IN` | Created by any of the specified members | | `NOT IN` | Not created by any of the specified members | | `=` | Created by this member | | `!=` | Not created by this member | ### Custom properties The available operators depend on the property type. #### Text | Operator | Description | | -------- | -------------------- | | `=` | Text matches exactly | | `!=` | Text does not match | | `~` | Text contains value | #### Number | Operator | Description | | --------- | --------------------------------------------- | | `=` | Number equals this value | | `!=` | Number does not equal this value | | `<` | Number is less than this value | | `<=` | Number is less than or equal to this value | | `>` | Number is greater than this value | | `>=` | Number is greater than or equal to this value | | `BETWEEN` | Number is within the specified range | | `IS NULL` | No number set | #### Dropdown | Operator | Description | | --------- | ----------------------------------------- | | `IN` | Option is any of the specified values | | `NOT IN` | Option is not any of the specified values | | `=` | Option matches exactly | | `!=` | Option does not match | | `IS NULL` | No option selected | #### Boolean | Operator | Description | | -------- | -------------------------- | | `=` | Value is true or false | | `!=` | Value is not true or false | #### Date | Operator | Description | | --------- | ---------------------------------- | | `=` | Date is this date | | `!=` | Date is not this date | | `<` | Date is before this date | | `<=` | Date is on or before this date | | `>` | Date is after this date | | `>=` | Date is on or after this date | | `BETWEEN` | Date is within the specified range | | `IS NULL` | No date set | #### Member picker | Operator | Description | | --------- | ----------------------------------------- | | `IN` | Member is any of the specified values | | `NOT IN` | Member is not any of the specified values | | `=` | Member matches exactly | | `!=` | Member does not match | | `IS NULL` | No member selected | #### URL | Operator | Description | | -------- | ------------------- | | `=` | URL matches exactly | | `!=` | URL does not match | | `~` | URL contains text | ## Built-in functions PQL includes functions that cover common scenarios. Type `(` after a field, or start typing a function name, and the editor suggests the ones that fit. Functions come in two kinds: * **Value functions** return a value or a list. You use them inside a condition, on the right side of a comparison or with `IN`. * **Condition functions** are standalone true/false checks. You use them on their own and combine them with `AND`, `OR`, and `NOT`. ## Value functions ### Date functions Return a date. Use them on the right side of a date-field condition. | Function | Returns | | ----------------------------------- | ----------------------------- | | `now()` / `today()` | Today's date | | `startOfDay()` / `endOfDay()` | Start / end of today | | `startOfWeek()` / `endOfWeek()` | Start / end of this week | | `startOfMonth()` / `endOfMonth()` | Start / end of this month | | `startOfYear()` / `endOfYear()` | Start / end of this year | | `daysAgo(n)` / `daysFromNow(n)` | n days before / after today | | `weeksAgo(n)` / `weeksFromNow(n)` | n weeks before / after today | | `monthsAgo(n)` / `monthsFromNow(n)` | n months before / after today | Examples: ``` dueDate BETWEEN startOfWeek() AND endOfWeek() createdAt >= daysAgo(7) ``` ### User functions Return a user or a list of users. Use `currentUser()` on the right of `=`; use the list-returning ones with `IN`, or pass them into a user function such as `votedBy(...)`. | Function | Returns | | ----------------------------------------- | ---------------------------------------------------- | | `currentUser()` | The person running the query | | `inactiveUsers()` | Deactivated workspace members | | `workspaceMembers()` | All active members of the workspace | | `membersOf("project:<id>")` | Active members of the given project | | `membersOf("teamspace:<id>")` | Active members of the given teamspace | | `userPropertyEquals("property", "value")` | Members whose profile matches a property (see below) | `userPropertyEquals` accepts one of these properties: `role`, `email`, `emailDomain`, `displayName`, `timezone`, `isActive`, `isBot`. If a people function resolves to nobody, the surrounding condition matches zero work items rather than being ignored. Examples: ``` assignee = currentUser() assignee IN (inactiveUsers()) assignee IN membersOf("project:1a2b3c4d-...") assignee IN userPropertyEquals("role", "admin") votedBy(workspaceMembers()) ``` ### Cycle functions Return a list of cycles. Use them with `IN`. | Function | Returns | | ------------------- | ---------------------------------------- | | `activeCycle()` | The cycle active today | | `completedCycles()` | Cycles whose end date has passed | | `upcomingCycles()` | Cycles whose start date is in the future | Example: ``` cycle IN (activeCycle()) ``` ### State group functions Return a list of state groups. Use them with `IN` on `stateGroup`. | Function | Returns | | ---------------- | -------------------------------------- | | `openStates()` | Backlog, unstarted, and started groups | | `closedStates()` | Completed and cancelled groups | | `activeStates()` | Unstarted and started groups | Example: ``` stateGroup IN (openStates()) ``` ### Release functions Return a release. Use them on the right side of a `release` condition. Available where the releases feature is enabled. | Function | Returns | | ----------------------------- | ---------------------------------------------------------------------------- | | `earliestUnreleasedRelease()` | The next unreleased release by target date (the earliest one still upcoming) | Example: ``` release = earliestUnreleasedRelease() ``` ## Condition functions Standalone checks that return true or false. Combine them with `AND`, `OR`, and `NOT`. Arguments shown as `"user"`, `"date"`, `"text"`, or `n` are values you supply; you pick users and dates from the editor's suggestions. Functions that take a user (such as `votedBy`, `commentedBy`, `attachedBy`, or `lastCommentBy`) accept a single member, or a list-returning [people function](#people-functions) to match a whole group at once. Use `currentUser()` for the person running the query, `workspaceMembers()` for everyone, or `membersOf("project:<id>")` for a project, for example `votedBy(currentUser())` or `votedBy(workspaceMembers())`. ### Structure and relationships Relation functions each take one or more work item identifiers, for example `blockedBy("WEB-11", "WEB-20")`. | Function | Matches work items that | Example | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | `isTopLevel()` | Are not a sub-work item (no parent) | `isTopLevel()` | | `isSubWorkItem()` | Are a sub-work item (have a parent) | `isSubWorkItem()` | | `hasChildren()` | Have at least one sub-work item | `hasChildren()` | | `hasRelations()` | Have at least one relation to another work item | `hasRelations()` | | `blockedBy("id", …)` | Are blocked by the given items | `blockedBy("WEB-11")` | | `blocks("id", …)` | Block the given items | `blocks("WEB-11")` | | `linkedTo("id", …)` | Are related to the given items | `linkedTo("WEB-11")` | | `duplicateOf("id", …)` | Are marked duplicate of the given items | `duplicateOf("WEB-11")` | | `childOf("id", …)` | Are a child of the given items | `childOf("WEB-11")` | | `parentOf("id", …)` | Are a parent of the given items | `parentOf("WEB-11")` | | `linkedToAny("id", …)` | Are connected to any of the given items through one relation hop (any relation type, both directions; hierarchy not walked) | `linkedToAny("WEB-11")` | | `linkedToAll("id", …)` | Same as `linkedToAny`, and also walks parent/child (sub-work-item and epic) links | `linkedToAll("WEB-11", "WEB-20")` | | `linkedToAnyRecursive("id", …[, depth])` | Multi-hop `linkedToAny`; optional trailing depth (default 5, maximum 10) | `linkedToAnyRecursive("WEB-11", 3)` | | `linkedToAllRecursive("id", …[, depth])` | Multi-hop `linkedToAll`, with the same depth rules | `linkedToAllRecursive("WEB-11")` | | `workItemPicker("name"[, "id", …])` | Whose issue-picker [custom property](#custom-properties) (matched by display name) has any value, or points at one of the given items | `workItemPicker("Related", "WEB-11")` | Recursive traversals stop at the depth you set (5 by default, 10 at most) and are capped at a maximum number of work items. `workItemPicker("Related")` with no ids matches any work item whose "Related" picker has a value. ### Rollups `aggregate("scope", "field", "agg", "threshold")` matches a work item when a numeric rollup meets a comparison. It takes exactly four arguments: | Argument | Allowed values | | ----------- | ------------------------------------------------------------------------------------ | | `scope` | `children` (roll up the work item's sub-work items) or `self` (the work item itself) | | `field` | `estimate` (points-type estimates only) or `worklog` (logged time, in **minutes**) | | `agg` | `sum`, `avg`, `min`, `max`, or `count` | | `threshold` | A comparison such as `"> 10"` or `">= 2.5"`. A bare number is treated as `>= n`. | ``` aggregate("children", "estimate", "sum", "> 10") aggregate("self", "worklog", "sum", ">= 480") ``` Only points-type estimates are counted; time and category estimates are ignored. For `sum` and `count`, a work item with no matching rows counts as 0. ### Assignees and labels | Function | Matches work items that | Example | | ----------------- | ----------------------- | ----------------- | | `hasNoAssignee()` | Have no assignee | `hasNoAssignee()` | | `hasNoLabel()` | Have no labels | `hasNoLabel()` | ### Dates and status | Function | Matches work items that | Example | | ----------------------- | -------------------------------------- | ----------------------- | | `isOverdue()` | Are past their due date and still open | `isOverdue()` | | `hasStartAndDueDates()` | Have both a start date and a due date | `hasStartAndDueDates()` | ### Comments, links, and attachments Count arguments accept a number or a comparison such as `">= 2"`. | Function | Matches work items that | Example | | ------------------------- | ------------------------------------------------ | ------------------------------------------ | | `hasComments([n])` | Have comments, optionally a count | `hasComments(">= 3")` | | `commentedAfter("date")` | Have a comment on or after the date | `commentedAfter("2026-01-01")` | | `commentedBefore("date")` | Have a comment on or before the date | `commentedBefore("2026-06-30")` | | `commentContains("text")` | Have a comment containing the text | `commentContains("blocker")` | | `lastCommentBy("user")` | Whose most recent comment is by the user | `lastCommentBy("Priya")` | | `commentedBy("user")` | Have a comment written by the user | `commentedBy("Priya")` | | `hasLinks([n])` | Have URL links, optionally a count | `hasLinks(">= 1")` | | `hasRemoteLinks()` | Have at least one link to an external URL | `hasRemoteLinks()` | | `linkContains("text")` | Have a link whose URL or title contains the text | `linkContains("figma")` | | `hasLinkUrl("url")` | Have a link at exactly this URL (exact match) | `hasLinkUrl("https://figma.com/file/abc")` | | `hasAttachments([n])` | Have attachments, optionally a count | `hasAttachments(">= 2")` | | `attachedBy("user")` | Have an attachment uploaded by the user | `attachedBy("Priya")` | Use `linkContains` for a partial match on a link's URL or title, and `hasLinkUrl` when you want to match one exact URL. ### Worklogs and activity | Function | Matches work items that | Example | | --------------------------------- | --------------------------------------- | ----------------------------------------------- | | `hasWorklogs()` | Have at least one worklog (logged time) | `hasWorklogs()` | | `workLoggedBy("user")` | Have time logged by the user | `workLoggedBy("Priya")` | | `workLoggedBetween("from", "to")` | Have time logged between two dates | `workLoggedBetween("2026-01-01", "2026-01-31")` | | `recentlyViewed()` | You viewed in the last 30 days | `recentlyViewed()` | ### Votes and history These match work items based on who took an action on them. Each takes exactly one user (pick a member, or use `currentUser()`). | Function | Matches work items that | Example | | ------------------------ | --------------------------------------------- | ------------------------- | | `votedBy("user")` | Were upvoted by the user | `votedBy("Priya")` | | `stateChangedBy("user")` | Had their state changed by the user | `stateChangedBy("Priya")` | | `resolvedBy("user")` | Were moved into a completed state by the user | `resolvedBy("Priya")` | ### Modules and releases | Function | Matches work items that | Example | | ----------------------- | ------------------------------------------------------------------ | ------------------------- | | `inNextRelease()` | Are linked to the next upcoming unreleased release | `inNextRelease()` | | `releaseMatch("regex")` | Are linked to an unreleased release whose name matches the pattern | `releaseMatch("v2\\..*")` | | `moduleMatch("regex")` | Are in a module whose name matches the pattern | `moduleMatch("^Front")` | `releaseMatch` and `moduleMatch` match names with a regular expression. The pattern is **case-sensitive** and **unanchored** (it matches anywhere in the name unless you anchor it with `^` or `$`). Start the pattern with `(?i)` to match case-insensitively, for example `moduleMatch("(?i)frontend")`. Patterns are limited to 200 characters. Besides standing on their own, `moduleMatch` and `releaseMatch` can also be used as value functions on the right side of `IN`, so you can match by name inside a list: ``` module IN moduleMatch("Front") release IN releaseMatch("v2") ``` --- --- url: 'https://docs.plane.so/core-concepts/issues/display-options.html' description: >- Customize display by showing specific properties, grouping by attributes, subgrouping, and ordering items to create the perfect project view. --- # Display options The Display dropdown in Plane gives you full control over how your work items are presented, grouped, and ordered. This flexibility ensures that you can tailor the layout to suit your workflow, whether you're a developer working through a backlog, a manager tracking priorities, or a QA engineer validating tasks. Let’s break down how you can make the most of this feature. ![Display options](https://media.docs.plane.so/issues/display-options.webp#hero-tr) ## Display properties Depending on the type of [layout](/core-concepts/issues/layouts) you're working with, you can choose which properties are shown or hidden for each work item. To customize, simply select the properties in the dropdown. This lets you declutter your view by hiding irrelevant fields while surfacing the ones you care about. Here’s the list of properties you can display in the layout: * ID * Work item Type * Assignee * Start Date * Due Date * Labels * Priority * State * Sub-work item Count * Attachment Count * Link * Estimate * Modules * Cycle ## Group by Grouping helps you organize work items based on shared attributes, making it easier to focus on specific workflows or priorities. You can group work items by: * State * Priority * Cycle * Module * Labels * Assignees * Created By * Milestones * Releases * Work Item Types * None ## Sub-group by You can further refine your view by adding a sub-grouping. For example, you could group by State and then sub-group by Assignees to see the state of tasks per team member. Sub-grouping options include: * State * Priority * Cycle * Module * Labels * Assignees * Created By * Milestones * Releases * Work Item Types * None ## Order by Fine-tune the order of work items within groups to reflect your team’s priorities. Plane offers the following ordering options: * Manual * Last Created * Last Updated * Start Date * Due Date * Priority ## Additional options ### Show sub-work items Expand main work items to display their sub-work items directly within the layout. ### Show empty groups Decide whether groups with no work items are visible. *** Explore these options to find the configuration that works best for your team and transform your work item board into a focused, actionable workspace. --- --- url: 'https://docs.plane.so/core-concepts/views.html' description: 'Create, save, and share Views in Plane to quickly access filtered work items.' --- # Views A View in Plane is a saved configuration of filters, layouts, display options, and sorting preferences applied to your work items. Views do not change the underlying data — they are lenses that let you see the same work items through different perspectives without creating duplicates or moving anything. Think of a view as a smart bookmark: you define what you care about (priority = urgent, assigned to me, due this week), how you want to see it (Kanban board, grouped by state), and which columns to show — and Plane remembers all of that for every session. ![Views](https://media.docs.plane.so/views/views.webp#hero) Views are especially useful when you need to: * Focus a recurring standup on a specific slice of work (e.g., all blockers this sprint). * Give stakeholders a curated window into progress without exposing the full backlog. * Share a stable URL that always shows the latest issues matching defined criteria. * Standardize how a team monitors a specific workflow (e.g., QA queue, release checklist). ## Types of Views Plane offers two scopes of views, with fundamentally different coverage. * **Project Views**\ Project views are created within a specific project and accessible to all members of that project. This feature is enabled by default and can be toggled from [Project Settings](/core-concepts/projects/overview#configure-project-settings). Project views support all layouts. * **Workspace Views**\ Workspace views are created at the workspace level and available to all workspace members. These include some default system-defined views that cannot be removed. Workspace views are visualized using the spreadsheet layout. ![Workspace Views](https://media.docs.plane.so/views/workspace-views.webp#hero) Workspace views include four built-in, non-deletable default views: **All Issues**, **Assigned to Me**, **Created by Me**, and **Subscribed**. These are always available and always reflect live data. * **Teamspace Views**\ Teamspace views provide a third scope: views tied to a teamspace rather than a single project or the full workspace. See more about [Teamspace Views](/core-concepts/workspaces/teamspaces#teamspace-views). ## Create view ### Create a project view ![Create view](https://media.docs.plane.so/views/create-view.webp#hero) 1. Open a project and go to **Views** in the left sidebar. 2. Click **Add view**. 3. Enter a **name** for the view. 4. Optionally add a **description** to explain the view's purpose. 5. Select the access level, layout and display options as per your requirements. 6. Set **Filters** to define which issues appear. Use the filter builder to select properties like Assignee, Priority, State, Label, or date ranges. 7. Click **Create View**. Alternatively, spin off a View from within the project's Work items section after applying the layout, filters, display options and then clicking **Save View**. ![Create view from filters](https://media.docs.plane.so/views/create-view-from-work-items.webp#hero) The view is created with your current filter selections and saved to the project's views list. Display filters and properties default to your workspace defaults and can be adjusted after creation from within the view. ### Create a workspace view 1. Click **Views** in the main sidebar (not inside a project — at the workspace level). 2. Click **Add View**. 3. Enter a **name** and optional **description**. 4. Set **filters** — these apply across all projects in the workspace. 5. Click **Create View**. Workspace views appear alongside the four built-in views (All Issues, Assigned to Me, Created by Me, Subscribed). Learn more about how to apply filters [here](/core-concepts/issues/visualise_filter). After creating a view, you can share the link to collaborate and investigate with other members. ## View access levels Every view has an access level. ### Public view By default, views are public. They are visible and usable by all members with access to the project. ### Private view They are visible only to the creator; other members cannot see or open it. Only the owner of a private view can change its access level. Project admins cannot override private view access. Toggle between public and private using the globe and lock icons in the create or edit view modal. ![Private view](https://media.docs.plane.so/views/private-view.webp#hero) ## Edit a view 1. Open the view. 2. Select your preferred layout: **List**, **Board**, **Calendar**, **Table**, or **Gantt**. 3. Add, remove, or modify filter conditions and display options. 4. Click **Update View** that appears in the filter bar. If you close the view without saving, your unsaved filter changes are discarded and the view reverts to its saved state on next open. ### Group work items in a view 1. Open the view. 2. Click **Display** in the top toolbar. 3. Under **Group by**, select a property: State, Priority, Label, Assignee, Cycle, Module, or others. 4. Optionally set **Sub-group by** for a second-level grouping (in the Board layout). 5. Toggle **Show empty groups** if you want to see group headers even when there are no matching issues. 6. Save the view. ## Lock view A view can be **locked** by its creator to prevent any edits — including filter changes, display changes, and renames. Locked views can still be read by all permitted members; only the creator can unlock them. 1. Open the view and click the **Lock** button on the top. 2. Alternatively, go to the Views list. Open the **...** menu → **Lock View**. A lock icon appears next to the view name. Members who try to edit the view will see a read-only message. To unlock, open the same menu and select **Unlock View** — only the creator can do this. Locking is useful when a view represents an agreed-upon team standard and you want to prevent accidental changes. ## Publish View Project views can be **published** to generate a public shareable link. Publishing is managed from within the Share panel. ![Publish view](https://media.docs.plane.so/views/publish-view.webp#hero) 1. Open the project view. 2. Click the **Share** button in the header. 3. In the share panel, find the **Publish** section. 4. Toggle on **Publish** to generate the public link. 5. Configure public access options: * Enable or disable **Comments**, **Reactions**, and **Votes** for public visitors. * Choose which **layouts** (List, Board, etc.) are available to public viewers. 6. Copy the generated link and share it. A published view: * Is accessible to anyone with the link - no Plane account required. * Shows issues filtered by the view's saved configuration. * Can optionally allow reactions, comments, or votes from public visitors. * Can restrict which layouts (List, Board, etc.) are exposed to public viewers. You can update publish settings or unpublish at any time without changing the original view. To unpublish, return to the share panel and toggle **Publish** off. The link immediately stops working. ## Share a view Share views with specific team members to give them access to your filtered work without exposing the full project backlog. Sharing is granular - each person gets a specific access level. ### Access levels for shared views When sharing a view, choose one access level per person: * **View** - Read-only access. They can see the filtered work items but cannot edit, change filters, or modify the layout. * **Edit** - Full collaboration. They can view, modify filters, change layouts, and manage the view configuration. ### Share a view 1. Open the view you want to share. 2. Click the **Share** button in the header. 3. Click **Add member** and search for team members by name. 4. For each member, select their access level (View or Edit). 5. Click **Share** or **Done**. Members are notified when first shared with. They can now access the view from their views list. ### Manage shared access To change someone's access level: 1. Open the share panel. 2. Click the access level dropdown next to their name and select a new level. To remove someone: 1. Find them in the share list. 2. Click the **X** or delete icon next to their name. They immediately lose access. ### Who can share * **View owner** - Can share their views with anyone in the workspace. * **Members with edit access** - Can share the view they were given edit access to. * **View-only members** - Cannot share the view further. ### Sharing vs publishing There are two ways to make a view accessible beyond your immediate team: * **Sharing** - Grant specific people access with granular control. Recipients must be workspace members. * **Publishing** - Generate a public link anyone can access without signing in. Use sharing for team collaboration. Use publishing for broader distribution. ### Limitations * Share updates replace the entire roster (you cannot add or remove one person without re-specifying everyone). * Sharing a view does not share the work items - shared viewers see only data they have access to based on their workspace role. * If a project member is removed from the project, all shares are automatically revoked. ## Export view When you export a view, Plane captures the view's filters, processes it and notifies you when it is ready to download. 1. Go to the views list or open a view. 2. Open the **...** menu → **Export**. 3. Select a format: **CSV**, **XLSX**, or **JSON**. 4. Click **Continue**. 5. A toast notification confirms the export has started. Click **View Exports** in the toast, or go to **Workspace Settings → Exports**, to monitor the job and download the file when it is ready. 6. Once the status shows as complete, click **Download** to save the file. The exported data reflects the work items that match the view's filters at the moment you trigger the export. Specifically, Plane uses the **currently active filters in your session** — so if you have modified the filters since last saving the view, the export will include those unsaved changes. This means the file you download matches exactly what you see on screen when you click Export. For **project views**, the export is scoped to the single project the view belongs to. For **workspace views**, the export spans all projects in the workspace, consistent with how workspace views work in general. Export is available on projects views and workspace views. ### Export formats | Format | Description | | ------ | ------------------------------------------------------------------------------------------------ | | CSV | Comma-separated values. Opens in any spreadsheet tool. Best for importing into other systems. | | XLSX | Excel workbook format. Opens directly in Excel or Google Sheets with formatting preserved. | | JSON | Structured data format. Intended for programmatic use or importing into other tools via scripts. | Learn more about [custom exports](/core-concepts/export#custom-exports). ## Add view to favorites From the views list: * Hover over the view and click the **star** icon. From inside the view: * Click the **star** icon in the view header. Favorited views appear in the **Favorites** section of the sidebar for quick access. ## Duplicate view 1. Go to the views list (project or workspace level). 2. Right-click or open the **...** menu on the view you want to duplicate. 3. Click **Duplicate** (or **Make a copy**). The duplicate is created with the same filters, display filters, and display properties, with "Copy of" prepended to the name. You can rename and modify it independently. ## Delete a view You can remove views by deleting them from the list of views in your workspace or project. Deleting a view has no impact on the associated work items. 1. Go to the views list. 2. Open the **...** menu on the view → **Delete**. 3. Confirm deletion. Deletion is permanent. Issues are not affected — only the saved view configuration is removed. The built-in workspace views (All Issues, Assigned to Me, Created by Me, Subscribed) cannot be deleted. --- --- url: 'https://docs.plane.so/your-work.html' description: >- Track assigned tasks, monitor your workload, visualize priorities, and stay on top of your personal project contributions. --- # Your Work The **Your work** page serves as a centralized hub for managing your individual responsibilities and progress within the workspace. This comprehensive dashboard gives you a clear, at-a-glance view of your current workload, work item prioritization, and overall activity. ![Your work](https://media.docs.plane.so/account/your-work.webp#hero) You can click the tabs to navigate to different categories and filter your assigned, created and subscribed work items. ## Summary At the top, the **Overview** section provides high-level metrics about the work assigned to you. You can quickly see the number of work items you've created, the ones currently assigned to you, and the total number of work items you're subscribed to, even if they aren't directly assigned. These top-level statistics give you a quick sense of your involvement and level of engagement with the projects. ### Workload Moving down, the Workload visualization breaks down your current tasks by their status: * **Backlog** - Work items that are waiting to be started * **Not started** - Tasks that are ready for you to begin work * **Working on** - Work items you are actively addressing * **Completed** - Tasks you have finished * **Cancelled** - Any work items that have been cancelled This at-a-glance view allows you to immediately identify where most of your time and effort is currently focused. ### Work items by priority and state You can see a breakdown of the tasks assigned to you organized by their designated priority level. The **Work items by state** pie chart gives you a holistic view of how your assigned tasks are progressing through the workflow. ### Recent activity This section keeps a chronological log of your most recent actions within your projects. *** By consolidating all of this valuable information into a single, centralized dashboard, the **Your Work** page empowers you to effectively oversee and prioritize your individual tasks and progress within the workspace. --- --- url: 'https://docs.plane.so/core-concepts/pages/overview.html' description: >- Create, format, and share project documentation with AI assistance, content blocks, version history, and web publishing options. --- # Manage project pages Pages in Plane let you easily capture and organize project-related information. Whether you’re documenting meeting notes or detailing technical or product requirements, Pages allow you to collaborate directly within the context of your project—no need for external tools. ## Turn on Pages Pages are turned on by default when you create a new project. If needed, you can turn it on or off later in your project settings. ## Create Page * To create a new page, simply press `D` within your project, or head to the **Pages** section in the sidebar and click the **Add page** button at the top right of your screen. ![Create page](https://media.docs.plane.so/pages/create-page.webp#hero) * You can set pages to be either public or private. Public pages are visible to everyone in your workspace, while private pages are only accessible to you. To change a page’s visibility, just go to the **•••** menu on that page anytime. ![Public or private pages](https://media.docs.plane.so/pages/public-private-page.webp#hero) ## Add content * Once you've created a page, you can add content using the `/` command, which supports 16 different content blocks from lists to images to tables to work item embeds, giving you the flexibility to structure your content exactly how you need it. For a full list of content blocks and to explore each one in detail, see [Editor blocks](/core-concepts/pages/editor-blocks). ![Slash commands](https://media.docs.plane.so/pages/slash-commands.webp#hero) * You can easily drag and drop content blocks in Plane to rearrange them on the page. Just hover over any block, grab the **⋮⋮** icon that shows up, and drag it to where you want. Let go of it to drop the block in its new spot. ### Format your content ![Static toolbar](https://media.docs.plane.so/pages/static-toolbar.webp#hero) * The static toolbar at the top of the page offers a range of styling options for your content, including basic blocks like headings and lists, and advanced blocks like images, tables, and more. - Quickly adjust headings (H1-H6) to create a clear, structured hierarchy in your document. - Add emphasis with text or background colors, and style important information with bold, italic, underline, and strikethrough options for better readability. - Align your content to the left, right, or center to ensure proper layout and visual balance in your document. ### Markdown support Plane allows you to use Markdown in Pages, making it easy to format content quickly with familiar Markdown syntax. You can create headings, lists, links, and other common formats right in your page without switching to a separate editor. To use Markdown in Plane, simply type the relevant symbols (like # for headings or - for lists) directly within the page. Plane will automatically convert your Markdown into the appropriate format, helping you keep your workflow smooth and efficient. ## AI helper ![AI helper](https://media.docs.plane.so/pages/ai-helper.webp#hero-tl) Plane’s AI tools enhance content creation by helping you refine, reframe, and enrich your writing. Whether you need to paraphrase a sentence, simplify complex information, or elaborate on a topic, Pages offers quick solutions right within the editor. * Make your content clearer or concise by rephrasing text or breaking down complex ideas. * Quickly generate summaries to highlight key points, ideal for meetings or lengthy documents. * Expand on ideas to add context, detail, or depth to your writing. - Get suggestions for clear, catchy titles. ## Mention work items Link directly to work items within your pages using the `@` mention feature. This creates a connection between your documentation and the actual work being tracked in your project. ![Mention work items](https://media.docs.plane.so/pages/mention-work-items.webp#hero) To mention a work item: 1. Type `@` anywhere in your page. 2. Start typing the work item name or ID. 3. Select the work item from the list that appears. The list shows your most recently created work items first, making it easy to reference new work. As you type, the suggestions filter to show relevant matches based on work item titles and IDs. ![Mentioned work items](https://media.docs.plane.so/pages/mentioned-work-items.webp#hero) Mentioned work items appear as interactive links in your page. Clicking them takes you directly to the work item's details, making it easy to jump between documentation and tasks. ## Block actions ![Block actions](https://media.docs.plane.so/pages/block-actions.webp#hero) You can perform several actions on any block within a page. Just hover over the block and click the **⋮⋮ icon** that appears. ### Copy link to block Get a direct URL to this specific block. When someone opens this link, they'll jump straight to this block in the page, making it easy to reference specific sections in discussions or work items. ### Duplicate block Create a copy of the block to reuse content without starting from scratch. ### Delete block Remove the block entirely from the page. These quick actions help you manage and reference your content efficiently, especially in longer documents where you need to point teammates to specific sections. ## Convert selected text to work items Turn any text selection in your page into a work item instantly. This feature helps you capture action items or tasks directly from your documentation without interrupting your flow. ![Convert selected text to work items](https://media.docs.plane.so/pages/convert-selected-text-to-work-items.webp#hero) To create a work item from selected text: 1. Highlight the text you want to convert. 2. Click **Create work item from selection** from the context menu. 3. Plane creates a new work item in your project using the selected text as the title. 4. The original text in your page automatically converts to a work item mention, linking back to the newly created item. This seamless workflow ensures nothing gets lost in translation between planning discussions and actual task tracking. Your documentation stays connected to the work being done, and your team can easily trace where work items originated. ## Page actions ::: info When a Member locks, unlocks, archives, or restores a Page, the action takes effect immediately for all users with access to the Page. ::: ![Page actions](https://media.docs.plane.so/pages/page-actions.webp#hero-tr) Once your page is created, you can click the **•••** menu in the top-right corner to perform the following actions: ### Full width Make your content area wider and shrink the margins on any page. ### Copy markdown Copy the page's content in markdown format for use in places like your wiki portal. ### Copy page link Share the page by copying its link to send to your teammates or link it in a work item. ### Make a copy Duplicate an existing page to jumpstart new content. ### Move Page Transfer a page to Wiki, Teamspace or a different Project in your workspace. ### Lock Page Prevent others from editing a page by locking it. ### Archive Page If a page is no longer needed, you can archive it. Archived pages are stored in the archives section, where you can either restore or permanently delete them. ### Version history Pages automatically tracks every edit, so you can see what changed, who changed it, and when. This is especially useful when multiple people are collaborating on the same document. ![Version history](https://media.docs.plane.so/pages/version-history-with-diff.webp#hero) To view version history: 1. Click the **•••** menu in the top-right corner. 2. Select **Version history**. 3. The Info panel on the right displays a list of all versions with timestamps and collaborators. **View changes between versions** Click any version to see the document as it was at that point in time. The page switches to "View only" mode, showing exactly what the document looked like then. Enable **Highlight changes** (on by default) at the bottom of the panel to see what was added or modified in that version. Changes appear highlighted, making it easy to spot edits at a glance. **Restore a previous version** If you need to revert to an earlier version: 1. Select the version you want to restore. 2. Review the content to confirm it's the right version. 3. Click **Restore** at the top of the page. The restored content becomes the current version, and a new entry is added to the version history. ### Export Page ![Export Page](https://media.docs.plane.so/pages/export-page.webp#hero) Pages lets you export your content in various formats, including PDF, Word, and Markdown. This feature is a game-changer for project managers and team members who need to share information with stakeholders, clients, or team members who might not be using Plane. When you export to PDF, your documents keep their formatting, making them easy to share and print without any hassle. If you choose to export to Markdown, you can seamlessly integrate your content into other tools or platforms, streamlining your workflow. ## Real-time collaboration Pages comes with built-in real-time collaboration that makes working together seamless. When multiple team members are viewing or editing the same page, you'll see their profile pictures displayed at the top of the document, giving you instant visibility into who's currently active. But it goes beyond just knowing who's there - you can actually see where your teammates are working in real-time. Each collaborator gets their own colored cursor that moves around the page as they navigate and edit content. This makes it easy to avoid conflicts when multiple people are making changes, and you can even see what sections others are focusing on. The live cursors update instantly as people type, select text, or move around the document. It's like having everyone gathered around the same whiteboard, but digitally. ## Publish Page ![Publish Page](https://media.docs.plane.so/pages/publish-page.webp#hero-tr) With Plane, you can publish Pages to the web, making them accessible to anyone with the link—no login required. This feature is perfect for sharing project updates, documentation, or any other information with external stakeholders. Published pages allow viewers to engage directly by leaving comments, providing an open channel for feedback without needing access to your workspace. To publish a page, click the **Publish** button at the top right of your screen. You’ll receive a unique link to share the page. ## Table of contents The Table of contents panel gives you a bird's-eye view of your document's structure. Just click the panel icon on the right side of your screen to reveal all the sections and headings in your current document. ![TOC](https://media.docs.plane.so/pages/toc-pages.webp#hero-tr) This feature is especially handy when you're working with longer guides - instead of scrolling through everything to find what you need, you can jump directly to any section with a single click. The table of contents automatically updates as you add or modify headings, so it always reflects your document's current structure. ## Info panel The Info panel is your document's dashboard, showing you all the key stats at a glance. You'll find useful metrics like word count, character count, number of paragraphs, and estimated read time - perfect for keeping track of your document's scope and helping readers know what to expect. ![Info panel](https://media.docs.plane.so/pages/info-panel-pages.webp#hero-tr) The panel also displays collaboration details, including who last edited the document and when it was created. This makes it easy to stay on top of recent changes and track your team's contributions. ## Troubleshooting ### Page content not visible **Issue**\ Page content is not visible to Members, even when the page is set to public. While the page title appears, the content does not, and only the page creator can view it. In some cases, content is visible on certain pages but not others, making the issue inconsistent and unpredictable. **Cause**\ When using an external reverse proxy, the necessary HTTP upgrade headers must be added to support WebSocket communication. The default configuration does not handle WebSocket connections correctly. **Solution**\ To resolve this issue, enable WebSocket support by adding specific headers in your external proxy configuration file. For example, if you are using NGINX, include the following settings: ```bash proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; ``` For more details on configuring an external reverse proxy for Plane and accessing different templates, refer to the [External reverse proxy](https://developers.plane.so/self-hosting/govern/reverse-proxy) guide. --- --- url: 'https://docs.plane.so/core-concepts/pages/wiki.html' description: >- Create and organize company-wide documentation with Wiki. Use collections to group pages by topic, share private pages with specific members, and build a knowledge base that lives beyond any single project. --- # Wiki Wiki is where your organization's shared knowledge lives — company policies, onboarding materials, technical guides, architecture decisions, and anything else that matters beyond a single project. Unlike project pages, which focus on work happening inside a specific project, Wiki pages belong to the workspace and are accessible to every workspace member. This makes Wiki the right place for documentation that crosses team boundaries. ![Wiki](https://media.docs.plane.so/wiki/wiki.webp#hero) ## Wiki Home Home is the landing page you see when you open Wiki. It gives you a personalized overview of your Wiki activity so you can pick up where you left off or quickly capture an idea. **Recents** shows the pages you've accessed or modified most recently, along with timestamps and the page owner. Click any page to jump straight into it, or click **Show all** to see the full history. [Stickies](/core-concepts/stickies) are personal quick-capture notes pinned to the bottom of the Home screen. ### What you see in the sidebar The Wiki sidebar organizes content into sections: * **Home** - your personalized landing page with recents and stickies. * **Collections** - your folders of pages. Each collection can hold pages and nested pages. The *General* collection is created automatically and holds any pages that haven't been moved elsewhere. * **Shared** - private pages that have been shared with you by other members. * **Private** - pages only you can see (unless you share them). * **Archived** - pages that have been archived for reference. ## Collections Collections are how your wiki stays organized. Every page in your wiki belongs to a collection, and collections appear as a flat list in your sidebar, expand one to see the pages inside it. [Learn how to create and manage collections](/pages/collections) ## Create and manage Wiki pages ### Create a new page 1. Click **New page** at the top of the Wiki sidebar. 2. The page opens in the editor. Start writing your content — it saves automatically. 3. By default, new pages are added to the collection that you are in. Drag the page to a different collection in the sidebar if needed. ### Public vs. private pages Pages can be **public** (visible to all workspace members) or **private** (visible only to you, unless you share it). * **Public pages** appear in their collection and are accessible to anyone in the workspace with Wiki view permissions. * **Private pages** appear in the **Private** section of your sidebar. Other members cannot see them unless you explicitly share access. ### Edit a page Open a page and start typing. Wiki pages support rich text editing, and multiple members can edit a public page collaboratively. Changes are saved automatically. ### Archive a page If a page is no longer actively used but you want to keep it for reference: 1. Open the page. 2. Use the page options to **Archive** it. Archived pages move to the **Archived** section of the sidebar. They can be unarchived later if needed. ### Lock a page Locking prevents other members from editing a page while still allowing them to view it. The page creator (or an Admin) can lock and unlock pages at any time. ### Publish a page Publishing makes a page available outside your workspace via a public URL. Use this for documentation you want to share externally — product guides, API references, or public knowledge bases. ### Export a page Pages can be exported for use outside of Plane. Open the page and use the export option to download it. ## Share private pages Private pages are only visible to their creator by default. On the Business plan and above, you can selectively share private Wiki pages with specific workspace members, giving you fine-grained control over who sees sensitive documentation. ![Share private pages](https://media.docs.plane.so/wiki/share-private-pages.webp#hero) ### Share a private page 1. Open any private page you've created. 2. Click the **Share** button in the top-right corner. 3. Search for and add the members you want to share with. 4. Set permissions for each person: * **can view** — the person can read the page but not edit it. * **can comment** — the person can add comments on the page. * **can edit** — the person can make changes to the page content. 5. Click **Share**. Shared pages appear in the **Shared** section of the recipient's Wiki sidebar. ### Manage shared access The page creator retains full control over sharing. To update access after sharing: 1. Open the shared page and click **Share**. 2. Click the dropdown next to a member's name to change their permission level. 3. Select **Remove** to revoke their access entirely. --- --- url: 'https://docs.plane.so/core-concepts/pages/editor-blocks.html' description: Explore all available content blocks in Plane's Page editor. --- # Editor blocks List of all the content blocks available in the page, description and comment editors. ## Text The standard block for paragraph text and general content. ## Headings (H1 - H6) Organize your content hierarchically using six heading levels: * **H1**: Main page title (use only once per page) * **H2**: Primary sections * **H3**: Subsections * **H4-H6**: Further content subdivision when needed ## To do Adds checkable items for tracking tasks and their completion status. ## Bullet list Creates unordered lists for items where sequence doesn't matter. ## Numbered list Creates ordered lists when sequence or priority matters. ## Table Organizes information in rows and columns for structured data presentation. ## Quote Highlights quoted text or important statements with distinct formatting. ## Code Displays code snippets or command-line text with proper formatting and syntax highlighting. ## Embed Seamlessly integrate external content directly into your documents with rich, interactive embeds. The embed feature supports a wide variety of platforms and content types, making it easy to enhance your documentation with multimedia and interactive elements. ![Embed](https://media.docs.plane.so/pages/external-embeds.webp#hero) Use the `/embed` slash command to quickly insert an embed block. This opens an embed dialog where you can paste any supported link. The system automatically detects the content type and creates an appropriate embed with a rich preview. This eliminates the need for users to navigate away from your content to view referenced materials. ## Link Dashboard widget Embed a live dashboard widget directly in a page. Instead of linking out to a dashboard, you bring a single chart, table, or metric from an existing dashboard into your page. It renders inline and stays in sync with your data. Type `/` in the editor and search for **Link dashboard widgets** to insert a dashboard widget block. When you insert the block, a selector opens where you choose a dashboard and then pick the specific widget you want to embed. The widget appears inline in your page. You can change the widget at any time by hovering over the block and clicking **Change widget**. To remove it, click **Delete** from the block menu. :::tip You need at least one dashboard with widgets already set up before you can embed one in a page. See [Dashboards](/dashboards) to get started. ::: ## Link Pages :::info Only available in Wiki pages. ::: Dynamically embed filtered lists of related pages in your content. Instead of manually maintaining a list, define filters and the block automatically shows matching pages. Type `/link` or `/link-pages` to insert the block. A configuration panel appears where you select your filter source and options. ### Filter sources Choose one of three ways to filter pages: * **Parent pages** - Show pages nested under a specific parent. Control depth from 1-6 levels or show all descendants. * **Created by** - Show pages authored by selected team members. * **Labels** - Show pages with selected labels. Uses OR logic - any matching label includes the page. ### Display options * **Nesting depth** - Set how many levels deep to show (1-6 or "all") * **Dynamic updates** - Automatically reflects new/deleted/modified pages without manual refresh ### Limitations * Maximum 100 pages per block * Cannot combine multiple sources in one block * Archived pages excluded ## Image Inserts and displays images within your content. ## Attachment Uploads and embeds files directly into your content, supporting documents, images, and other file types up to 100MB each. #### Show video preview When you upload video files as attachments, you can display them with inline playback controls. Just hover over the block and click the **⋮⋮** icon that appears. Select **Show preview** to convert the file link into an embedded video player. This works for all supported video formats. ![Show preview](https://media.docs.plane.so/pages/show-preview.webp#hero) ## Columns Organize content side-by-side using multi-column layouts. Columns help you create visually structured pages for comparisons, parallel information, or more efficient use of horizontal space. ![Columns](https://media.docs.plane.so/pages/columns.webp#hero) Use the slash command to insert the layout you need: * `/2 Columns` * `/3 Columns` * `/4 Columns` Each column appears with an "Add content" placeholder where you can add any block type - text, lists, code, images, and more. ## Tabs Tabs let you organize content into a tabbed block within a page, so related sections can share one space and readers switch between them instead of scrolling. You can lay tabs out horizontally (along the top) or vertically (down the side). ### Insert tabs Type `/tabs` in the editor and choose one of: * **Horizontal tabs** - the tab labels run along the top of the block. * **Vertical tabs** - the tab labels run down the side of the block. A new block is inserted with two tabs, named "Tab 1" and "Tab 2". Each tab holds its own content, and you can put any editor content inside a tab, including text, lists, images, and other blocks. ### Rename a tab Double-click a tab label, type the new name, and press Enter (or click away) to save. ### Change the layout While editing, use the layout controls on the block to switch between horizontal and vertical orientation at any time. Your tabs and their content are preserved. ### Notes * Tabs cannot be nested. You cannot insert a tabs block inside another tabs block. * In read-only or published pages, readers can switch between tabs but cannot add, rename, delete, or edit them. ## Video Embeds video content directly into your pages for rich multimedia documentation. ![Embed videos](https://media.docs.plane.so/pages/embed-videos.webp#hero) Type `/video` to insert a video block, then upload a video file. The video appears inline with playback controls, allowing viewers to watch without leaving the page. Supported video formats include MP4, MPEG, OGG Video, WebM, QuickTime, AVI, and WMV. #### Show as attachment If you have a video displayed with inline preview and want to convert it to a simple file link, hover over the video block and select **Show as attachment** from the actions menu. This collapses the video player into a compact attachment link. ![Show as attachment](https://media.docs.plane.so/pages/show-as-attachment.webp#hero) ## Math equations Add mathematical expressions and formulas to your Pages using LaTeX syntax. Whether you need to document complex calculations, display statistical formulas, or include scientific notations, Plane supports both inline and block-style mathematical equations. This is perfect for technical documentation, engineering specs, data analysis reports, and any content requiring precise mathematical notation. ![Math equations](https://media.docs.plane.so/pages/math-equations.webp#hero) ### Block equation Creates standalone mathematical expressions using LaTeX syntax. Block equations are displayed on their own line with centered formatting, perfect for formulas, theorems, and complex mathematical statements that need emphasis. Use the `/blockequation` slash command: ``` \lim_{x \to \infty} \frac{1}{x} = 0 ``` Or use double dollar syntax: ```latex $$ \int_a^b f(x)\,dx = F(b) - F(a) $$ ``` ### Inline equation Embeds mathematical expressions within regular text flow using LaTeX syntax. Inline equations maintain the same text baseline, allowing you to seamlessly integrate mathematical notation into sentences and paragraphs. Use the `/inlineequation` slash command: ``` \bar{x} = \frac{1}{n}\sum_{i=1}^{n} x_i ``` Or use single dollar syntax: ```latex $ a^2 + b^2 = c^2 $ ``` Both equation types support full LaTeX rendering with built-in validation and error handling for invalid mathematical expressions. ## Draw.io diagrams ::: tip Prerequisites Before you can add Draw.io diagrams to Pages or Wiki, you need to [connect the Draw.io integration](/integrations/draw-io) from Workspace Settings. ::: Create and manage interactive diagrams and whiteboards directly within your Pages using the integrated Draw.io editor. Whether you need professional flowcharts, system architecture diagrams, or freehand sketches for brainstorming, the diagram feature provides powerful visual documentation capabilities without leaving Plane. ![Draw.io diagram](https://media.docs.plane.so/pages/draw-io-diagram.webp#hero) ### Diagram Create professional diagrams, flowcharts, and visual documentation using the full Draw.io editor with comprehensive shape libraries. Perfect for technical documentation, process flows, system architecture, network diagrams, and organizational charts. Use the `/diagram` or `/drawio-diagram` slash command to insert a diagram block. Click the placeholder to launch the Draw.io editor. ### Board Create whiteboards with freehand drawing and sketching capabilities using a simplified interface. Ideal for brainstorming sessions, quick mockups, concept visualization, and collaborative ideation. Use the `/board` or `/drawio-board` slash command to insert a whiteboard block. Click the placeholder that says "Click to start editing whiteboard" to launch the board interface. Both modes feature a consistent toolbar with **Save** and **Exit** buttons, making it easy to preserve your work and return to your Page. All diagrams are fully interactive—simply click any saved diagram to edit it again. ## HTML artifact An HTML artifact embeds a self-contained HTML file as a live, interactive block inside a page. Instead of pasting a link or a screenshot, you upload an `.html` file and it renders inline, right where you put it. This is useful for embedding things like a prototype, a self-contained report, a chart exported as HTML, or any standalone web snippet. The rendered artifact is fully interactive: scripts in the file run, so buttons, tabs, and other in-page interactions work. Hover over the block to reveal its toolbar: * **Open in new tab** opens the artifact in its own browser tab. * **View full screen** opens the artifact in a large modal for a closer look. * **Replace file** (edit mode) swaps in a different HTML file, keeping the block in place. * **Download** (edit mode) downloads the original HTML file. * **Delete artifact** (edit mode) removes the block. **Resize:** in edit mode, drag the bottom edge of the block to change its height. The height is saved with the page. In read-only or published pages, the artifact still renders and stays interactive. Readers get the **Open in new tab** and **View full screen** actions, but not the edit-only controls (replace, download, delete, resize). HTML artifacts run in a sandboxed frame that is isolated from Plane. The embedded file can run its own scripts and open links, but it cannot access your Plane session, your workspace data, or the surrounding page. Treat an artifact like any embedded third-party web page: only embed files you trust. ### Notes * Accepted file types are `.html` and `.htm` only. * Deleting an artifact block also removes its uploaded file, unless the same file is embedded elsewhere in the page. * HTML artifacts are available in pages and other rich text fields (such as work item descriptions), wherever the editor is used. ## Callout Creates visually distinct sections with customizable icons and colors for highlighting warnings, tips , and calls-to-action. ## Toggle A toggle is a collapsible block that hides its content behind a title. Readers see the title, and click to expand it when they want the detail. Toggles keep long documents tidy: use them for optional context, FAQs, step-by-step details, or anything you want available without cluttering the page. Toggles are available anywhere you use the editor, including **pages**, **wiki pages**, and **work item descriptions**. ### Insert a toggle 1. Place your cursor where you want the toggle. 2. Type `/` to open the command menu. 3. Search for **Toggle**. You can also type `/accordion`, `/expand`, `/collapse`, `/details`, or `/summary` to find it. 4. Select it. Plane inserts an open toggle with the cursor in its title, ready for you to type. ### Add a title and content A toggle has two parts: * **The title** is the line that always stays visible. Type the title first. An empty title shows the hint "Give this a title..." * **The body** is the content that expands and collapses. Press **Enter** from the title to move into the body, then add your content. An empty body shows "Empty toggle. Click or drop a block inside." The body can hold almost anything the editor supports: paragraphs, lists, headings, images, callouts, and more. You can also **nest toggles inside toggles** to build layered, collapsible sections. ### Expand and collapse Click the arrow next to the title to expand or collapse a toggle. A newly inserted toggle starts **expanded** so you can add content right away. Toggles keep working in read-only and published views: anyone viewing the page can click to expand and collapse them, even when they cannot edit. ### Things to know * **The open or closed state is not saved.** Collapsing or expanding a toggle changes what you see, but it is not written into the document. If you reload the page, toggles return to their default state rather than staying exactly as you left them. This also means every reader sees toggles in their default state, not whatever a previous viewer left behind. * **Removing a toggle.** Pressing **Backspace** at the start of an empty title removes the toggle and keeps you in the document. ## Table of contents On a long page, a table of contents gives readers a quick map of the content and a way to jump straight to any section. Plane builds it from the **headings** in your page, so there is nothing to maintain by hand: as you add, rename, reorder, or remove headings, the table of contents updates on its own. The table of contents is available on **pages** and **wiki pages**. It is not available in work item descriptions or comments, which don't track headings. A table of contents only shows what it can find, so start by giving your page headings. Type `/` and choose a heading (Heading 1, Heading 2, or Heading 3), or use Markdown shortcuts by starting a line with `#`, `##`, or `###`. Until a page has at least one heading, the table of contents shows an empty message. ### Insert a table of contents 1. Place your cursor where you want the table of contents, usually near the top of the page. 2. Type `/` to open the command menu. 3. Search for **Table of contents**. You can also type `/toc`, `/contents`, `/outline`, or `/headings` to find it. 4. Select it. Plane inserts the block, described as "a live outline of this page's headings," and adds an empty line after it so you can keep writing. The block lists every heading on the page, indented by level so the structure is easy to scan. ### How it behaves * **Shows every heading level.** Headings from level 1 through level 6 all appear, each indented according to its level. * **Stays up to date.** The list rebuilds automatically whenever you add, edit, reorder, or delete a heading. You never edit the table of contents directly. * **Jumps to a section.** Click any entry to smoothly scroll the page to that heading. * **Handles empty headings.** A heading with no text yet appears as "Untitled heading" until you name it. Because it is a normal block, you can drag it to move it elsewhere on the page, or delete it like any other block. ## AI block Generate or transform content directly within your pages using AI. The AI Block lets you draft new content, summarize existing text, or run custom prompts without leaving the editor. ![AI Block](https://media.docs.plane.so/pages/ai-block.webp#hero) Type `/ai` to insert an AI Block. The block appears with a prompt input area and a dropdown to select the action type. #### Action types **Summarize page**\ Generates a concise summary of your page content. Useful for creating executive summaries, TL;DRs, or quick overviews of longer documents. **Custom prompt**\ Write your own instructions to generate or transform content. Use this for drafting sections, rewriting text, structuring notes, expanding ideas, or any other AI-assisted writing task.
 ## Work item References work items directly in the editor to track details and progress. ## Divider Adds a horizontal line to separate content sections visually. ## Emoji Add emojis to your content across all Plane editors. Type `/emoji` to open the picker or use `:` and start typing for suggestions like `:smile:`. Choose from standard Unicode emojis and GitHub's extended collection. ## Date block The date block inserts an inline date picker anywhere in a page. It renders as a small pill showing a formatted date and can be clicked to open a calendar and change the selection. #### Insert a date block Type `/date` in the editor to open the slash command menu and select **Date**. You can also search for it by typing `/calendar`, `/deadline`, or `/due`. The block is inserted at the cursor position with no date selected. #### Pick a date Click the date pill to open a calendar popover. Select any date. The popover closes and the pill updates to show the selected date formatted as `Jan 15, 2025`. Click the pill again at any time to change the date. #### In read-only pages The date renders as plain formatted text. It cannot be clicked or changed. ## Status block The status block inserts an inline colored label anywhere in a page. You define the text and choose from six colors. Use it to mark sections of a page with a state, flag, or category without creating a separate work item. #### Insert a status block Type `/status` in the editor and select **Status**. You can also search for it by typing `/label`, `/badge`, or `/tag`. The block is inserted with the default text "STATUS" and a gray background. #### Edit the label Click the status badge to open a popover with a text field and a color picker. Type your label text in the field. Changes appear on the badge as you type. Select a color from the six options: Gray, Emerald, Crimson, Yellow, Indigo, Purple. Press **Enter** or click outside the popover to close it and save. #### In read-only pages The status badge renders with its color and text preserved. It cannot be clicked or edited. --- --- url: 'https://docs.plane.so/pages/organize-pages.html' description: >- Keep your pages tidy with favorites, moving, duplicating, archiving, and deleting. --- # Organize pages As your pages grow, a few actions help you keep them organized and findable. This page covers the everyday actions you take on a single page. For the bigger organizing tools, see: * **[Nested pages](/pages/nested-pages)** - build a hierarchy of pages and sub-pages. * **[Collections](/pages/collections)** - group wiki pages into folders, including private collections. * **[Page labels](/pages/page-labels)** - tag pages and filter by label. You reach the actions below from a page's **options menu** (the **⋯** in the top-right of an open page), or by opening a page's actions menu from any page list. ## Favorite a page Favoriting keeps a page one click away. Open the options menu and choose **Add to favorites**. Favorited pages appear in the **Favorites** view, and starred in your page lists, so the pages you return to most stay at hand. To remove one, choose **Remove from favorites**. Favorites are personal to you. Favoriting a page does not change who can see it or affect anyone else's view. ## Move a page Moving relocates a page to a different place in your workspace. On the top right of a page, click the **Move page**con i, then pick a destination. Depending on where the page currently lives, you can move it to: * another **project**, * a **teamspace**, * the **workspace wiki**, or a specific **wiki collection**. Use the search box in the move dialog to find the destination, then confirm with **Move**. A few rules apply: * A page must be unlocked and not archived before it can be moved. * **Private and shared pages cannot be moved to a teamspace.** Make the page public first, or choose a different destination. * If you move a page to a wiki collection and it cannot be added to that collection, the page still moves to the wiki and lands in the default **General** collection. Moving a page brings its sub-pages with it, keeping the hierarchy intact. ## Duplicate a page To create a copy of a page, open the options menu and choose **Make a copy**. Plane creates a new page with the same content, including any images and file attachments. The copy is independent: editing it does not affect the original. ## Archive a page Archiving removes a page from your active lists without deleting it, so you can bring it back later. Open the options menu and choose **Archive**. Archived pages move to the **Archived** view for that scope. Archiving a page also archives its sub-pages. On the workspace wiki, archiving a page that is published to the web also unpublishes it. To bring a page back, open it from the Archived view and choose **Restore**. Restoring returns the page, and its sub-pages, to their previous place. ## Delete a page Deleting removes a page permanently. A page must be **archived first**: the **Delete** action becomes available only from the Archived view. Open the archived page's options menu and choose **Delete**. Deleting is permanent and cannot be undone, so archive is the safer choice when you might want the page again. --- --- url: 'https://docs.plane.so/pages/collections.html' description: >- Organize your Plane wiki with Collections. Create public or Invite Only collections and control access with View, Comment, and Edit roles. --- # Collections Collections are how Plane organizes your wiki pages. Think of them as folders for your workspace's knowledge. Every wiki page in your workspace lives inside a collection, and you can control exactly who gets to see each one. In your wiki sidebar, collections appear as a flat list. When you expand a collection, you see the pages inside it, and each page can have its own nested pages beneath it. The collections themselves don't nest inside each other, just the pages do. ## The General collection Every workspace starts with one collection called **General**. Plane creates it automatically, and it works as the default landing spot for any new wiki page you create without explicitly placing it somewhere else. You can add pages to it and move pages out of it, but you can't rename it or delete it. ## Collections visibility Plane gives you two kinds of collections, and the difference comes down to who can see what's inside. ### Public collections Public collections are visible to everyone in your workspace with a Member or Admin role. Anyone with those roles can read pages in a public collection, and create one. ### Private collections Private collections are visible only to the people you explicitly invite. If you haven't invited someone, the collection doesn't show up in their sidebar at all. This makes Private collections the right choice for anything sensitive like internal proposals, confidential decisions, HR documents, or anything that shouldn't be visible workspace-wide. For a full breakdown of what each role can do across all collection actions, see the [permissions matrix](/roles-and-permissions/permissions-matrix#wiki-collections). ## Create a collection **Create a public collection** 1. In your wiki sidebar, click the **+** next to **Collections**. 2. Enter a name. 3. Leave the visibility as **Public**. 4. Click **Create collection**. **Create a private collection** 1. In your wiki sidebar, click the **+** next to **Collections**. 2. Enter a name. 3. Select **Private** as the visibility. 4. Click **Create collection**. The collection appears in your sidebar immediately. Since no one else can see it yet, your next step is to invite the people who need access. :::warning You can't change a collection's visibility after you create it. If you need to switch, say, from private to public, create the new collection first, move your pages to it, then delete the old one. If you delete private collection before moving its pages, they'll be archived automatically. ::: ## Create a new page inside a collection You can create a new page directly from a collection without going through the main wiki page creation flow. 1. Open the collection. 2. Click the **+** menu inside the collection view. 3. Select **Create new page**. Plane creates the page and adds it to that collection immediately. It works just like creating any other wiki page, the only difference is it lands in the collection you're already in, rather than the General collection. ## Add an existing page to a collection If a page already exists and you want to move it into a collection, you add it from inside the collection. 1. Open the collection. 2. Click the **+** button inside the collection, then select **Add existing page**. 3. Search for the page by name, or browse the list. 4. Select one or more pages and confirm. A few things to keep in mind: * A page can only belong to one collection at a time. Adding it to a new collection removes it from its current one. * **For private collections**, only root-level pages can be added. You can't independently add a child page, it inherits its parent's collection. If you want a child page in a private collection, move its parent there and the children follow automatically. * The search shows only eligible pages. Pages that don't appear are either already in this collection, or aren't eligible (for example, a child page when adding to a private collection). ## Edit a collection You can rename a collection or change its icon at any time, the visibility setting is the only thing you can't change after creation. This does not apply to the General collection, which can't be renamed. 1. Open the collection's options menu (the **···** next to its name in the sidebar). 2. Select **Edit**. 3. Update the name, or click the icon to pick a new emoji or icon. 4. Save. ## Manage access in a private collection Once you create a private collection, you manage who can access it through the collection's share settings. **Invite a member** 1. Open the private collection. 2. Click the **Share** button (or open the collection's options menu and select **Share**). 3. Search for a workspace member by name or email. 4. Choose their access level: * **View** — they can read pages but not edit or comment * **Comment** — they can read and leave comments * **Edit** — they can read, comment, and edit pages 5. Click **Save**. The member can now see and access the collection according to the level you set. **Change a member's access level** 1. Open the collection's **Share** settings. 2. Find the member in the list. 3. Click their current access level and select a new one. **Remove a member** 1. Open the collection's **Share** settings. 2. Find the member in the list. 3. Click the remove option next to their name. They immediately lose access to the collection and all pages inside it. :::info **Workspace owners and admins always have full access** to every private collection in the workspace, regardless of whether they're in the members list. ::: ## Search and filter pages within a collection When a collection has many pages, you can search and filter to find what you need. * **Search** - type in the search box inside the collection view to filter pages by name in real time. * **Filter** - use the filter menu to narrow pages by creator, date created, or your favorited pages. These controls apply only to the current collection view, they don't affect other collections or the sidebar. ## Move pages between collections Drag the page to its destination collection in the wiki sidebar. Depending on the visibility change involved, Plane shows a confirmation dialog before completing the move. The page moves immediately. Nested pages follow their parent. If you move a parent page, all its children move with it. * **Moving a page into a private collection** automatically makes that page private. Only people with access to the collection will be able to see it. * **Moving a page out of a private collection** into a public one makes it visible to the whole workspace again. * **Removing a page from a private collection without moving it elsewhere** keeps the page private. It doesn't automatically become public. You'll need to update the page's own access setting manually if you want to make it public again. ## Reorder collections and pages **Reorder collections in the sidebar** Drag a collection up or down in the sidebar list to change its position. **Reorder pages within a collection** Inside a collection, drag pages up or down to change the order they appear in. This affects how pages show up in the collection view and in the sidebar when the collection is expanded. ## Delete a collection 1. Open the collection's options menu. 2. Select **Delete**. 3. Confirm the deletion. **What happens to the pages** For **public collections**, Plane gives you a choice when you delete. * **Delete collection only** - the collection is removed and the pages return to the General collection. * **Delete collection and archive pages** - the collection is removed and all its pages are archived. Archived pages aren't permanently deleted; you can find and restore them from your workspace archive. For **private collections**, pages are always archived when you delete the collection, there's no option to keep them unarchived. :::info You can't delete the **General** collection. ::: ## See also * [Wiki](/core-concepts/pages/wiki) * [Collections permissions matrix](/roles-and-permissions/permissions-matrix#wiki-collections) --- --- url: 'https://docs.plane.so/pages/nested-pages.html' description: >- Create structured documentation with Nested Pages. Build parent-child hierarchies, organize content logically, and improve navigation for your team's knowledge base. --- # Nested Pages Nested Pages allows you to create a hierarchical structure for your content, helping you organize documentation logically and improve navigation for your team. This feature enables you to build robust knowledge architecture with parent and child pages, similar to folders and files. Nested pages are available in two contexts: * Wiki Pages (Workspace level) * Project Pages (Project level) ## Create nested pages While editing any page, type `/page` to insert a new page reference. Name your new page and it will automatically be created as a child of the current page. ![Page command](https://media.docs.plane.so/pages/page-command.webp#hero) Wiki Pages offer an additional ways to create nested pages. Click the **+** icon that appears next to any page name. This creates a new page nested under the selected parent. ![Nested page on the wiki sidebar](https://media.docs.plane.so/pages/create-nested-page-sidebar.webp#hero) ## Move pages between levels Both Wiki Pages and Project Pages support reorganizing your page hierarchy. To promote a nested page to a higher level, drag it to the desired position in the hierarchy. To demote a page to become nested under another, drag it under the new parent. ![Move nested pages](https://media.docs.plane.so/pages/move-nested-pages.webp#hero) ## Navigate nested pages * Your page hierarchy is displayed with visual indentation showing the nesting structure (in the sidebar for Wiki, or in the Pages section for project pages). * Expand or collapse parent pages using the ▶ arrow to show or hide nested pages. * Breadcrumbs appear at the top of each page showing the full path. * Click any page in the breadcrumb trail to navigate to that level. This provides context about where you are in the documentation hierarchy. ## Visibility and access control #### Public vs private pages * Public pages are visible to anyone with Admin/Member access to your Workspace (for Wiki Pages) or Project (for Project Pages). * Private pages are only visible to you and the Workspace Admins (for Wiki Pages) or Project Admins (for Project Pages). * You can nest private pages under public pages for controlled access to sensitive information. * A private nested page is not visible to users who only have access to the public parent. #### Visibility inheritance * Nested pages do not automatically inherit the visibility settings of their parent. * Each page can have its own visibility settings, allowing for flexible access control. * Users without access to a parent page will not see any nested pages, regardless of the nested pages' individual visibility settings. ## Archiving and deletion * When you archive a parent page, all nested pages under it will also be archived. This helps maintain the integrity of related content. * Archived pages can be restored from the **Archived** section. * Deleting a parent page prompts a warning about nested content. You can choose to: * Delete only the parent page and move nested pages up one level. * Delete the parent and all nested content permanently. --- --- url: 'https://docs.plane.so/pages/page-labels.html' description: >- Tag and organize wiki pages with workspace-level labels, and filter pages by label. --- # Page Labels Page labels let you tag pages so you can categorize and find them. A label has a name and a color, and a page can carry as many labels as you need. Labels are shared across the workspace, so the same set is available on every page. ## Apply labels to a page 1. Open the page and go to its **info panel** in the navigation pane. 2. Open the **Labels** field. 3. Search for a label and select it. A page can have multiple labels; select as many as apply. Applied labels appear on the page with their color. To remove one, click the **x** on the label. ### Create a label while tagging If the label you want does not exist yet, type its name in the labels search box and choose **Create "\<name>"** at the bottom of the list. The new label is created with a color and applied to the page immediately. It then becomes available for every other page in the workspace. ## How labels are scoped Labels are **workspace-level**. Creating a label once makes it available on all pages across the workspace, and label names are unique within a workspace, so you cannot create two labels with the same name. ## Filter pages by label In the pages list, use the filters to narrow pages by label. This makes labels a quick way to pull up a set of related pages, for example everything tagged `runbook` or `RFC`. ## Permissions Applying and removing labels on a page follows your edit access to that page. Managing the workspace's label set (creating, renaming, recoloring, and deleting labels) is governed by page label permissions in the workspace. ## Notes * Deleting a label removes it from every page it was applied to. The pages themselves are not affected. * A page's labels are independent of work item labels; page labels apply only to pages. --- --- url: 'https://docs.plane.so/templates/page-templates.html' description: >- Create Page templates to standardize documentation and build reusable page structures. Save time and ensure consistency with our step-by-step guide. --- # Page Templates Page Templates help you standardize and streamline your documentation workflow by providing reusable page structures for common content types. Instead of manually creating similar pages from scratch, templates allow you to quickly apply predefined formats and content, saving time and ensuring consistency across your workspace. Templates are perfect for teams who: * Create recurring documentation with similar structures. * Need to maintain consistency across pages and content. * Want to reduce setup time for new documentation. * Need to ensure all pages follow standard formats and include required information. ## Create page template 1. Navigate to [Workspace Settings](https://docs.plane.so/core-concepts/workspaces/overview#access-workspace-settings). ![Create page template](https://media.docs.plane.so/templates/create-page-templates.webp#hero-tr) 2. Select the **Templates** tab on the right pane. 3. Click the **Create template** button in the top-right corner. 4. Select **Page template** from the dropdown options. 5. Fill in the template details: ![Page template details](https://media.docs.plane.so/templates/page-template-details.webp#hero) * Give your template a clear, descriptive name. * Add a description explaining when and how to use this template. * Design your page layout and add any standard content, headers, or formatting. * Include placeholder text or instructions for future users. * Set up any recurring elements like tables, checklists, or sections. 6. Click **Create page template** to save. ## Use page templates Once you've created templates, you can use them whenever you create a new page. ![Use Template when creating pages](https://media.docs.plane.so/templates/use-template-pages.webp#hero) 1. Navigate to the location (Project page or Wiki) where you want to create a new page. 2. Click the + button to add a new page. 3. Select from available page templates in the template picker. 4. Your new page will be pre-populated with all the template content and formatting. 5. Replace placeholder content with your specific information. 6. Make any necessary adjustments to customize the page. Alternatively, from the Templates settings page: ![Use template in settings](https://media.docs.plane.so/templates/use-page-template-settings.webp#hero-br) 1. Find your template in the list. 2. Click the **Use template** button next to the template name. 3. This will immediately create a new page with all template content pre-filled. ## Manage templates You can manage your templates from two locations: * **Workspace-level templates**: Access from **Workspace Settings > Templates** * **Project-level templates**: Access from **Project Settings > Templates** From either location you can: * View all existing templates * Create new templates * Use existing templates * Edit or delete templates --- --- url: 'https://docs.plane.so/pages/edit-ms-office-files.html' description: >- Edit Word, Excel, and PowerPoint files attached to a wiki page directly in your desktop Microsoft Office app, with changes saved back to Plane. --- # Edit Microsoft Office Files You can edit Microsoft Office files that are attached to a **wiki page** without downloading them, re-uploading them, and losing track of versions. Plane opens the attachment in the **Microsoft Office desktop app** already installed on your computer, and when you save in Office, the changes are written straight back to the same attachment on the page. This is real editing of the file in place, not a preview and not a separate copy. The attachment keeps its place on the page, and everyone sees the updated version. ## Requirements * You need the **Microsoft Office desktop app** (Word, Excel, or PowerPoint) installed on your computer. Plane opens the file in that app; it is not an in-browser editor. * You need a **desktop web browser**. This does not work on mobile. * Your Plane site must be served over **HTTPS**. On Plane Cloud this is always the case. Self-hosted instances must be configured with HTTPS. ## Supported file types Editing works with the standard Office formats: * **Word:** `.doc`, `.docx` * **Excel:** `.xls`, `.xlsx` * **PowerPoint:** `.ppt`, `.pptx` ## Where it works This feature is limited to **attachments on wiki pages**. Office files attached to work items or added to comments cannot be edited this way; they can still be downloaded and re-uploaded as usual. ## Edit a file 1. Attach an Office file to a wiki page, or open a page that already has one. 2. On the attachment, click **Edit**. 3. Your browser asks to open the file in the matching Microsoft Office app. Allow it. 4. The file opens in the desktop app. Make your changes and **save** in Office as you normally would. 5. Your saves are written back to the attachment in Plane. When you are done, close the file in Office. You do not need to re-upload anything. The file on the page updates in place and keeps the same attachment. ## While you are editing To prevent two people from overwriting each other, the file is **locked** while it is open for editing. During that time, another person cannot start editing the same attachment. The lock is released when you finish, and it also expires on its own after a period of inactivity, so a file is never left locked forever if an editing session is abandoned. ## Notes and limits * **Desktop only.** Editing requires the desktop Office app and a desktop browser. There is no in-browser or mobile editing. * **Your local Office app does the editing.** Plane does not convert the file or render it in the browser. It hands the file to Word, Excel, or PowerPoint on your machine over a secure connection, and commits your saves back. * **The file stays the same file.** Edits keep the same attachment rather than creating a new copy, so links to it stay valid and its history stays in one place. * **Wiki pages only.** Work item and comment attachments are not covered. --- --- url: 'https://docs.plane.so/pages/page-analytics.html' description: 'Track page views, contributors, engagement, and measure content performance.' --- # Page Analytics Page analytics track how pages are discovered, viewed, and used within your workspace. Understand content performance, identify engaged readers, and see which pages drive collaboration. ## What gets tracked ### Views * **Total views** - Sum of all page views across all users * **Unique viewers** - Count of distinct people who viewed the page ### Contributors * **People who edited** - Users who made changes to the page (comments, edits, uploads) * **Last activity** - When they last contributed * **Session count** - How many separate contribution sessions they had ### Content metrics * **Nested pages** - Count of child pages in the hierarchy * **Attachments** - Count of files uploaded to the page ### Time series data * **Daily breakdown** - Track total and unique views over time (7 days, 30 days, 90 days, or all-time) * **Viewer list** - Who viewed the page and when ## View analytics for a page 1. Open any page (project page, workspace page, or collection). 2. Look for the **Analytics** button or panel icon in the page header. 3. Click to open the analytics panel. 4. The analytics panel shows a dropdown for time range: * **7 days** - Last week's data (default) * **30 days** - Last month * **90 days** - Last quarter * **All** - All-time data since page creation ### Explore the data The analytics panel has sections #### Overview Four metrics cards show * **Total views** - All views across all users * **Unique viewers** - How many distinct people viewed the page * **Nested pages** - Child pages in this hierarchy * **Attachments** - Files uploaded to this page #### Views chart A stacked area chart shows * **Total views** (upper area) - All views combined * **Unique viewers** (lower area) - Distinct people per day * Hover over any day to see exact numbers * Chart covers your selected time range, with daily breakdowns #### Viewers A list of people who viewed the page * **Name and avatar** - Who viewed * **Last viewed** - When they last opened the page * **View count** - How many times they viewed * **Search** - Type a name to filter the list (searches across all pages viewed in the range) #### Contributors People who made changes to the page: * **Name and avatar** - Who contributed * **Last activity** - When they last edited, commented, or uploaded * **Sessions** - How many separate contribution sessions * **Owner badge** - Marks if they own the page ## Analytics for collections Collections show analytics across all pages within them. 1. Open a collection. 2. Click the **Analytics** button in the collection header. 3. The collection analytics panel opens. Summary metrics for all pages in the collection: * **Total pages** - Count of pages in the collection * **Total views** - All views across all collection pages * **Unique viewers** - Distinct people who viewed any page * **Total contributors** - People who edited any page in the collection ### Collection views trend Shows how the entire collection is performing over time. The chart breaks down: * **Total views** - All views on all pages * **Unique viewers** - Distinct people viewing collection pages * Hover to see daily breakdown ### Collection pages table A searchable, paginated table of all pages in the collection: * **Page name** - Clickable link to the page * **Views** - Total views for that page * **Unique viewers** - How many people viewed it * **Nested pages** - Child pages under it * **Search** - Type to filter by page name * **Pagination** - Navigate through pages (10 per page) ## Understanding the data ### What counts as a view A view is recorded when someone opens or navigates to a page. Views within 1 hour of the previous view by the same person count as one session - this prevents inflating the count if someone refreshes or navigates back to the page. ### Who sees analytics * **Page editors** - Can see analytics for pages they can edit. * **Viewers** - Cannot see analytics (read-only access). * **Workspace admins** - Can see analytics for all pages. ### Exclude yourself Owner views are tracked but can be identified (marked with "Owner" badge). Owner self-views do not count toward "Unique viewers" - only external views are counted for uniqueness. ### Time zone All timestamps are shown in your workspace's time zone. All aggregations (daily, weekly) are calculated relative to the workspace time zone. ## Exporting analytics Export analytics data as CSV for external analysis or record-keeping. 1. Open page analytics panel. 2. Click the **Export** button. 3. A CSV file downloads with: * Page metadata (name, URL, created date) * All viewers and their view counts * All contributors and their activity dates * Timestamps for each row ### Export collection analytics 1. Open collection analytics panel. 2. Click the **Export** button. 3. A CSV file downloads with * Collection metadata * One row per page in the collection * Views, unique viewers, and contributor count per page * Timestamps The export includes all data visible in the analytics panel for your selected time range. ## Data accuracy ### Session windows * **Views** - Counted as one session if within 1 hour of the last view * **Contributions** - Counted as one session if within 30 minutes of the last contribution * Adjusts session count but not total view count ### Data delays Analytics data updates in real-time as you view and edit pages. No batch processing or delays. ### Archived pages * Archived pages stop recording new analytics * Historical analytics remain available * Archived pages excluded from collection analytics ### Deleted pages * Deleted pages are removed from analytics entirely * No historical data is retained --- --- url: 'https://docs.plane.so/pages/report-page.html' description: >- Learn how to report a publicly published Plane page that contains harmful, misleading, or policy-violating content. --- # Report page When someone publishes a page on Plane and makes it publicly accessible, anyone who can view that page can report it if the content looks harmful, deceptive, or otherwise unsafe. Reporting sends a flagged notice directly to Plane's support team, who review it and decide what action to take. You don't need a Plane account to file a report — if you can see the page, you can report it. ## How to report a published page ![Report page](https://media.docs.plane.so/pages/report-page.webp#hero) 1. Open the published page you want to report. 2. Click the **...** menu in the top-right corner of the page. 3. Select **Report page**. 4. In the dialog that opens, choose the reason that best describes the issue: * **Phishing or spam** — misleading links, scams, or deceptive content designed to trick readers * **Inappropriate content** — violent, explicit, or otherwise harmful material * **Copyright / DMCA takedown** — content that infringes on intellectual property you own or represent * **Other violation** — anything that doesn't fit the above; describe the issue in the text field 5. Add a description to give Plane's team more context. This is required if you select **Other violation**. 6. Click **Report this page**. Your default email client will open with a pre-filled message to Plane's support team. Send the email to complete the report. The page link and your selected reason are already included — you don't need to add anything unless you want to. ## Report by email If you can't access the report option - for example, the page has already been taken down, or you're reporting on behalf of a security team - email **security@plane.so** with: * The full URL of the page * A short description of the issue * Any supporting evidence: screenshots, email headers, originating IPs, or related URLs ## What you should report The following types of content and activity are not permitted on publicly published Plane pages. * **Phishing and impersonation**\ Pages designed to impersonate other services, brands, or individuals, or to harvest credentials, payment details, or personal information under false pretences. * **Malware and malicious code**\ Hosting, distributing, or linking to malware, viruses, ransomware, or any code intended to harm users or systems. * **Illegal activity**\ Content that encourages, plans, or facilitates activity that breaks the law, or instructs others on how to do so. * **Harmful or graphic content**\ Sexually explicit material, graphic violence, content promoting self-harm, or anything else that endangers public safety. * **Child safety violations**\ Any content that exploits, abuses, endangers, or sexualizes minors. * **Harassment and threats**\ Bullying, threatening, or defaming individuals or groups. * **Hate speech and discrimination**\ Content that promotes violence or discrimination based on race, ethnicity, religion, gender, sexual orientation, disability, age, nationality, or any other protected characteristic. * **Fraud and scams**\ Fake giveaways, investment schemes, deceptive offers, or any content designed to defraud readers. * **Privacy violations**\ Publishing someone's personal or confidential information without their consent. * **Intellectual property infringement**\ Content that reproduces copyrighted material, trademarks, or other intellectual property without permission. * **Spam and deceptive practices**\ SEO manipulation, link farms, misleading redirects, or other deceptive distribution tactics. * **Disruption of Plane**\ Using Plane in ways that interfere with our service, infrastructure, or users. This isn't an exhaustive list. If something feels wrong, report it. ## What happens after you report Reports are reviewed by our trust and safety team. Confirmed violations result in one or more of the following: * The published page is disabled immediately. * The workspace is suspended pending further investigation. * The account is permanently terminated for severe or repeat violations. We don't share the identity of the reporter with the person who published the page. --- --- url: 'https://docs.plane.so/core-concepts/issues/estimates.html' description: >- Set up and customize work item estimation using points, categories, or time to quantify task complexity and effort. --- # Estimates Estimates in Plane help quantify the time and effort required for each work item in your project. Whether using a simple number scale or categories like T-shirt sizes, estimates provide a clearer idea of the work involved. They act as a proxy for complexity, helping teams gauge task scale quickly without detailed breakdowns. Estimates also aid in prioritizing, resource allocation, managing workload expectations, and identifying potential bottlenecks. ## Set up estimate system Getting started with estimates in your project is quick and easy. Here’s how you can set it up: 1. By default, your project won’t have an estimate system in place. To set one up, go to **Project > Settings** and select the **Estimates** tab. ![Add estimate system](https://media.docs.plane.so/projects/enable-estimate-system.webp#hero) 2. Click on **Add estimate system**. 3. You can choose from the following options: * [Points](/core-concepts/issues/estimates#points) * [Categories](/core-concepts/issues/estimates#category) * [Time](/core-concepts/issues/estimates#time) ![Choose estimate type](https://media.docs.plane.so/projects/choose-estimate-system.webp#hero) 4. You can either choose a ready-made template and tweak it to fit your needs or create your own custom estimate system from scratch. 5. When you are done, turn on the **Enable estimates for my project** toggle. ![Enable estimate type](https://media.docs.plane.so/projects/enable-estimate-toggle.webp#hero-tr) ::: info Free plan projects support up to 6 custom estimate values. [Upgrade to Pro](https://plane.so/pricing) to add additional estimate values for Points, Categories, and Time-based estimates. ::: ## Types of estimates ### Points This system uses numeric values to quantify effort, making it a great fit for teams that prefer to track progress based on numbers. Plane offers several preset progressions for you to choose from: * **Linear**\ A simple, evenly spaced number progression. * **Fibonacci**\ A more dynamic progression where each number is the sum of the previous two (e.g., 1, 2, 3, 5, 8, 13, etc.). This is useful when estimating tasks of varying complexity. * **Squares**\ A progression where each value is the square of the number (e.g., 1, 4, 9, 16, etc.). * **Custom**\ Create your own progression to match your team's specific needs. ### Category If you prefer to estimate effort by text categories rather than numbers, this is the system for you. Typical examples include: * **T-shirt sizes**\ A common approach to estimating effort, this system uses sizes like XS, S, M, L, and XL to represent the complexity or effort of a work item. This method is popular in agile teams for its simplicity. * **Easy to Hard**\ This system uses categories like "Easy", "Medium", and "Hard" to represent how difficult or time-consuming a work item might be. It's useful when you want to quickly categorize tasks without needing exact numbers. * **Custom**\ You can create your own custom categories to fit your team’s workflow. Whether you want to use something like "Low", "Medium", "High" or something more specific to your project, the custom option allows complete flexibility. This system provides a high-level estimate of effort based on intuitive categories, which is especially helpful in teams where relative effort matters more than precise numeric estimates. ### Time This system uses time durations to estimate how long work items will take to complete. It's ideal for teams that need to plan based on actual time investments or track billable hours. Plane offers two ways to set up your time estimates: * **Hours**\ A predefined set of time durations (1h, 2h, 3h, 4h, 5h 30m, 6h 30m) that covers most task timeframes. * **Custom**\ Create your own time-based estimation system with the exact durations that match your team's workflow needs. Starts with basic time increments (1h, 2h) that you can use as a foundation for your own estimation system. Time estimates provide concrete forecasting for project planning and resource allocation, making them particularly valuable for client work, deadline-driven projects, or when tracking productivity metrics based on time spent. ## Edit estimate system ![Edit estimate system](https://media.docs.plane.so/projects/edit-estimate-system.webp#hero) To update your estimate system, follow these steps: 1. Click the pencil icon next to the estimate system you’ve set up. 2. Select **Add, update or remove estimates**. * Add new estimates as needed or remove ones that are no longer relevant. 3. Select **Change estimate type**. * If a different type of estimate system suits your project better, you can switch between system types here. ::: info In earlier versions of Plane, we allowed multiple estimate systems within a single project, giving you the ability to switch between them. Based on user feedback, we’ve simplified this process. Now, each project can only have one active estimate system, and older, inactive systems have been archived for better clarity and ease of use. ::: --- --- url: 'https://docs.plane.so/core-concepts/issues/bulk-ops.html' description: >- Learn how to save time by updating multiple work items at once in Plane. Change states, priorities, assignees, dates, and more with efficient bulk operations. --- # Bulk Operations Working with multiple work items at once can save you significant time. ![Bulk update](https://media.docs.plane.so/issues/bulk-update.webp#hero) ## Bulk edit work items To perform bulk operations: 1. Make sure you're in either the **List** or **Table** layout - bulk operations aren't available in other layouts. 2. Select work items by clicking the checkbox next to each one, or use the select all checkbox at the top of the list. 3. After selecting work items, update the available properties at the bottom of the screen. 4. Click the **Update** button to apply your modifications. Until you click this button, your changes won't be saved. ## Available bulk operations You can modify several properties across multiple work items simultaneously: * Change the state (like moving work items from "In Progress" to "Done") * Update priority levels * Assign or reassign team members * Add work items to cycles * Change work item types * Apply or remove labels * Set or modify modules * Add or update start and due dates ## Copy work items Select the work items you want, then choose **Make a copy** from the bulk actions. Pick a destination project — it defaults to the current one — and confirm. Which properties survive the copy depends on whether the destination is the same project or a different one. See [What gets copied](/core-concepts/issues/overview#what-gets-copied) for the full field-by-field breakdown; bulk copies follow the same rules as copying a single work item. A few things specific to copying in bulk: * You can copy up to **1000 work items** at a time. * You need permission to create work items in the destination project. * The copy runs in the background, so the new work items appear in the destination project shortly after you confirm rather than all at once. * If the selection contains epics and the destination project has no Epic type, those epics are skipped and the rest of the selection still copies. ## Subscribe to multiple work items If you need to keep track of several work items at once, you can subscribe to multiple work items in a single operation. This ensures you'll receive notifications about any updates to those work items. ## Manage work item lifecycle You can also perform bulk management actions: * Archive multiple work items when they're no longer active but you want to preserve their history. * Delete multiple work items if they're no longer needed (note: this action cannot be undone) ## Tips for bulk operations * Take advantage of filters to select related work items more easily. * Double-check your selection before performing destructive actions like deletion. * Consider using bulk operations during project transitions or when doing major reorganization of work --- --- url: 'https://docs.plane.so/core-concepts/issues/time-tracking.html' description: >- Log hours on work items, view timesheet records, and download comprehensive reports for project time management. --- # Time Tracking > **Role**: Project Admins ## Overview Log time per work item, record time by members and guests per work item, and download consolidated worklogs from one screen with Time Tracking in Plane. Project members can easily log the time they spend working on specific work items directly within the work item details page. Each time entry can include details such as the amount of time spent and optional notes to provide context. Plane also offers comprehensive reports that aggregate time-tracking data across different projects helping managers analyze productivity and ensure successful project delivery. ## Turn on Time Tracking To turn on the Time Tracking feature on your project, follow the steps below: 1. Click the **…** icon next to your project name on the sidebar and click **Settings**. ![Project settings](https://media.docs.plane.so/time-tracking/project-settings.webp#hero-bl) 2. Select **Features** on the right pane. Turn on the **Time Tracking** toggle button. ![Enable time tracking](https://media.docs.plane.so/time-tracking/enable-time-tracking.webp#hero) The Time Tracking feature is now turned on for your project. ## Log time To track time on your work items, follow the steps below: 1. Under your project, open the work item on which you want to log time. 2. Click the **+ Log work** button. Enter the hours, minutes, and description. Click **Save**. ![Log work](https://media.docs.plane.so/time-tracking/log-work.webp#hero-br) 3. The **Tracked time** property will display the logged time. Every time you log work to the work item, this property is updated. ![Worklog created](https://media.docs.plane.so/time-tracking/worklog-created.webp#hero) ## Edit or delete a time log To update or remove a time entry, find the worklog in the work item's activity trail. Click the … menu on the entry to see two options: * **Edit** — opens the log with editable hours, minutes, and description fields. Adjust the values and click Update. * **Delete** — permanently removes the entry. The Tracked time property on the work item updates automatically. ## View worklogs To view timesheet records and download reports, follow the steps below: 1. Click the **∨** icon next to your workspace name on the sidebar and click **Workspace settings**. ![Workspace settings](https://media.docs.plane.so/workspaces/workspace-settings.webp#hero-tl) 2. Select **Worklogs** on the right pane to view the timesheet records. ![View worklogs](https://media.docs.plane.so/time-tracking/view-worklogs.webp#hero) 3. You can filter the records by **Users**, **Projects**, **Start date** and **End date**. It also allows you to download the timesheet reports as Excel or CSV files. ![Filter and download worklogs](https://media.docs.plane.so/time-tracking/filter-and-download-worklogs.webp#hero) --- --- url: 'https://docs.plane.so/workflows-and-approvals/workflows.html' description: >- Set up workflows to control how work items move through states, define transition rules, and require approvals before work progresses. --- # Workflows and Approvals Workflows give you control over how work items move through states in your project. Think of it as creating guardrails that ensure work follows your team's agreed-upon path, with the right people making decisions at each step. You define which transitions are allowed, who can make them, and whether certain moves need approval before they take effect. Every project has a single default workflow that applies to all work items regardless of type. On the Enterprise Grid, you can create additional workflows, each scoped to specific work item types, so different kinds of work can follow their own process. :::tip If you already had a workflow configured before, it's now your project's default workflow. All your existing transition rules and reviewer settings have been preserved. You can edit them at any time from the Workflows settings page. ::: ## Where workflows live depends on your plan Every plan builds workflows the same way, with the same states, flows, and conditions. What differs is **where** they are configured and **who** manages them. Find your setup below. | Plan / setup | Where you configure workflows | What you get | | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Business** | Inside each project, under **Project Settings → Workflows** | One **default workflow** per project that governs all work items in it. | | **Enterprise Grid** (project-managed) | Inside each project, under **Project Settings → Workflows** | Everything above, plus **approval flows**, **transition conditions**, and **multiple custom workflows** scoped to specific work item types. | | **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)** | Once for the whole workspace, under **Workspace Settings → Workflows** | Workflows are defined centrally by a workspace admin and applied to every project. Project admins no longer edit workflows inside a project; they choose from the workflows the workspace allows. | **In short** * If you're on **Business** or **Enterprise Grid without governance**, workflows live in **project settings**. Everything in [Set up workflows](#set-up-workflows) below is where you work. * If your workspace has turned on **[Workspace Governance](/workspace-administration/workspace-governance)**, workflow management moves to the **workspace level**. You still build workflows the same way, but in workspace settings, and projects consume them within the limits you set. See [Workspace level workflows](#workspace-level-workflows). :::warning Turning on governance moves workflows to the workspace Enabling workspace governance is a one-way change that relocates workflow management from individual projects to the workspace. Existing project workflows are migrated up and preserved. Read [Workspace Governance](/workspace-administration/workspace-governance) before enabling it. ::: ## Set up workflows The rest of this section describes how to build and run a workflow. It applies whether you manage workflows in **project settings** or in **workspace settings** (Enterprise Grid with governance) - the builder is identical. Where a step differs at the workspace level, it's called out inline. ### Turn on workflows Head over to your [Project Settings](https://docs.plane.so/core-concepts/projects/overview#configure-project-settings) and select **Workflows** from the sidebar. Toggle **Enable workflows** on at the top of the page. Once enabled, you'll see your project's default workflow listed with **Default** and **Active** badges. This workflow is active by default and governs all work items in the project. ![Workflows settings page](https://media.docs.plane.so/workflows/workflows-settings-page.webp#hero) The workflows list includes a search bar to find workflows by name. You can also filter the list by status (Active or Inactive) and by work item type, and sort it by name, date created, or date modified in ascending or descending order. ::: warning **Enterprise Grid with governance** There is no per-project **Enable workflows** toggle. Workflows are managed centrally under **Settings → Workflows** at the workspace level, and the workspace always has one default workflow. The list additionally shows how many **projects** and **work item types** use each workflow. ::: ### Define a workflow Whether you're editing the default workflow or a type-specific one, the workflow detail page works the same way. It lists all the states included in the workflow and lets you add flows that control how work items move between them. #### Add states The default workflow includes all states configured in your project. When you create a new workflow, it starts empty. You choose which states to include by clicking **Add states** in the top-right corner of the "Define workflow" section. A panel lists all available project states grouped by category. Select the ones you need and click **Add selected**. ![Select states](https://media.docs.plane.so/workflows/select-states.webp#hero) ::: warning **Enterprise Grid with governance** The states you add come from the workspace's shared [states](/core-concepts/issues/states#where-to-configure-states) catalog, not a project-specific list. ::: #### Allow new work items Each state has an **Allow new work items** toggle on the right side. When this is on, team members can create work items directly in that state. Turn it off for states that should only be reached through progression. ![Workflow states with allow new work items](https://media.docs.plane.so/workflows/allow-new-work-items.webp#hero) #### Add flows Flows define the rules for moving a work item from one state to another. To add a flow, expand a state by clicking its arrow, then click **+ Add flow**. A panel appears on the right where you choose the flow type - **Transition** or **Approval** - then click **Next** to configure it. You can add multiple flows to a single state, but they must all be the same type - either all transitions or all approvals. ##### Transition flows A transition flow defines a permitted state change. When you add one, you configure three fields: * **via** - shows **Transition** to indicate the flow type. * **move to** - the destination state. Click to select from available project states on the right pane. * **by** - who can make this transition. Defaults to **All**, meaning any project member. To restrict it, open the Members panel and select specific individuals. * **with** - optional conditions that run before or after the transition. See [Transition conditions](#transition-conditions) below. ![Transition flow](https://media.docs.plane.so/workflows/transition-flow.webp#hero) Click **Save** to confirm the flow, or **Discard** to cancel it. ##### Approval flows An approval flow adds a gate: the work item won't move forward until designated approvers accept or reject it. When you add one, you configure: * **via** - shows "Approval" to indicate the flow type. * **on approve, move to** - the state the item moves to when approved. * **on reject, move to** - the state the item falls back to when rejected. * **by** - who can approve or reject. Defaults to **All**, but you can restrict it to specific members. * **with** - optional conditions that run before or after the approval decision. See [Transition conditions](#transition-conditions) below. ::: warning **Enterprise Grid with governance** The members you pick under **by** are **workspace** members. At the project level they are the project's members. ::: ![Approval flow](https://media.docs.plane.so/workflows/approval-flow.webp#hero) For example, you might add an approval flow on "Testing" so that moving to "Ready for Release" requires sign-off from a QA lead. If rejected, the item moves back to "In Development" for further work. ### Transition conditions Transition conditions let you attach custom logic to any transition or approval flow. They use [Plane Runner](/automations/plane-runner) scripts to validate whether a transition should proceed and to perform follow-up actions after it completes. When you click the **Conditions** option in the "with" column of a flow, a panel opens on the right with two sections: **Pre validation** and **Post actions**. #### Pre-validation Pre-validation scripts run **before** a transition happens. They verify that the work item is ready to move - for example, checking that all required fields are filled, that an estimate exists, or that a linked document has been approved. If a pre-validation script returns `{ success: false }` or throws an error, the transition is blocked and the user sees an error message explaining why. If all pre-validation scripts return `{ success: true }`, the transition proceeds. You can chain multiple pre-validation scripts - they run in the numbered order shown (#1, #2, etc.). All must pass for the transition to proceed. **To add a pre-validation script:** 1. In the Conditions panel, under **Pre validation**, click **+ Select script**. 2. Choose an existing Runner script of type "Workflow Transition" from the list. 3. Or click **New Script** to create one inline - the script editor opens with the type pre-set to "Workflow Transition" and a template showing the return rules: * `return { success: true }` - allow the transition. * `return { success: false }` - block the transition. * `throw new Error("reason")` - block the transition with a specific message shown to the user. 4. Click **Save and use** to save the script and attach it to the condition in one step. 5. Click **+ Add more** to chain additional pre-validation scripts. #### Post actions Post-action scripts run **after** a transition completes successfully. They handle follow-up work - posting a Slack notification, creating a linked work item in another project, adding a comment, updating a custom property, or calling an external API. Post-action scripts don't block the transition (it has already happened). If a post-action script fails, the transition still stands, but the error is logged in the script's execution history. **To add a post-action script:** 1. Under **Post actions**, click **+ Select script**. 2. Choose an existing Runner script or create one inline. 3. Click **+ Add more** to chain additional post-action scripts. #### Example: enforcing quality gates A common pattern is combining pre-validation and post-actions on a single transition: **Transition: "In Development" → "In Review"** Pre-validation: * Script #1: Verify the work item has at least one assignee and an estimate. * Script #2: Verify all sub-work items are completed. Post actions: * Script #1: Post a message to Slack notifying the review channel. * Script #2: Add a "Ready for Review" label to the work item. If either pre-validation script fails, the developer sees an error message and the work item stays in "In Development." If both pass, the transition happens and the post-action scripts fire in sequence. For details on writing Runner scripts, including the full SDK reference, available globals, and security model, see [Plane Runner](/automations/plane-runner). ### Activate the workflow Once you've defined all the states and flows you need, toggle the workflow on from the Workflows settings page to make it active. You can toggle it off at any time to pause enforcement without losing your configuration. ### Additional options The three-dot menu on each workflow provides three options: * **Edit** - update the workflow's name, description, or assigned work item types. * **View change history** - see a log of all modifications made to the workflow, including who made each change and when. * **Delete** - permanently remove the workflow. Work items previously governed by this workflow will fall back to the default workflow. ## Create a custom workflow A custom workflow lets you define separate rules for different kinds of work. For example, you might want bug fixes to go through a stricter approval process than feature work, or you might want improvements to skip certain states entirely. When a work item matches a type-specific workflow, that workflow takes precedence over the default. To create one: 1. On the Workflows settings page, click **Add new workflow**. 2. Give the workflow a unique name and an optional description. 3. Under **Select types**, choose one or more work item types that this workflow will govern. ![Create new workflow](https://media.docs.plane.so/workflows/create-new-type-workflow.webp#hero) 4. Click **Create**. You'll land on the workflow detail page, where you can [define its states and flows](#define-a-workflow). ::: warning **Enterprise Grid with governance** The workflow name must be unique across the workspace, and you attach workflows to work item types through **governance modes** rather than a simple type assignment. See [Workspace level workflows](#workspace-level-workflows). ::: ## How workflows work Once a workflow is active, work items in the project follow its rules: **State creation restrictions**\ Items can only be created in states where **Allow new work items** is enabled. If a member tries to create a work item in a restricted state, they won't be able to. **Transition enforcement**\ Members can only move items along the transitions you've defined. If someone tries to make a state change that isn't permitted, they'll see a blocker message explaining why. ![Blocker message](https://media.docs.plane.so/workflows/blocker-message.webp#hero) **Approval gates**\ When a work item reaches a state with an approval flow, it enters a pending state. Approvers see **Approve** and **Reject** buttons at the top of the work item detail view. The item moves to the appropriate destination based on the approver's decision. ![Approve and reject buttons on a work item](https://media.docs.plane.so/workflows/approval-buttons.webp#hero) **Workflow precedence**\ If a work item's type matches a type-specific workflow, that workflow's rules apply instead of the default. For example, if you have a type-specific workflow for bugs, any bug in the project follows that workflow's transition and approval rules. All other work item types continue to follow the default workflow. ## Workspace level workflows On **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)** enabled, workflows are managed once for the entire workspace instead of project by project. A workspace admin builds a shared catalog of workflows under **Settings → Workflows**, and every project uses workflows from that catalog. Project admins no longer create or edit workflows inside a project; they choose from what the workspace allows. You build these workspace workflows exactly as described in [Set up workflows](#set-up-workflows) above. This section covers only what's different at the workspace level: the shared catalog, the default workflow, and how projects consume workflows. ### The shared catalog and default workflow * All workflows live in one workspace-level catalog. Each is listed with its status (Active or Disabled), its states, and how many projects and work item types use it. * The workspace has exactly **one default workflow**. It is the fallback for any project and work item type not bound to a more specific workflow, and it **cannot be deleted**. * Workflow names must be **unique across the workspace**. ### How projects use a shared workflow You control how much freedom each project has to pick its own workflow, set **per work item type** using a **governance mode**: | Mode | What a project admin can do | | --------------- | ------------------------------------------------------------------------- | | **Any** | Choose any active workspace workflow for that work item type. | | **Constrained** | Choose only from an **allowlist** of workflows you approve for that type. | | **Required** | No choice. One workflow is mandated, and every project uses it. | **Pins** - in **Any** or **Constrained** mode, you can **pin** a specific project to a specific workflow. This forces that one project's choice while leaving other projects free. Pins are unavailable in Required mode, and are removed automatically if a type is later switched to Required. **Effective workflow resolution** - for any project and work item type, the workflow that actually applies resolves in this order: 1. The **required** workflow, if the type's mode is Required. 2. The project's **pin**, if one exists. 3. The project's own **choice**, if set. 4. Otherwise, the **workspace default workflow**. The effective workflow determines the starting states, which states allow creation, and the allowed transitions for work items of that type in that project. :::warning Switching a workflow can move work items When a project's effective workflow changes - for example, because a type is set to Required - work items whose current state is not part of the new workflow are moved to a fallback state. Always review the preview before confirming a workflow change. ::: These controls are configured on the work item type. For the full details, see [Work item types](/work-items/workspace-work-item-types) and [Workspace governance](/workspace-administration/workspace-governance#how-projects-use-shared-workflows). ### What project admins see From a project's work item type settings, a project admin sees, per type: whether the type is free to choose, **constrained** to an allowlist, **mandated** (required), or **pinned**; the current effective workflow and any workflows they may pick; and a **preview** of how existing work items would be remapped if they switch, before applying the change. If a project admin tries to change a workflow they are not allowed to change, they get an error explaining that the workflow is mandated by the workspace, assigned by the workspace (pinned), or outside the allowed list. --- --- url: 'https://docs.plane.so/work-items/custom-relations.html' description: >- Define custom relation types at the workspace level to represent how work items connect across your projects. --- # Custom relations Relations describe how work items are connected to each other. Plane includes three [default relation types](/core-concepts/issues/overview#add-relations) that cover common use cases. You can create additional relation types tailored to how your organization thinks about work. For example, a team might define a "Tests" relation so QA work items link back to the features they validate, or a "Depends On" relation to model logical dependencies that don't map to scheduling constraints. Custom relations are workspace-level configurations. Once created, they're available when linking work items across any project in the workspace. ## Create a custom relation > **Role**: Workspace Admin 1. Go to **Workspace Settings > Relations**. 2. Click **Add relation**. 3. Fill in the three fields: * **Title** — the name of the relation type. * **Inward name** — how the relation reads from the perspective of the work item you're adding it to (e.g., "blocking," "depended on by," "tested by"). * **Outward name** — how the relation reads from the perspective of the work item you're linking to (e.g., "blocked by," "depends on," "tests"). 4. Click **Save**. ![Create custom relation](https://media.docs.plane.so/workspaces/custom-relations.webp#hero) The directional naming ensures the relation reads correctly from either side. The inward name appears on the work item you're adding the relation to, and the outward name appears on the work item you're linking. #### Examples | Title | Inward name | Outward name | | --------- | ----------- | ------------ | | Tests | tested by | tests | | Caused by | caused | caused by | ## Edit or delete a custom relation > **Role**: Workspace Admin From **Workspace Settings > Relations**, click on any custom relation to update its title, inward name, or outward name. You can also delete custom relations you no longer need. Changes apply across the workspace and update how the relation appears on any work items that already use it. ## Use relations in work items Once a custom relation exists, any project member can use it when linking work items. 1. Open a work item. 2. Click **Add relation**. 3. Choose the relation type from the dropdown — both default and custom relations appear here. 4. Select the work item to link. The relation appears on both work items using the appropriate inward or outward label. Learn more about [adding relations to work items](/core-concepts/issues/overview#add-relations). --- --- url: 'https://docs.plane.so/automations/overview.html' description: Automate repetitive project tasks in Plane. --- # Automations Automations handle repetitive project work so your team can focus on the work that matters. Instead of manually closing stale issues, archiving completed work, or nudging assignees about deadlines, you set up rules once and let Plane run them. There are two kinds of automations: **Default automations** come built into every project. They cover the most common housekeeping tasks — archiving completed work items, closing stale ones, and sending due date reminders — and you configure them with a single time-based setting. **Custom automations** are rules you build yourself. You choose a trigger, optionally add conditions to narrow scope, then define what happens. They run at either the project level or the workspace level. See [Custom automations](/automations/custom-automations). ![Automations](https://media.docs.plane.so/automations/automations.webp#hero) ## Set up default automations ### Auto-archive completed work items Auto-archive moves work items that have been sitting in a completed or cancelled state into an archived state. 1. Navigate to **Project Settings → Automations**. 2. Toggle on **Auto-archive closed work items**. 3. Set the **Auto-archive work items that are closed for** duration. Options include 1 month, 3 months, 6 months, 9 months, 12 months, or a custom time range. Once enabled, work items that have been in a completed or cancelled state for longer than the configured duration are archived automatically. Archived work items remain searchable and accessible in the project's archived view, but they no longer appear in active lists, boards, or spreadsheets. :::info Work items in active cycles or modules won't be archived even if they've been completed for longer than your threshold. ::: ### Auto-close stale work items Auto-close moves unfinished work items — those in Backlog, Unstarted, or Started states — to a closed/cancelled state after a period of inactivity. This prevents stale work items from cluttering your project indefinitely. 1. Navigate to **Project Settings → Automations**. 2. Toggle on **Auto-close work items**. 3. Set the **Auto-close work items that are inactive for** duration — for example, 1 month. 4. Choose the **Auto-close status** — the state that inactive work items will be moved to (e.g., Cancelled). ### Set up due date reminders Plane sends in-app and email notifications to assignees and subscribers when a work item's due date is approaching. 1. Navigate to **Project Settings → Automations**. 2. Toggle on **Auto-reminders**. 3. Set the **Send reminder before** timing — for example, 3 days before the due date. Only work items with a due date and at least one assignee or subscriber trigger reminders. Plane sends one reminder per window — not a daily flood. If you've set a 3-day reminder and the due date is 3 days away, each person gets one notification. --- --- url: 'https://docs.plane.so/automations/custom-automations.html' description: >- Automate repetitive project tasks with trigger-based workflows. Set up rules to automatically update work item properties, assign team members, and manage priorities when specific conditions are met. --- # Custom automations Custom automations let you streamline your project management workflow by automatically performing actions based on specific triggers and conditions. This powerful feature eliminates repetitive manual tasks, ensures consistency in your processes, and helps your team maintain focus on high-value work by letting the system handle routine operations. ![Create automations](https://media.docs.plane.so/automations/create-automation.webp#hero) For default automations, see [Automations](/automations/overview). Every custom automation has three components. When \[trigger] happens, if \[conditions] are met, then perform \[actions]. This trigger-condition-action framework allows you to create sophisticated workflows that adapt to your team's specific needs. * **Triggers** are events that start the automation. A single event fires the automation, which then evaluates conditions before executing actions. * **Conditions** are optional filters that must be satisfied for the automation to proceed. If you add multiple conditions, all of them must be met (AND logic). * **Actions** are what the automation does when fired. Multiple actions execute in sequence. ## Where automations live depends on your plan Every plan builds automations the same way, with the same triggers, conditions, and actions. What differs is **where** they are configured, **which projects** they can act on, and **which actions** are available. Find your setup below. | Plan / setup | Where you configure automations | What you get | | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Business** | Inside each project, under **Project Settings → Automations** | Custom automations scoped to one project, with the **Change property** and **Add comment** actions. | | **Enterprise Grid** (project-managed) | Project settings, plus **Workspace Settings → Automations** | Everything above, plus **workspace automations** that span all projects or a chosen subset, the **Send webhook** and **Run script** actions, and **scheduled** triggers. | | **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)** | Once for the whole workspace, under **Settings → Automations** | Automations are managed centrally by a workspace admin and applied to projects. Project admins no longer create or edit automations inside a project. | **In short** * On **Business**, automations live in **project settings** and act on that one project. * On **Enterprise Grid without governance**, you keep project automations and can also create **workspace automations** and use the webhook and script actions. * On **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)**, automation management moves to the **workspace level**. Project admins can no longer edit automations inside a project. See [Automations under workspace g\`overnance](#automations-under-workspace-governance). :::warning Turning on governance moves automations to the workspace Enabling Workspace Governance is a one-way change that relocates automation management from individual projects to the workspace. Existing project automations are migrated up and keep running. Read [Workspace Governance](/workspace-administration/workspace-governance) before enabling it. ::: ## Create a custom project automation Project automations apply to work items within a single project. ![Configure trigger and action](https://media.docs.plane.so/automations/configure-trigger-and-action.webp#hero) 1. Navigate to **Project Settings → Automations**. 2. In the **Custom automations** section, click **Create automation**. 3. Give your automation a descriptive name and an optional description, then save. 4. Click **Add trigger** and choose the event that should start the automation. 5. Optionally click **Add condition** to narrow when the automation runs. You can add multiple conditions - the automation only fires when all conditions are met. 6. Click **Add action** to define what happens. Choose from **Add comment**, **Change property**, or **Run Script**. You can add multiple actions - they execute in sequence. 7. Click **Confirm**. 8. Click **Enable** when you're ready for it to go live. An automation needs at least one trigger and one action before you can enable it. Until you enable it, it stays in draft and doesn't run. ::: tip You can add multiple conditions to create more specific rules and multiple actions to perform several operations in sequence on a single trigger. ::: ## Create a workspace automation Workspace automations can span your entire workspace or a specific set of projects. 1. Go to **Workspace Settings → Automations**. 2. Click **Create automation**. 3. Choose which projects the automation should apply to - all projects in the workspace, or a specific subset. 4. Follow the same steps as a project automation: name → trigger → conditions → actions. 5. Enable when ready. ## Configure a scheduled trigger If you want an automation to run on a timer rather than in response to an event: 1. Open the automation and go to the **Trigger** tab. 2. Select **Scheduled**. 3. Choose a frequency: **Daily**, **Weekly**, or **Monthly**. * Weekly: pick which days of the week. * Monthly: pick the day of the month (1–31). 4. Set the time (hour and minute) and your timezone. 5. Alternatively, switch to **Cron mode** and enter a 5-field cron expression directly. When you use a scheduled trigger, the only available action is **Run script**. There's no work item event to react to, so the script handles the logic of fetching and modifying work items itself. ## Add conditions Conditions filter which work items an automation acts on. Without them, the automation runs on every work item that matches the trigger. 1. Open the automation and go to the **Trigger** tab. 2. Scroll to **Conditions** and click **Add condition**. 3. Choose a field (Priority, State, Assignees, Labels, Work Item Type, or Created By). 4. Choose an operator (is, in, contains, etc.) and set the value. 5. Add more conditions as needed. Multiple conditions use **AND** logic by default - all of them must match. You can also create **OR** groups where only one condition in the group needs to match. ## Add actions 1. Open the automation and go to the **Action** tab. 2. Click **Add action** and choose a type: * **Change property** - update a field on the work item * **Add comment** - post a comment on the work item * **Run script** - execute a saved script via the Runner * **Send webhook** - POST a payload to an external URL when the automation fires 3. Configure the action details (see [Actions](#actions) for parameters). 4. Add more actions if needed. They run in the order listed. ## Manage automations ### Enable or disable an automation * **Enable**: open the automation and click **Enable**. The automation must have at least one trigger and one action. * **Disable**: open the automation and click **Disable** or toggle the status off. You can't delete an enabled automation - disable it first. ### Check automation run history Open any automation and click the **Activity** button on the top right. You'll see every run, the work items it acted on, whether the run succeeded or failed, and the full execution log. ## Reference ### Triggers | Trigger | Fires when | | ----------------- | --------------------------------------------- | | Work item created | A work item is created | | Work item updated | Any field on a work item changes | | State changed | A work item's state changes | | Assignee changed | An assignee is added or removed | | Comment added | A comment is added to a work item | | Scheduled | A configured time or cron schedule is reached | #### Scheduled trigger options | Option | Notes | | -------- | ------------------------------------------------------------------- | | Daily | Runs once a day at the time you set | | Weekly | Runs on the days of the week you pick, at the time you set | | Monthly | Runs on the day of the month you pick (1–31), at the time you set | | Cron | Enter a 5-field cron expression for custom schedules | | Time | Hour and minute (0–23 and 0–59) | | Timezone | Defaults to the project timezone, then workspace timezone, then UTC | ### Conditions Conditions let you filter which work items an automation acts on. You can combine multiple conditions with AND or OR logic. #### Fields you can filter on | Field | What it checks | | -------------- | ---------------------------------- | | State | The work item's current state | | Priority | Urgent, High, Medium, Low, or None | | Assignees | Who the work item is assigned to | | Labels | Labels applied to the work item | | Work item type | The type set on the work item | | Created by | Who created the work item | #### Operators | Operator | Use when | | ------------------------ | ----------------------------------------------- | | Is | The field exactly matches a specific value | | Is not | The field does not match a specific value | | In | The field matches any value in a set | | Contains | The field includes the value | | Greater than | The field is greater than the value | | Greater than or equal to | The field is greater than or equal to the value | | Less than | The field is less than the value | | Less than or equal to | The field is less than or equal to the value | ### Actions #### Change property Updates a field on the work item. | Property | What you can do | | ---------- | -------------------------------------------------------------------------------------------------- | | Priority | Set, add, or remove a priority level (Urgent, High, Medium, Low, None) | | State | Move the work item to a specific state | | Assignees | Add or remove assignees | | Labels | Add, remove, or replace all labels | | Start date | Set, update, or remove the start date | | Due date | Set, update, or remove the due date | | Cycle | Assign the work item to a cycle, move it to a different cycle, or remove it from its current cycle | :::tip When assigning a cycle, the cycle must belong to the work item's own project, and you cannot assign a work item to a cycle that has already ended. A work item can be in only one cycle at a time, so assigning a cycle moves the work item off any cycle it is currently in. ::: #### Add comment Posts a comment on the work item. You write the comment text in a rich text editor. The comment is always internal and appears as coming from Automation Bot in the activity log. You can include dynamic values in the comment using template variables - for example, inserting the current priority or state name into the comment text. **Example:** Say you have an automation that triggers when a work item's state changes. You want to leave a note with context each time that happens. Your comment template might look like: ``` This item has been moved to a new state. Current priority: {{priority}}. Please check if the due date needs updating. ``` #### Send webhook Posts an HTTP payload to a URL you specify whenever the automation fires. Use this to push automation events into external systems - trigger a deployment, open a ticket in another tool, post to a custom service, or sync data outside of Plane. This is different from workspace webhooks, which fire on any matching event across your workspace. A Send webhook action fires only when this specific automation runs - you control the trigger, conditions, and timing. **Configuration** | Field | Required | Notes | | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | URL | Yes | Must be a publicly reachable `http://` or `https://` address. Local and private network addresses are not accepted. | | Secret key | Auto-generated | Generated when you save the action. Shown once in plain text - copy it before leaving. After that it appears masked as `plane_wh_••••XXXX`. | | Custom headers | No | Up to 20 headers. Mark a header as secret to store its value encrypted - the value won't be returned in subsequent reads. | **The secret key** Plane generates a secret key when you first save the Send webhook action. It is shown in plain text once - copy and store it before navigating away. After that, it is masked and cannot be retrieved. If your key is compromised or you lose it, open the action in the automation editor and click **Regenerate secret**. The old key stops working immediately. Update your server before regenerating or your signature verification will fail. **What Plane sends** Every request includes these headers: | Header | Value | | ------------------- | ---------------------------------------------- | | `Content-Type` | `application/json` | | `User-Agent` | `Autopilot` | | `X-Plane-Delivery` | Unique ID for this delivery attempt | | `X-Plane-Event` | The automation event that triggered the action | | `X-Plane-Signature` | HMAC-SHA256 signature of the request body | Custom headers you add are merged in. You cannot override the reserved headers listed above. **Verifying the payload** Use the `X-Plane-Signature` header to confirm the request came from Plane and wasn't tampered with. Compute an HMAC-SHA256 digest of the raw request body bytes using your secret key and compare it to the header value. ```python import hashlib import hmac def verify_webhook(request_body_bytes: bytes, secret: str, signature_header: str) -> bool: expected = hmac.new( secret.encode("utf-8"), request_body_bytes, hashlib.sha256, ).hexdigest() return hmac.compare_digest(expected, signature_header) ``` Use raw request body bytes - not a parsed or re-serialized version - or the signature will not match. **Delivery behavior** Plane makes a single attempt with a 30-second timeout. If the request fails or times out, it is not retried. Check your automation's Activity log to see whether the delivery succeeded and what response your server returned. #### Run script Runs a saved script from your [Plane Runner](/automations/plane-runner) library. You pick the script from a dropdown. This is the only action available when using a scheduled trigger. ## How custom automations work ### How automations run Every time something changes in Plane - a work item is created, a state changes, a comment is posted - Plane checks whether any of your enabled automations should respond. If a trigger matches, Plane evaluates any conditions you've set. If those pass, it runs the actions in order. That's the whole flow: something happens → conditions are checked → actions run. If a condition doesn't match, nothing happens and the automation sits quietly. If an action runs into a problem, Plane stops there and marks that run as failed - you can see exactly what happened in the Activity tab. Each event is only processed once per automation, so you won't end up with the same action firing twice on the same work item. ### Project automations vs. workspace automations The distinction comes down to scope and reuse. **Project automations** are the right choice when the rule is specific to one project. They're simpler to configure - the states, labels, and members you pick from are all scoped to that project. **Workspace automations** are the right choice when you want the same behavior across multiple projects. Instead of recreating the same automation in five different places, you define it once and choose which projects it applies to - all of them, or just a specific subset. Either way, automations always act on individual work items. Workspace automations aren't doing anything different - they're just defined once and applied more broadly. ### Automation bot Every custom automation acts through its own dedicated bot account. When an automation changes a field or posts a comment, the activity log shows it came from "Automation Bot" - not from any person on your team. There are two reasons this matters: **You always know what made a change.** If a work item's priority changed unexpectedly, one glance at the activity log tells you whether it was a person or an automation. No guessing. **Automations don't trigger themselves.** Plane knows when a change originates from an automation, so it doesn't feed that change back in as a new event. A "state changed" automation that updates a state won't keep firing on its own output. ### Why scheduled automations only run scripts Most automations respond to something happening - a trigger gives them a specific work item to act on. Scheduled automations are different. They fire at a time you set, not because of any particular event. Since there's no work item that kicked off the run, Plane has nothing to apply a property change or comment to. That's why the only available action for scheduled automations is Run script. The script defines the logic - what to look for, which items to act on, and what to do with them. Scheduled automations check whether they're due roughly every 5 minutes. The time you configure follows your project's timezone, falling back to the workspace timezone, then UTC. ### Why your trigger isn't enough on its own Triggers tell Plane *what type of event* to watch for - not which work items to care about. A "state changed" trigger fires for every single state change in the project, across every work item, regardless of type, priority, or who it's assigned to. Without conditions, an action like "set priority to Urgent" would run on every state change in the project. That's almost never what you want. Conditions are what make an automation surgical. They let you say "only run this when the work item is a Bug, assigned to this person, with no due date set" - whatever combination of criteria actually defines the case you're building for. One thing worth knowing: when a work item is first created, some fields like assignees and labels can take a moment to register, even if someone filled them in during creation. Plane handles this - it checks the latest state of those fields before evaluating your conditions, so a filter like "assignee is X" on a creation trigger will work as expected. ## Automations under workspace governance On **Enterprise Grid with [Workspace Governance](/workspace-administration/workspace-governance)** enabled, automations are managed once for the entire workspace instead of project by project. A workspace admin owns all automation configuration, and project admins can no longer create or edit automations inside a project. You build these automations exactly as described above. This section covers only what's different when governance is on: * **Project-level automation editing is locked.** Project admins can no longer create or edit automations inside a project. Opening an automation in a project shows it as read-only, with a message that automations are managed at the workspace level. * **Existing project automations are preserved.** When governance is enabled, each project's automations are migrated up to the workspace level and scoped back to their original project, so they keep running exactly as before. * **All automations are managed centrally.** A workspace admin creates and edits every automation under **Settings → Automations**, choosing whether each one applies to all projects or a specific subset. See [Workspace governance](/workspace-administration/workspace-governance) for the full picture of what centralizes and what changes for projects. ## Common use cases Some common things people use automations for. * **State management.** Automatically move work items through your workflow when something changes - for example, transition a work item to "In Review" when an assignee is added, or back to "Backlog" when an assignee is removed. * **Triage and routing.** Make sure new work lands in the right place without manual intervention - for example, assign a default owner whenever a specific work item type is created, or apply a label to every incoming bug so nothing slips through untagged. * **Priority escalation.** React to signals that indicate urgency - for example, automatically mark a work item as Urgent when a specific label is applied, or raise priority when it gets reassigned to a senior team member. * **Contextual reminders.** Surface the right information at the right moment - for example, post an internal comment with a checklist when a work item enters "Ready for QA," or flag missing information when a work item is created without an assignee. * **Scheduled operations.** Run scripts on a timer to handle things that don't map to a single event - for example, sweep stale items weekly, sync data to an external tool nightly, or generate a status comment on open items every Monday morning. * **Sprint assignment.** Put work items into the right cycle automatically - for example, add a work item to the current cycle when its state changes to "In Progress," or remove it from its cycle when it moves to "Backlog." --- --- url: 'https://docs.plane.so/automations/plane-runner.html' description: >- Write custom scripts and reusable functions in JavaScript or TypeScript to automate workflows, enforce rules, and extend Plane's behavior. --- # Plane Runner Plane Runner is a secure, sandboxed execution engine that lets you write custom logic in JavaScript or TypeScript. You can use it to automate actions when events happen, run scheduled jobs, and enforce rules during workflow transitions. Runner provides two building blocks — **Scripts** and **Functions** — that work together to extend Plane's behavior beyond what [built-in automations](/automations/custom-automations) offer. ## Activate Plane Runner > **Role**: Workspace Admin 1. Go to **Workspace Settings > Plane Runner**. 2. Click **Activate now** under the Scripts card. 3. On the authorization screen, review the permissions Runner requires — read and write access to all workspace resources and your user profile. 4. Click **Accept**. Once activated, you'll see the **Scripts** and **Functions** tabs in the Plane Runner settings page. ![Plane Runner activated](https://media.docs.plane.so/automations/activate-runner.webp#hero) ## Building blocks ### Scripts A script is a piece of executable code that runs in response to a trigger. Scripts are the primary unit of custom logic in Plane Runner. Each script is written in JavaScript or TypeScript, runs in an isolated sandbox, and has access to the Plane SDK, reusable functions, and environment variables. When triggered, a script receives contextual data about what caused it to run and returns a result indicating success or failure. Scripts can be workspace-scoped (created by your team) or system-provided (built-in, read-only templates). ### Functions A function is a reusable, named piece of logic with defined parameters and return types. Functions work like utility libraries — you write them once and call them from any script. Functions can also be workspace-scoped or system-provided. **The key difference**: scripts are *triggered* by events, schedules, or transitions. Functions are *called* from within scripts. ## How scripts are triggered Scripts run in response to one of three trigger types. The trigger determines what data the script receives. ### Event-based automations Event-based automations run a script when something happens in your workspace — a work item's state changes, a new item is created, a label is added, and so on. The script receives the full event payload including the entity that changed, previous attributes, and the automation context. ```typescript export async function main(input: AutomationEventInput, variables: Record<string, string>) { // input.event — the Plane event that triggered this // input.context.automation_id — the automation rule ID // input.context.automation_run_id — this specific run's ID // variables — key-value pairs configured on the automation } ``` ### Scheduled automations (cron) Scheduled automations run a script on a recurring basis, such as daily or weekly. Since there's no triggering event, the script only receives variables. ```typescript export async function main(variables: Record<string, string>) { // variables — key-value pairs configured on the schedule } ``` ### Workflow transitions Run a script during state changes defined in [Workflows](/workflows-and-approvals/workflows). Workflow transition scripts serve two purposes: **Pre-validation** scripts run before a transition to check whether it should proceed. If the script returns an error or throws, the transition is blocked and the user sees the error message. These are attached to the **Conditions > Pre validation** section of a workflow transition flow. **Post-action** scripts run after a transition completes to perform follow-up work like notifying a channel, creating related items, or updating properties. These are attached to the **Conditions > Post actions** section. ```typescript export async function main(input: WorkflowTransitionEventInput, variables: Record<string, string>) { // input.event — the Plane event for the transition // input.context.workflow_transition_id — the transition ID // input.context.rule_id — the workflow rule ID // variables — key-value pairs configured on the rule } ``` Pre-validation scripts follow these return rules: * `return { success: true }` — allow the transition to proceed. * `return { success: false }` — block the transition. * `throw new Error("reason")` — block the transition with a specific message shown to the user. Post-action scripts don't block transitions. If they fail, the transition still stands and the error is logged. For details on attaching scripts to workflow transitions, see [Transition conditions](/workflows-and-approvals/workflows#transition-conditions). ## Create a script > **Role**: Workspace Admin 1. Go to **Workspace Settings > Plane Runner > Scripts**. 2. Click **New Script**. 3. Enter a title for the script. 4. Select a **Script Type** from the dropdown — **Automation**, **Workflow Transition**, or **Cron Trigger**. 5. Expand the **Variables** section to define any key-value parameters the script needs. These values are provided when the script is attached to an automation rule or workflow. 6. Write your script in the code editor. The editor includes IntelliSense — type `Plane.` to see available API methods. You can also click the **Functions** button to browse available functions. 7. Click **Save**. ### Script structure Every script must export an `async function main(...)`. This is the entry point that Runner calls when the script is triggered. ```typescript export async function main(input: AutomationEventInput, variables: Record<string, string>) { const projectId = input.event.project_id; const workItemId = input.event.entity_id; // Your logic here... return { success: true, message: "Done!" }; } ``` You can use TypeScript syntax freely — type annotations, interfaces, generics, enums, `as const`, optional chaining, and more are all supported. ### The event object For event-based and workflow scripts, the `input.event` object contains: | Field | Type | Description | | ----------------------------- | -------- | ----------------------------------------- | | `event_id` | `string` | Unique event identifier | | `event_type` | `string` | Type of event (e.g., `work_item.updated`) | | `entity_type` | `string` | Entity type (e.g., `work_item`) | | `entity_id` | `string` | ID of the affected entity | | `project_id` | `string` | Project where the event occurred | | `workspace_id` | `string` | Workspace ID | | `initiator_id` | `string` | User who initiated the action | | `timestamp` | `number` | Unix timestamp of the event | | `payload.data` | `object` | Current state of the entity | | `payload.previous_attributes` | `object` | Fields that changed (previous values) | ### Variables Variables are key-value string pairs that parameterize your script. Define them on the script and provide values when attaching the script to an automation rule, schedule, or workflow. To define variables on a script, expand the **Variables** section when creating or editing: ```json [ { "key": "sourceProjectId", "description": "Project ID to watch for changes", "required": true }, { "key": "slackWebhook", "description": "Slack webhook URL for notifications", "required": false } ] ``` Access variables in your code: ```typescript export async function main(input: AutomationEventInput, variables: Record<string, string>) { const projectId = variables.sourceProjectId; const webhook = variables.slackWebhook; } ``` ### Returning data Scripts should return an object. The return value is stored in the execution record and can be inspected later. ```typescript // Success return { updated: true, parentId: "abc-123" }; // Skipped (nothing to do) return { skipped: true, reason: "Work item has no parent" }; ``` If your script throws an error, the execution is marked as `errored` and the error details are captured. ## Create a function > **Role**: Workspace Admin 1. Go to **Workspace Settings > Plane Runner > Functions**. 2. Click **New Function**. 3. Enter a name and description. 4. Select a **Category** from the dropdown — HTTP, Notifications, Data, Utils, or Custom. 5. Expand **Parameters** to define input parameters. For each parameter, specify a name, type, description, and whether it's required. 6. Enter a **Return Type** describing what the function returns (e.g., `{ success: boolean }`). 7. Write the function code in the **Function Code** editor. 8. Click **Create Function**. The function is now available to call from any script using `Functions.yourFunctionName({ ... })`. A usage example is auto-generated at the bottom of the form. ### Using functions in scripts Functions are available via the `Functions` global. Call them by name with a single parameter object: ```typescript export async function main(input: AutomationEventInput, variables: Record<string, string>) { // Call a system function const siblings = await Functions.getSiblings({ projectId: input.event.project_id, workItemId: input.event.entity_id, }); // Call a custom workspace function const result = await Functions.calculatePriority({ severity: "high", isBlocking: true, }); // Call another system function await Functions.addComment({ projectId: input.event.project_id, workItemId: input.event.entity_id, comment: `Priority set to ${result.priority}`, }); } ``` Runner automatically detects which `Functions.*` calls your script makes during the build phase. Only the required functions are loaded at execution time — you don't need to import or configure anything. ## Test a script You can test a script without saving it or attaching it to an automation. Expand the **Test** section at the bottom of the script editor, provide test input data and variables, and run the script. Testing validates the code for security violations, builds it (detecting function dependencies), executes it with the provided input, and returns the result or error details. Test executions are recorded with `trigger_type: "test"` so you can review output, timing, and errors separately from production runs. ## Available globals Every script runs in a sandboxed environment with these pre-injected globals. ### Plane SDK (`Plane`) A pre-initialized client for the Plane API. Use it to read and modify work items, projects, states, labels, and more. ```typescript // Retrieve a work item const item = await Plane.workItems.retrieve(workspaceSlug, projectId, workItemId); // Update a work item await Plane.workItems.update(workspaceSlug, projectId, workItemId, { state: newStateId, priority: "high", }); // Create a work item const newItem = await Plane.workItems.create(workspaceSlug, projectId, { name: "Auto-created item", description_html: "<p>Created by automation</p>", priority: "medium", }); // List states const states = await Plane.states.list(workspaceSlug, projectId); // List labels const labels = await Plane.labels.list(workspaceSlug, projectId); // Create a label const label = await Plane.labels.create(workspaceSlug, projectId, { name: "auto-tagged", color: "#e53e3e", }); // Add a comment await Plane.workItems.comments.create(workspaceSlug, projectId, workItemId, { comment_html: "<p>Auto-comment</p>", }); // Create a relation await Plane.workItems.relations.create(workspaceSlug, projectId, workItemId, { relation_type: "relates_to", issues: [otherItemId], }); // Advanced search const results = await Plane.workItems.advancedSearch(workspaceSlug, { filters: { and: [{ parent_id: parentId }] }, project_id: projectId, }); ``` The `workspaceSlug` global is also pre-injected and always available. ### Functions library (`Functions`) The collection of reusable functions, both system-provided and workspace-scoped. See [Built-in system functions](#built-in-system-functions) for what's available out of the box. ### Environment variables (`ENV`) A `Record<string, string>` containing environment variables configured on the script. Use these for secrets, API keys, or configuration that shouldn't be hardcoded. ```typescript const apiKey = ENV.EXTERNAL_API_KEY; const webhookUrl = ENV.SLACK_WEBHOOK; ``` ### Fetch (HTTP requests) A sandboxed `fetch` function for making HTTP requests. It works like the standard Fetch API but is restricted to domains explicitly allowed on the script. See [Domain restrictions](#domain-restrictions). ```typescript const response = await fetch("https://api.example.com/data", { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${ENV.API_TOKEN}`, }, body: JSON.stringify({ key: "value" }), }); const data = await response.json(); ``` ## Built-in system functions These functions are available in every workspace out of the box: | Function | Category | Description | | ------------------------------------------------------------------ | ------------- | ---------------------------------------------------------------------------------------- | | `Functions.httpRequest({ url, method?, headers?, body? })` | HTTP | Makes an HTTP request. Returns `{ status, headers, data }`. Throws on non-2xx responses. | | `Functions.postToSlack({ webhookUrl, text?, blocks? })` | Notifications | Posts a message to a Slack incoming webhook. Supports plain text and Block Kit. | | `Functions.getChildren({ projectId, workItemId })` | Data | Returns all child work items of a given parent. | | `Functions.getSiblings({ projectId, workItemId })` | Data | Returns sibling work items (same parent, excluding self). | | `Functions.addComment({ projectId, workItemId, comment })` | Data | Adds a comment to a work item. Accepts plain text or HTML. | | `Functions.addLabel({ projectId, workItemId, labelName, color? })` | Data | Finds a label by name (or creates it) and attaches it to a work item. | ## Built-in system scripts Plane ships with ready-to-use system scripts that cover common automation patterns. These are read-only templates that you can attach to automations or workflows directly. **Mark parent as done if all children are done** — when a work item completes, checks all siblings. If every sibling is also completed, automatically marks the parent as done. **Create linked work item in another project** — when a work item in a source project reaches a specified state, creates a copy in a destination project with a `relates_to` link. System scripts appear alongside your custom scripts in the Scripts tab. ## Security model Runner executes scripts in a secure, isolated sandbox. ### What's allowed Standard JavaScript globals are available: `JSON`, `Math`, `Date`, `Array`, `Object`, `String`, `Number`, `Boolean`, `RegExp`, `Map`, `Set`, `WeakMap`, `WeakSet`, `Promise`, `Symbol`, `Proxy`, `Reflect`, `URL`, `URLSearchParams`, `atob`, `btoa`, `encodeURI`, `decodeURI`, `encodeURIComponent`, `decodeURIComponent`, `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` (function callbacks only), `TextEncoder`, `TextDecoder`, and standard error types. Runner-specific globals are also available: `Plane`, `Functions`, `ENV`, `fetch`, `workspaceSlug`, and `console`. ### What's blocked | Category | Blocked | Reason | | ---------------------- | ------------------------------------------------------------------------------------- | ------------------------------ | | Module system | `require`, `module`, `exports`, `import()` | No filesystem or module access | | Node.js APIs | `fs`, `child_process`, `http`, `net`, `os`, `path`, `cluster`, `vm`, `worker_threads` | No system access | | Code execution | `eval()`, `Function()`, `new Function()` | Dynamic code execution risk | | Process control | `process.exit()`, `process.kill()`, `process.env` | No process access | | Prototype manipulation | `__proto__`, `constructor`, `prototype` | Sandbox escape prevention | | Infinite loops | `while(true)`, `for(;;)` | Resource protection | | Implicit eval | `setTimeout("string")`, `setInterval("string")` | Must use function callbacks | ### Domain restrictions External HTTP requests via `fetch` or `Functions.httpRequest` are restricted to domains you explicitly allow. Configure the `allowed_domains` list on your script. Any fetch to a domain not on the list throws a `"Domain not allowed"` error. ## Execution limits | Limit | Default | Description | | ---------------------- | ---------- | ----------------------------- | | Execution timeout | 10 seconds | Maximum time a script can run | | Initialization timeout | 5 seconds | Maximum time for script setup | | Memory limit | 128 MB | Maximum memory per execution | If a script exceeds any limit, the execution is terminated and marked as `errored`. ## Examples ### Auto-close parent when all children are done When a work item moves to a completed state, check if all its siblings are also completed. If so, automatically mark the parent as done. ```typescript export async function main(input: AutomationEventInput, variables: Record<string, string>) { const projectId = input.event.project_id; const workItemId = input.event.entity_id; const item = await Plane.workItems.retrieve(workspaceSlug, projectId, workItemId); if (!item.parent) return { skipped: true, reason: "No parent" }; const statesResult = await Plane.states.list(workspaceSlug, projectId); const states = statesResult.results || statesResult; const stateGroupMap: Record<string, string> = {}; for (const s of states) { stateGroupMap[s.id] = s.group; } if (stateGroupMap[item.state] !== "completed") { return { skipped: true, reason: "Current item not in completed state" }; } const siblings = await Functions.getSiblings({ projectId, workItemId }); const allDone = siblings.every((s: any) => stateGroupMap[s.state_id] === "completed"); if (!allDone) { return { skipped: true, reason: "Not all siblings are completed" }; } const completedState = states.find((s: any) => s.group === "completed"); await Plane.workItems.update(workspaceSlug, projectId, item.parent, { state: completedState.id, }); return { updated: true, parentId: item.parent, stateId: completedState.id }; } ``` **Variables**: None required. **Functions used**: `getSiblings` ### Create a linked work item in another project When a work item in a source project moves to a specific state, create a copy in a destination project and link them. ```typescript export async function main(input: AutomationEventInput, variables: Record<string, string>) { const sourceProjectId = variables.sourceProjectId; const sourceProjectStateName = variables.sourceProjectStateName; const destinationProjectId = variables.destinationProjectId; const projectId = input.event.project_id; const workItemId = input.event.entity_id; if (projectId !== sourceProjectId) { return { skipped: true, reason: "Not in source project" }; } const statesResult = await Plane.states.list(workspaceSlug, sourceProjectId); const states = statesResult.results || statesResult; const targetState = states.find( (s: any) => s.name.toLowerCase() === sourceProjectStateName.toLowerCase(), ); if (!targetState) { return { skipped: true, reason: "State not found: " + sourceProjectStateName }; } const item = await Plane.workItems.retrieve(workspaceSlug, sourceProjectId, workItemId); if (item.state !== targetState.id) { return { skipped: true, reason: "Work item not in target state" }; } const newItem = await Plane.workItems.create(workspaceSlug, destinationProjectId, { name: item.name, description_html: item.description_html, priority: item.priority, }); await Plane.workItems.relations.create(workspaceSlug, sourceProjectId, workItemId, { relation_type: "relates_to", issues: [newItem.id], }); return { created: true, newWorkItemId: newItem.id, destinationProjectId }; } ``` **Variables**: | Key | Required | Description | | ------------------------ | -------- | -------------------------------------------------------- | | `sourceProjectId` | Yes | Project ID to watch for state changes | | `sourceProjectStateName` | Yes | State name that triggers the copy (e.g., "Ready for QA") | | `destinationProjectId` | Yes | Project ID where the new work item is created | ### Post to Slack on state change Notify a Slack channel whenever a work item moves to "In Review". ```typescript export async function main(input: AutomationEventInput, variables: Record<string, string>) { const projectId = input.event.project_id; const workItemId = input.event.entity_id; const item = await Plane.workItems.retrieve(workspaceSlug, projectId, workItemId); const statesResult = await Plane.states.list(workspaceSlug, projectId); const states = statesResult.results || statesResult; const currentState = states.find((s: any) => s.id === item.state); if (currentState?.name !== "In Review") { return { skipped: true, reason: "Not in 'In Review' state" }; } await Functions.postToSlack({ webhookUrl: variables.slackWebhook, text: `Work item "${item.name}" is now In Review\nProject: ${projectId}`, }); return { notified: true, itemName: item.name }; } ``` **Variables**: | Key | Required | Description | | -------------- | -------- | -------------------------- | | `slackWebhook` | Yes | Slack incoming webhook URL | **Allowed domains**: `hooks.slack.com` ### Enforce a workflow pre-condition Block a transition from "To Do" to "In Progress" unless the work item has an assignee and an estimate. ```typescript export async function main(input: WorkflowTransitionEventInput, variables: Record<string, string>) { const projectId = input.event.project_id; const workItemId = input.event.entity_id; const item = await Plane.workItems.retrieve(workspaceSlug, projectId, workItemId); const errors: string[] = []; if (!item.assignees || item.assignees.length === 0) { errors.push("Work item must have at least one assignee"); } if (!item.estimate_point) { errors.push("Work item must have an estimate"); } if (errors.length > 0) { throw new Error("Transition blocked: " + errors.join("; ")); } return { allowed: true }; } ``` Attach this script as a **pre-condition** on the "To Do → In Progress" workflow transition. If the script throws, the transition is blocked and the user sees the error message. --- --- url: 'https://docs.plane.so/communication-and-collaboration/project-updates.html' description: Share project status and track progress over time --- # Project Updates Project updates provide a way to share project status and create a timeline of project progress. Use updates to communicate where your project stands, highlight blockers, and keep stakeholders informed without requiring meetings or status check-ins. **What are project updates**\ Updates are status posts that appear in your project's side panel. Each update includes a status indicator (On Track, At Risk, or Off Track) and a message describing the current state of the project. Updates appear in chronological order, creating a history of your project's progress over time. **When to use project updates** * Regular status reporting (weekly sprints, monthly milestones) * Communicating blockers or risks to stakeholders * Keeping remote or distributed teams aligned * Creating a historical record of project decisions and progress * Providing visibility to team members who aren't in daily standups ## Turn on project updates Project updates must be enabled in project settings. ![Turn on project updates](https://media.docs.plane.so/projects/turn-on-project-updates.webp#hero) 1. Navigate to your project. 2. Click the **…** icon next to your project name. 3. Select **Settings**. 4. Go to the **Project Updates** tab. 5. Toggle the option on. ## Add a project update 1. Navigate to the **Overview** page under your project. 2. Click the **rocket icon** (🚀) in the side panel to open the updates view. 3. Click **Add an Update**. 4. Select your project status from the dropdown. 5. Write your update message in the text field. 6. Click **Add update**. ![Add project updates](https://media.docs.plane.so/projects/add-project-updates.webp#hero) Your update appears immediately in the updates timeline with a timestamp. ### Project status options Each update requires a status indicator that signals the project's current state: **🚀 On Track**\ The project is progressing as planned. Work is moving forward according to schedule, no significant blockers exist, and the team is meeting milestones as expected. Use this status for regular positive progress updates. **⚠️ At Risk**\ The project has potential issues that need attention. There may be emerging blockers, resource concerns, or dependencies that could impact timelines if not addressed. Use this status to flag concerns early and request help before issues become critical. **❗ Off Track**\ The project has significant blockers or delays. Critical issues are preventing progress, timelines are at risk, or major decisions are needed to get back on track. Use this status when immediate action or escalation is required. ## Collaborate on updates Project updates support threaded discussions and reactions, allowing team members to engage with status updates directly. **Start discussions** * Add comments in the thread below the update. * Use threads to discuss specific points, ask questions, or provide additional context. * Threaded discussions keep conversations organized and connected to the relevant update. **Use emoji reactions** * React to updates with emojis for quick feedback. * Reactions provide lightweight acknowledgment without requiring a full comment. **Mention team members** *(Coming soon)* * Tag specific team members in update comments to notify them directly. * Use mentions to request input, escalate issues, or delegate follow-up actions. --- --- url: >- https://docs.plane.so/communication-and-collaboration/comments-and-activity.html description: 'Add comments, mention team members, and track activity on work items' --- # Work Item Comments Comments are threaded, rich-text messages attached to a work item. They are the primary place for discussion — asking questions, sharing context, reviewing decisions, or signalling blockers — without editing the work item's description or fields. Every comment is associated with a specific work item and scoped to a project and workspace. Comments appear in the activity panel of a work item alongside system-generated activity events (field changes, state transitions, assignments), but comments and activity are distinct things: activity is system-written and immutable; comments are user-written and editable. ## Add a comment to a work item ![Work item comments](https://media.docs.plane.so/issues/work-item-comments.webp#hero) 1. Open a work item. 2. Navigate to the **Activity** or **Comments** section in the detail panel. 3. Click the comment input area. 4. Type your comment. Use **Shift+Enter** to add a line break. 5. Press **Enter** (or **Mod+Enter** if you have changed your shortcut) to submit, or click the **Comment** button. Your comment appears immediately in the activity feed with a timestamp and your profile picture. ### Rich text formatting The comment editor is a full rich text environment. You can format text (bold, italic, code, lists, headings), embed images, and insert links. Pressing **Shift+Enter** inserts a line break without submitting the comment. **Available formatting:** * **Bold** - Emphasize important points * *Italic* - Add subtle emphasis * `Code` - Share code snippets or technical terms * Bullet lists - Organize information * Numbered lists - Create step-by-step instructions * Block quotes - Quote previous comments or external sources * Code blocks - Share longer code snippets with syntax * Links - Reference external resources ## Reply to comments Comments support one level of threading. Any top-level comment can receive replies. Replies are displayed nested under the parent and show a count of how many replies exist and which members participated. The reply editor behaves identically to the top-level comment editor, including shortcut and mention support. Replies inherit the access level of their parent comment and cannot be changed independently. ### Create a threaded reply ![Reply to comments](https://media.docs.plane.so/issues/reply-to-comments.webp#hero) 1. Hover over a comment. 2. Click the **Reply** icon or **Reply** button that appears in the comment toolbar. 3. Type your reply in the reply input that opens below the comment. 4. Click **Add reply** to post your reply. Replies appear nested under the original comment, making it easy to follow the conversation thread. Team members get notified when you reply to their comments. ## Mention team members Tag team members in comments to notify them and draw their attention to specific work items. 1. While typing a comment, type `@` followed by the name of the member you want to mention. 2. A suggestion list appears. Use the arrow keys or mouse to select the target. 3. Press **Enter** or click to insert the mention. **What happens** * The mentioned person receives an email notification (if they have notifications enabled) * The work item appears in their Inbox ## React to a comment 1. Hover over the comment. 2. Click the **emoji** icon in the comment toolbar. 3. Select an emoji from the picker. Your reaction appears below the comment. Click an existing reaction to add your vote to it or to toggle it off. ## Copy a link to a specific comment Share a direct link to a specific comment for reference in other discussions or documents. 1. Hover over any comment. 2. Click the three dots (⋯) menu. 3. Select **Copy link**. The link copies to your clipboard. When someone clicks the link, they'll be taken directly to that work item with the comment. ## Edit a comment Update your comments to fix errors or add additional context. 1. Hover over your comment. 2. Click the **Edit** (pencil) icon. 3. Modify the comment text in the editor that opens inline. 4. Submit to save, or press **Escape** to cancel. Edited comments show an **edited** label with the edit timestamp. The previous version of the comment is preserved in the work item activity log. You can only edit your own comments. ## Delete a comment Remove comments that are no longer relevant or were posted in error. 1. Hover over your comment. 2. Click the three dots (⋯) menu. 3. Select **Delete**. 4. Confirm the deletion. You can only delete your own comments. Admins can delete other members' comments. ::: warning Deletion is permanent. The deletion event is recorded in the work item activity log. ::: ## Activity tracking The Activity log shows a chronological history of everything that happens on a work item, including comments and system updates. ### Activity types tracked **System activities:** * Work item creation * Status changes (To Do → In Progress → Done) * Assignee changes * Priority updates * Estimate changes * Due date modifications * Module or cycle assignments * Label additions or removals * Relation changes (blocking, blocked by, etc.) **User activities:** * Comments posted * Time logged ([Worklogs](/core-concepts/issues/time-tracking)) * Attachments uploaded * Description edits Every comment action — creation, edit, or deletion — is recorded as a work item activity event. This means the full comment history (including the text of previous versions on edit) is preserved in the activity log. Reaction events are also logged. Comment edits display an **edited** indicator with the `edited_at` timestamp. The original text is accessible in the activity log. ### Filter activity Show only specific types of activity to focus on what matters. 1. Click the **Filters** button in the Activity panel. 2. Select **Assignee** to see relevant activity. 3. The activity log updates immediately. ### Sort activity Change the order in which activities appear. **Sort options:** * **Newest first** (default) - Most recent activity at the top * **Oldest first** - Original activity at the top Click the sort icon next to Filters to toggle between sort orders. ## Notification preferences Members can configure whether they receive email notifications for new comments on work items they are involved in. This is set per-workspace and can be further overridden at the project level. The preferences cover two triggers: * **Comment** — a new comment is posted on a work item you are subscribed to, assigned to, or created * **Mention** — you are @mentioned in a comment ## Comment submit shortcut By default, pressing **Enter** submits a comment. Pressing **Shift+Enter** always inserts a line break regardless of this setting. If you prefer to use Enter freely for line breaks and only submit intentionally, you can switch the shortcut to **Mod+Enter** (Ctrl+Enter on Windows/Linux, ⌘+Enter on macOS) in your profile preferences. This setting is stored on your user profile and applies globally — it affects the comment create form, the comment edit form, and the reply editor, across all projects and workspaces. The setting is per-user, not per-workspace. Other members are not affected by your preference. ## Moderation and content control Workspace and project admins can hide inappropriate comments to maintain healthy discussions. See [Comments moderation](/communication-and-collaboration/comments-moderation) for details on hiding, unhiding, and moderation best practices. --- --- url: 'https://docs.plane.so/core-concepts/pages/inline-comments.html' description: >- Collaborate directly in Plane pages with inline comments. Highlight text, mention teammates, and resolve discussions across projects, wikis, and teamspaces. --- # Page Inline Comments Inline comments allow you to collaborate directly within your documentation by highlighting specific text and starting focused discussions. This feature is available across Project pages, Wiki pages, and Teamspace pages. ## Overview When you need to discuss, clarify, or provide feedback on specific content in your pages, inline comments let you anchor conversations directly to the relevant text. Team members can respond to comments, mention colleagues, and mark discussions as resolved once they're addressed. ![Inline comments](https://media.docs.plane.so/pages/inline-comment.webp#hero) ## Where you can use inline comments Inline comments work across three different page types in Plane: * **Project pages**\ Collaborate on project-specific documentation with your project team. Comments are visible to all project members. * **Wiki pages**\ Discuss workspace-wide documentation that spans multiple projects. All workspace members can view and participate in these conversations. * **Teamspace pages**\ Have focused discussions within your teamspace. Only teamspace members have access to these comments. Each location functions independently, allowing you to keep conversations contextual to their scope. ## Add an inline comment ![Add inline comment](https://media.docs.plane.so/pages/add-inline-comment.webp#hero) To comment on specific text within any page: 1. Select the text you want to comment on by clicking and dragging across it. 2. A comment icon will appear in the formatting toolbar above your selection. 3. Click the icon to open the comment panel on the right. 4. Type your comment in the text box. 5. Optionally, attach images to provide visual context. See [Attach images](#attach-images-to-comments) below. 6. Press the send button or use the keyboard shortcut to post. Your comment will be anchored to the selected text, indicated by highlighting on the page. ## Attach images to comments You can add images to any comment or reply to provide screenshots, diagrams, or visual references: * In the comment input field, click the attachment icon. * Select an image file from your device. * The image will be uploaded and attached to your comment. * You can attach multiple images to a single comment if needed. ## Mention team members To bring specific people into the conversation: 1. Type `@` in the comment box. 2. A dropdown menu will appear showing available team members. 3. Start typing a name to filter the list. 4. Click on the person you want to mention, or use arrow keys and press Enter. ## Reply to comments To continue a conversation thread: 1. Navigate to the Comments panel on the right side of the page. 2. Find the comment you want to respond to. 3. Click **Reply** below the comment. 4. Type your response in the reply field. 5. Send your reply. Replies are threaded under the original comment, keeping related discussions organized. ## Manage comment status ### Resolve comments When a discussion is complete or a work item has been addressed: 1. Locate the checkmark icon next to the comment (in the top-right area). 2. Click the checkmark icon. 3. Select **Mark as resolved**. The comment will be hidden from the default view and moved to the resolved comments list. ### Unresolve comments If a discussion needs to be reopened or the work item resurfaces: 1. Use the Filters button to show resolved comments. 2. Locate the resolved comment you want to reopen. 3. Click the checkmark icon next to the comment. 4. Select **Mark as unresolved**. The comment will return to the active comments list and become visible in the default view. ### Filter comments Use the **Filters** button in the Comments panel to control which comments you see: * **Show active**\ Displays only unresolved comments (default view). * **Show resolved**\ Displays only resolved comments. * **Show all**\ Displays all comments regardless of status. This helps you focus on conversations that still need attention or review closed discussions when needed. ## Edit and delete comments To modify or remove your own comments: 1. Click the three-dot menu (•••) next to your comment. 2. Choose either: * **Edit**\ Modify the comment text and save your changes. * **Delete**\ Permanently remove the comment. Note that only the comment author can edit or delete their own comments. ## Permissions and visibility Comment permissions align with page access: * **Project pages**\ Project admins and members can view and comment on all project pages. If you have access to view the project page, you can participate in its comment threads. * **Wiki pages**\ Workspace admins and members can view and comment on wiki pages. For private pages that have been shared with you, you can also add and view comments based on your sharing permissions. * **Teamspace pages**\ Only teamspace members can view and comment on teamspace pages. These comments remain private to the teamspace and are not visible to users outside the teamspace. ::: info Guest users can only comment on pages they create. ::: --- --- url: 'https://docs.plane.so/communication-and-collaboration/comments-moderation.html' description: >- Hide inappropriate comments and maintain healthy discussion with moderation controls. --- # Comments moderation Comments moderation allows workspace and project admins to hide inappropriate comments from view. Hidden comments are archived but not deleted, they can be unhidden at any time. ## Hide a comment You can hide comments on any work item, project page, workspace page, teamspace, or initiative. 1. Locate the comment you want to moderate. 2. Hover over the comment to reveal the comment actions menu. 3. Click the **three-dot menu** (⋯) button. 4. From the menu, click **Hide comment**. 5. A modal dialog appears asking you to select a reason. 6. Click **Hide**. The comment is now hidden from view. ### What happens when a comment is hidden **For everyone viewing the work item** * The comment disappears from the comment thread * A **hidden comment banner** appears in its place. **In the activity log** * An activity entry records who hid the comment and when * The hide reason is recorded **The comment is never deleted** * The original comment text is preserved in the database * The comment author still sees their own comment (marked as hidden) * The comment can be unhidden at any time ## Viewing a hidden comment When a comment is hidden, everyone (including the comment author) sees a banner instead of the comment text. **To temporarily view the hidden comment:** 1. Click **Show** on the hidden comment banner 2. The comment expands to show the full text 3. Click **Hide** to collapse it again ## Unhiding a comment 1. Locate the **hidden comment banner**. 2. Hover over the banner to reveal options. 3. Click the **three-dot menu** (⋯). 4. From the menu, click **Unhide comment**. 5. The comment reappears in the thread. 6. An activity entry records who unhid it and when. ## Hidden comments in replies Comments can have nested replies. If you hide a comment: * The entire comment and all its replies are hidden together * Unhiding shows the comment and all original replies Replies can also be hidden individually using the same process. ## Hidden comments in activity logs Activity logs record all moderation actions. These are visible in the work item's activity timeline and [audit logs](/workspaces-and-users/audit-logs). ## Hidden comments in different contexts ### Work items Comments on work items can be hidden using the standard process. Hidden comments are collapsed in the discussion thread. ### Project pages Pages within a project support comments and comment moderation. ### Wiki pages Workspace-level pages support comments that can be moderated. ### Teamspaces Teamspace-level discussions support comment moderation. ### Initiatives Initiative discussions support comment moderation. ### Public shared links When a work item is shared publicly, comments are visible. Moderation still applies. **Access:** * Only logged-in workspace admins can hide comments * Hidden comments do not appear on the public link * Viewers of the public link see the hidden comment banner --- --- url: 'https://docs.plane.so/communication-and-collaboration/subscribers.html' description: >- Learn how to subscribe to work items in Plane, manage subscriber lists, set up project-level auto-subscriptions, and understand how Plane subscribes you automatically. --- # Subscribers A subscription is how you tell Plane to keep you in the loop on a work item. When you're subscribed, you get notified whenever something changes — a state update, a new comment, a priority shift, an assignee change. You don't always have to subscribe manually. Plane adds you automatically in a few situations: when you're assigned to something, when someone @-mentions you, or when an admin has set you up as a project-level subscriber. Everything else is opt-in. ## Subscribe to a work item Open any work item and look for the **Subscribe** button — you'll find it in the detail panel on the right side, or in the peek view. Click it once and you're subscribed. The button switches to **Unsubscribe** to confirm. From that point on, you'll get in-app and email notifications whenever someone makes a change to that work item. ## Unsubscribe from a work item Open the work item and click **Unsubscribe**. That's it — you'll stop receiving notifications for it immediately. If you were auto-subscribed (because you were assigned, for example), unsubscribing works the same way. Being removed as an assignee doesn't automatically unsubscribe you — you have to do that yourself if you want to stop getting notifications. ## Subscribe to multiple work items at once If you need to subscribe to several work items in one go: 1. Select the work items you want from a project list view. 2. In the bulk operations toolbar that appears, click the bell icon. 3. Click **Subscribe** in the modal and you'll be subscribed to all selected items. This subscribes you, specifically. It doesn't change anyone else's subscriptions. ## Set up project-level subscribers > Role: Project Admin Project subscribers are members who are automatically subscribed to every work item in a project — both existing ones and any new ones created going forward. 1. Go to **Project Settings → Members**. 2. Find the **Project subscribers** section. 3. Add the members you want to auto-subscribe. When you add someone as a project subscriber, Plane subscribes them to all current work items in the project in the background. They'll also be subscribed automatically to any new work items created afterward. The trade-off is volume. Project subscribers get notifications for every tracked change on every work item in the project. If a project is active, that adds up quickly. Notification preferences help here — you can reduce the email noise without losing in-app visibility. ## Manage who's subscribed to a work item You can see and edit the subscriber list directly from a work item. 1. Open the work item. 2. Next to the Subscribe button, you'll see a member selector showing current subscribers. 3. Add or remove members as needed. Only workspace members can be added as subscribers. You need edit permission on the work item to make changes here. ## View all work items you're subscribed to You can see every work item you're currently subscribed to. Go to the [Your Work](/your-work) page and look for the **Subscribed** tab. It shows all work items across all projects where you're an active subscriber. ## How you get auto-subscribed | Situation | Subscribed automatically? | | ------------------------------------------- | --------------------------------------------- | | You are assigned to a work item | Yes | | You @-mention someone (they get subscribed) | Yes, the mentioned person | | You create a work item | No — but you're still notified as the creator | | You comment on a work item | Yes | | You are a project subscriber | Yes, to all work items in the project | ## See also * [Notifications](/communication-and-collaboration/notifications) * [Inbox](/communication-and-collaboration/inbox) --- --- url: 'https://docs.plane.so/communication-and-collaboration/notifications.html' description: >- Understand what triggers notifications in Plane, how in-app, email, and push notifications work, how to set your notification preferences, and how stacked emails reduce inbox noise. --- # Notifications Notifications are how Plane tells you something changed on a work item you care about. Every time a tracked change happens, Plane builds a list of people who should know — subscribers, assignees, and the creator — and sends them a notification. There are three channels: in-app inbox, email, and push (mobile). You can control which events send you emails. ## Set your notification preferences You can control which types of changes send you email notifications — you don't have to receive emails for everything. 1. Go to **Profile Settings → Notifications**. 2. Toggle on or off: * **Property changes** — assignee, label, priority, due date, and other field changes * **State changes** — when a work item moves to a different state * **Issue completed** — specifically when a work item reaches a completed state (sub-toggle under state changes) * **Comments** — new or updated comments * **Mentions** — when someone @-mentions you These preferences apply across your whole workspace — there's no per-project setting. Changes save immediately. Inbox notifications always come through regardless of these settings. These toggles only affect emails. ## Events that trigger notifications | Event | Notifies? | | ----------------------------------------------------------------- | -------------------------------------------------------------------- | | Work item created | Yes | | Any field updated (state, priority, assignee, label, dates, etc.) | Yes | | Comment added | Yes | | Comment edited | Yes | | Comment deleted | Yes | | Link added, updated, or removed | Yes | | Attachment added or removed | Yes | | Work item relation added or removed (blocked by, duplicate, etc.) | Yes | | Work item deleted | Yes | | @mention in description or comment | Yes (mention notification) | | Work item update published (progress or status post) | Yes — all work item subscribers get an email | | Due date approaching (reminder) | Yes — subscribers and assignees get an in-app and email notification | ## Notification channels | Channel | When it fires | Can be turned off? | | ------------- | --------------------------------------- | --------------------------------- | | Inbox | Every tracked event | No | | Email | Tracked events, batched every 5 minutes | Yes, via notification preferences | | Push (mobile) | Every tracked event | Yes | Emails are batched — they don't go out the instant something changes. Plane groups pending email notifications and sends them every 5 minutes. ## Batched email notifications Plane doesn't send one email per change. Multiple changes to the same work item are grouped into a single email, sent every 5 minutes. If someone updates the priority, changes the state, and adds a comment in quick succession, you get one email covering all three — not three separate ones. This means there's always a short delay before an email arrives, but it also means your email inbox doesn't fill up when a work item goes through a burst of activity. ## Who gets notified For each change, Plane notifies: * Everyone subscribed to the work item * All current assignees * The person who created the work item The person who made the change is excluded — you don't get notified about your own actions. If someone is @-mentioned in the same activity, they get a mention notification specifically, not an additional subscriber notification. ## Notification preferences These settings live in **Profile Settings → Notifications** and apply globally across all your projects. | Preference | What it controls | | ---------------- | ------------------------------------------------------------------------------------------------ | | Property changes | Emails for any field update (assignee, label, priority, dates, etc.) | | State changes | Emails when a work item moves to a different state | | Issue completed | Emails specifically when a work item reaches a completed state (sub-setting under state changes) | | Comments | Emails for new or updated comments | | Mentions | Emails when you are @-mentioned | Turning off a preference stops the email — it does not stop the in-app notification. ## The difference between inbox and email notifications In-app notifications always come through — your notification preferences don't affect them. They accumulate in the Inbox panel and you can read, snooze, or archive them from there. Email notifications are the ones you can control. Your preferences in Profile Settings let you decide which types of changes are worth an email. If you want in-app pings for everything but only emails for comments and mentions, you can set that up. ## Due date reminders Due date reminders are a special notification type configured at the project level (in Project Settings → Automations). When enabled, Plane sends a notification to both the work item's subscribers and its assignees when the due date is within the configured window — say, 3 days out. These are one-time per window. If you've set a 3-day reminder and someone already received it, they won't get another one until the window resets. Reminders only go out for work items that are still in progress — completed and cancelled items are skipped. See [Set up due date reminders](/automations/overview#set-up-due-date-reminders). ## See also * [Subscribers](/communication-and-collaboration/subscribers) * [Inbox](/communication-and-collaboration/inbox) --- --- url: 'https://docs.plane.so/communication-and-collaboration/inbox.html' description: >- Learn how to use Plane's notifications inbox — filter by type, mark as read, snooze, archive, and use stacked notifications to quickly catch up on work item activity. --- # Inbox The Inbox is a space for tracking and managing updates to work items you're connected with. Whether you're assigned to a work item, its creator, mentioned in a discussion, or subscribed to its updates, you'll find everything here. It's where all your in-app notifications live. The inbox has two tabs: **All** and **Mentions**. Each tracks its own unread count. The sidebar icon shows a red dot when either tab has unread notifications. ## Where to find Inbox Click the **Notifications** icon in the top right of the screen to open the inbox. Clicking a notification opens the work item in a panel on the right — you stay in the inbox. ![Inbox](https://media.docs.plane.so/inbox/inbox.webp#hero) Use the **All** tab for everything except @-mentions — state changes, field updates, comments, assignments. Use the **Mentions** tab to see only notifications where someone @-tagged you. ::: tip Email notifications All inbox notifications are also sent to your email by default. You can [customize your email notification preferences](/communication-and-collaboration/notifications#set-your-notification-preferences) in Profile Settings. ::: ### Manage notifications in your inbox Hover over any notification card to reveal three action buttons: * **Mark read / unread** — toggles the unread indicator * **Archive** — removes it from your default view; you can still find archived notifications by turning on Show archived in the menu * **Snooze** — hides it until a time you choose To clear everything at once, use **Mark all as read** in the inbox header. ### Filter your notifications Use the **filter icon** to narrow by type — you can combine multiple filters: * **Assigned to me** — notifications for work items where you're an assignee * **Created by me** — notifications for work items you created * **Subscribed by me** — notifications for items you're subscribed to but didn't create or get assigned to Use the **three-dot menu** to toggle display options — only one can be active at a time: * **Show unread** — only unread notifications * **Show archived** — only archived notifications * **Show snoozed** — only snoozed notifications, including ones whose snooze time has already passed Active filters appear as tags below the tab bar. Remove them individually or clear all at once. ## Notification card content Each notification card shows: * **Who did it** — the actor's avatar (or a bell icon for due date reminders) * **What they did** — a one-line summary, e.g. "Alice added assignee Bob" or "Carol set due date to Jan 15" * **Which work item** — the project identifier and sequence number, and the work item name * **When** — a relative timestamp, e.g. "3 hours ago" * **Unread dot** — a small coloured dot on the left edge when unread * **Snoozed indicator** — if snoozed, the timestamp is replaced with "Till {date}, {time}" ## Snooze options | Option | Hides until | | ------- | ------------------------- | | 1 day | Tomorrow at the same time | | 3 days | Three days from now | | 5 days | Five days from now | | 1 week | One week from now | | 2 weeks | Two weeks from now | | Custom | A date and time you pick | ## Stacked notifications Notifications are grouped by work item. Instead of one card per event, you get one card per work item covering all the changes to it. The stacked card shows: * The work item name and identifier * Avatars of everyone who made changes * An unread count badge for the group * The time of the most recent notification Hovering over a stacked card opens a preview showing all the individual changes inside it — each one with the actor, what changed, and when. Clicking a stacked card marks all grouped notifications as read and, in full-page view, opens the work item with the relevant activity items scrolled into view and highlighted. The highlight fades after 5 seconds. Actions on a stacked card — read/unread, archive, snooze — apply to all notifications in the group at once. ## See also * [Subscribers](/communication-and-collaboration/subscribers) * [Notifications](/communication-and-collaboration/notifications) --- --- url: 'https://docs.plane.so/intake/overview.html' description: >- Use Intake to collect work items from guests, forms, and email submissions, then triage and manage them before adding to your project workflow. --- # Intake Overview Intake helps you collect, review, and triage work items from external sources before adding them to your project workflow. Whether you're gathering bug reports from customers, feature requests from stakeholders, or support tickets from clients, Intake provides a dedicated space to evaluate and organize incoming requests. ## How Intake works Intake creates a buffer between external submissions and your active project work. Items submitted through any intake channel land in a *Triage* state where your team can review, add context, and decide whether to accept them into your workflow or decline them. This approach helps you: * Keep your project backlog focused and intentional * Give external users an easy way to submit requests without project access * Review and add context to submissions before they enter your workflow * Maintain control over what work enters your project ## Intake channels Plane offers three ways to collect work items through Intake: ### Intake In-app Allow guests in a project to create work items through Plane's interface. Best for stakeholders who need regular access to submit requests. [Learn about Intake In-app →](/core-concepts/intake) ### Intake Forms Share a public web form where anyone can submit work items without creating an account. Perfect for collecting bug reports, feature requests, or support tickets from a wider audience. [Learn about Intake Forms →](/intake/intake-forms) ### Intake Email Get a dedicated email address that automatically converts incoming messages into work items. Ideal for customers or clients who prefer email communication. [Learn about Intake Email →](/intake/intake-email) ## Turn on Intake Intake operates at the project level and is disabled by default. Project admins can enable Intake and choose which channels to activate: 1. Navigate to your project settings. 2. Select the **Features** tab. 3. Toggle on the **Intake** feature to enable the core functionality. 4. Enable individual channels (Forms, Email) as needed for your workflow. Once enabled, you'll see an **Intake** section under your project in the sidebar where all incoming work items appear. ## Intake responsbility Assign a team member to take ownership of incoming work items and ensure nothing falls through the cracks. When you designate an intake responsible person, they'll automatically be assigned to and notified about every new work item that comes through any intake channel (in-app, forms, or email). This helps teams: * Ensure someone is always accountable for reviewing new requests * Get timely notifications when work items arrive * Smooth the transition from intake to your project workflow * Avoid missed or overlooked requests ### Assign intake responsibility **Role:** Project Admin ![intake-responsibility](https://media.docs.plane.so/intake/intake-responsibility.webp#hero) 1. Go to your project settings. 2. Navigate to the **Features > Intake** section. 3. Scroll to **Intake responsibility**. 4. Select the team member who should receive intake assignments. The designated person will now be automatically assigned to all new work items created through in-app intake, intake forms, or intake email. They'll receive notifications for each new item, allowing them to triage, add details, or reassign as needed. ::: tip The intake responsible person can still reassign work items after initial review. This role is about ensuring accountability for the intake process, not permanent ownership of every request. ::: ## Intake state All work items in Intake use a single state called **Triage**, regardless of which channel they came through. This intake-specific state keeps incoming requests separate from your project's workflow and doesn't appear in your project's state groups. When you accept an intake work item into your project, you can choose which project state it should move to. By default, it moves to your project's default state, but you can select any state during the acceptance process. Work items that are declined or marked as duplicates remain in Intake under the Triage state for your records. --- --- url: 'https://docs.plane.so/core-concepts/intake.html' description: >- Use Intake feature to collect, triage, and manage external work item submissions from stakeholders, clients, and guests before adding them to your workflow. --- # Intake In-app Intake is a Plane-only feature that lets `Guests` create work items following which `Admins` and `Members` can move these work items inside a project. Intake can take bug reports, feature or service requests, or raise a ticket by stakeholders, customers, or clients. Work items created in Intake can then be accepted to move them to the Project’s workflow. ## Turn on Intake Intake functions at the project level and is toggled off by default. Project `Admins` can turn on the Intake feature for the project. 1. Click the three-dots icon next to your project name on the left pane and click **Settings**. 2. Select **Features** on the right pane. 3. Switch on the toggle button for the **Intake** feature to turn it on for the project. ![enable-intake-feature](https://media.docs.plane.so/intake/enable-intake-feature.webp#hero) ## Create Work item in Intake Users with a `Guest` role can create work items in Intake. To create a work item: 1. Click on **Intake** under the project on the sidebar. 2. Click the **Add Work item** button at the top right corner. ![create-work item-intake](https://media.docs.plane.so/intake/create-issue-intake.webp#hero) 3. Enter the required details and click the **Create Work item** button. ![enter-work item-details](https://media.docs.plane.so/intake/enter-issue-details.webp#hero) ### Properties A `Guest` role can assign properties when creating an Intake work item. However, these properties can be overridden by the project `Admin` or `Member` later. For a work item in the Intake, you can choose to assign the following properties: | Property | Description | | --------- | -------------------------------------------------------------------------------------------------------------- | | Priority | Set the priority of the work item to align the expectations on how quickly the work item should be acted upon. | | Assignees | Assign the team member who should triage or prioritize the work item. | | Labels | Categorize work items using the labels available in the project. | | Due date | Set when the work item needs to be prioritized or triaged by adding a due date. | All intake work items use the Triage state, which is specific to Intake and separate from your project's state groups. When you accept a work item into your project, you'll choose which project state it should move to. ## Intake work item actions When a Guest creates a work item in Intake, it is added to the `Pending` state. Admin and Member roles can accept, decline, snooze or mark the work item as a duplicate. ### Accept work item ![accept-intake-work item](https://media.docs.plane.so/intake/accept-intake-issue.webp#hero) 1. Open a pending work item in Intake. 2. Click the **Accept** button on the top right. This will open a modal where you can change the work item details before moving it to your project. 3. Click the **Add to project** button to move the work item from **Intake** to **Work items** under the project. The work item will be visible under the **State** selected when accepting the Intake work item. ### Decline work item If the work item is not relevant to your project, you can choose to decline it. Click the **Decline** button present on any pending work item to decline it. Once the work item is declined, it ends up in the `Cancelled` state under your project. ### Snooze work item A work item can be snoozed to review it at a later time. ![snooze-intake-work item](https://media.docs.plane.so/intake/snooze-intake-issue.webp#hero-bl) 1. Open a pending work item in Intake. 2. Click on the three dots icon in the top right corner. 3. Select the **Snooze** option in the menu. 4. Select a date to review it later. The work item is moved out of pending Intake work items and can be accessed in the **Filters** drop-down under `Open` work items. You can also un-snooze the work item from the three dots menu. ### Mark work item as duplicate In cases where a similar work item exists in your project, an Intake work item can be marked as duplicate. 1. Open a pending work item in Intake. 2. Click on the three dots icon in the top right corner. 3. Select the **Mark as duplicate** option in the menu. 4. Select a work item in the project that is a duplicate of the Intake work item. ![mark-duplicate-intake-work items](https://media.docs.plane.so/intake/mark-duplicate-intake-issues.webp#hero) The work item is now declined with a ‘Duplicate’ label on it. It will also appear in the `Cancelled` state under your project. ### Delete Intake work item Only `Admins` have permission to delete Intake work items before it goes through the workflow. Deleted work items will not appear under any label in the `Closed` work items of Intake. ## View Intake work items You can view **Open** and **Closed** work items in Intake by clicking on the appropriate tabs. The description editor also shows the last edited timestamp and the person who made the edit. ![view-intake-work items](https://media.docs.plane.so/intake/intake-tabs.webp#hero) `Pending` or `Snoozed` work items are considered open work items. Further action can take place on such work items. Whereas, `Accepted`, `Declined`, and `Duplicate` appear under closed work items. No further action is required on closed work items. ### Sort and filter Like work items in the project, sorting and filtering can create a focused view of work items in Intake. Filters and sorting can be applied to a list of work items simultaneously. Filters can be assigned from the **Filters** dropdown available on the left-hand side of the Intake page. Work items can be filtered by *Work item status*, *State*, *Priority*, *Assignee*, *Created by*, *Labels*, *Created date*, and *Last updated date*. Next to the Filters dropdown, you can use the sort drop-down to arrange Intake work items sequentially. Work items can be sorted by *Date created*, *Date updated*, and *ID* in ascending or descending order. ## Additional features * Intake work item description has a rich text editor that allows you to format text, attach pictures, links and files, or add tables and dividers. ![intake-description-box](https://media.docs.plane.so/intake/intake-description-box.webp#hero) * Intake has an activity and comments section to know the status and see feedback from users and customers. All the changes made to the work item can be tracked in real-time under the **Activity** section. ![intake-activity](https://media.docs.plane.so/intake/intake-activity.webp#hero) * The **Add Comment** box has a rich text editor where you can react with emojis and mention your teammates to communicate. ![RTE-reactions-and-mentions](https://media.docs.plane.so/intake/RTE-reactions-and-mentions.webp#hero) * You can review pending requests in Intake sequentially using 🔼 or 🔽 button. ![intake-navigate](https://media.docs.plane.so/intake/intake-navigate.webp#hero) --- --- url: 'https://docs.plane.so/intake/intake-forms.html' description: >- Set up public web forms to collect bug reports, feature requests, and support tickets from external users without giving them project access. --- # Intake Forms Now, you can easily gather bug reports, feature requests, or support tickets from external users, all by sharing a simple form link. ## Enable Intake Forms Head to your Project settings and toggle on the **Forms** option under the **Features** tab. This will generate a unique URL for collecting Intake work items. If the URL ever gets compromised, you can regenerate it by clicking **Renew**, ensuring only the right people can submit work items. ![enable-intake-form](https://media.docs.plane.so/intake/enable-intake-form.webp#hero-br) ## Share the link Share the link with anyone who needs to submit a work item. They’ll land on a simple form where they can fill out their name, email, and work item details. ![submit-intake-form](https://media.docs.plane.so/intake/submit-intake-form.webp#hero) ## Review work items in Intake Once users submit the form, you’ll see their work item in your project's **Intake** section. From here, you can choose to accept the work item and move it into your project workflow or reject it if it doesn’t fit your current priorities—just like any other Intake work item. ![mark-duplicate-intake-issues](https://media.docs.plane.so/intake/review-intake-form-issues.webp#hero) ::: info All work items submitted through forms appear in Intake under the **Triage** state. When you accept an item into your project, you'll choose which project state it should move to. ::: ## Custom intake forms Plane provides a default intake form structure for quick setup. However, if you need more control over what information you collect, you can build custom forms using your project's [work item types](/work-items/project-work-item-types). When you build forms with work item types, you design the form around a specific type's properties. This approach lets you: * Build forms that match the structure of your work item types * Select exactly which properties appear on the form. * Create multiple forms for different purposes, each with its own structure. * Collect the right information based on what users are submitting. ### Create a custom form ![custom-intake-form](https://media.docs.plane.so/intake/custom-intake-forms.webp#hero-br) 1. In your project settings, go to **Features > Intake > Forms**. 2. Click **+** next to **Create Forms using work item types**. 3. Enter a form title and select the work item type it should use to create the form. 4. Under **Properties**, choose which custom fields from that work item type to include. 5. Use **Preview** to see how the form appears to external users. 6. Click **Save** when you're ready to generate the form URL. Each custom form gets its own unique URL that you can share. Users filling out the form will only see the fields you've selected, keeping their experience focused and straightforward. --- --- url: 'https://docs.plane.so/intake/intake-email.html' description: >- Set up a dedicated email address for your project that automatically converts incoming messages into work items for easy review and processing. --- # Intake Email With Intake Emails, you get a dedicated email address where people can send requests that automatically appear in your project's Intake section. ## How Intake emails work When someone sends an email to your project's dedicated address, our system automatically converts it into a work item in your Intake section. The email subject becomes the work item title, while the body becomes the description. Any attachments are preserved and added to the work item for easy reference. ::: danger Self-hosted Plane instance If you're running a self-hosted instance of Plane, you'll need to set up a few extra configurations to get Intake Email working. Check out the [setup guide](https://developers.plane.so/self-hosting/govern/configure-dns-email-service) first before diving into the steps on this page. ::: ## Enable Intake Email ![enable-intake-email](https://media.docs.plane.so/intake/enable-intake-email.webp#hero) 1. Navigate to your project's **Settings**. 2. Go to the **Features** tab. 3. Toggle on the **Intake Email** option. 4. We'll generate a unique email address for your project (something like `plane-master-be7b64a655d7484....`). 5. If security is ever a concern, you can click **Renew** to get a fresh email address and invalidate the old one. ## Share the email address Share your project's intake email address with clients, stakeholders, or team members who need to submit work items. There's no login required—they simply send an email as they normally would. ## Review email submissions in Intake When someone emails your project address, their submission appears in your **Intake** section alongside items from other sources. From there, you can: * Review the content and attachments. * Accept items you want to work on (moving them into your project workflow). * Reject items that don't fit your current priorities. ::: info All work items submitted through forms appear in Intake under the **Triage** state. When you accept an item into your project, you'll choose which project state it should move to. ::: *** Intake Emails is another powerful way to streamline how work enters your project, making it easier to collect feedback and manage requests without giving outside users direct access to your project environment. --- --- url: 'https://docs.plane.so/customers.html' description: >- Track client requests, link work items to specific customers, and prioritize tasks based on customer importance. --- # Customers The Customers feature transforms how you organize and prioritize work by placing your clients at the center of your process. Instead of managing tasks in isolation, Customers creates direct connections between your work items and the people they serve, helping teams make better decisions about what to prioritize and ensuring customer requests receive proper attention. With Customers, you can create comprehensive client profiles, track specific requests, link those requests to your work items, and maintain important context about why certain work matters throughout your organization. ## Enable Customers ![Enable Customers](https://media.docs.plane.so/customers/enable-customers.webp#hero) 1. Go to [Workspace Settings](https://docs.plane.so/core-concepts/workspaces/overview#access-workspace-settings). 2. Select the **Customers** tab on the right pane. 3. Toggle the feature on at the top right. Alternatively, you can click the **Enable Customers** button. ## Configure customer properties ![Custom properties](https://media.docs.plane.so/customers/custom-properties.webp#hero) ### Default properties Plane comes with essential customer fields pre-configured. These properties appear on every customer record and help organize your customer data consistently. * **Customer name** * **Description** * **Email** * **Website** * **Employees** * **Industry** * **Stage** * **Contract status** * **Revenue** ### Custom properties You can extend customer records with properties specific to your business. Custom properties appear in customer records alongside default properties. 1. Navigate to **Workspace Settings → Customers**. 2. Find the **Custom properties** section. 3. Click **Add new property**. ## Create customer records ![Create Customers](https://media.docs.plane.so/customers/create-customer-record.webp#hero) 1. Navigate to **Customers** in the sidebar. 2. Click **Create customer record** in the top-right corner. 3. Enter the required information. Here you will see the default and custom properties (if any). 4. Click **Create customer record**. ## View and manage your customers ![Customer records](https://media.docs.plane.so/customers/customers-list.webp#hero) The Customers page displays all your customer records. Each customer appears with their logo and website for easy identification. 1. Click on a customer record to view all details. 2. Use the options menu (three dots) for actions: * **Edit** - Update customer information. * **Copy link to customer** - Share the customer record. * **Delete** - Remove the customer record. 3. To update customer information: * Click the options menu (three dots) and select **Edit**. * Update any fields as needed. * Click **Update customer** to save your changes. The customer detail view shows all properties on the right side and requests on the left, making it easy to see all customer information at a glance. ![Customer details](https://media.docs.plane.so/customers/view-customer-details.webp#hero) ## Create and manage customer requests Customer requests serve as the bridge between what your clients need and the actual work your team performs. Each request captures a specific client requirement or feedback that can then be translated into actionable work items in your projects. ### Add a request ![Add request](https://media.docs.plane.so/customers/add-request.webp#hero) 1. Open a customer record. 2. Go to the **Requests** tab. 3. Click **Add request**. 4. Name your request and add a description. 5. Add source links to document where the request originated and connect it directly to work items in your project that will fulfill this request. 6. Click **Create request**. ### Link work to requests * Add source information ![Add source](https://media.docs.plane.so/customers/add-source.webp#hero) 1. From a request, click **Add source**. 2. Enter the URL for the source. 3. Click **Submit**. * Connect existing work items ![Link work items](https://media.docs.plane.so/customers/link-work-items.webp#hero) 1. From a request, click **Link work items**. 2. Search and select relevant work items. 3. Click **Add selected work items** to confirm. 4. In the work item properties panel, a new **Customers** field displays all associated customers. This connection helps your teams instantly see which customers are impacted by or have requested specific work items, maintaining customer context throughout your workflow. 5. Admins can hover over the **Customer** name to view details. ![Customer property](https://media.docs.plane.so/customers/customer-property.webp#hero) --- --- url: 'https://docs.plane.so/core-concepts/analytics.html' description: >- Visualize work item data, track team capacity, measure progress, and create custom charts. --- # Analytics Transform your entire workspace data into actionable insights with Analytics. Get instant answers to complex questions, forecast demand, track progress across all dimensions, and make data-driven decisions with confidence. ![Analytics Overview](https://media.docs.plane.so/analytics/analytics-overview.webp#hero) The enhanced visualization experience brings your data to life with interactive charts featuring hover details and tooltips that provide instant context as you explore your metrics. ## Analytics access levels Plane Analytics operates at multiple levels to provide the right insights: * **Workspace level**\ Users in the `Admin` roles have access to Analytics at the Workspace level. You can locate it on the left sidebar. * **Project level**\ Users with `Admin`, or `Member` roles can access project-specific analytics. Navigate to your project and find Analytics in the top navigation bar. * **Cycle and Module level**\ Drill down into specific cycles or modules for focused insights. Access through the respective Cycle or Module views with Analytics in the top bar. ## Analytics types The new analytics experience provides comprehensive views across six key areas: ### Overview Get a bird's-eye view of your entire workspace with essential performance indicators that drive strategic decision-making. The workspace metrics section displays comprehensive user statistics including total users, admins, members, and guests, alongside project count and distribution across your organization. You can monitor the overall work item count across all projects and track active cycles and intake statistics to understand your team's current workload. ### Projects analysis ![Analytics Projects](https://media.docs.plane.so/analytics/projects-analytics.webp#hero) The Projects analytics tab gives you a clear snapshot of how all your projects are performing across your workspace. Right at the top, you'll see the big picture numbers - your total project count along with a health check showing how many are on-track, off-track, or at risk. This instant overview helps you quickly spot if anything needs your attention. The *Projects by status* chart breaks things down by where each project sits in its lifecycle. You can see how many projects are still in draft phase versus those that are actively in execution. It's a handy way to understand your project pipeline and see if you've got a good balance between planning and doing. Below that, you'll find a detailed table that shows you the nitty-gritty details - how many team members are involved, the number of work items, which cycles and modules are part of the project, and even how many pages and views have been created. There's also an intake column that tracks incoming requests or ideas for each project. What's really useful here is that you can search through all your projects if you're looking for something specific, and of course, export everything to CSV if you want to do some deeper analysis or create reports for stakeholders. ### Work items analysis ![Analytics Work Items](https://media.docs.plane.so/analytics/work-item-analytics.webp#hero) The Work Items tab is where you can really dig into what your team is actually working on day-to-day. The top section gives you the essential numbers at a glance -total work items with state-based breakdown, showing started, backlog, unstarted, and completed counts to give you a complete picture of your team's workload distribution. It's a great way to get a sense of your team's current workload and how much is getting done versus how much is piling up. The *Created vs Resolved* chart tells about your team's workflow patterns. The green area shows your resolution rate - how many items are actually getting closed out over time. The gap between created and resolved items gives you a visual sense of whether you're keeping up with demand or if things are starting to pile up. #### Customized insights ![Customized insights](https://media.docs.plane.so/analytics/customized-insights.webp#hero) The interactive chart builder lets you choose what you want to measure and then break it down by any dimension that matters to you - whether that's priority, assignee, state, labels, or cycles. You can quickly spot things like priority distribution imbalances, workload concentration among team members, or bottlenecks in specific workflow states. The visual breakdown makes it easy to see proportions and identify outliers at a glance. You can easily export all your analytics data to CSV format, making it simple to dive deeper into the numbers using spreadsheets or other analysis tools you prefer. ### Cycles analysis ![Analytics Cycles](https://media.docs.plane.so/analytics/cycle-analytics.webp#hero) The Cycles tab gives you a comprehensive look at how your sprints and cycles are performing across your workspace. The summary metrics at the top provide an instant snapshot of your cycle pipeline - you can see your total cycle count broken down into current, upcoming, and completed cycles, which helps you understand your team's sprint cadence and planning horizon. The *Cycle progress* scatter plot shows each cycle's completion percentage, giving you an immediate visual sense of how different sprints are progressing. You can quickly spot cycles that might be falling behind or identify patterns in how your team typically performs throughout a sprint. The color coding makes it easy to distinguish between current work, future planning, and completed cycles at a glance. What makes this view particularly valuable is the detailed hover information that appears when you examine individual cycles. You get a complete breakdown of the work within each cycle - how many items are completed, started, unstarted, in backlog, or cancelled. This level of detail helps you understand not just whether a cycle is on track, but why it might be ahead or behind schedule. The cycle table at the bottom provides all the essential management information in one place - who's leading each cycle, which project it belongs to, the planned timeline, and current completion percentage. This makes it easy to spot potential issues like cycles that are running over their planned end dates or identify which team leads might need support. This kind of cycle analysis is invaluable for sprint retrospectives and improving your team's estimation accuracy over time. You can identify patterns in cycle performance and use that data to make better decisions about sprint planning and workload distribution. ### Modules analysis ![Analytics Modules](https://media.docs.plane.so/analytics/module-analytics.webp#hero) The Modules tab gives you visibility into how your bigger pieces of work are progressing. The summary at the top shows your module pipeline - you can see how many modules are completed, actively in progress, still in planning, or paused. The module progress scatter plot is really useful for getting a visual sense of where everything stands. Each dot represents a module, and you can quickly scan across to see which ones are making good progress, which might be stalled, or which are just getting started. The color coding helps you distinguish between different module states at a glance - whether something's in backlog, planned, in progress, completed, or cancelled. When you hover over any module in the chart, you get a detailed breakdown of the work within it - how many work items are completed, started, unstarted, or cancelled. It's especially helpful for spotting modules that might look like they're progressing but actually have a lot of work still sitting unstarted. The table gives you all the management essentials - who's leading each module, which project it belongs to, planned timelines, and current completion status. This makes it easy to identify modules that might need attention, whether that's because they're running behind schedule, don't have a clear lead assigned, or are sitting at 0% completion when they should have started by now. ### Intake analysis ![Analytics Intake](https://media.docs.plane.so/analytics/Intake-analytics.webp#hero) The Intake tab gives you valuable insights into how work requests flow into your system and how your team manages that incoming demand. The summary metrics at the top provide a quick overview of your total intake volume along with the breakdown of what's been accepted, declined, or marked as duplicate. This helps you understand both the volume of requests coming in and how effectively your team is triaging and processing them. The *Intake trends* chart is particularly useful for understanding demand patterns over time. You can see when request volume spikes or dips, which helps with capacity planning and understanding seasonal patterns in your workload. The timeline view shows both accepted and declined requests, giving you insight into not just when demand is high, but also when your team's filtering process is most active. This kind of trend analysis is really valuable for predicting future demand and understanding whether your intake process is keeping up with the flow of requests. If you see periods where lots of requests come in but very few get accepted or declined, it might indicate bottlenecks in your triage process. The project breakdown table at the bottom shows how intake is distributed across different areas of your organization. This helps you identify which projects are generating the most requests, and how different areas handle their intake processing. You can spot patterns like certain projects having higher acceptance rates, or identify areas where requests might be sitting unprocessed. ## Export analytics You can export comprehensive data from every analytics view with our CSV export functionality, giving you the flexibility to perform deeper analysis using your preferred external tools. The export process is designed for simplicity with one-click data downloads that include detailed datasets containing all relevant metrics and dimensions from your selected view. Export functionality is available only to users with an Admin role. *** Analytics transforms raw data into strategic insights, helping you optimize team performance, predict bottlenecks, and drive successful project outcomes. --- --- url: 'https://docs.plane.so/dashboards.html' description: Build custom dashboards in Plane to visualize project metrics. --- # Dashboards Dashboards are customizable data visualization spaces where you build charts, metrics, and tables from your work item data. Each dashboard is a canvas of **widgets**, individual visualizations you configure independently, arranged on a responsive grid. ![Dashboards](https://media.docs.plane.so/dashboards/dashboards.webp#hero) Dashboards do not change any data. They are read-only lenses that aggregate issue data from one or more projects in your workspace and render it as charts or numbers. Every time you open a dashboard, Plane recomputes the data live from the current state of your work items. Dashboards are workspace-scoped. They are not tied to a single project - each dashboard draws data from a set of projects you choose, which means one dashboard can show work across an entire organization. ## Dashboards visibility Every dashboard has a visibility setting. ### Public dashboards Public dashboards are visible to everyone in your workspace. Any workspace member can open a public dashboard and see the data it displays. Only the creator, workspace admins, and owners can edit or delete a public dashboard. ### Private dashboards Private dashboards are visible only to you. Other workspace members can't see private dashboards in their list. A private dashboard is the right choice for metrics you're building out, drafts, or data you don't want to share workspace-wide. When you create a dashboard, the default visibility is **Public**. You can change a dashboard's visibility after creation from within the dashboard. ## Widgets A widget is a single chart or metric panel on a dashboard. You configure each widget independently with its own chart type, data axes, grouping, and filters. Widgets sit on a shared grid and can be resized and repositioned freely. Every widget answers a question of the form: *"For these work items, grouped by X, what is the count/metric of Y?"* ## Create a dashboard ![Create Dashboard](https://media.docs.plane.so/dashboards/create-new-dashboard.webp#hero) 1. Navigate to the **Dashboards** section in the left sidebar. 2. Click the **Add dashboard** button in the top-right corner. 3. Give your dashboard a descriptive name (e.g., `Project Analytics Dashboard` or `Workload by Team`) 4. Under **Projects**, select one or more projects whose issues this dashboard should draw data from. All widgets on this dashboard can only see issues from these projects. 5. Optionally set **filters** to restrict the base work item pool for all widgets. 6. If Private Dashboards is enabled on your plan, set the **Visibility** to Public or Private. 7. Click **Create dashboard** to finish. ## Switch between edit mode and view mode When you open a dashboard, you're in view mode by default. In view mode, you can see widget data but can't add, configure, move, or resize widgets. To make changes to a dashboard, switch to edit mode: 1. Click **Edit** in the header. 2. Make your changes. 3. Click **View** to return to view mode. The **Edit** button is only visible if you have edit permission on the dashboard. ## Add widgets to a dashboard Once you've created a dashboard, it's time to add widgets. Widgets are visualization components that display your project data in different formats. ![Add Widget](https://media.docs.plane.so/dashboards/add-widget.webp#hero) 1. Open a dashboard. 2. Click **Add widget** in the toolbar. 3. In the widget type selector, choose a chart type and model. 4. The widget appears on the grid at the next available position. 5. The configuration sidebar opens automatically - configure the widget's axes, metrics, and filters (see below). 6. Click **Save** or close the sidebar. ## Widget types and models Each widget type supports one or more **models** - variations that change how the data series is structured and displayed. ### Bar chart A bar chart plots one value per group as a rectangular bar. Bars can run vertically (categories on the x-axis) or horizontally (categories on the y-axis). It is the most versatile chart type for comparing values across discrete categories - states, assignees, priorities, labels, and so on. **Basic** One bar per group. You pick a single color for all bars. Best used when each group is a distinct, non-overlapping category and you want a straightforward count or metric comparison. Example: number of work items per assignee, or number of work items per priority. **Stacked** Each bar is divided into colored sub-segments, one per sub-group value. The full bar height represents the total for that group; the segments show how it breaks down. Best used when you want to see both the total and the composition. Requires a group-by dimension in addition to the x-axis property. Example: work items per assignee, broken down by priority within each assignee bar. **Grouped** Each group produces a cluster of side-by-side bars, one per sub-group value. Unlike stacked, the bars are placed next to each other rather than on top. Best used when you need to compare sub-group values against each other across groups, rather than showing a total. Requires a group-by dimension. Example: issues per state, with separate bars per label shown side by side. ### Line chart A line chart connects data points with a line across a continuous or ordered dimension. It is most useful when the x-axis is a date property (start date, due date, created at, completed at) with a date grouping applied, making trends over time legible. It can also be used with categorical dimensions when the ordering of categories matters. **Basic** A single line across all groups. You pick the line color, style (solid or dashed), whether to show data point markers, and whether to smooth the curve. Best for tracking a single metric over time. Example: number of work items completed per week over the last quarter. **Multi-line** Multiple lines on the same chart, one per sub-group value. Each line has a distinct color from the selected color scheme. Best for comparing trends across multiple dimensions simultaneously. Requires a group-by dimension. Example: work items created per month, with separate lines per project. ### Area chart An area chart is a line chart with the space beneath the line filled in. The fill communicates volume and cumulative weight more visually than a line alone. It is well-suited to showing how a quantity accumulates or changes over time. **Basic** A single filled area. You can configure the fill color, border line color and style, opacity, whether to show markers, and smoothing. Best for showing one metric over time with emphasis on magnitude. Example: total open work items per month. **Stacked** Multiple filled areas stacked on top of each other, so the total height of the chart at any point represents the sum of all series. Each sub-group gets its own color. Best for showing how multiple categories contribute to an overall total over time. Requires a group-by dimension. Example: open work items over time, stacked by state group. **Comparison** Two overlapping areas - one representing the primary metric and one a reference or comparison value - displayed with distinct colors and line styles (typically one solid and one dashed). Best for comparing actual versus expected, or current period versus prior period. Requires a group-by dimension. The comparison baseline is rendered with a dashed border by default. ### Donut chart A donut chart is a ring divided into segments proportional to each group's value. The empty center distinguishes it from a pie chart and can optionally display a total count. It is most readable when you have a small number of distinct groups (5–8 at most) with meaningfully different proportions. **Basic** Segments sized by their proportion of the total. You choose a color scheme for the segments. Optionally display the total count in the center of the ring. Best for showing distribution across a small number of categories. Example: work item distribution by priority. **Progress** A two-segment ring showing completed versus total. One segment represents completed issues, the other represents remaining. You set the color for the completed segment; the remainder is neutral. The x-axis property is fixed to **state groups** for this model - it always measures completion by grouping issues into completed versus not-completed state groups. Best for a simple at-a-glance progress indicator. Example: percentage of work items completed in a given set of projects. ### Pie chart A pie chart is a circle divided into slices proportional to each group's value. It conveys the same information as a donut chart but without the center space. It is best when you have a small number of groups and care about the relative proportion more than the absolute count. **Basic** Slices sized by proportion. You can display values on each slice as either a raw count or a percentage of the total. A thin-slice grouping option combines all slices below a configurable percentage threshold into a single "Other" segment, preventing many tiny slivers from making the chart unreadable. ### Number A number widget displays a single large metric value with no chart - just the computed count or metric rendered as text. It is the fastest way to communicate one key figure and works well as a dashboard header or summary widget alongside more detailed charts. **Basic** You configure the text alignment (left, center, or right) and text color. The widget displays the y-axis metric for the full issue set matching the dashboard and widget filters. There is no x-axis property or grouping for number widgets - they compute a single aggregate. Note: the number widget supports all y-axis metrics except estimate points. If you need an estimate point total as a single number, use a table chart instead. ### Work items statistics The work items statistics widget groups work items by a dimension you choose and shows the total for each group. Grouping by assignee gives a "work items by assignee" view, showing how work is distributed across your team. It is most useful for workload and distribution questions: how many work items each person has, how work splits across states or priorities, or how it spreads across projects. **Basic** Configure the widget with: * **Group by** - the dimension to group work items by: State, State group, Project, **Assignee**, Label, Work item type, Cycle, Module, Created by, or Priority. * **Metric** - **Work item count**, **Estimate points**, or both. The first selected metric is the primary one. * **Max rows** - between 1 and 100 (default 10). Style options: * **Show percentage** - display each group's share of the total. * **Progress bar color** - the color of the group bars. ### Smart Counter The smart counter widget groups work items by a dimension you choose and displays the count for each group. It is the fastest way to see how work is distributed across a single dimension without needing a full chart - for example, how many work items each person has, or how work splits across priorities. It supports two visualization modes: a grid of tiles for quick scanning or a table for precise counts and easy sorting. **Basic** Configure the widget with: * **Group by** - the dimension to group work items by: State, State group, Project, Assignee, Label, Work item type, Cycle, Module, Created by, or Priority. * **Metric** - Work item count or Estimate points. * **Max rows** - how many groups to display per page (1-100, default 10). Style options: * **Visualization** - choose between **Grid** (tiles showing counts) or **Table** (rows with precise numbers). In grid view, each group appears as a tile with the group value and count. In table view, groups appear as rows with sortable columns for easier analysis. Navigate between pages using the pagination control at the bottom. ### Smart Gauge The smart gauge widget measures progress for items grouped by a dimension you choose. Each gauge shows the percentage of completed items within that group, making it ideal for tracking progress across multiple deliverables at a glance. It displays a semi-circular gauge for each group with the completion percentage, so you can quickly see which groups are nearly done and which need attention. **Basic** Configure the widget with: * **Group by** - the dimension to group work items by (same options as smart counter). * **Metric** - Work item count (progress by count) or Estimate points (progress by points). * **Max rows** - how many groups to display per page (1-100, default 10). Style options: * **Gauge color** - the color of the gauge fill (defaults to blue). * **Show percentage** - toggle whether to display the completion percentage as text (on by default). Each row displays a group name and a semi-circular gauge showing the percentage of completed items in that group. Completed items are those in a completed state; all other states count as not completed. The widget updates live as work items change state. Pagination allows you to navigate through many groups. Use this widget to monitor progress on multiple fronts simultaneously - for example, gauges for each epic, module, or team showing how far along each is. ### Two dimensional table A two dimensional table renders issues grouped by the x-axis property as rows, with a count column. It presents the same data as a bar chart but in a structured grid format rather than a visual chart. It is useful when the precise numbers matter more than the visual shape of the distribution, or when you need to display many groups that would be hard to read as bars. **Basic** One row per group, with a count column. The y-axis metric is fixed to **work item count** and cannot be changed - table charts always show a raw count. The appearance settings (column color, legend, tooltip) match the bar chart config options. ### Work Items Table A work items table lists individual work items as rows with configurable columns. Unlike the table chart, which aggregates issues into groups and shows a count, the work items table renders one row per work item - giving you a live filtered spreadsheet view of your issues directly on a dashboard. It is most useful when you need a quick-reference list of specific issues on a dashboard - for example, all open blockers, issues due this week, or unassigned high-priority work - without navigating to a project view. **Basic** Rows display each matching work item with its identifier and name always visible. You choose which additional columns appear, how many rows to show per page, and navigate across pages directly on the widget. The widget does not have an x-axis property, y-axis metric, or group-by dimension - it is a flat list, not a chart. Dashboard-level and widget-level filters control which work items appear. **Columns** The identifier, name, and project are always present. All other columns are optional and can be enabled or disabled in the widget configuration. | Column | What it shows | | ----------------- | ------------------------------------------- | | State | State name, color, and group | | Priority | Work item priority | | Assignees | Assigned members with avatars | | Due date | Target date | | Start date | Start date | | Labels | All labels on the work item | | Cycle | Current cycle | | Modules | All modules the work item belongs to | | Work item type | The type, if work item types are configured | | Estimate points | Estimate value | | Created by | Member who created the work item | | Sub-work items | Count of child work items | | Attachments | Attachment count | | Links | Link count | | Customer requests | Number of customer requests linked | | Customers | Number of customers linked | | Releases | Releases the work item is part of | **Rows per page** Set between 1 and 100 rows per page (default 10). Use a lower number for a compact at-a-glance list and a higher number when you need to scan many items at once. ### Assigned to you The "Assigned to you" widget lists the work items assigned to whoever is viewing the dashboard. It is the same table as the work items table, but scoped automatically to the current viewer, so it always shows "my work." This makes it ideal for shared team dashboards: a single widget gives every team member their own personal task list, without each person needing their own dashboard or filter. **Basic** Rows display each work item assigned to you, with the identifier and title always visible. It is configured exactly like the work items table: * **Columns to display** - choose which additional columns appear. The available columns are State, Priority, Assignees, Due date, Start date, Labels, Cycle, Modules, Type, Estimate, Created by, Releases, Sub work items, Attachments, Links, Customer requests, and Customer. New widgets start with State, Priority, and Due date. * **Max rows** - the number of rows per page, between 1 and 100 (default 10). Use the pagination control to move through pages. Dashboard-level and widget-level filters still apply, narrowing your assigned items further. Because the widget resolves to the current viewer, it shows results only for a signed-in user. On a published (public) dashboard, where there is no signed-in viewer, it has nothing to resolve to and shows no items. ### Work item type progress The work items progress widget shows progress broken down by work item type. Each row is a work item of the type or types you choose (for example, an Epic or any custom type), and its progress bar reflects the completion of that item's direct sub-items. It is most useful for tracking a set of large deliverables, such as all Epics in a project, and seeing how close each is to done in one view. **Basic** Each row shows the work item's name, its completion count, a distribution across state groups, and a percentage complete. Configure the widget with: * **Work item type** - one or more work item types whose items become the rows. At least one is required. * **Metric** - what the progress measures: **Work item count** or **Estimate points**. * **Rows per page** - between 1 and 100 (default 6). Style options: * **Progress bar type** - **Linear** (a single bar) or **State group breakdown** (a bar segmented by state group). * **Progress color** - the bar color, used with the linear style. * **Show completed** - count cancelled sub-items as completed. * **Show empty items** - include rows that have no sub-items. * **Show percentage** - display the percentage alongside the bar. ### Cycle progress bar The cycle progress bar shows the progress of a single cycle at a glance. Unlike the chart widgets, it summarizes one cycle rather than plotting a data series, making it a compact status indicator for a dashboard. It is most useful for keeping a specific active cycle visible on a shared dashboard, so the team can see how far along it is without opening the cycle itself. **Basic** Pick the project, then the cycle within that project to summarize. The widget then shows * **Distribution** across state groups (backlog, unstarted, started, completed, cancelled), with a count and percentage for each * **Work completed**, as a share of the cycle's total scope * **Scope change**, reflecting work added or removed after the cycle started * **Blocked items**, the count of work items with a blocking relationship * **Time elapsed** and **days left** in the cycle * The cycle's overall **status** and **total work item count** The widget reports on one cycle. To track several cycles, add one widget per cycle. ### Intake accepted vs declined The intake accepted vs declined widget plots two time series side by side: how many intake requests were accepted and how many were declined over a period you choose. It is most useful for seeing how your triage decisions trend and whether the balance between accepting and declining is shifting. **Basic** Configure the widget with: * **Date grouping** - bucket the timeline by Day, Week, Month (default), or Year. Each bucket counts the decisions made in that period, by the date the decision was made. * **Chart style** - show the two series as a **Multi-line** chart (default) or a **Stacked bar** chart. Style options: * **Legends** and **Tooltip** - toggle each on or off. Accepted counts intake items you accepted; declined counts items you rejected or marked as a duplicate. Pending and snoozed items are not counted. The axes and group-by are fixed, the Accepted series is always green and Declined always red, and there are no widget-level filters. Point the dashboard at projects that use Intake; projects with no intake items contribute nothing. ### Average time to accept and decline This widget tracks how long intake requests take to reach a decision - the average time between when an item arrived in intake and when it was accepted or declined - so you can see whether triage is getting faster or slower. **Basic** Configure the widget with: * **Date grouping** - Day, Week, Month (default), or Year. Each bucket shows the average decision time for the items decided in that period. * **Display** - **Line** (default), a trend of average time per period; or **Number**, a single figure showing the overall average across the whole range. Style options: * **Legends** and **Tooltip** apply to the line display. * **Text alignment** and **text color** apply to the number display. The average is measured in days from an item's creation in intake to its decision, across all decided items (accepted, rejected, and duplicate). Pending and snoozed items are excluded. In the line display, a period with no decisions leaves a gap rather than dropping to zero. ### Intake breakdown The intake breakdown widget is a compact snapshot of intake activity across the dashboard's projects. Instead of a chart, it shows a fixed set of headline numbers so you can read the state of your intake at a glance. **Basic** The widget always displays the same six metrics: * **In-app volume**, **Email volume**, **Form volume** - counts of intake items by source, across all statuses. * **Total accepted** and **Total rejected** - decided counts. * **Avg. time to decide** - average number of days from an item's arrival to its decision. The only setting is **View**: **Grid** (default), showing the metrics as tiles, or **Table**, showing them as a two-column list. This is a presentation choice only; it does not change the numbers, and the widget is not narrowed by widget-level filters. ### Intake items ageing The intake items ageing widget shows how long your undecided intake requests have been waiting, grouping items that still need a decision into age bands so you can spot a backlog before it goes stale. **Basic** Configure the widget with: * **Color scheme** - Modern, Horizon (default), or Earthen. * **Center value** - show the total count of undecided items in the middle of the ring (on by default). Style options: * **Legends** and **Tooltip** - toggle each on or off. The widget renders a donut split into three fixed age bands: **0-2 days**, **3-7 days**, and **7+ days**. It covers only undecided items (pending and snoozed); accepted, rejected, and duplicate items are not shown. Each item is aged from its arrival date in intake, and the age bands cannot be changed. ## Configure a widget Open the configuration sidebar by clicking the widget or by clicking the pencil icon. ![Customize Widget](https://media.docs.plane.so/dashboards/customize-widget.webp#hero) **Basic config** * **Name** - the widget's title as displayed on the dashboard. **X-axis property**\ What to group work items by along the horizontal axis (or segments for pie/donut). *Options:* * State, State group * Priority * Assignees, Created by * Labels * Cycles, Modules * Work item types * Projects * Start date, Due date, Created date, Completed date When a date property is selected for the x-axis, you also choose a **date grouping**: Day, Week, Month, or Year. Plane truncates dates to the chosen granularity and groups work items accordingly. **Y-axis metric**\ What value to compute per group. | Metric | What it counts | | ---------------------- | ---------------------------------------------- | | Work item count | Total issues in each group | | Estimate points | Sum of story points in each group | | Pending work items | Issues in backlog, unstarted, or started state | | Completed work items | Issues in completed state | | In-progress work items | Issues in unstarted or started state | | Due today | Issues with a due date of today | | Due this week | Issues with a due date in the current week | | Blocked work items | Issues that have a blocked-by relationship | Estimate points require the project to have estimates configured in points mode. If a project does not have estimate points set up, that metric returns zero for work items in that project. **Group by**\ Adds a second dimension by splitting each x-axis bar or line into sub-series. Available for Stacked, Grouped, Multi-line, and Comparison models. Uses the same options as the x-axis property. **Style config**\ Appearance options vary by chart type * Bar chart: color, orientation (vertical/horizontal), legends, tooltip, color scheme * Line chart: line color, line type (solid/dashed), markers, smoothing, legends, tooltip, color scheme * Area chart: fill color, line color, line type, opacity, border, markers, smoothing, legends, tooltip, color scheme * Pie chart: group thin slices toggle, minimum threshold, value type (percentage or count), color scheme * Donut chart: center value toggle, completed color, color scheme * Number: text alignment (left/center/right), text color * Table: same options as bar chart **Filters** Widget-level filters narrow the issue data for this widget only, on top of any dashboard-level filters. ## Filter layering Dashboards have two levels of filters that apply to all widget data in a stacked order: **Dashboard-level filters** are set once on the dashboard and apply to every widget on it. They restrict the base work item pool from which all widgets compute their data. **Widget-level filters** apply on top of the dashboard-level filters and further restrict data for that individual widget only. When a widget fetches data, Plane applies filters in this order: 1. Dashboard-level filters 2. Dashboard-level PQL filters 3. Widget-level filters The result is always the intersection - widget-level filters can only narrow, never expand, the work item set defined by dashboard filters. Triage states and archived and draft work items are always excluded from widget data regardless of filters. ## Change a dashboard's visibility 1. Open the dashboard. 2. In the header, click the button that shows the current access level - it displays either **Public** or **Private**. 3. In the modal that opens, select the new access level. 4. Click **Confirm**. Only the dashboard creator, workspace admins, and owners can change visibility. ## Interact with your dashboard ![Hover over widget](https://media.docs.plane.so/dashboards/hover-on-widget.webp#hero) After setting up your widgets, use your dashboard for insights: * Hover over chart elements to see detailed tooltips. * Use the legends to identify specific categories. ## Export a dashboard A dashboard can be exported to a PDF file. Each widget is rendered into its export block type: * Chart widgets (bar, line, area, pie, donut) are captured as PNG images * Table widgets are exported as structured tables * Number widgets are exported with their value, text color, and alignment preserved 1. Open the dashboard. 2. Click the **Export** button in the toolbar or **...** menu → **Export**. 3. Choose orientation (portrait or landscape). 4. Click **Download**. Plane renders each widget into the PDF. Chart widgets become images; table and number widgets are rendered as structured content. The PDF renderer respects the desktop grid layout and places widgets in their configured positions and sizes across pages. ## Share a dashboard Sharing a dashboard grants specific workspace members access to a private dashboard without making it public to the whole workspace. You choose which members to invite and what level of access they get. A shared dashboard appears in the recipient's **Shared** tab in the dashboard list. ### Share with members 1. Open the dashboard. 2. Click **Share** in the header. 3. In the modal, open the **Share** tab. 4. Search for a workspace member and select them. They are added with **View** access by default. 5. To change their access level, click the permission dropdown next to their name and select **View** or **Edit**. 6. Click **Save**. You can add multiple members before saving. All changes are applied in one batch when you click Save. Only the dashboard owner can share a dashboard. Shared members cannot re-share it with others. ### Access levels **View** - The member can open and read the dashboard. They cannot add, edit, move, or delete widgets, and cannot change dashboard settings or filters. **Edit** - The member can do everything the owner can, except delete the dashboard, change its visibility, or manage sharing. ### Remove a member 1. Open **Share** in the header, then the **Share** tab. 2. Find the member in the list and click the permission dropdown, then **Remove**. 3. Click **Save**. Removed members immediately lose access. The dashboard disappears from their Shared tab. ### The Shared tab Dashboards appear under the **Shared** tab in the left sidebar when * You own a private dashboard that you have shared with at least one member. * Someone has shared their private dashboard with you. Both cases show in the same tab. You can tell which dashboards you own by the presence of the Share and edit controls in the header. Shared members who do not own the dashboard will not see those controls. ### Limits There is no limit on the number of members you can share a dashboard with. You can share with any active, non-guest workspace member. The dashboard owner and guest-role members cannot be added. *** ## Publish a dashboard Publishing a dashboard generates a unique public URL that anyone can open with no Plane account required. It is the right choice when you want to share dashboard data with stakeholders, clients, or teammates who are not part of your workspace. A published dashboard is always read-only for viewers. They can see widget data but cannot edit the dashboard, change filters, or modify anything. ### Publish 1. Open the dashboard. 2. Click **Share** in the header. 3. In the modal, open the **Publish** tab. 4. Click **Publish**. Plane generates a unique link. 5. Copy the link and share it. Anyone with the link can view the dashboard without signing in. Only the dashboard owner can publish or unpublish a dashboard. ### Unpublish 1. Open the dashboard. 2. Click **Share**, then the **Publish** tab. 3. Click **Unpublish**. The public URL immediately becomes inaccessible. The link is deactivated but not permanently deleted, so the same anchor can be reactivated if you publish again. ### Regenerate the link If you need to invalidate the current public URL without unpublishing the dashboard, click **Regenerate link** in the Publish tab. This creates a new URL. The old URL stops working immediately. Use this if the link was shared with the wrong people and you want to cut off their access without taking the dashboard fully offline. ### What viewers see Viewers see the dashboard name, all widgets in their configured layout, and all data subject to the dashboard-level and widget-level filters. The grid is responsive; widgets stack vertically on smaller screens. Viewers cannot see who owns the dashboard, edit any settings, or interact beyond reading the data. ### Access controls Published dashboards are link-only. There is no password protection, no expiration date, and no view limit. Anyone with the URL can view the dashboard. To restrict access, unpublish the dashboard or regenerate the link. ## Resize and reposition widgets While a dashboard is in **edit mode**: * **Resize** - drag the resize handle at the bottom-right corner of a widget to change its height or width. * **Reposition** - drag the widget by its header to move it to a different position on the grid. Positions and sizes are saved when you make a change. ## Delete a widget 1. Hover over the widget. 2. Click the **...** menu → **Delete**. 3. Confirm. The widget is permanently removed. ## Add a dashboard to favorites On the dashboard list, click the star icon on a dashboard to mark it as a favorite. Click again to remove it. You can also favorite from inside the dashboard. :::info Only the dashboard creator, workspace admins, and owners can favorite a dashboard. ::: ## Delete a dashboard 1. Go to the dashboards list. 2. Click the **...** menu on the dashboard → **Delete**. 3. Confirm. Only the dashboard owner can delete a dashboard. *** You can build up to any number of dashboards per workspace. Each dashboard draws from one or more projects you choose and holds any number of widgets. There is no enforced limit on widgets per dashboard, though very large grids become difficult to navigate in practice. You can visualize work across **7 chart types**, each with up to **6 chart models**, giving 42 chart type/model combinations. Each widget is independently configured with its own grouping dimension, metric, date grouping (where applicable), appearance settings, and filter expression. --- --- url: 'https://docs.plane.so/integrations/about.html' description: >- Connect your workspace to external tools for synchronized workflows, reduced context switching, and improved team efficiency. --- # Native Integrations Plane's integrations make it easy to connect your workspace and projects with your favorite tools to streamline your workflow and keep everything in sync. Instead of constantly switching between different platforms, you can access and manage your external tools directly inside Plane. This creates a more efficient workflow, keeping your team focused and your projects running smoothly. --- --- url: 'https://docs.plane.so/integrations/bitbucket.html' description: >- Integrate Plane with Bitbucket Cloud and Bitbucket Data Center to automate pull request tracking and work item state mapping. Connect repositories to projects for seamless development workflows. --- # Bitbucket Integration Integrating Bitbucket with Plane allows you to sync your development workflow by linking Bitbucket pull requests with Plane work items. This connection enables automated state updates and keeps your development activity visible alongside project planning. Plane supports integration with: * **Bitbucket Cloud**\ The standard cloud-hosted Bitbucket service at bitbucket.org * **Bitbucket Data Center**\ Self-hosted Bitbucket instances for organizations with specific compliance or security requirements ::: info Bitbucket integration supports **pull request automation only**. Issue sync between Bitbucket and Plane is not available. ::: This guide walks you through connecting your Bitbucket account, linking repositories to Plane, and configuring pull request automation. ## Set up Bitbucket integration To get started, you'll need to connect your Bitbucket account, link repositories, and configure Plane projects for PR automation. Follow the steps below: 1. [Connect your Bitbucket account](/integrations/bitbucket#connect-bitbucket-account) 2. [Connect a Bitbucket repository](/integrations/bitbucket#connect-bitbucket-repository) 3. [Connect Plane project](/integrations/bitbucket#connect-plane-project) ### Connect Bitbucket account Link your Bitbucket account to your Plane workspace to start syncing pull requests. :::tabs key:bitbucket-edition \== Bitbucket Cloud {#bitbucket-cloud} > \[!CAUTION] Self-hosted Plane instance (Commercial Edition) > If you're running a self-hosted instance of Plane, you'll need to configure Bitbucket OAuth app credentials before proceeding. Check out the [setup guide](https://developers.plane.so/self-hosting/govern/integrations/bitbucket?edition=bitbucket-cloud) first before diving into the steps on this page. 1. Navigate to [Workspace settings](/core-concepts/workspaces/overview#access-workspace-settings) in Plane. 2. Go to the **Integrations** tab. 3. Locate the **Bitbucket** integration section. 4. Click **Connect** to authenticate your Bitbucket account and initiate the connection. ![Connect Bitbucket](https://media.docs.plane.so/integrations/bitbucket/connect-bitbucket.webp#hero) 5. Review the requested permissions and click **Grant access** to authorize Plane. 6. Once authenticated, your Bitbucket account will appear as connected. \== Bitbucket Data Center {#bitbucket-dc} > \[!CAUTION] Plane Cloud and self-hosted instances > Before integrating with Bitbucket Data Center, you must first create a Application Link in your Bitbucket DC admin panel. This is required for both Plane Cloud and self-hosted users. > > Follow this [setup guide](https://developers.plane.so/self-hosting/govern/integrations/bitbucket?edition=bitbucket-datacenter) first before diving into the steps on this section. 1. Navigate to [Workspace settings](/core-concepts/workspaces/overview#access-workspace-settings) in Plane. 2. On the right pane, select **Integrations**. 3. Find the **Bitbucket Data Center** integration and click **Configure**. 4. In the **Connect Account** section, click **Connect**. 5. Fill in the form with your Bitbucket Data Center instance details: * **Base URL** — The URL of your Bitbucket DC instance (e.g. `https://bitbucket.yourcompany.com`) * **Client ID** — From the OAuth consumer you created in Bitbucket DC * **Client Secret** — From the OAuth consumer you created in Bitbucket DC * **Webhook Secret** — Optional but recommended for webhook signature verification 6. Click **Connect** to start the OAuth flow. 7. Authorize the Plane app on your Bitbucket DC instance. 8. After authorization, you'll be redirected back to Plane with your account shown as connected. ::: At this stage, your Bitbucket account is linked to Plane, but you still need to connect specific repositories. ### Connect Bitbucket repository Connecting a Bitbucket repository allows Plane to receive pull request events from that repository via webhooks. Plane automatically creates the required webhook on the repository when you connect it. To connect a repository: 1. In the **Repository Connections** section, click **Add**. 2. Search for and select the **Bitbucket repository** you want to link. 3. Click **Continue** to confirm the selection. Once connected, the repository will appear in the list and Plane will begin listening for pull request events from it. ### Connect Plane project After linking a Bitbucket repository, associate it with a Plane project to enable PR state automation. This connection determines which Plane project's work items are updated when pull requests change state. 1. Select the **Plane project** you want to connect. 2. In the **Pull Request Automation** section, configure how Plane should update work item states based on pull request lifecycle events. 3. Once configured, the project connection will appear in the **Plane Project Connections** section. ### Connect personal Bitbucket account This step allows comments made in Plane to appear in Bitbucket under your personal Bitbucket user account, rather than the Plane integration bot. Workspace admins and members can connect their personal Bitbucket account from the Bitbucket integration page. 1. In the **Connect personal account** section under **Integrations**, click **Connect**. 2. Review the required permissions and authorize Plane to access your Bitbucket account. 3. After granting permissions, the status will update to show your personal account is connected. 4. Once connected, your Bitbucket account will be listed in Plane. ## Configure PR state automation Pull requests in connected Bitbucket repositories are synchronized with Plane work items to keep your project tracking accurate throughout the development lifecycle. To automate pull request state changes with Plane work items: 1. Reference Plane work items in your Bitbucket PR title or description using the appropriate format. See [Reference formats](#reference-formats) below. 2. Plane automatically updates the work item state based on the Bitbucket PR state, as defined in your PR state mapping. ### Reference formats There are two ways to reference Plane work items in your Bitbucket pull requests: #### With brackets \[WEB-344] — State automation * Links the work item to the PR * Adds a comment from the Plane bot showing linked work items * Automatically updates the work item state based on PR state changes (as configured in your PR state mapping) #### Without brackets WEB-344 — Link only * Links the work item to the PR as a reference * Adds a comment from the Plane bot showing referenced work items * Does not trigger automatic state updates *Example* ``` PR Title: [WEB-344] Add user authentication feature PR Description: Implements login functionality for WEB-345 ``` In this example: * WEB-344 will be fully automated — its state changes along with the PR state * WEB-345 will be linked as a reference only — no state automation ### PR lifecycle mapping The lifecycle of a Bitbucket pull request can be mapped to workflow states in Plane. The following PR states are available for mapping: * A PR is opened * A PR is updated * The PR is merged * The PR is declined (closed without merging) :::tabs key:bitbucket-edition \== Bitbucket Cloud {#bitbucket-cloud-pr} Bitbucket Cloud fires events at each stage of the pull request lifecycle: * `pullrequest:created` — A new PR is opened * `pullrequest:updated` — The PR title, description, or reviewers change * `pullrequest:fulfilled` — The PR is successfully merged * `pullrequest:rejected` — The PR is declined/closed without merging \== Bitbucket Data Center {#bitbucket-dc-pr} Bitbucket Data Center fires the following pull request events: * `pr:opened` — A new PR is opened (including draft PRs) * `pr:modified` — The PR title, description, or reviewers change * `pr:merged` — The PR is successfully merged * `pr:declined` — The PR is declined/closed without merging ::: ### Work item backlinks in pull requests When a PR references Plane work items, Plane posts a confirmation comment on the pull request listing all linked and referenced work items. This keeps Bitbucket reviewers informed about which Plane issues the PR relates to. --- --- url: 'https://docs.plane.so/integrations/cursor.html' description: >- Connect Plane to Cursor AI to assign coding tasks directly from work items. Cursor reads your spec, writes the code, and opens a pull request in your linked GitHub repository. --- # Cursor integration The Cursor integration connects Plane to [Cursor](https://cursor.com), an AI-powered code editor. Once set up, anyone on your workspace can hand a coding task to Cursor's AI agent directly from a work item - either by assigning Cursor as a work item assignee or by mentioning `@cursor` in a comment. Either way, Cursor reads the work item, writes the code, and opens a pull request in the linked GitHub repository. The work item becomes the spec; Cursor does the implementation. The integration works through Plane's work item interface - no IDE required on the person's end to trigger the task. The PR appears in GitHub once Cursor completes the work. Two things need to be true before anyone can use Cursor from a work item: 1. A workspace admin has installed and configured the integration, including mapping at least one Plane project to a GitHub repository. 2. Depending on how the admin has configured authentication, either the workspace has a shared Cursor API key or the individual member has connected their own Cursor account. ## Set up the integration This section is for workspace admins. You'll install the integration, provide a Cursor API key, and map your Plane projects to GitHub repositories. ### Install the Cursor integration 1. Go to **Workspace settings → Integrations**. 2. Find **Cursor** and click **Connect**. 3. Follow the installation prompts. Once installed, the configuration panel appears on the same page. ## Configure the API key After installation, you need to provide a Cursor API key so the integration can communicate with Cursor on your workspace's behalf. By default, the integration runs in shared mode - one key for the whole workspace. 1. Go to **Workspace settings → Integrations → Cursor**. 2. Under **Configuration**, find the **API Key** field. 3. Paste your Cursor API key and click **Save API key**. Your key is encrypted at rest and masked after saving. To replace it, paste a new key into the same field. You can get your Cursor API key from [cursor.com/settings](https://cursor.com/settings). ### Set up project mappings Project mappings tell Cursor which GitHub repository to push code to when someone uses `@cursor` on a work item in a given Plane project. You need at least one mapping before anyone can use the integration. 1. Go to **Workspace settings → Integrations → Cursor**. 2. Scroll to **Project Mappings**. 3. Click the **+** button to add a mapping. 4. Select a **Plane project** from the dropdown. 5. Select the **GitHub repository** to link it to. If your repositories don't appear in the list, type `owner/repo` manually. 6. Optionally enter a **Branch** to specify which branch Cursor should target. Defaults to your repository's default branch. 7. Click **Save**. A project can be mapped to more than one repository. If a project has multiple mappings, users need to specify which repository they want Cursor to work in when they use `@cursor`. See [Using @cursor on work items](#use-cursor-on-work-items). ### Edit or delete a project mapping 1. Go to **Workspace settings → Integrations → Cursor**. 2. In the **Project Mappings** section, find the mapping you want to change. 3. Click the edit icon to modify it, or the delete icon to remove it. Deleting a mapping means `@cursor` will no longer work for that project until a new mapping is added. ## Choose an authentication mode The integration has two modes that control how Cursor authenticates when creating pull requests. ### Shared key mode In shared mode, all workspace members share one Cursor API key set by the admin. Pull requests are created by the Cursor bot - not on behalf of individual users. Usage is billed to the workspace's Cursor account. This is the default after installation. It's the simplest setup: the admin configures the key once and every member can immediately start using `@cursor`. ### Per-user mode In per-user mode, each member connects their own Cursor account using their personal Cursor API key. Pull requests are opened on behalf of each individual, not the bot. Usage is tracked against each member's personal Cursor plan. This mode gives more visibility into who triggered which PR and is the right choice when your team members each have their own Cursor subscriptions. When per-user mode is on, members who haven't connected their account will see a warning in Plane and won't be able to use `@cursor` until they connect. Admins can see how many members have connected from the **Member connections** card on the integration settings page. ### Switch to per-user mode 1. Go to **Workspace settings → Integrations → Cursor**. 2. Under **Configuration**, toggle on **Require each user to connect their Cursor account**. 3. Read the confirmation dialog - it explains what changes for your workspace - and confirm. What happens when you switch: * Members must connect their own Cursor API key from the **Connections** page before they can use `@cursor`. * PRs will be opened on each user's behalf instead of by the Cursor bot. * Cursor usage is tracked against each member's individual plan. * Your existing workspace API key becomes your personal Cursor connection - you don't need to re-paste it. * The shared workspace key is retained but disabled. You can switch back at any time. ### Switch back to shared key mode 1. Go to **Workspace settings → Integrations → Cursor**. 2. Toggle off **Require each user to connect their Cursor account**. 3. Confirm in the dialog. What happens when you switch back: * All `@cursor` tasks will be created by the shared Cursor bot, regardless of who triggered them. * Usage is billed to the workspace account. * Members' personal connections are retained but ignored until per-user mode is re-enabled. ## Connect your Cursor account This section is for individual workspace members when per-user mode is enabled. If your workspace admin has enabled per-user auth, you need to connect your own Cursor account before you can use `@cursor`. You'll see a "Required by admin" badge on the Cursor connection card if this applies to you. 1. Go to your workspace's **Connections** page. 2. Find the **Cursor** card. 3. Click **Connect Cursor**. 4. In the **Cursor API key** field, paste your personal Cursor API key. * Get your key from [cursor.com/settings](https://cursor.com/settings). * The key format looks like `cursor_sk_••••••••••••••••`. 5. Click **Connect**. Plane verifies the key and saves it encrypted. Once connected, the card shows your connected email address and the last four characters of your key. You won't be able to see the full key after saving - generate a new one if you think it's been exposed. ### Disconnect your Cursor account 1. Go to the **Connections** page. 2. Find the **Cursor** card. 3. Click **Disconnect**. Disconnecting removes your key from Plane. You can reconnect at any time. ## Use Cursor on work items Once the integration is set up and you're authenticated, there are two ways to hand a task to Cursor from a work item in a mapped project. ### Assign Cursor as an assignee When you assign Cursor to a work item, Cursor picks up the task automatically - no comment needed. Cursor reads the work item's title and description as its spec, writes the code, and opens a pull request in the linked repository. 1. Open a work item in a project that has a repository mapping. 2. In the **Assignees** field, search for and select **Cursor**. 3. That's it. Cursor begins working on the task using the work item title and description. Cursor appears in the assignee picker like any other team member once the integration is installed. The PR is created on your behalf in per-user mode, or by the Cursor bot in shared mode. If your project is mapped to more than one GitHub repository, Cursor needs to know which one to use. Add a comment with `[repo=owner/name]` after assigning: ``` [repo=acme/backend] ``` ### Mention @cursor in a comment You can also trigger Cursor by posting a comment that includes `@cursor`. This is useful when you want to give Cursor a specific instruction beyond what's in the work item, or when you want to send a follow-up prompt to an already-active Cursor session. 1. Open a work item in a project that has a repository mapping. 2. Add a comment describing the coding task you want Cursor to complete. 3. Include `@cursor` in the comment. 4. Post the comment. Cursor uses the comment - along with the work item's title and description - as its instructions. You can continue the conversation by posting additional comments with `@cursor` to give Cursor follow-up instructions. ### Specify a repository when a project has multiple mappings If your project is mapped to more than one GitHub repository, you need to tell Cursor which one to use. Add `[repo=owner/name]` anywhere in your comment: ``` @cursor Fix the null pointer exception in the auth module [repo=acme/backend] ``` If you don't specify a repository and the project has multiple mappings, Cursor may not know where to push the code. ### Write effective instructions Whether you're using the assignee or a comment, Cursor uses the work item's title and description as context. The clearer and more specific your work item (and comment), the better the result. Include: * What needs to change and where * Any constraints or requirements (don't break this test, match this pattern, etc.) * The acceptance criteria if it's not already in the work item description --- --- url: 'https://docs.plane.so/integrations/draw-io.html' description: >- Connect Draw.io to your Plane workspace to create and edit diagrams and whiteboards directly inside Plane Pages. --- # Draw.io integration Connect Draw.io to create and edit powerful diagrams and whiteboards directly inside Plane Pages and Wiki. ## Before you start You need workspace admin permissions to connect integrations. ## Install Draw.io app 1. Go to **Workspace settings → Integrations**. 2. Find the **Draw.io** card. 3. Click **Configure**. 4. Review the permissions Draw.io is requesting: * Read-only access to your workspace * Write access to your workspace * Read-only access to your user profile * Write access to your user profile 5. Click **Accept**. Draw.io is now connected to your workspace. ## What you can do next Once connected, you can add Draw.io diagrams and whiteboards to any page in your workspace. See [Add Draw.io diagrams to Pages](/core-concepts/pages/editor-blocks#drawio-diagrams) to get started. --- --- url: 'https://docs.plane.so/integrations/github.html' description: >- Integrate Plane with GitHub Cloud and GitHub Enterprise Server to synchronize issues and pull requests. Connect repositories to projects for bidirectional updates and seamless workflows. --- # GitHub integration GitHub integration with Plane allows seamless synchronization between your GitHub repositories and Plane projects. By linking the two, your issues and pull requests stay updated across both platforms. Issues, comments, labels, and assignees reflect changes from either system. Pull request events automatically move work items through your Plane workflow. Plane supports integration with: * **GitHub Cloud** (github.com)\ The standard GitHub service, available at github.com. Covers all plans * **GitHub Enterprise Cloud** (ghe.com)\ GitHub's managed enterprise service where your organization gets a dedicated subdomain * **GitHub Enterprise Server** (self-hosted)\ A self-hosted GitHub instance deployed on your own infrastructure :::tip GitHub Cloud has its own integration page in Plane's settings. GitHub Enterprise Cloud (GHE.com) and GitHub Enterprise Server share the same page - a toggle at the top of the configuration form switches between the two. ::: ## What the integration does **Issue syncing**\ A GitHub issue with the `plane` label syncs to a linked Plane project as a work item. A Plane work item with the `github` label syncs to the linked GitHub repository as an issue. Changes to title, description, state, assignees, and labels in one system update the other. A comment with a cross-link is automatically added to each issue. **Comment syncing**\ Comments on a GitHub issue sync to the corresponding Plane work item, and vice versa when bidirectional sync is enabled. **PR state automation**\ When a pull request is opened, sent for review, merged, or closed, Plane moves the linked work item to the state you've mapped to that event. **User attribution**\ When a team member connects their personal GitHub account and is added to the user map, updates they make in one system appear attributed to them in the other - not posted by the integration bot. ## Prerequisites * Your Plane account must have **Admin** or **Owner** role in the workspace. * One GitHub organization can be connected to **one** Plane workspace. If an organization is already connected to another workspace anywhere in Plane, the connection attempt fails with an error. * The `plane` label on a GitHub issue and the `github` label on a Plane work item are what trigger syncing. Create these labels on both platforms. ## Set up GitHub integration To get started, you'll need to connect your GitHub account, organization, and repositories with Plane. Follow the steps below to complete the setup: 1. [Connect your GitHub organization](/integrations/github#connect-github-organization) 2. [Connect your personal GitHub account](/integrations/github#connect-personal-github-account) 3. [Configure PR state automation](/integrations/github#configure-pr-state-automation) ### Connect GitHub organization Link your GitHub organization to your Plane workspace to start syncing repositories. :::tabs key:github-edition \== GitHub Cloud {#github-cloud} > \[!CAUTION] Plane self-hosted instances > If you're running a self-hosted instance of Plane, you'll need to first create and configure a GitHub App to get GitHub integration working. Follow this [setup guide](https://developers.plane.so/self-hosting/govern/integrations/github?edition=github-cloud#create-github-app) first before diving into the steps on this page. ![Connect GitHub Cloud](https://media.docs.plane.so/integrations/github/github-cloud.webp#hero) 1. Go to **Workspace settings → Integrations → GitHub** in your Plane workspace. 2. Click **Connect**. 3. You are redirected to github.com. Select the organization or personal account where you want to install the Plane app. 4. Select whether you want to sync all repositories or pick specific ones. 5. Click **Install** to finalize the connection. 6. After authorization, you'll be redirected back to Plane, where your GitHub organization will appear as connected. The integration page shows the connected organization name and avatar. Plane has stored the GitHub App installation ID and fetched your organization's details. \== GitHub Enterprise Cloud {#ghe-cloud} GitHub Enterprise Cloud (GHE.com) organizations have a dedicated subdomain (`<your-org>.ghe.com`). This is a distinct setup from GitHub Cloud - you create your own GitHub App on your GHE.com organization and provide Plane with its credentials. > \[!CAUTION] Plane Cloud and self-hosted instances > Before you can integrate with GitHub Enterprise Cloud, you must first create and configure a GitHub App. This is required for both Plane Cloud and self-hosted users. > > Follow this [setup guide](https://developers.plane.so/self-hosting/govern/integrations/github?edition=github-enterprise#create-github-app) first before diving into the steps on this section. ![Connect GitHub Enerprise Cloud](https://media.docs.plane.so/integrations/github/github-enterprise-server.webp#hero) 1. Go to **Workspace settings → Integrations → GitHub Enterprise** in your Plane workspace. 2. Click **Connect**. 3. At the top of the configuration form, enable the **GitHub Enterprise Cloud (ghe.com)** toggle. 4. Fill in the form. **App ID**\ The numeric identifier for your GitHub App. Find it on your GHE.com GitHub App settings page under **App ID**. **App slug**\ The URL-safe name assigned to your app, visible in the app's GitHub URL. Find it in the URL when viewing your app settings - the segment after `/apps/`\ Example: `my-plane-app` **Enterprise slug**\ The subdomain prefix of your GHE.com organization. This is the part before `.ghe.com` in your organization's URL.\ Example: `acme` from `acme.ghe.com` **Organisation ID**\ The numeric ID of your GHE.com organization. Retrieve it from the [GitHub REST API](https://docs.github.com/en/rest/orgs/orgs?apiVersion=2026-03-10#get-an-organization): send `GET https://api.github.com/orgs/<org-name>` and use the `id` field from the response. **Client ID**\ The OAuth client identifier for your GitHub App. Find it on your GHE.com GitHub App settings page under **Client ID**. **Client secret**\ The OAuth client secret generated from your GHE.com GitHub App settings. It is shown only once when generated - use the value you copied at that time. **Webhook secret**\ The secret string you set when creating the GitHub App on GHE.com. Must match exactly what is configured on the app - Plane uses it to verify incoming webhook signatures. **Private key**\ The base64-encoded contents of the `.pem` private key file you downloaded from your GHE.com GitHub App settings. To encode it, run `base64 -i your-key.pem` and paste the full output. 5. Click **Connect app**. You are redirected to your GHE.com instance. 6. Select the organization to install on and authorize. You are redirected back to Plane. Plane stores these credentials tied to your workspace and uses them to authenticate API calls and verify webhook signatures from your GHE.com organization. \== GitHub Enterprise Server {#github-enterprise-server} > \[!CAUTION] Plane Cloud and self-hosted instances > Before you can integrate with GitHub Enterprise Server, you must first create and configure a GitHub App in your GitHub Enterprise Server instance. This is required for both Plane Cloud and self-hosted users. > > Follow this [setup guide](https://developers.plane.so/self-hosting/govern/integrations/github?edition=github-enterprise#create-github-app) first before diving into the steps on this section. ![Connect GitHub Enerprise Server](https://media.docs.plane.so/integrations/github/github-enterprise-server.webp#hero) 1. Go to **Workspace settings → Integrations → GitHub Enterprise Server** in your Plane workspace. 2. Click **Connect**. 3. Fill the form with the details of your GitHub Enterprise instance. **App ID**\ The numeric identifier for your GitHub App. Find it on your GHES GitHub App settings page under **App ID**. **App Name**\ The display name you gave the app when creating it. Must match exactly as entered in GHES. Example: `My Plane App` **Base URL**\ The root URL of your GHES instance. No trailing slash. Use exactly what appears in your browser when accessing your instance. Example: `https://github.example.com` **Client ID**\ The OAuth client identifier for your GitHub App. Find it on your GHES GitHub App settings page under **Client ID**. **Client Secret**\ The OAuth client secret generated from your GHES GitHub App settings. It is shown only once when generated - use the value you copied at that time. **Webhook Secret**\ The secret string you set when creating the GitHub App on GHES. Must match exactly what is configured on the app - Plane uses it to verify incoming webhook signatures. **Private Key**\ The contents of the `.pem` private key file you downloaded from your GHES GitHub App settings. Paste the full PEM content including the `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----` lines. 4. Click **Connect app**. You are redirected to your GHES instance. 5. Select the organization to install on and authorize. 6. Select whether you want to sync all repositories or pick specific ones. 7. Click **Install** to finalize the connection. 8. After authorization, you'll be redirected back to Plane, where your GitHub organization will appear as connected. Plane stores these credentials tied to your workspace. They are used to authenticate API calls and verify webhook signatures from your GHES instance. ::: ### Connect personal GitHub account Connecting a personal account lets Plane attribute your actions in GitHub to your Plane identity, and vice versa. This is optional. If you do not connect, your actions in one system appear as the integration bot in the other. When this connection is enabled, comments made in Plane will appear in GitHub under your GitHub user account, else comments will be posted as `Plane GitHub App` or your custom GitHub app name. Workspace admins and members can connect their personal GitHub accounts from the GitHub configuration page. ![Connect personal account](https://media.docs.plane.so/integrations/github/connect-personal-account-admin.webp#hero) 1. In the **Connect personal account** section under **Integrations**, click **Connect**. 2. Review the required permissions GitHub requests and authorize. 3. After granting permissions, you’ll see the status updated to show that your personal account is connected. 4. Once connected, your GitHub account will be listed in Plane. ## Sync issues With the GitHub integration set up, you can sync issues between Plane and GitHub at the project level. This ensures GitHub issues and Plane work items stay synchronized within your configured repositories and projects. ### Add project work item sync Once GitHub is connected to Plane, workspace admins can link GitHub repositories with Plane projects. 1. Navigate to the **Project Issue Sync** section under **Integrations**. 2. Click the (+) button to create a new sync mapping. ![Sync project to GitHub](https://media.docs.plane.so/integrations/github/sync-project-github.webp#hero) 3. In the modal that appears, configure the following: 1. **Plane project**\ Select the Plane project you want to sync with. 2. **GitHub repository**\ Choose the GitHub repository to connect. 3. **Project issue sync**\ Map GitHub issue states to Plane states: * Issue Open → Select a Plane state (e.g., Todo) * Issue Closed → Select a Plane state (e.g., Done) 4. **Select issue sync direction**\ Choose how issues should sync: * Unidirectional → Sync issues from GitHub to Plane only. ::: warning This will overwrite Plane work item content with GitHub issue data. ::: * Bidirectional → Sync issues both ways between GitHub and Plane. ![Sync direction](https://media.docs.plane.so/integrations/github/sync-direction.webp#hero) 5. Click **Start Sync**. All configured project issue syncs will appear in a list where you can edit or remove them as needed. ### Sync issues to Plane After configuring project work item sync, you can link existing GitHub issues into your Plane project. #### GitHub → Plane 1. In your GitHub repository, add the `plane` label to any issue you want to sync. 2. The issue will automatically be created as a work item in the linked Plane project. 3. Plane posts a comment on the GitHub issue with a link to the newly created work item, confirming the connection. 4. The work item in Plane will include a link back to the original GitHub issue. ### Sync work items to GitHub If you have existing work items in Plane that you want to sync to GitHub, you can do so using labels. #### Plane → GitHub 1. In your Plane project, add the `gitHub` label to any work item you want to sync. 2. A new issue will automatically be created in the linked GitHub repository. 3. The GitHub issue will be linked back to the Plane work item. 4. Future updates will sync according to your configured sync direction (unidirectional or bidirectional). ### How issue syncing works #### State synchronization * When a GitHub issue is opened or closed, the corresponding Plane work item automatically moves to the mapped state. * With bidirectional sync enabled, state changes in Plane work items will also update the GitHub issue status (open/closed). #### Creating synced issues * Issues created in GitHub (within a synced repository) are automatically created in the linked Plane project. * With bidirectional sync enabled, work items created in Plane (with the sync configured) are also created in GitHub. #### Continuous updates * All synced properties (title, description, assignees, labels, comments, etc.) update automatically based on your sync direction settings. * See [What gets synced?](#what-gets-synced) for detailed information on property-level sync behavior ### What gets synced? ::: warning important In unidirectional sync mode (GitHub → Plane only), data from GitHub issues will overwrite corresponding data in Plane. Changes made in Plane will not sync back to GitHub unless you enable Bidirectional sync in your integration settings. ::: Here’s what syncs automatically between Plane and GitHub: | Property   | Sync direction   | Notes | | -------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Title | Both ways | Updates in either platform reflect in the other. | | Description | Both ways | Content remains consistent between Plane and GitHub. | | Assignees | Both ways | Assigned users are mapped based on the initial setup. If a user isn’t mapped, the assignee field may be left empty. | | Labels | Both ways | If a Label doesn’t exist in Plane, it will be created (and vice versa). | | States | Both ways | Updates in either platform reflect in the other. | | Comments | Both ways | Comments sync between platforms with source attribution. If the commenter isn’t mapped to a Plane user, the comment appears as posted by the GitHub Bot. See [Connect personal GitHub account](/integrations/github#connect-personal-github-account) for more info. | | Mentions | Both ways | Mentioned users sync if they are mapped; otherwise, a GitHub profile link is included. | | Issue links | GitHub → Plane | Any issue references in GitHub descriptions or comments will be displayed in Plane with a direct link to the issue including the repository name and owner. | ## Configure PR state automation Pull requests (PRs) are also synchronized with Plane to ensure work item tracking remains accurate throughout the development lifecycle. ### Add pull request mapping Once GitHub is connected to Plane, workspace admins can configure pull request state mapping for Plane projects. This ensures PR states automatically sync with work item states in the mapped project. 1. Navigate to the **Pull request state mapping** section. 2. Click the (+) button to create a new mapping. ![Repository mapping](https://media.docs.plane.so/integrations/github/pr-state-mapping.webp#hero) 3. In the modal that appears, configure the following: * **Plane project**\ Select the Plane project where PR state automation should be enabled. * **Pull request automation** Map GitHub pull request states to Plane work item states ![Sync repo and project](https://media.docs.plane.so/integrations/github/pr-automation.webp#hero) 4. Click **Save**. All configured pull request state mappings will appear in a list where you can edit or remove them as needed. ### Set up PR automation To automate pull request state changes with Plane work items: 1. Configure PR state mapping for your Plane project to enable PR state automation. See [Add pull request mapping](#add-pull-request-mapping). 2. Reference Plane work items in your GitHub PR title or description using the appropriate format. See [Reference formats](#reference-formats) below. 3. Automatic state updates will move the work item state in Plane based on the GitHub PR state defined in your mapping. #### Reference formats There are two ways to reference Plane work items in your GitHub PRs: ##### With brackets \[WEB-344] - State automation * Links the work item to the PR * Adds a comment from Plane App showing linked work items * Automatically updates the work item state based on PR state changes (as configured in your PR state mapping) ##### Without brackets WEB-344 - Link only * Links the work item to the PR as a reference * Adds a comment from Plane App showing referenced work items * Does not trigger automatic state updates *Example* ```bash PR Title: [WEB-344] Add user authentication feature PR Description: Implements login functionality for WEB-345 ``` In this example: * WEB-344 will be fully automated (state changes with PR state) * WEB-345 will be linked as a reference only (no state automation) ### PR lifecycle mapping The lifecycle of a pull request can be [mapped](#configure-pr-state-automation) to workflow states in Plane. The following PR states are available for mapping: * A draft PR is created. * A PR is opened. * A review is requested. * The PR is approved and ready to be merged. * The PR is successfully merged. * The PR is closed without merging. ### Work item backlinks in pull requests When a PR references Plane work items, Plane will post a confirmation comment on the pull request, ensuring visibility into which issues are linked. *** With GitHub integration, Plane makes managing your issues and pull requests across both platforms easy and efficient. Whether you’re tracking progress, syncing updates, or managing workflows, you’ll always have a clear view of your project’s status. --- --- url: 'https://docs.plane.so/integrations/gitlab.html' description: >- Integrate Plane with GitLab and Self-managed GitLab to automate pull requests and work item state mapping. Connect repositories to projects for bidirectional updates and seamless workflows. --- # GitLab integration Integrating GitLab with Plane allows you to sync your development workflow seamlessly by linking GitLab merge requests with Plane work items. This connection enables automated updates and enhances collaboration between developers and project managers. Plane supports integration with: * **GitLab.com**\ The standard cloud-hosted GitLab service * **GitLab Self-managed**\ Self-hosted GitLab instances for organizations with specific compliance or security requirements This guide walks you through the steps to connect your GitLab account, link GitLab projects to Plane, and configure pull request automation. ## Set up GitLab integration To get started, you'll need to connect your GitLab account, organization, and repositories with Plane. Follow the steps below to complete the setup: 1. [Connect your GitLab organization](/integrations/gitlab#connect-gitlab-organization) 2. [Connect GitLab project](/integrations/gitlab#connect-gitlab-project) 3. [Connect Plane project](/integrations/gitlab#connect-plane-project) ### Connect GitLab organization Link your GitLab organization to your Plane workspace to start syncing repositories. This step is crucial for enabling the full range of GitLab-Plane integration. :::tabs key:gitlab-edition \== GitLab.com {#gitlab-cloud} > \[!CAUTION] Self-hosted Plane instance (Commercial Edition) > If you're running a self-hosted instance of Plane, you'll need to set up a few extra configurations to get GitLab integration working. Check out the [setup guide](https://developers.plane.so/self-hosting/govern/integrations/gitlab?edition=gitlab-cloud) first before diving into the steps on this page. 1. Navigate to Workspace **Settings** in Plane. 2. Go to the **Integrations** tab. 3. Locate the **GitLab** integration section. 4. Click **Connect** to authenticate your GitLab account and initiate the connection. ![Connect GitLab](https://media.docs.plane.so/integrations/gitlab/connect-gitlab.webp#hero) 5. Review the requested permissions and click **Authorize Plane** to grant access. 6. Once authenticated, you should see your GitLab account listed as connected. \== GitLab Self-managed {#gitlab-self-managed} > \[!CAUTION] Plane Cloud and self-hosted instances > Before you can integrate with GitLab Self-managed, you must first set up the necessary configurations in your GitLab instance. This is required for both Plane Cloud and self-hosted users. > > Follow this [setup guide](https://developers.plane.so/self-hosting/govern/integrations/gitlab?edition=gitlab-self-managed) first before diving into the steps on this section. 1. Navigate to [Workspace settings](/core-concepts/workspaces/overview#access-workspace-settings) in Plane. 2. On the right pane, select **Integrations**. 3. Find the **GitLab Self-managed** integration and click **Configure**. 4. In the **Connect Organization** section, click **Connect**. ![Connect GitLab Enterprise organization](https://media.docs.plane.so/integrations/gitlab/connect-gitlab-self-managed.webp#hero) 5. Fill the form with the details of your GitLab self-managed instance and click **Connect**. ![Configure GitLab Self-managed organization](https://media.docs.plane.so/integrations/gitlab/configure-gitlab-self-managed.webp#hero) 6. On the GitLab app installation page, choose the organization you want to connect. 7. Select whether you want to sync all repositories or pick specific ones. 8. Click **Install** to finalize the connection. 9. After authorization, you'll be redirected back to Plane, where your GitLab organization will appear as connected. ::: At this stage, your GitLab account is linked to Plane, but you still need to connect specific GitLab projects to Plane projects. ### Connect GitLab project Connecting a GitLab project allows Plane to receive updates from that project via webhooks. These webhooks are essential for GitLab merge request automation. ![Connect GitLab project](https://media.docs.plane.so/integrations/gitlab/connect-gitlab-project.webp#hero) To connect a GitLab project: 1. In the **GitLab Project Connections** section, click **Add**. 2. Select the **GitLab Project** you want to link. 3. Click **Continue** to confirm the selection. Once connected, the GitLab project will be listed in the UI, confirming the integration. ### Connect Plane project After linking a GitLab project, the next step is to associate it with a Plane project. This connection ensures that Plane work items can be updated automatically based on GitLab merge request activities. ![Connect Plane project](https://media.docs.plane.so/integrations/gitlab/connect-plane-project.webp#hero) 1. Select the **Plane Project** you want to connect. 2. In the **Pull Request Automation** section, set up rules for how Plane should update work item states based on merge request lifecycle events. 3. Once configured, you will see the project connection appear in the **Plane Project Connections** section. ### Connect personal GitLab account This step allows you to make comments on issues and merge requests in GitLab through your Plane account, using your personal GitLab identity. When this connection is enabled, comments made in Plane will appear in GitLab under your GitLab user account, else comments will be posted as `Plane GitLab App` or your custom GitLab app name. Workspace admins and members can connect their personal GitLab accounts from the GitLab configuration page. ![Connect personal account](https://media.docs.plane.so/integrations/github/connect-personal-account.webp#hero) 1. In the **Connect personal account** section under **Integrations**, click **Connect**. 2. Review the required permissions GitLab requests and authorize. 3. After granting permissions, you’ll see the status updated to show that your personal account is connected. 4. Once connected, your GitLab account will be listed in Plane. ## Sync issues With the GitLab integration set up, you can sync issues between Plane and GitLab at the project level. This ensures GitLab issues and Plane work items stay synchronized within your configured GitLab Projects and Plane projects. ### Add project work item sync Once GitLab is connected to Plane, workspace admins can link GitLab Projects with Plane projects. 1. Navigate to the **Project Issue Sync** section under **Integrations**. 2. Click the (+) button to create a new sync mapping. ![Sync project to GitLab](https://media.docs.plane.so/integrations/gitlab/sync-project-gitlab.webp#hero) 3. In the modal that appears, configure the following: 1. **Plane project**\ Select the Plane project you want to sync with. 2. **GitLab Project**\ Choose the GitLab Project to connect. 3. **Project issue sync**\ Map GitLab issue states to Plane states: * Issue Open → Select a Plane state (e.g., Todo) * Issue Closed → Select a Plane state (e.g., Done) 4. **Select issue sync direction**\ Choose how issues should sync: * Unidirectional → Sync issues from GitLab to Plane only. ::: warning This will overwrite Plane work item content with GitLab issue data. ::: * Bidirectional → Sync issues both ways between GitLab and Plane. ![Sync direction](https://media.docs.plane.so/integrations/gitlab/sync-direction.webp#hero) 5. Click **Start Sync**. All configured project issue syncs will appear in a list where you can edit or remove them as needed. ### Sync issues to Plane After configuring project work item sync, you can link existing GitLab issues into your Plane project. #### GitLab → Plane 1. In your GitLab project, add the `Plane` label to any issue you want to sync. ![Add Plane label](https://media.docs.plane.so/integrations/gitlab/add-plane-label.webp#hero) 2. The issue will automatically be created as a work item in the linked Plane project. 3. Plane posts a comment on the GitLab issue with a link to the newly created work item, confirming the connection. 4. The work item in Plane will include a link back to the original GitLab issue. ![Creates issue in Plane](https://media.docs.plane.so/integrations/gitlab/creates-plane-issue.webp#hero) ### Sync work items to GitLab If you have existing work items in Plane that you want to sync to GitLab, you can do so using labels. #### Plane → GitLab 1. In your Plane project, add the `gitlab` label to any work item you want to sync. ![Add gitlab label](https://media.docs.plane.so/integrations/gitlab/add-gitlab-label.webp#hero) 2. A new issue will automatically be created in the linked GitLab project. ![Creates issue in GitLab](https://media.docs.plane.so/integrations/gitlab/create-gitlab-issue.webp#hero) 3. The GitLab issue will be linked back to the Plane work item. 4. Future updates will sync according to your configured sync direction (unidirectional or bidirectional). ### How issue syncing works #### State synchronization * When a GitLab issue is opened or closed, the corresponding Plane work item automatically moves to the mapped state. * With bidirectional sync enabled, state changes in Plane work items will also update the GitLab issue status (open/closed). #### Creating synced issues * Issues created in GitLab (within a synced project) are automatically created in the linked Plane project. * With bidirectional sync enabled, work items created in Plane (with the sync configured) are also created in GitLab. #### Continuous updates * All synced properties (title, description, labels, comments, etc.) update automatically based on your sync direction settings. * See [What gets synced?](#what-gets-synced) for detailed information on property-level sync behavior ### What gets synced? ::: warning important In unidirectional sync mode (GitLab → Plane only), data from GitLab issues will overwrite corresponding data in Plane. Changes made in Plane will not sync back to GitLab unless you enable Bidirectional sync in your integration settings. ::: Here’s what syncs automatically between Plane and GitLab: | Property   | Sync direction   | Notes | | -------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Title | Both ways | Updates in either platform reflect in the other. | | Description | Both ways | Content remains consistent between Plane and GitLab. | | Labels | Both ways | If a Label doesn’t exist in Plane, it will be created (and vice versa). | | States | Both ways | Updates in either platform reflect in the other. | | Comments | Both ways | Comments sync between platforms with source attribution. The comment appears as posted by the Admin with the username of the user who posted the comment. | | Mentions | Both ways | Mentioned users username will be displayed in Plane and in the GitLab issue. | | Issue links | GitLab → Plane | Any issue references in GitLab descriptions or comments will be displayed in Plane with a direct link to the issue including the project name and owner. | ## Configure PR state automation Pull requests (PRs) are also synchronized with Plane to ensure work item tracking remains accurate throughout the development lifecycle. To automate pull request state changes with Plane work items: 1. Reference Plane work items in your GitLab PR title or description using the appropriate format. See [Reference formats](#reference-formats) below. 2. Automatic state updates will move the work item state in Plane based on the GitLab PR state defined in your mapping. #### Reference formats There are two ways to reference Plane work items in your GitLab PRs: ##### With brackets \[WEB-344] - State automation * Links the work item to the PR * Adds a comment from Plane App showing linked work items * Automatically updates the work item state based on PR state changes (as configured in your PR state mapping) ##### Without brackets WEB-344 - Link only * Links the work item to the PR as a reference * Adds a comment from Plane App showing referenced work items * Does not trigger automatic state updates *Example* ```bash PR Title: [WEB-344] Add user authentication feature PR Description: Implements login functionality for WEB-345 ``` In this example: * WEB-344 will be fully automated (state changes with PR state) * WEB-345 will be linked as a reference only (no state automation) ### PR lifecycle mapping The lifecycle of a pull request can be mapped to workflow states in Plane. The following PR states are available for mapping: * A draft PR is created. * A PR is opened. * A review is requested. * The PR is approved and ready to be merged. * The PR is successfully merged. * The PR is closed without merging. ### Work item backlinks in pull requests When a PR references Plane work items, Plane will post a confirmation comment on the pull request, ensuring visibility into which issues are linked. --- --- url: 'https://docs.plane.so/integrations/sentry.html' description: >- Integrate Plane with Sentry to automatically create work items from Sentry issues, sync issue states, and streamline your error tracking workflow. --- # Sentry integration Integrating Sentry with Plane allows your team to automatically create work items from Sentry issues and keep your error tracking workflow streamlined. Whether you're syncing issue states, creating work items from errors, or collaborating on bug fixes, this integration brings the power of Sentry and Plane together for a more connected development workflow. This guide will walk you through how to set up and connect your Sentry account to Plane. ## Set up Sentry integration ::: danger Self-hosted Plane instance (Commercial Edition) If you're running a self-hosted instance of Plane, you'll need to set up a few extra configurations to get Sentry integration working. Check out the [setup guide](https://developers.plane.so/self-hosting/govern/integrations/sentry) first before diving into the steps on this page. ::: Follow the steps below to complete the setup: 1. [Connect your Sentry account](/integrations/sentry#connect-your-sentry-account) 2. [Set up Resolution States](/integrations/sentry#set-up-resolution-states) ### Connect your Sentry account To get started, you need to connect your Sentry account to Plane. ![Connect Sentry](https://media.docs.plane.so/sentry/sentry_install.png#hero#hero) 1. Navigate to [Workspace settings](/core-concepts/workspaces/overview#access-workspace-settings) in Plane. 2. On the right pane, select **Integrations**. 3. Find the **Sentry** integration and click **Configure**. 4. Click the **Install** button. This will redirect you to Sentry's authentication page. Sentry will ask you to review the permissions it needs to integrate with Plane. Make sure to allow them. 5. After allowing permissions, you'll be redirected back to Plane. You should now see that your Sentry account is successfully connected. That's it! Your Sentry account is now integrated with Plane. ### Set up resolution states Select resolution states for Sentry issues. Configure which states to use when a Sentry issue is resolved or unresolved and vice versa. 1. In the **Sentry** integration settings, find the **State Mapping** section. 2. Select the Plane project you want to sync Sentry issues to. 3. Configure how Sentry issue states should map to Plane project states: * **Unresolved** → Select the appropriate Plane project status (e.g., "Open" or "In Progress") * **Resolved** → Select the appropriate Plane project status (e.g., "Done" or "Closed") 4. Click **Save** to apply your state mapping configuration. ![State Mapping](https://media.docs.plane.so/sentry/sentry_project_mapping.png#hero) ![Post State Mapping](https://media.docs.plane.so/sentry/sentry_config.png#hero#hero) ::: info State mapping ensures that when Sentry issues are automatically synced to Plane, they appear with the correct state. You can always modify these mappings later if your workflow changes. ::: ## Use the Sentry integration Now that Sentry is connected to your Plane workspace, we can resolve Sentry issues from Plane and vice versa. ### Set up Sentry alerts In Sentry alerts, users can setup an action to auto create a work item in Plane when trigger and conditions are met. ![Sentry Alert Setup](https://media.docs.plane.so/sentry/create_issue_alert.png#hero) ![Sentry Plane Sync Modal](https://media.docs.plane.so/sentry/create_workitem_modal.png#hero) 1. Navigate to your Sentry project settings. 2. Go to **Alerts** and click **Create Alert Rule**. 3. Select environment and project. 4. Setup conditions to filter the alerts (e.g., error rate threshold, issue frequency, etc.). 5. Create an action to create a Plane work item. 6. Click **Settings** and open the modal to configure the properties on work item that will be created on Plane like priority, assignee, etc. 7. Save your alert rule. ::: info Once configured, Sentry will automatically create work items in your selected Plane project whenever the alert conditions are met. This ensures that critical errors are immediately tracked and assigned to your development team. ::: ### Link Sentry issues to Plane work items On a Sentry issue, you can use Makeplane in the "Issue Tracking" section to link the current issue to a Plane work item. This will start a bi-directional state sync between Sentry issues and Plane work items. 1. Navigate to any Sentry issue in your project. 2. Scroll down to the **Issue Tracking** section. 3. Click on **Makeplane** to link this issue to a Plane work item. 4. Search for and select the existing Plane work item you want to link, or create a new one. 5. Click **Save Changes** to establish the connection. ![Link Sentry Issue](https://media.docs.plane.so/sentry/issue_tracking.png#hero) ![Create / Link Work Item](https://media.docs.plane.so/sentry/create_link.png#hero) Once linked, the Sentry issue and Plane work item will sync bi-directionally: * If the issue is resolved on Sentry, it will be closed on Plane. * If the work item is marked as done on Plane, it will be resolved on Sentry. ::: info This bi-directional sync keeps your error tracking and project management in perfect alignment, ensuring that issue resolution status is consistent across both platforms. ::: ### Update work item status from Plane Once the state on a work item is moved to the resolved state specified during state mapping, the Sentry issue will get automatically resolved. 1. Navigate to the linked work item in Plane. 2. Change the work item state to the resolved state you configured during state mapping. 3. The Sentry issue will automatically be marked as resolved. If the status is changed back to the unresolved state of your Sentry mapping, it will mark the Sentry issue as "unresolved" as well. ::: info This automatic status synchronization works both ways - changes in Plane reflect in Sentry, and changes in Sentry reflect in Plane, keeping your error tracking and project management perfectly synchronized. ::: --- --- url: 'https://docs.plane.so/integrations/slack.html' description: >- Integrate Plane with Slack to create work items from messages, sync thread conversations, and take actions directly from your chat interface. --- # Slack integration Plane's Slack integration brings your project management directly into your team's communication flow. Create work items from conversations, get notified about updates, interact with Plane AI, and keep everyone aligned — all without leaving Slack. This guide will walk you through how to set up and connect your Slack account to Plane. ## Set up Slack integration ::: danger Self-hosted instances (Commercial Edition) If you're running a self-hosted instance of Plane, you'll need to set up a few extra configurations to get Slack integration working. Check out the [setup guide](https://developers.plane.so/self-hosting/govern/integrations/slack) first before diving into the steps on this page. ::: Follow the steps below to complete the setup: 1. [Connect your Slack Workspace](/integrations/slack#connect-slack-workspace) 2. [Connect your personal Slack account](/integrations/slack#connect-personal-slack-account) ### Connect Slack Workspace To get started, you need to connect your Slack workspace to Plane. ![Connect Slack](https://media.docs.plane.so/integrations/slack/configure-slack-integration.webp#hero) 1. Navigate to **Workspace settings → Integrations** in Plane. 2. Find the **Slack** integration and click **Configure**. 3. Click the **Install** button. This will redirect you to Slack’s authentication page. Slack will ask you to review the permissions it needs to integrate with Plane. Make sure to allow them. 4. After allowing permissions, you’ll be redirected back to Plane. You should now see that your Slack workspace is successfully connected. Your workspace is now integrated. Team members can start using Plane shortcuts in Slack channels. ### Connect personal Slack account For a more personalized experience, you can connect your personal Slack account. This is particularly useful for features like Thread Sync. When Thread Sync is enabled, any messages posted to a work item will be sent back to Slack. If you're connected, it will show your name as the sender. If you're not connected, the message will appear as coming from the Plane Bot or the name of your Slack bot. ![Connect personal account](https://media.docs.plane.so/integrations/slack/connect-personal-slack-account.webp#hero) #### From Workspace settings Workspace admins and members can connect their personal Slack accounts from Workspace settings. 1. In the **Connect your personal account** section under **Integrations**, click **Connect**. 2. Slack will ask for permission to integrate with Plane. Review and allow the necessary permissions. 3. After granting permissions, you’ll see the status updated to show that your personal account is connected. ## Use the Slack integration Now that you’ve connected Slack to Plane, let’s explore what you can do with this integration. We built this to reduce the constant back-and-forth between Plane and Slack—so instead of switching between tools to create work items, update statuses, or share links, you can do it all from Slack. ### Create work items from Slack Turn conversations into trackable work without switching apps. There are two easy ways to create issues from Slack, depending on your workflow: using the message shortcut or the `/plane` command. Any updates in Plane to fields like State, Assignee, or others will automatically reflect in the linked Slack thread. #### Message shortcut ![Thread sync](https://media.docs.plane.so/integrations/slack/create-plane-work-item.webp#hero) Convert any Slack message into a Plane work item: 1. Hover over any message in Slack. 2. Click the three-dot menu. 3. Select **Create a Work Item**. 4. A modal opens with options: ![Slack modal](https://media.docs.plane.so/integrations/slack/create-work-item-modal.webp#hero) * **Project** - Select which Plane project receives the work item. * **Add as** - Choose between: * **Work Item** - Standard task in your project. * **Intake** - Sends to your project's intake queue for triage. * **Work Item Type** - Select from your project's work item types. This will also show mandatory custom properties associated with the work item type. 5. Add a title and description. The original Slack message text auto-fills as the description. 6. Assign Labels, State, Priority, and Assignees. 7. Turn on Thread Sync (optional). When enabled, Thread Sync keeps your conversation and Plane work item comments in sync. Anything you say in the Slack thread appears in the Plane work item comments, and vice versa. It’s the easiest way to keep everyone aligned without repeating updates in two places. 8. Click **Create** and the work item appears in Plane, with a confirmation posted in the Slack thread. #### `/plane` command The `/plane` command lets you create a work item on the fly, without referencing a specific message. ![Slash Plane command](https://media.docs.plane.so/integrations/slack/plane-command.webp#hero) 1. Type `/plane` in any Slack channel or DM. 2. Press Enter to open the creation modal. 3. Fill in the same fields as the message shortcut. 4. Click **Create**. This is great for when an idea or task comes up mid-conversation—you can create the work item in just a couple of clicks without breaking your flow. ### Link existing work items to Slack threads If a Plane work item already exists, and you want to connect it to a Slack thread (for updates, visibility, or comments), just use the **Link Work Item** shortcut. Here’s how: 1. Hover over the relevant Slack message or thread. 2. Click the three-dot menu and select **Link Work Item**. ![Link Work Item](https://media.docs.plane.so/integrations/slack/link-work-item-to-slack.webp#hero) 3. In the modal, search for the work item by title or ID. 4. Select the right work item and hit **Link**. That’s it. Now the thread and the work item are connected. Comments in the thread can sync to Plane (and vice versa, if **Thread Sync** is enabled on that work item), and the thread will display a rich preview of the linked work item. This is perfect for situations where someone logs a work item in Plane but the conversation about it happens in Slack. Just link them up and avoid duplication. ### Add Plane to private Slack channels When you use Plane in public Slack channels, it automatically adds the Plane bot to those channels. However, for private channels, you must manually add the bot before you can create or link work items. Here's how to add Plane to your private channels: 1. Navigate to your private channel. 2. Open the channel settings. 3. Go to the **Integrations** tab. 4. Click **Add apps** in the **Apps** section. 5. Search for `Plane` in the app directory. You'll see the Plane app with the `/plane` slash command 6. Click *Add* next to the Plane app. This will add the Plane bot to your private channel, and Slack will show you a confirmation message. ::: info Only channel members with the right permissions can add apps to private channels. If you don't see the option to add apps, ask a channel admin or the channel creator to add Plane for you. ::: Once you add Plane to your private channel, you can use all the same features you'd use in public channels - creating work items, linking existing ones, and getting rich link previews. The bot just needs that initial invitation to join your private conversation. ### Connect project to Slack channel Stay on top of project updates by linking Plane projects to Slack channels. You can configure which events trigger notifications, so your team only sees updates that matter. ![Connect project to Slack channel](https://media.docs.plane.so/integrations/slack/project-notifications.webp#hero) To configure this: 1. Go to your [Workspace settings](/core-concepts/workspaces/overview#access-workspace-settings) in Plane. 2. Navigate to **Integrations → Slack** in Plane. 3. Click **Configure** on the Slack integration. 4. Under **Project Notifications**, click the **➕** button. 5. Select a Plane Project and the corresponding Slack Channel you’d like to connect. 6. Under **Notify when**, choose which events trigger Slack notifications: * **When a work item is created** - Posts a notification whenever someone creates a new work item in this project. * **When a work item state changes** - Notifies the channel when work items move between states (e.g., Todo → In Progress). * **When a comment is created on a work item** - Posts updates when someone comments on a work item. You can reply to these comments directly from Slack using the **Reply** button on the notification. * **When a work item is marked cancelled or done** - Notifies when work items reach completion states or the cancelled state. ![Project Slack updates](https://media.docs.plane.so/integrations/slack/project-slack-updates.webp#hero) 7. Click **Save**. **To edit or remove a project notification**. Find the project-channel mapping in the Project Notifications list. Click the edit icon to change notification settings or the delete icon to remove the connection entirely. ### Get DM notifications Stay informed about work items that need your attention through Slack DMs. #### Enable DM notifications 1. Go to **Settings** → **Integrations** → **Slack**. 2. Connect your personal account. 3. Enable **Get notified in Slack DMs for important updates, reminders, and alerts just for you**. ![Enable DM notifications](https://media.docs.plane.so/integrations/slack/connect-personal-slack.webp) #### What triggers DM notifications Once enabled, you receive Slack DMs when: * **Someone mentions you** in a work item comment or description. * **You're assigned** to a work item. Each notification includes: * Direct link to the work item * Context about what triggered the notification * Quick actions (**View Work Item**, **Reply**) This keeps you updated on work that requires your attention without checking Plane constantly. ### Use Plane AI agent in Slack Interact with Plane AI directly from Slack to create work items, check project status, and get updates—all through natural conversation. ::: info Disclaimer Plane uses AI models powered by Anthropic. AI-generated responses may not always be accurate. ::: #### Mention @Plane in threads Tag `@Plane` in any Slack thread to ask questions or request actions: **Create work items conversationally:** ``` @Plane create a work item 'live tail' and assign it to Mike. ``` Plane AI responds with clarifying questions if it needs more details (like which project), then creates the work item and confirms with a link. **Get project information:** ``` @Plane can you provide the identifiers of these projects? ``` **Check cycle progress:** ``` @Plane how are we doing in the current cycle for the AI project? ``` The AI understands context from your conversation, so follow-up questions work naturally without repeating details. ### Link previews When you share a work item link in Slack, the preview displays as an interactive card. Click anywhere on the preview to open a sidebar that shows the full work item details without leaving Slack. ![Work item sidebar view](https://media.docs.plane.so/integrations/slack/work-item-sidebar-view.webp#hero) You can view and navigate through all work item details right from Slack. If you need to make changes, use the quick action buttons at the bottom of the preview. #### Quick action buttons With link previews, you can interact with the work item directly from Slack. * **View in Plane** - Opens the work item in Plane * **Add me to Assignees** - Instantly adds you as an assignee to the work item * **Edit** - Opens a modal on the right pane to update work item details Make your changes and click Save Changes. The work item updates in Plane immediately, and the preview in Slack refreshes to show the new details. This means you can triage work items, update priorities, reassign tasks, and manage details during Slack conversations without opening Plane. ## Privacy and permissions When you use the Slack integration with Plane, we take your privacy seriously. The integration only accesses the minimum permissions necessary to function properly, and we handle your data in accordance with our [Privacy Policy](https://plane.so/legals/privacy-policy). The integration may collect and process: * Messages and threads you choose to sync with Plane work items * Channel information for project notifications * Basic user information for authentication and personalization All data is encrypted in transit and at rest, and you can disconnect the integration at any time from your [Workspace settings](/core-concepts/workspaces/overview#access-workspace-settings) or [Profile settings](/core-concepts/account/settings). *** --- --- url: 'https://docs.plane.so/importers/overview.html' description: Importers to migrate your project data to Plane --- # Import data Switching to Plane? No need to start from scratch. Our importers make it simple to move your project data from other tools, saving you time and effort. Instead of manually setting up your structure and history, you can directly transfer your existing issues into Plane, keeping your team's progress intact for a smooth transition. ::: info Importers are available on Plane Cloud and the Commercial Edition for self-hosted instances. ::: --- --- url: 'https://docs.plane.so/importers/asana.html' description: Migrate your Asana data to Plane. --- # Asana importer With the Asana importer, you can easily import issues, states, labels, priorities and user data from Asana to Plane and continue managing your existing projects. ::: info The Asana importer is available on Plane Cloud and on all plans of the Commercial Edition for self-hosted instances. ::: ## Import from Asana > **Role**: Workspace admins ::: tip To import issue types from Asana, make sure the [Work item types](/work-items/project-work-item-types) feature is enabled in your Plane project. ::: To import Asana issues to a Plane project, follow these steps: 1. Click the **∨** icon next to your workspace name on the sidebar and select **Workspace settings**. 2. Select **Imports** on the right pane and click the **Import** button in the Asana section. ![Import from Asana](https://media.docs.plane.so/importers/asana/import-asana.webp#hero) 3. In the **Asana to Plane Migration Assistant** screen, enter your **Personal Access Token** to allow Plane access to your Asana account. ![Connect Asana](https://media.docs.plane.so/importers/asana/asana-plane-migration-assistant.webp#hero) 4. Click the **Connect Asana** button to link the accounts. 5. Click the **Import** button under the **Imports** section. ![Import Asana](https://media.docs.plane.so/importers/asana/import-asana-data.webp#hero) 6. **Configure Plane**\ Select the Plane project where you want to import your Asana data and and click **Next**. ![Configure Plane](https://media.docs.plane.so/importers/asana/configure-plane.webp#hero) 7. **Configure Asana**\ Choose the workspace and project in Asana from where you want to import data. ![Configure Asana](https://media.docs.plane.so/importers/asana/configure-asana.webp#hero) 8. **Map states**\ Map **Asana sections** to their equivalent **Plane states**. ![Map states](https://media.docs.plane.so/importers/asana/map-states.webp#hero) 9. **Map priorities**\ Map the **Asana priorities** to the corresponding **Plane priorities**. If there's no match, select **None** in the **Plane priorities** list. ![Map priorities](https://media.docs.plane.so/importers/asana/map-priorities.webp#hero) 10. **Summary**\ Review the mappings and make any changes if needed. Click **Back** to adjust, or click **Confirm** to start the migration. ![Review mappings](https://media.docs.plane.so/importers/asana/import-summary.webp#hero) 11. The data migration begins and takes a few minutes to complete depending on the number of issues in your Asana workspace. ![Migration complete](https://media.docs.plane.so/importers/asana/import-complete.webp#hero) 12. Once it's done, go to **Work items** in your Plane project to confirm that the data import is successful. ## Imported entities Here’s a quick look at what gets imported during the migration from Asana to Plane: | Asana | Plane | Notes | | ------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Labels | Labels | | | Status | States | | | Issue priorities | Priorities | | | Users | Users | | | Issues | Work items | | | Relations | Parent | Includes only parent-child relationships | | Issue comments | Work item comments | Includes username and timestamp. If you skip user import during migration, comments will show the name of the user who performed the migration. | | Issue attachments | Work item attachments | | | Reporter | Created by | | | Created | Created at | | | Assignee | Assignees | If you skip user import during migration, this will be blank. | | Issue types | Labels | Prefix in Work item title | | | Images in the Issue description | Images in the Work item description | | | Summary | Work item title | | | Start date | Start date | | | Due date | Due date | | | Linked Issues | Links | Includes backlinks to the original Asana issue. | ## Sync Asana to Plane After the import, if there are any new or updated issues in Asana, you can easily sync these changes to Plane: 1. Go to **Workspace settings**. 2. Select **Imports** on the right pane. 3. Click the **Re run** button next to the project you want to sync. ![Sync Asana](https://media.docs.plane.so/importers/asana/rerun-import.webp#hero) --- --- url: 'https://docs.plane.so/importers/confluence.html' description: Import data from Confluence to Plane. --- # Confluence importer The Confluence to Plane importer lets you transfer your Confluence pages and content to Plane's Wiki. This is useful when you want to bring your documentation, notes, and structured content from Confluence into your Plane workspace as Wiki pages. The importer takes exported Confluence content and converts it into Plane Wiki pages. It preserves your page structure, including subpages, and maintains the hierarchical organization of your Confluence space within Plane's Wiki system. Plane supports both XML and HTML Confluence exports. XML is the preferred format and is selected by default in the Confluence importer. HTML remains available as a legacy format for existing HTML exports. ## Export your Confluence content First, you need to export your content from Confluence: 1. Navigate to your Confluence space. 2. Go to **Space settings** (you can find this in the space sidebar or settings menu). 3. In the left sidebar, expand **General** if it's not already expanded. 4. Click on **Export space**. 5. In the export options: * **File format**: Select **XML**. XML is the preferred format for Confluence imports. * **HTML (legacy)**: HTML exports are also supported for existing exports. If you need to export HTML, choose **Export each item, with attachments. Comments are excluded.** 6. Click **Export**. 7. The system will process your export and show a progress bar with time elapsed, time remaining, and completion percentage. 8. Once complete, you'll see "Export complete. Download here.". Click the download link. 9. Confluence will generate a ZIP file containing your exported content. ## Import Confluence content ![Import from Confluence](https://media.docs.plane.so/importers/confluence/import-confluence.webp#hero) Once you have your exported ZIP file: 1. Go to the **Imports** section in your Plane workspace. 2. Click **Import** next to the Confluence option. 3. On the Confluence import page, use the format dropdown to select **XML**. XML is selected by default; choose **HTML** only when importing a legacy HTML export. 4. Click **Upload Confluence Exported ZIP**. 5. Select and upload the ZIP file you exported from Confluence. ![Upload confluence file](https://media.docs.plane.so/importers/confluence/upload-confluence-file.webp#hero) 6. Wait for the upload to complete. You'll see a "Upload complete!" message. 7. Click **Start Import** to begin processing your Confluence data. 8. The import will process in phases. Once finished, the status will change to "Finished". ![Confluence file uploaded](https://media.docs.plane.so/importers/confluence/confluence-file-uploaded.webp#hero) 9. After the import completes, your Confluence pages will be available in Plane's **Wiki** section. The page hierarchy from Confluence will be preserved, with main pages and their subpages organized in the same structure. ## Imported fields Here's how different Confluence elements are handled during import: | Confluence | Plane | | -------------------------- | ----------------------------------- | | Markdown | Markdown | | Videos | Links | | Embeds | Links | | Attachments | Links | | Text and background colors | Text and background colors | | Links | Links | | Subpages | Nested pages | | Page mentions | Links | | User mentions | Link (Atlassian user) | | Table background colors | Not imported | | Block highlight | Text highlight (not supported) | | Columns | Rendered Vertically (not supported) | | Comments | Not supported | | Databases | Tables | | Collapsible | Callout | --- --- url: 'https://docs.plane.so/importers/clickup.html' description: Import work items from ClickUp to Plane. --- # ClickUp importer The ClickUp importer helps you transfer your project data from ClickUp to Plane. It pulls information from your ClickUp workspace and maps it to the corresponding structure in Plane. This includes your projects, tasks, team members, custom fields, attachments, and comments. ::: info The ClickUp importer is available on Plane Cloud and on all plans of the Commercial Edition for self-hosted instances. ::: ## Prerequisites * A ClickUp Personal Access Token from your ClickUp App Settings. * ClickUp Lists organized within Folders. ::: tip To import custom task types from ClickUp, make sure the [Work item types](/work-items/project-work-item-types) feature is enabled in your Plane project. ::: ## Import from ClickUp > **Role**: Workspace admins ![Import from ClickUp](https://media.docs.plane.so/importers/clickup/import-clickup.webp#hero) 1. Go to your Workspace settings. 2. Select **Imports** on the left pane and click **Import** next to ClickUp. ![Personal access token](https://media.docs.plane.so/importers/clickup/personal-access-token.webp#hero) 3. Enter your ClickUp Personal Access Token on the Migration Assistant page. If you don't have one, go to your ClickUp settings under **Apps** to generate it. Click **Connect ClickUp** after entering the token. 4. Choose what to import: ![Configure ClickUp](https://media.docs.plane.so/importers/clickup/configure-clickup.webp#hero) 1. Select your ClickUp team (workspace). 2. Pick your ClickUp space. 3. Choose the folders to migrate. 4. Check "Import comments and attachments" if you want these included. 5. Click **Next** to continue. 5. Match your ClickUp priorities to Plane priorities using the dropdown menus. This keeps your task prioritization consistent after migration. ![Map priorities](https://media.docs.plane.so/importers/clickup/map-priorities.webp#hero) 6. Review the mappings and make any changes if needed. Click **Back** to adjust. 7. You can check "Skip importing User data" if you don't want to migrate user information and manually add them later. ::: warning If you skip user import, work items and comments will show the name of the person who performed the migration, and the Assignees field will be empty. ::: 8. Click **Confirm** to start. The migration runs in batches with real-time status updates. You'll see progress indicators and can cancel if needed. Migration time depends on your data size rate limits. 9. After completion, review your imported projects in Plane. Check that work items, modules, and custom fields transferred correctly. ## Data mapping Here's how your ClickUp structure converts to Plane: | ClickUp | Plane | | -------------------- | ---------------------------------- | | Users | Members | | Folders | Projects | | Lists within folders | Modules within projects | | Tasks | Work items | | Custom task types | Work item types | | Custom fields | Custom properties at project level | | Task attachments | Work item attachments | | Task comments | Work item comments | | Task data | Work item data | ### Supported custom fields The importer handles these custom field types: * User fields * Short text and textarea fields * Date fields * Checkboxes * Dropdowns * Numbers * Email, phone, and website fields ## Sync ClickUp to Plane After the import, if there are any new or updated issues in ClickUp, you can easily sync these changes to Plane: ![Rerun import](https://media.docs.plane.so/importers/clickup/rerun-import.webp#hero) 1. Go to **Workspace settings**. 2. Select **Imports** on the left pane. 3. Click the **Re run** button next to the project you want to sync. --- --- url: 'https://docs.plane.so/importers/csv.html' description: Import work items from CSV files to Plane using the CSV Importer --- # CSV importer The CSV Importer lets you bring work items into Plane from a CSV file. :::info Plane also offers a [Flatfile Importer](/importers/flatfile) with interactive field mapping and inline editing. The Flatfile Importer is only available on Plane Cloud. ::: ## Prepare your CSV Your CSV file should include columns for the fields you want to import. [Download the sample CSV](https://media.docs.plane.so/importers/csv/plane_csv_sample.csv) to see the expected format, or use it as a starting point. ### Before you start Most fields in the CSV are matched by name against things that already exist in your project. If a match isn't found, the import doesn't stop and it doesn't warn you. It quietly falls back to a default or leaves the field empty. So it's worth setting these up first: | Set this up first | Why | | --------------------- | -------------------------------------------------------------------------------------------------------- | | **States** | A state name that doesn't exist puts the work item in the project's default state instead. | | **Work item types** | A type that doesn't exist falls back to the project's default type. | | **Cycles** | Cycles are never created by the import. An unknown cycle name leaves the work item out of every cycle. | | **Estimate scale** | The estimate value has to match a point on the scale that's currently active in the project. | | **Members** | Assignees and subscribers must already be members of the project. People are never invited by an import. | | **Custom properties** | These have to exist on the work item type you're importing into. | **Labels are the exception.** Any label in your file that doesn't exist yet is created for you, with a random color. ### An example file ```csv Identifier,Name,Description,State Name,Issue Type,Priority,Start Date,Due Date,Labels,Assignees,Cycle Name,Estimate,Parent,Links,Comments,Story Points,Platforms PROJ-1,Design the import flow,Work out the file format,In Progress,Task,high,2024-01-10,2024-01-20,Backend|P0,alice@example.com,Sprint 1,5,,https://example.com/spec;Spec,2024-01-15 10:30:00;alice@example.com;Draft is up,8,iOS|Web PROJ-2,Write the parser,,Todo,Task,medium,,,Backend,bob@example.com,Sprint 1,3,PROJ-1,,Blocked on the spec,3,Web ``` In above example file `Story Points` and `Platforms` are custom Properties. ### A few things to know * The file has to be a **CSV**, saved as UTF-8. Excel and Google Sheets both offer this. * **One row is one work item.** * Column order doesn't matter, and extra columns you don't need are ignored. * Column headers aren't case-sensitive, and spaces and underscores are interchangeable. `Due Date`, `due date` and `due_date` all work. * If you export work items from Plane first, you can edit that file and import it straight back. The headers already match. Note: * **Priority** accepts `urgent`, `high`, `medium`, `low`, or `none`. * **Start Date** and **Due Date** use `YYYY-MM-DD` format. * Multiple values are separated by `|`. * Custom property columns are named exactly as the properties are in Plane. :::warning Make sure your CSV is properly formatted before uploading. Malformed rows or mismatched columns may cause individual rows to fail during import. ::: ## Import from CSV > **Role**: Workspace Admin 1. Go to **Workspace settings → Imports**. 2. Find the **CSV** tile and click **Import**. ![CSV Importer](https://media.docs.plane.so/importers/csv/csv-importer-landing.webp#hero) 3. On the **Select Project** step, choose the Plane project where you want to import your work items. The project must already exist — create it first if needed. ![Select project](https://media.docs.plane.so/importers/csv/select-project.webp#hero) 4. Click **Next**. 5. On the **Upload CSV** step, upload your CSV file by dragging it onto the upload area or clicking to browse. ![Upload CSV](https://media.docs.plane.so/importers/csv/upload-csv.webp#hero) 6. Click **Import CSV**. The importer processes your file and creates work items in the selected project. You'll see the import job appear in the **Migrations** table with a status of **Transforming** while it's in progress. Once complete, the status changes to **Finished**. ![Import finished](https://media.docs.plane.so/importers/csv/import-finished.webp#hero) *** ## The fields | Column | Required | What to write | | ------------------------ | -------- | -------------------------------------------------- | | **Name** | Yes | The title of the work item | | **Description** | No | Plain text | | **Priority** | No | `urgent`, `high`, `medium`, `low` or `none` | | **Start Date** | No | `2024-01-15` | | **Due Date** | No | `2024-01-20` | | **State Name** | No | `In Progress` | | **Issue Type** | No | `Task` | | **Labels** | No | `Bug\|Backend` | | **Assignees** | No | `alice@example.com\|bob@example.com` | | **Subscribers** | No | `carol@example.com` | | **Comments** | No | `2024-01-15 10:30:00;alice@example.com;Looks good` | | **Links** | No | `https://example.com;Spec` | | **Cycle Name** | No | `Sprint 1` | | **Estimate** | No | `5` | | **Identifier** | No | `PROJ-1` | | **Parent** | No | The Identifier of another row | | *(custom property name)* | No | One column per custom property | *** ## Notes on each field ### Name The only column you can't leave out. It's the title of the work item, up to 255 characters. A row with an empty Name is skipped and reported as an error. Everything else in the file still imports. ### Description Plain text. Line breaks are kept, and each line becomes its own paragraph. ### Priority One of five values, and it has to be **lowercase**: `urgent` · `high` · `medium` · `low` · `none` Leave it blank and the work item gets no priority. Anything else, including `Urgent` with a capital U, makes the row fail. ### Start Date and Due Date Both use the format `YYYY-MM-DD`, for example `2024-01-15`. Any other format makes the row fail. Two things that catch people out: * **Spreadsheets love to reformat dates.** Excel will happily turn `2024-01-15` into `15/01/2024` when you save. Format the date columns as plain text before you type in them, and open the finished CSV in a text editor to check. * **The due date can't be before the start date.** If it is, the row fails. ### State Name The name of a state in the project, for example `In Progress`. * The state has to exist in the project already. States are never created. * The match is exact, **including capitalization**. `in progress` won't match `In Progress`. * If it doesn't match, the work item goes into the project's default state and nothing tells you. It's worth spot-checking a few items after a large import. ### Issue Type The name of a work item type in the project, for example `Task` or `Bug`. * The type has to exist and be turned on in the project. * The match is exact, including capitalization. * **Epics can't be imported this way.** An epic name here falls back to the default type. * If it doesn't match, or you leave it blank, the work item gets the project's default type. This column also decides which custom property columns apply to the row, so it's worth getting right if you're importing custom properties. ### Labels Label names separated by pipes: `Bug|Backend|P0` * **Labels that don't exist yet are created for you**, each with a random color. This is the one thing in the import that gets created automatically. * Matching against existing labels is exact, **including capitalization**. If your project already has `Bug` and your file says `bug`, you'll end up with two separate labels. Before importing, it's worth opening your project's label list and matching the spelling exactly. ### Assignees Email addresses separated by pipes: `alice@example.com|bob@example.com` * Everyone listed has to already be **a member of the project**. The import never invites anyone. * The email match ignores capitalization. * Someone who isn't a project member is skipped. The work item is still created with the assignees who did match. * If you don't have emails, a person's display name in Plane works too. Emails are more reliable, because two people can share a display name. ### Subscribers Same rules as Assignees: email addresses separated by pipes, and everyone has to be a project member. One difference from normal use: assignees aren't automatically subscribed during an import. You get exactly the subscribers listed in the file. ### Comments Each comment has three parts, separated by semicolons, in this order: ``` date;author email;comment text ``` Multiple comments are separated by pipes: ``` 2024-01-15 10:30:00;alice@example.com;Draft is up|2024-01-16 09:00:00;bob@example.com;Shipping today ``` * The **date** uses `YYYY-MM-DD HH:MM:SS` and is read as UTC. Leave it out or get it wrong and the comment is simply dated to the time of the import. * The **author** has to be a project member. If they aren't, the comment is still added, but posted under the name of whoever ran the import. * The **text** is plain text. * **If you only want the text**, you can write just that: a comment cell of `Blocked on the spec` works on its own. * If the comment text contains a semicolon or a pipe, put a backslash in front of it. ### Links Each link is a URL and an optional title, separated by a semicolon. Multiple links are separated by pipes: ``` https://example.com;Spec|https://plane.so;Plane ``` * **Just the URL is fine.** `https://example.com` on its own works, and so does a plain list of URLs separated by pipes. * A URL without `http://` or `https://` gets `http://` added for you. * A URL that isn't valid is skipped. The work item still imports. * If you leave the title out, the URL is used as the title. ### Cycle Name The name of a cycle in the project, for example `Sprint 1`. * The cycle has to exist already and must not be archived. **Cycles are never created** by an import. * The match is exact, including capitalization. * A work item can be in one cycle, so this is a single name, not a list. * If the name doesn't match, the work item is imported without a cycle. ### Estimate The estimate value, for example `5` or `M`. * It has to match a point in the estimate scale that's **currently active** in the project. Points from an older, switched-off scale won't match. * It's matched as text, so write it exactly as it appears in the scale. * If the project has no active estimate scale, or the value doesn't match, the work item is imported without an estimate. ### Identifier and Parent (creating sub-work items) Use these two together to build parent and child relationships inside your file. 1. Give every row an **Identifier**. Anything unique works: `PROJ-1`, `A`, `1`. If you exported from Plane, this column is already filled in. 2. In the child row, put the **parent's** Identifier in the **Parent** column. Notes: * Rows can be in any order. A child can point to a parent that appears further down the file. * **Both rows have to be in the same file.** You can't point at a work item that already exists in Plane. * A parent link that doesn't work out, because the parent isn't in the file, or because the two work item types can't be nested, is skipped. The child is still imported, just at the top level. ### Custom properties If your project uses work item types with custom properties, **give each property its own column** and use the property's name as the header. A property called "Story Points" goes in a column headed `Story Points`. For this to work, the row's work item type has to have that property on it. What to write, by property type: | Property type | What to write | Notes | | ------------- | ---------------------------------- | ----------------------------------------------------------------------- | | Text | Any text | | | Number | `12.5` | | | Checkbox | `true` or `false` | Lowercase only. `TRUE`, `Yes` and `1` are ignored. | | Date | `2024-01-15` | | | Email | `alice@example.com` | | | URL | `https://example.com` | Include `https://`. Unlike the Links column, nothing is added for you. | | Dropdown | The option name, for example `iOS` | Capitalization doesn't matter. The option has to exist on the property. | | Multi-select | `iOS\|Web` | Separate options with pipes. | If a value doesn't fit its property, it's skipped and the work item is still created with everything else. An empty cell leaves the property unset, it doesn't clear anything. **Not supported:** properties that link to a person, a work item or a release, file properties, and calculated properties. Leave those columns out. *** ## View import summary After an import finishes, click **Summary** in the Migrations table to download a JSON report. The report includes the total number of rows processed, how many were successfully imported, and how many failed. For failed rows, the report lists the specific errors so you can fix your CSV and re-import. :::tip Re-importing the same file does not create duplicates. The import fails instead. ::: --- --- url: 'https://docs.plane.so/importers/flatfile.html' description: Import work items from CSV files to Plane using the Flatfile importer. --- # Flatfile importer The Flatfile importer provides a streamlined way to bring your work items into Plane from CSV files. With intelligent field mapping and data validation, you can migrate your data accurately and efficiently. ::: info The Flatfile importer is only available on Plane Cloud. If you're using the self-hosted Commercial Edition, use the [CSV importer](/importers/csv) instead. ::: ## Import from CSV > **Role**: Workspace admins Here's how to get started: 1. Click your Workspace name at the top left on the sidebar. 2. Select **Settings**. 3. In the right pane, click **Imports**. 4. Look for the **Flatfile Importer** tile (marked Beta) and click the **Import** button. ![Flatfile Importer on Imports page](https://media.docs.plane.so/importers/flatfile/flatfile-imports-page.webp#hero) 5. **Configure your destination project** Select the Plane project where you want your CSV data to go. If you haven't created your destination project yet, you'll need to create it first before proceeding. ![Configure Plane project](https://media.docs.plane.so/importers/flatfile/configure-plane.webp#hero) Click **Next** to continue. 6. **Upload your CSV file** Click **Upload CSV** to begin the upload process. ![Upload CSV screen](https://media.docs.plane.so/importers/flatfile/upload-csv.webp#hero) You can either drag and drop your file onto the upload area, click to browse your files, or manually enter data if you prefer to input information directly. ::: tip Sample CSV template Download our [sample CSV file](https://media.docs.plane.so/importers/flatfile/flatfile-import-sample.csv) to see the correct format and field structure for importing your data. Make sure your CSV is properly formatted before uploading. Save your CSV file with UTF-8 encoding. Malformed rows or mismatched columns may cause individual rows to fail during import. ::: 7. **Map your fields** The field mapping screen appears with two columns: * **INCOMING FIELDS** (left): Your CSV column headers * **DESTINATION FIELDS** (right): Corresponding Plane fields ![Map fields screen](https://media.docs.plane.so/importers/flatfile/map-fields.webp#hero) The importer automatically maps fields when column names match Plane's field names. You can adjust any mapping by clicking the dropdown next to each incoming field. Required fields are marked with an asterisk (\*). ::: warning User fields require email addresses For fields like **Assignees** and **Created By**, you must use email addresses rather than usernames. This ensures team members are correctly linked to their work items in Plane. ::: 8. **Validate field values** For fields like State and Priority, you'll need to map your CSV values to valid Plane options: * The screen shows each unique value from your CSV under "Incoming Values" * Select the matching Plane value from the "Destination Values" dropdown * The mapping count shows your progress (e.g., "0 of 2 values mapped") ![Validate field values](https://media.docs.plane.so/importers/flatfile/validate-fields.webp#hero) Continue mapping until all values are matched to valid Plane options. Click **Continue** when all fields are properly mapped. 9. **Review your data** You'll see a table preview of your data with all mapped fields. This is your last chance to verify everything looks correct before import. ![Data preview table](https://media.docs.plane.so/importers/flatfile/data-preview.webp#hero) * Review each row to ensure the data appears as expected * Check that field mappings are correct * If something's not right, click **Back** to adjust your field mapping When you're satisfied, click **Submit** to start the import. 10. **Track your import** Once submitted, your import appears in the Migrations list with: * Status indicator (Finished, In Progress, or Failed) * Total batches and imported batches count * Start time * Options to **Re Run** or **Cancel** the migration ![Migrations list](https://media.docs.plane.so/importers/flatfile/migrations-list.webp#hero) For large datasets, the import might take a few minutes to process. You can monitor progress from this screen. 11. **Verify your data** After the import shows "Finished" status, navigate to **Work Items** in your Plane project to confirm your data imported successfully. ## Imported fields When bringing your data from CSV into Plane, here's exactly what you can transfer over: | Field | Notes | | -------------- | ------------------------------------------------------------------------------------------------------------- | | Title | Required for all items | | Description | Plain text only - any formatting, images, or tags will be imported as raw text | | Work Item Type | Make sure the [Work item types](/work-items/project-work-item-types) feature is enabled in your Plane project | | State | Must map to valid states in your Plane project | | Assignees | **Must be email addresses**, not usernames - this is how Plane connects work items to users | | Priority | Must map to valid priority values in your Plane project | | Created By | **Must be email addresses** - allows Plane to track who originally created the item | | Start Date | | | Target Date | | | Labels | | | Cycle | | | Module | | | Created At | | ## Managing your imports After completing imports, you can: * **View import history**: All your imports appear in the Migrations list on the Flatfile Importer page. * **Re-run imports**: Click **Re Run** if you need to import the same data again. * **Cancel imports**: Use **Cancel** to stop an in-progress import. This migration history helps you track when data was imported and troubleshoot any issues that arise. --- --- url: 'https://docs.plane.so/importers/jira.html' description: >- Import your projects and issues from Jira Cloud, Jira Server, or Jira Data Center into Plane. --- # Jira importer Plane imports your projects, issues, and related data from Jira. There are two connectors, depending on your Jira deployment: * **Jira Cloud** for sites hosted at `*.atlassian.net`. * **Jira Server / Data Center** for self-hosted Jira. Server and Data Center use the same connector and the same steps. Both connectors import into a Plane project you choose and run on the same import engine, so the data you get is the same. The differences are in how you connect and a few deployment-specific options, called out below. ::: info The Jira importer is available on Plane Cloud and on all plans of the Commercial Edition for self-hosted instances. ::: ## Before you begin * **Issue types**: To bring Jira issue types in as Plane work item types, enable the [Work Item Types](/work-items/project-work-item-types) feature on the target Plane project before importing. Without it, issues still import, but issue types are not created as work item types. * **Jira access**: The account you connect with must be able to read the Jira project you are importing, along with its issues, statuses, priorities, issue types, and labels. ## Choose your connector Go to **Workspace settings → Imports**, then click **Import** in either the **Jira** section (for Jira Cloud) or the **Jira Server/Data Center** section (for self-hosted Jira). ## Connect to Jira Jira connects with a Personal Access Token. Provide three values: | Field | What to enter | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Personal Access Token** | An API token created at [id.atlassian.com](https://id.atlassian.com/manage-profile/security/api-tokens) or from your Jira Server / Data Center instance | | **User email** | The email address linked to that token | | **Jira domain** | Your Jira site URL, for example `https://your-site.atlassian.net` | Click **Connect Jira** to link the accounts. Plane verifies the credentials before continuing. ## Run the import After connecting, work through the import steps. The steps are the same for all deployments, except that the **Import users** step appears only for Jira Cloud (Server and Data Center bring in users automatically). 1. **Select Plane project.** Choose the Plane project to import into. 2. **Configure Jira.** Choose the Jira site and the Jira project to import from. Optionally, add a **JQL** filter to import only the issues that match a query. Plane scopes your query to the selected project automatically. 3. **Import users** *(Jira Cloud only)*. Choose how to bring in users: * **Upload CSV** *(recommended)*. Upload a user export from Jira. See [Export users from a site](https://support.atlassian.com/organization-administration/docs/export-users-from-a-site/) for how to generate it. Admin or Member users invited to your workspace count toward your billed seats immediately, but the importer treats them as active members only once they accept the invitation. So you have two options: let the importer create users (don't invite them manually first), or invite everyone first and wait for them to accept before importing. * **Skip user import.** Select **Skip Importing User data** and add users later. ::: warning If you skip user import, work items and comments show the name of the person who ran the migration, and the Assignees field is left empty. ::: For **Jira Server / Data Center**, there is no user step. Plane automatically syncs the users referenced by the imported issues. 4. **Map states.** Map each Jira status to a Plane state. Select **Auto create and map the remaining Jira states** to create and map anything you don't map by hand. 5. **Map priorities.** Map each Jira priority to a Plane priority. If there is no match, choose **None**. 6. **Summary.** Review your mappings. Click **Back** to adjust, or **Confirm** to start the import. The import runs in the background and takes a few minutes to hours depending on the size of your Jira project. When it finishes, open **Work items** in your Plane project to confirm the data imported. ::: info Issue types and work item types When the Work Item Types feature is enabled, Jira issue types are imported as Plane work item types. You do not map them; they are created automatically. On the Free plan (or with the feature off), issues still import but issue types are not created as work item types. ::: ## What gets imported | Jira | Plane | Notes | | -------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Issues | Work items | Summary becomes the work item title. | | Issue description | Work item description | Formatting is preserved. Inline images are re-uploaded to Plane. | | Status | States | Mapped in the Map states step. | | Priority | Priority | Mapped in the Map priorities step. | | Issue types | Work item types | Requires the Work Item Types feature. Imported automatically, not mapped. Can be created at the project or workspace level. | | Epics | Work item type | Imported as a regular work item type, not as Plane's dedicated Epics feature. | | Labels | Labels | Every imported work item also gets a `JIRA IMPORTED` label so you can find migrated items easily. | | Custom fields | Custom properties | Supported Jira custom and system fields become work item custom properties, with their options. Unsupported field types are skipped. Rich text custom fields require the rich text property feature. | | Users | Members | Cloud: from your CSV, or skipped. Server / Data Center: synced automatically from the issues. | | Reporter | Created by | Also stored as a "reporter" property on the work item. | | Assignee | Assignees | Blank if you skip user import. | | Comments | Comments | Includes author and timestamp. If you skip user import, comments show the person who ran the migration. | | Attachments | Attachments | On both issues and comments. See [Attachments](#attachments) for a Server / Data Center note. | | Sub-tasks and parent links | Parent-child relationships | Sub-tasks import as work items linked to their parent. | | Linked issues | Relations | Blocks, blocked by, relates to, and duplicate. Jira link types with no Plane equivalent are created as custom relation types. Links across projects resolve once the other project is also imported. | | Sprints | Cycles | Including the cycle's work items and start and end dates. | | Components | Modules | Including the module's work items. | | Fix versions / affected versions | Custom properties | Stored as work item properties. | | Story points | Story points | From your configured story-points field. | | Worklogs | Worklogs | Time tracking is enabled on the project when worklogs are imported. | | Watchers | Subscribers | | | Change history | Work item activity | | | Start date / Due date | Start date / Due date | | | Created date | Created at | | Every imported work item also gets a **Linked Jira Issue** link back to the original issue in Jira, and its original Jira key number is preserved. ## Attachments Attachments on issues and comments are imported by default. **Jira Server / Data Center behind SSO.** Jira Server and Data Center stream attachment files from a secure servlet (`/secure/attachment/...`). On instances where that servlet sits behind web SSO (SAML), it does not accept the personal access token the way the REST API does, so the download is redirected to your identity provider and Plane receives the login page instead of the file. When this happens, attachments fail to import. To work around it, expose a custom attachment download endpoint on your Jira instance (typically a ScriptRunner REST endpoint) that is not behind the SSO filter, and have Plane use it for attachment downloads. Follow the [attachment endpoint setup instructions](https://sites.plane.so/pages/4cfee57ef84d4b50bacfb110e37316e5). * On **self-hosted Plane**, set the download path (with an `{id}` placeholder for the attachment ID, for example `/rest/scriptrunner/latest/custom/downloadAttachment?id={id}`) in your integration service configuration. * On **Plane Cloud**, contact Plane support to have the download path configured for your instance. This applies to **Jira Server and Data Center only**. Jira Cloud is not affected and needs no workaround. ## Re-run and resume an import Open the import from **Workspace settings → Imports** to manage it. **Re-run** (all deployments). Re-running restarts the import for that project from the beginning, using the same configuration and filter. It is a full re-sync, not a changed-only sync, but it does **not** create duplicates: Plane matches items by their original Jira identity and updates existing work items in place while adding any new issues. Use re-run to bring across new and updated Jira issues after your initial import. ![Re-run import](https://media.docs.plane.so/importers/jira/rerun-import.webp#hero) **Resume** (Jira Server / Data Center only). If a Server or Data Center import fails or times out, you can resume it. Resume continues from where the import stopped rather than starting over. It is available for a limited window (about 7 days) after the job stops; after that, use re-run instead. ## Notes and limits * **Reliability.** Server and Data Center imports track each batch of issues and automatically re-dispatch any batch that goes missing, and they detect and recover from stalls. This significantly reduces timeout and error failures on large imports. * **Large instances.** Very large Jira projects import in batches and may take a while. If your Data Center instance rate-limits aggressively, imports still complete but run more slowly. * **Cross-project links.** Links between issues in different Jira projects resolve only after both projects have been imported into Plane. * **Unsupported custom field types** are skipped rather than failing the import. --- --- url: 'https://docs.plane.so/importers/linear.html' description: Migrate your Linear data to Plane. --- # Linear Importer With the Linear importer, you can easily import issues, states, labels, priorities and user data from Linear to Plane and continue managing your existing projects. ::: info The Linear importer is available on Plane Cloud and on all plans of the Commercial Edition for self-hosted instances. ::: ## Import from Linear > **Role**: Workspace admins ::: tip To import issue types from Linear, make sure the [Work item types](/work-items/project-work-item-types) feature is enabled in your Plane project. ::: To import Linear issues to a Plane project, follow these steps: 1. Click the **∨** icon next to your workspace name on the sidebar and select **Workspace settings**. 2. Select **Imports** on the right pane and click the **Import** button in the Linear section. ![Import Linear](https://media.docs.plane.so/importers/linear/import-linear.webp#hero) 3. In the **Linear to Plane Migration Assistant** screen, enter your **Personal Access Token** to allow Plane access to your Linear account. ![Connect Linear](https://media.docs.plane.so/importers/linear/linear-plane-migration-assistant.webp#hero) 4. Click the **Connect Linear** button to link the accounts. 5. Click the **Import** button in the **Imports** section. ![Import Linear data](https://media.docs.plane.so/importers/linear/import-linear-data.webp#hero) 6. **Configure Plane**\ Select the Plane project where you want to import your Linear data and and click **Next**. ![Configure Plane](https://media.docs.plane.so/importers/linear/configure-plane.webp#hero) 7. **Configure Linear**\ Choose the Linear team from where you want to import data. ![Configure Linear](https://media.docs.plane.so/importers/linear/configure-linear.webp#hero) 8. **Map states**\ Map **Linear states** to their equivalent **Plane states**. ![Map states](https://media.docs.plane.so/importers/linear/map-states.webp#hero) 9. **Summary**\ Review the mappings and make any changes if needed. Click **Back** to adjust, or click **Confirm** to start the migration. ![Review mappings](https://media.docs.plane.so/importers/linear/import-summary.webp#hero) 10. The data migration begins and takes a few minutes to complete depending on the number of issues in your Linear workspace. ![Migration complete](https://media.docs.plane.so/importers/linear/import-complete.webp#hero) 11. Once it's done, go to **Work items** in your Plane project to confirm that the data import is successful. ![Verify import](https://media.docs.plane.so/importers/linear/verify-import.webp#hero) ### Imported entities Here’s a quick look at what gets imported during the migration from Linear to Plane: | Linear | Plane | Notes | | ------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Labels | Labels | | | Status | States | | | Issue priorities | Priorities | | | Users | Users | | | Issues | Work items | | | Relations | Parent | Includes only parent-child relationships | | Issue comments | Work item comments | Includes username and timestamp. If you skip user import during migration, comments will show the name of the user who performed the migration. | | Issue attachments | Work item attachments | | | Reporter | Created by | | | Created | Created at | | | Assignee | Assignees | If you skip user import during migration, this will be blank. | | Issue types | Labels | Prefix in Issue title | | | Images in the Issue description | Images in the Work item description | | | Summary | Work item title | | | Start date | Start date | | | Due date | Due date | | | Linked Issues | Links | Includes backlinks to the original Linear issue. | | Cycles | Cycles | Includes the work items, start and end date. | | Projects | Modules | Includes the work items. | ## Sync Linear to Plane After the import, if there are any new or updated issues in Linear, you can easily sync these changes to Plane: 1. Go to **Workspace settings**. 2. Select **Imports** on the right pane. 3. Click the **Re run** button next to the project you want to sync. ![Sync Linear](https://media.docs.plane.so/importers/linear/rerun-import.webp#hero) --- --- url: 'https://docs.plane.so/importers/notion.html' description: Import data from Notion to Plane. --- # Notion importer The Notion to Plane importer lets you transfer your Notion pages and content to Plane's Wiki. This is useful when you want to bring your documentation, notes, and structured content from Notion into your Plane workspace as Wiki pages. The importer takes exported Notion content and converts it into Plane wiki pages. It preserves your page structure, including subpages, and maintains the hierarchical organization of your Notion workspace within Plane's wiki system. ## Export your Notion content 1. Open the Notion page you want to export. 2. Click the three-dot menu (⋯) in the top-right corner of the page. 3. Select **Export** from the dropdown menu. 4. In the export dialog: * **Export format**: Choose **HTML** * **Include databases**: Select **Current view** * **Include content**: Choose **Everything** * **Include subpages**: Toggle this **ON** * **Create folders for subpages**: Toggle this **ON** * **Export comments**: Toggle this **OFF** (unless you want comments included) ::: info Only HTML exports from Notion are supported. Make sure to select HTML as your export format. ::: 5. Click **Export**. 6. Notion will generate a ZIP file containing your exported content. ::: warning Nested ZIP files Some Notion exports contain a nested ZIP file inside the main export ZIP. If your export has this structure, you'll need to extract the inner ZIP file before uploading to Plane. To check and extract on Mac or Linux, run this in terminal: ```bash unzip your-notion-export.zip ``` This will extract the contents, including any inner ZIP file. Upload the extracted inner ZIP file to Plane, not the outer one. ::: ## Import Notion content ![Import from Notion](https://media.docs.plane.so/importers/notion/import-notion.webp#hero) Once you have your exported ZIP file: 1. Go to your Workspace settings. 2. Select **Imports** on the left pane and click **Import** next to Notion. 3. On the Notion import page, click **Upload Notion Exported ZIP**. 4. Select and upload the ZIP file you exported from Notion. ![Upload notion file](https://media.docs.plane.so/importers/notion/upload-notion-file.webp#hero) 5. Wait for the upload to complete. You'll see a "Upload complete!" message. 6. Click **Start Import** to begin processing your Notion data. 7. The import will process in phases. Once finished, the status will change to "Finished". ![Notion file uploaded](https://media.docs.plane.so/importers/notion/notion-file-uploaded.webp#hero) 8. After the import completes, your Notion pages will be available in Plane's **Wiki** section. The page hierarchy from Notion will be preserved, with main pages and their nested pages organized in the same structure. ## Imported blocks Here's how different Notion elements are handled during import: | Notion | Plane | | -------------------------- | ----------------------------------- | | Markdown | Markdown | | Videos | Links | | Embeds | Links | | Attachments | Links | | Text and background colors | Text and background colors | | Page icons | Page icons | | Page banner | Not imported | | Links | Links | | Subpages | Nested pages | | Page mentions | Links | | User mentions | Text (Not imported) | | Table background colors | Not imported | | Block highlight | Text Highlight (not supported) | | Columns | Rendered vertically (not supported) | | Comments | Not supported | | Databases | Tables | --- --- url: 'https://docs.plane.so/core-concepts/export.html' description: >- Export work items from Plane in CSV, Excel, or JSON formats for backup, analysis, or sharing. --- # Export data Plane allows you to export all your work items, from a single project or multiple projects, so you can access your data outside of Plane. You can export work items into CSV, Excel, or JSON formats. ## Export projects > **Role**: Workspace Admins 1. Go to your [Workspace settings](/core-concepts/workspaces/overview#access-workspace-settings). 2. In the left pane, select **Exports**. ![Export data](https://media.docs.plane.so/workspaces/export-data.webp#hero) 3. **Exporting project** * Choose to export work items from all projects or a specific project using the dropdown. 4. **Choose format**\ You can export work items in one of the following formats: * CSV: A plain text file with values separated by commas. * Excel: A formatted spreadsheet file. * JSON: A lightweight, machine-readable format. 5. **Apply filters**\ Narrow down your export by filtering work items based on available filters. 6. **Click Export**\ This will package the export into a ZIP file. ::: info Exporting large workspaces may take some time depending on the number of work items. ::: 7. **Download file**\ You can view the history of your exports under **Previous exports**. For each export: * You'll see its status (e.g., Queued, Completed). * The date and the name of the user who triggered the export. * The format used for the export. Once completed, click **Download** to get your file. Use the **Refresh status** button to check for the latest updates. ::: warning Exported files remain downloadable for a limited time (7 days). After this period, they will show as "Expired" and you'll need to create a new export. ::: ## Custom exports Export filtered work items, cycles, views, or modules directly from your project. Custom exports let you export exactly what you see after applying filters and display options—perfect for reports, analysis, or sharing specific data sets. You can export data from: * Work items: Export filtered work item lists from any view * Cycles: Export work items within a specific cycle * Modules: Export work items within a specific module * Views: Export custom filtered views you've saved ### How to export ![Export work items](https://media.docs.plane.so/issues/export-work-items.webp#hero) 1. Navigate to the work items, cycle, module, or view you want to export. 2. Apply any filters or display options to narrow down your data. 3. Click the ⋯ (more options) menu in the top right. 4. Select **Export**. 5. Choose your format: * CSV: For spreadsheet applications. * JSON: For programmatic use or data processing. 6. Click **Continue** to download your file. The exported file will include all visible work items based on your current filters and settings. --- --- url: 'https://docs.plane.so/ai/plane-ai.html' description: >- Plane AI is your intelligent assistant for finding project data, analyzing work items, and managing tasks using natural language. --- # Plane AI > \[!CAUTION] Self-hosted Plane instances (Commercial Edition) > If you're running a self-hosted instance of Plane, you'll need to first configure Plane AI services to get it working. Follow this [setup guide](https://developers.plane.so/self-hosting/govern/plane-ai) first to use Plane AI. Plane AI is a built-in AI layer embedded throughout the product. It is not a generic chatbot bolted on to the side. It understands your workspace: your projects, work items, cycles, modules, pages, and members. It can answer questions about your work, create and update work items, generate charts from workspace data, draft and edit page content in real time, find duplicate work items, suggest labels, and filter work items using plain English. ![Plane AI chat sidebar](https://media.docs.plane.so/plane-ai/plane-ai.webp#hero) Plane AI understands your workspace - work items, projects, cycles, modules, members, pages, comments, and more. When you ask something or give it a task, it draws from your actual data, not generic knowledge. It can also search the web and connect to external tools like GitHub, Posthog and Granola through MCP connectors. ## Enable Plane AI for a workspace 1. Go to **Workspace Settings → Plane AI**. 2. Toggle on **Turn on AI for this workspace**. Once enabled, Plane AI features become available to workspace members based on which capabilities your plan and server configuration include. Guest users cannot access any Plane AI features. ## Open Plane AI Click the **AI Assistant** in the top navigation to open the chat panel. It slides in on the right side of the screen. Drag the left edge to resize it. To use the full-page view, click the **AI** button on the siderail. The full-page view shows your conversation history in a left sidebar alongside the active chat. ## Choose a mode Every conversation runs in one of three modes. Switch modes from the dropdown in the chat input before sending your message. The three modes reflect a deliberate safety model. Project management data is consequential - moving the wrong work items into the wrong sprint, bulk-reassigning work to the wrong person, or archiving things that shouldn't be archived are mistakes that are annoying to undo and visible to everyone. The modes give you control over how much autonomy Plane AI has, depending on how certain you are of what you want. ### Ask Ask is for questions and information retrieval. Plane AI searches your workspace and answers in natural language. It does not create or modify anything - it only reads. Use Ask when you want to understand something: "What's blocking the login flow?", "Which high-priority issues are unassigned?", "Summarize what shipped this week in the backend project." ### Build Build is for creating and updating things. Plane AI plans a set of actions, shows them to you as action cards before executing anything, and waits for your confirmation. Nothing in your workspace changes until you confirm each action. You can edit or cancel individual actions before confirming. The review step exists because AI can misread intent, especially on bulk or destructive operations. Showing you the plan before executing means you can catch misunderstandings before they become real changes. This is particularly important for prompts like "close everything from last sprint" or "reassign all of Alice's issues" where the blast radius of a wrong interpretation is large. Use Build when you want to create work items, update statuses, assign members, move work into cycles or modules, log time, or make bulk changes - with full review before anything happens. ### Autopilot Autopilot works like Build but skips the review step. Actions execute immediately when Plane AI finishes planning. You see a record of what was done after the fact. Autopilot makes sense when the task is narrow, the instructions are precise, and the consequence of a small error is low. For open-ended or high-impact tasks, Build is safer. Use Autopilot for clearly scoped, unambiguous tasks. Be specific - vague prompts can produce unexpected results with no review step to catch them. ## Ask questions about your workspace In Ask mode - and as the retrieval step in Build and Autopilot - Plane AI has access to the following data: * Work items and all their properties: state, assignees, labels, priority, type, dates, descriptions, comments, history * Projects, cycles, modules, views, teamspaces, and initiatives * Pages and their full content * Members and their workspace roles and assignments * Plane's own documentation (for help questions) * The web, when web search is enabled You can ask broad or narrow questions: * "Which issues are In Progress but have no assignee?" * "What's blocking the API migration project?" * "Who is working on the most issues right now?" * "Summarize the onboarding module" * "Are there any overdue cycles?" ### Suggestion tiles When you open a new chat, a **Suggestions** section appears in the conversation area with a list of prompt ideas. These are fetched from Plane AI based on the current context - the active mode, the workspace, and which project or entity you're focused on. Click any suggestion to send it as your first message. All suggestions are disabled while Plane AI is generating a response. ### Thinking panel As Plane AI works through a complex question, it shows a **Thinking...** panel above the answer. This is its internal reasoning - how it's planning the retrieval, what it's considering, and how it's arriving at its answer. You can expand or collapse it. The final user-facing answer appears below it. The thinking panel is separated from the answer deliberately. For most questions you only care about the result, so it collapses by default and stays out of the way. But when an answer surprises you or seems wrong, the thinking panel lets you see exactly what the AI was doing - which tools it called, what data it found, and how it reasoned to that conclusion. This makes it easier to understand whether the problem was a bad query, missing data, or an AI error. ### Focus the AI on a project or workspace Use the context selector (the **@ Add context** button in the chat input) to set the scope Plane AI searches. Select a specific project to keep answers focused, or select the whole workspace for cross-project questions. The active context appears as a pill in the input field. You can also turn off workspace context entirely for general questions - Plane AI answers faster when it's not searching your data. When workspace context is on, every query goes through a retrieval phase - Plane AI searches work items, pages, and other entities before forming an answer. That retrieval takes time and adds to the response latency. For questions that don't need Plane data ("Help me write a decision document structure"), turning context off routes directly to the language model and responds noticeably faster. ### Enable web search The **Globe** icon in the chat input footer toggles web search on and off. When web search is on, the icon is highlighted and the tooltip reads **"Disable web search"**. When off, the icon is dimmed and reads **"Enable web search"**. If the currently active model doesn't support web search, the icon shows as **GlobeOff**, is grayed out and non-interactive, and the tooltip reads **"Web search is not available for this model"**. Web search is only available for OpenAI and Anthropic models. It is not available for custom or self-hosted models. Web search is a provider-level capability, not something Plane AI adds on top. OpenAI provides it through a dedicated search-enabled model; Anthropic exposes it as a tool in its API. A custom self-hosted model - a Llama instance running on your infrastructure, for example - doesn't have a mechanism to make live web requests. Routing web queries through a proxy would require building that infrastructure separately, which is outside the scope of the integration. ### @Mentions for specific context You can pull specific items into the AI's context by mentioning them in your message. Plane AI resolves the mention in real time and includes the current state of the item in the query. Supported entity types: * Work items * Projects * Cycles * Modules * Pages * States * Issue views * Teamspaces * Initiatives Example: "Can you summarize the current status of @PROJ-123 and who is assigned?" Plane AI always fetches fresh data for mentions - not cached. Fetching fresh is an intentional choice. Because Plane data changes constantly - someone closes an issue, a sprint gets updated, an assignee changes - a cached snapshot would frequently be stale. Fresh fetching means the AI's answer reflects the actual current state of your workspace at the moment you ask. ### Clarification requests If your query is ambiguous or missing a required detail, Plane AI will ask for clarification rather than guessing. It shows candidate interpretations and lets you select the one you meant. The query then re-runs with that clarification applied. Clarification is especially important in Build and Autopilot modes. Guessing wrong on a retrieval question costs you a bad answer; guessing wrong on an action can mean creating or changing the wrong things at scale. Asking before acting is the more conservative choice when the cost of a wrong interpretation is high. ## Charts and data visualization Plane AI can generate charts directly in the chat window from your workspace data. When you ask a question that's best answered visually, it produces the chart inline in the response. Four chart types are available: ### Bar chart Shows counts or values across categories. Useful for: work item counts by state, workload by assignee, issues by priority. Example prompt: "Show me how many open issues each team member has." ### Pie chart Shows proportional breakdowns. Useful for: priority distribution, state composition, work item type split. Zero-value segments are automatically excluded. Example prompt: "What's the breakdown of issue priorities in the backend project?" ### Line chart Shows trends over time, with support for multiple series, fill areas, dashed lines, and data point markers. Useful for: burndown charts, velocity trends, daily or weekly completion rates. Example prompt: "Show me the burndown for the current cycle." ### Stacked bar chart Shows values broken down by a second dimension. Useful for: states by assignee, priorities by module, issue types per sprint. Example prompt: "Show me work items by state for each assignee." Charts render with tooltips and responsive sizing. You can ask follow-up questions about a chart - for example, "Now break that down by priority" - and Plane AI will generate a new chart. ## Cycle metrics and analytics When asking about a cycle, Plane AI can retrieve detailed faceted metrics rather than just a summary. You can ask for any combination of: * **Summary**: Total completed vs. open work items * **Scope changes**: How many items were added or removed from the cycle * **By state**: Breakdown of work items by state * **By assignee**: Breakdown by team member * **By priority**: Breakdown by priority level * **Burndown**: Daily progress over the cycle duration * **Work item list**: The actual issues in the cycle with their current states Example prompts: "Show me the burndown for Sprint 14", "How has the scope of the current cycle changed?", "Break down the active cycle's issues by assignee." ## Create and update things (Build and Autopilot) In Build and Autopilot mode, Plane AI can take a wide range of actions across your workspace. Describe what you want in natural language - it handles the translation to specific operations. ### What Plane AI can create and update **Work items** * Create new work items with any combination of: title, description, state, priority, assignees, labels, type, start date, due date, estimate, parent (creates a sub-issue), cycle, module * Update any property on existing work items * Assign or unassign members * Add or remove labels * Archive or unarchive work items * Add comments * Log time worked (worklogs) * Create relationships between work items: duplicate, related, blocking, blocked by, and more * Apply custom properties * Create sub-work items under any existing work item **Cycles** * Create cycles with name, dates, and description * Add work items to a cycle or remove them **Modules** * Create modules * Add work items to a module or remove them **Pages** * Create new pages in any project **Labels** * Create new labels and apply them to work items **States** * Define new workflow states **Estimates** * Create story point scales and sizing systems **Intake** * Manage items in the intake queue **Stickies** * Create quick notes **Initiatives** * Organize work by initiative **Teamspaces** * Create team groupings ### How Build mode works 1. Describe what you want: "Create three sub-work items under PROJ-45 for the auth redesign - one for the login screen, one for token refresh logic, and one for session expiry handling." 2. Plane AI plans the actions and shows them as action cards. Each card shows the action type, key details, and what will be created or changed. 3. Review the plan. Edit individual cards if something looks wrong. 4. Click **Confirm** to execute. Nothing changes in your workspace until you confirm. You can let some actions execute and cancel others. After execution, a summary shows which actions succeeded, which failed (with reasons), and links to each created or updated item. ### Tips for better results * Reference specific items: use project names, issue identifiers, member names, or cycle names. * Describe the outcome, not the steps: "Move all unstarted issues past their due date into next sprint" works better than step-by-step instructions. * For bulk operations, state the scope clearly: "In the mobile project, assign all unassigned high-priority issues to @alice." * If Plane AI asks a clarification question, answer it - it needs the missing detail to proceed safely. ## Voice input Click the microphone button in the chat input to start recording. A waveform animation shows that audio is being captured in real time. Click the mic button again to stop, then click the checkmark to send. Plane AI transcribes the audio and adds the text to the input - you can edit it before submitting. Plane AI requests browser microphone permission on first use. If you see an error, check that your browser has microphone access enabled for the site. Voice input is available when your workspace admin has enabled it and a transcription API key is configured. ## Attach files Click the **paperclip** button in the chat input or drag files directly into the chat window. Files appear as previews in the input before you send. Plane AI reads the content and uses it as context for your message - useful for pasting in a spec, a design brief, or any external document you want it to reason over. For self-hosted Plane instances, file uploads require storage to be configured. If the button does not appear, file uploads have not been enabled on your workspace. ## Switch models mid-conversation Use the model dropdown in the chat header to switch between available LLM models at any point in a conversation. The selected model applies to all subsequent messages in that conversation. ## MCP connectors MCP (Model Context Protocol) connectors extend Plane AI with access to external tools and services. When connectors are active, Plane AI can pull data from and take actions in those systems as part of its response - without leaving Plane. Connectors are only available in Build and Autopilot modes. This restriction matches the purpose of each mode. Ask mode is read-only by design - adding action-capable connectors to it would break that guarantee. MCP connectors are fundamentally about doing things: creating a GitHub issue, querying a customer record. Those are actions, not lookups, and they belong in the modes that are designed for action with the appropriate level of oversight. See [MCP connectors](/ai/mcp-connectors) for the full list of available connectors, how to connect them, and how authentication works. To drive Plane from an external AI tool instead, use the [MCP server](/ai/mcp-server). ## Plane AI in pages Plane AI has a separate, deep integration inside the page editor. These features are distinct from the AI chat - they work directly within the editing surface. ### The AI prompt input The page editor includes an AI Assistant at the top of the page. Type a free-form instruction describing what you want done to the page - for example: * "Write an executive summary at the top" * "Add a risks section after the Timeline section" * "Rewrite the introduction to be more concise" * "Draft three acceptance criteria for the feature described above" Plane AI streams its response directly into the editor as it generates. You see the content appear in real time. The input shows a **Thinking...** state while the AI plans, then a **Persisting...** state as it writes the content. ### Inline suggestions - accept or reject per block As Plane AI writes content into the page, each generated segment appears as a **proposal** - highlighted text that has not yet been committed. A floating control panel appears at the bottom of the editor showing how many proposals are pending (for example, "2 / 5"). You can: * **Accept** the current proposal - commits it to the page * **Reject** the current proposal - removes it without changing the page * **Navigate** between proposals with arrow controls * **Accept all** proposals at once * **Reject all** proposals at once Keyboard shortcuts: **Cmd+Opt+Enter** to accept, **Cmd+Opt+Backspace** to reject, **Cmd+Opt+Up/Down** to navigate. This means Plane AI can propose changes to multiple sections simultaneously and you decide block by block what gets committed. Changes you reject leave the original text untouched. The per-block proposal model is intentional. When you give Plane AI a broad instruction - "add an executive summary, a risks section, and a glossary" - it may generate all three at once. Without per-block control, you'd be forced to accept or reject the entire output. The proposal model lets you keep the summary, reject the risks section draft, and accept the glossary without manually editing anything. You're reviewing AI output the same way you'd review a colleague's tracked changes in a document. ### Editing selected text with AI Select any text in the page editor to open the AI editing menu. The following actions are available: | Action | What it does | | -------------- | --------------------------------------------------- | | **Paraphrase** | Rewords the selected text while keeping the meaning | | **Simplify** | Makes the text easier to read | | **Elaborate** | Expands the selected text with more detail | | **Summarize** | Condenses the selected text to key points | | **Get title** | Generates a title based on the selected content | After Plane AI generates a result, you can: * **Replace selection** - swaps the original text with the AI output * **Add to next line** - inserts the output below the selection (keyboard shortcut: Cmd+Enter) * **Regenerate** - runs the action again for a different result Before regenerating, you can set a **tone**: **Default**, **Professional**, or **Casual**. The tone affects the style of the next generation. ### AI blocks AI blocks are purpose-built content blocks you insert into a page and ask Plane AI to fill. Insert one via a slash command or the page block menu, then type your prompt inside the block - for example, "Draft a sprint retrospective template" or "Write a three-column comparison of these approaches." Plane AI generates the content directly in the block. Once content is generated, you can revise it - ask Plane AI to elaborate or shorten it - or regenerate it entirely. AI blocks are useful for generating first drafts, structured templates, or any section where you want to start from AI-generated content rather than a blank slate. ### Page summary Open any page and look for the **AI summary** block at the top of the content area. If no summary exists, generate one. The summary appears in a highlighted block. Controls on the summary block: * **Regenerate** - refreshes the summary from the current page content * **Delete** - removes the summary block from the page If the page has been edited since the summary was generated, a **stale indicator** appears telling you the summary may be out of date. ## AI in the work item editor Plane AI surfaces two features directly inside the work item creation and edit form - in the description field - without going to the chat. ### Generate a description automatically When you've entered a title for a work item and an LLM is configured, an **I'm feeling lucky** button (sparkle icon) appears below the description editor. Clicking it sends the work item title to Plane AI with the instruction to generate a proper description. The description appears directly in the editor field. While generating, the button shows **"Generating response"** and is disabled. If the title is too vague for Plane AI to work with, you'll see: *"Work item title isn't informative enough to generate the description. Please try with a different title."* ### Custom AI prompt on the description The **AI** button (sparkle icon) next to the description field opens a prompt panel. From here you can give Plane AI any instruction about the work item content: * If the description is already written: the panel shows the existing content and prompts you to tell AI what to do with it - rephrase, expand, summarize, translate, reformat, or anything else. * If the description is blank: the panel prompts you to ask AI anything. Type your instruction and press **Enter** (or click **Generate response**). The AI-generated result appears below your instruction. You can then: * Click **Use this response** to apply it to the description editor. * Click **Generate again** to try again with the same instruction. * Click **Close** to discard and return to the form. A consent note is shown before any response is generated: *"By using this feature, you consent to sharing the message with a 3rd party service."* ## Duplicate detection When you create a work item, Plane AI automatically checks whether similar issues already exist in your workspace. If it finds likely matches, a panel appears before the issue is saved. The panel shows up to five potential duplicates, each with the issue ID, title, and a brief excerpt. You can: * **Select the issues that are duplicates** and click **Mark as duplicate** - this links them as duplicates. * **Discard** - dismisses the panel if none are actual duplicates (this also sends feedback to improve future predictions). Duplicate detection is proactive - you don't trigger it manually. It runs every time a work item is created. Duplicate detection runs at creation time because that's when it matters most. Once an issue is saved and work begins on it - someone assigns themselves, leaves a comment, adds it to a sprint - merging or closing it becomes disruptive. Catching the duplicate before it's saved costs nothing; catching it a week later costs everyone's attention. The proactive check is what makes it useful rather than just a search you have to remember to do. Plane AI detects similarity through vector search, not keyword matching. It converts the work item title and description into a mathematical representation and finds existing items whose representation is mathematically close. This means it can find "fix login timeout after inactivity" as a potential duplicate of "session expires too quickly on the web app" even though they share no words in common. ## Label prediction When you create or edit a work item, Plane AI automatically suggests labels based on the title and description as you type. After a short pause (about 1.5 seconds), a suggestion strip appears at the top of the work item form with a gradient background and a shimmer animation while loading. It shows the header **"AI suggestion for label"** followed by one chip per suggested label, each with a **+** icon. * Click any label chip to apply just that label. * If more than one label is suggested, an **Apply all** button appears at the end of the strip. Label prediction is fully automatic - there is no button to trigger it. If you don't want a suggestion, ignore the strip and pick labels manually as you normally would. Label prediction requires that you have permission to create labels in the project. The 1.5-second delay before predictions appear is deliberate. Triggering on every keystroke would generate predictions while you're still mid-sentence, producing irrelevant suggestions and wasting API calls. The debounce waits until you've paused - a signal that you've finished a thought - before asking the model for suggestions. The result is predictions that are based on something close to your final title and description, not a fragment of them. ## Convert a response to a page Any Plane AI response can be saved as a Plane page. Look for the **Convert to Page** button below the AI message. Clicking it creates a new page in your workspace with the response content. Use this to save summaries, generated plans, research answers, or any AI output you want to keep and share. ## Regenerate a response If you're not satisfied with an answer, click **Regenerate** below the latest message. Plane AI runs the same query again and produces a new response. ## Give feedback Each AI response has **thumbs up** and **thumbs down** buttons. Thumbs up records positive feedback with no prompt. Thumbs down opens a dialog where you can add a note describing what went wrong. Both types of feedback are tracked and used to improve Plane AI over time. ## Manage conversations ### History All conversations are saved. Access them from the left panel in the full-page view. Conversations are listed with their auto-generated titles and timestamps. Click any conversation to continue it. Use **Load More** to page through older conversations. ### Star Star conversations you want to keep easy to find. Starred conversations appear at the top of the list in the **Favorites** section. ### Search Use the search input in the conversation sidebar to filter conversations by title. ### Rename Conversations are auto-titled from your first exchange. To rename, open the conversation options and select **Rename**. ### Delete Open the conversation options and select **Delete**. Deleted conversations cannot be recovered. ## Models Plane AI gives you a choice of models from OpenAI and Anthropic. You pick the model for your conversation; Plane AI handles everything else internally. ### Select a model The model switcher is the dropdown in the top-right corner of the Plane AI chat, labeled **"Plane AI (Model Name)"**. Click it to see the available models and switch. The selected model applies to all subsequent messages in the current conversation - earlier messages stay as they were. You can switch models at any point mid-conversation. ### Available models | Model | Provider | Context window | Web search | | --------------------- | --------- | -------------- | ---------- | | **GPT-5.4** | OpenAI | 272k tokens | Yes | | **GPT-5.2** | OpenAI | 400k tokens | Yes | | **Claude Sonnet 4.6** | Anthropic | 200k tokens | Yes | | **Claude Sonnet 4.5** | Anthropic | 200k tokens | Yes | All four models are available on Plane Cloud. GPT-5.4 is the default. ### Choosing between models The models differ in how they reason and write, not just in benchmark scores. GPT-5.4 tends to be more structured and direct; Claude Sonnet tends to be more nuanced and conversational. Neither is universally better. If a response isn't landing the way you want, switching models and regenerating is the fastest way to get a different perspective. GPT-5.2 has the largest context window of the four, which matters when you're working with very long pages, large work item lists, or extended conversations where Plane AI needs to hold a lot in view at once. Both Claude models support Anthropic's prompt caching. Every Plane AI request carries a substantial system prompt - workspace context, tool definitions, conversation history. Processing this from scratch on every request adds latency. Prompt caching lets Anthropic reuse the processed version of the stable parts of that prompt across requests in the same session, producing faster responses on long conversations without any action needed from you. Caching is session-scoped and ephemeral - nothing is stored between sessions. ### How Plane AI uses models internally The model you select handles your main conversation. Separately, Plane AI routes background tasks - generating chat titles, running duplicate detection, translating natural language to filter queries, handling intermediate reasoning steps - to smaller, faster models that don't need frontier-level capability. These internal tasks are invisible to you and are not affected by your model selection. This is why operations like title generation and duplicate detection feel instant even when the main model takes longer: they run on a lightweight tier built for speed. ### Available providers and models ### Semantic search and the embedding model Separate from the chat model, Plane AI uses an embedding model for semantic search - finding relevant work items, pages, and comments by meaning rather than exact keyword match. This model is not user-selectable and runs automatically in the background whenever Plane AI searches your workspace. The embedding model converts text into vectors - mathematical representations of meaning. When Plane AI searches for relevant content, it compares the vector of your query against the vectors of everything in your workspace. Items that are semantically similar score as close matches even if they share no words in common. This is why Plane AI can surface "session timeout bug" when you ask about "login expires after inactivity" - the concepts are the same even though the phrasing is different, and vector similarity catches it where keyword search would not. ## What Plane AI can and cannot access **Can access:** * All work items, projects, cycles, modules, labels, states, views, teamspaces, and initiatives your account has access to * Page content in projects you're a member of * Member profiles and assignments * Plane's own documentation * The web (when web search is enabled) * External tools connected via MCP connectors **Cannot access:** * Private pages you don't own * Workspaces you are not a member of * External systems not connected via MCP ## Constraints * Guest users cannot use any Plane AI feature. * Autopilot mode must be explicitly enabled by your workspace plan and configuration. * Voice input requires browser microphone permission and a server-side Groq API key. * File uploads require cloud storage (AWS S3 or compatible) to be configured. * MCP connectors require per-user authentication setup before use. See [MCP connectors](/ai/mcp-connectors). * Label predictions only appear when the flag is enabled and the user has label create permission in the project. * Natural language filter conversion may fail for ambiguous or unsupported queries - the error message will indicate what went wrong. * Chart generation is triggered by the AI based on the nature of your question - you cannot force a specific chart type, but you can ask for one explicitly. * The LLM provider and model options available in the model switcher are determined by your workspace's server configuration, not by individual users. * Workspace-level Plane AI must be enabled before any per-feature flags take effect. --- --- url: 'https://docs.plane.so/ai/ai-skills.html' description: >- Save reusable instructions for Plane AI and run them as slash commands in chat. --- # AI Skills AI Skills are reusable instructions you save once and run in Plane AI chat with a slash command. Instead of retyping a detailed prompt every time, you capture it as a skill, give it a name, and invoke it with `/name` whenever you need it. Skills can include variables so a single skill adapts to different work items, projects, or people each time you run it. :::info Requirement AI Skills are part of Plane AI and are available when Plane AI is enabled for your workspace. ::: ## Skill scopes Every skill has a scope that determines who can use it. | Scope | Who creates it | Who can use it | | ------------- | ----------------- | ---------------------------- | | **Personal** | Any member | Only you | | **Workspace** | A workspace admin | Everyone in the workspace | | **System** | Built into Plane | Everyone, in every workspace | Personal and workspace skills are the ones you create. System skills are built-in and ready to use; they cannot be edited or deleted. ## Find your skills Open **Skills** from the Plane AI sidebar. The page has two tabs * **Personal** - the skills only you can use. * **Workspace level** - the skills shared across the workspace. Each skill is listed with its name and who created it, along with **Edit** and **Delete** actions. ## Create a skill 1. On the Skills page, click **Add new skill** (or **Add personal skill** / **Add workspace skill**). 2. Fill in the form. * **Skill name** (required)\ The name becomes the skill's slash command. Use lowercase words separated by hyphens, for example `weekly-update`. In chat you will run it as `/weekly-update`. The name is shown with a leading `/` in the form to make this clear. * **Description** (optional)\ A short summary of what the skill does, so you and your teammates can tell skills apart in the list. * **Scope**\ Choose **Personal** (only you can use it) or **Workspace** (anyone in the workspace can use it). The Workspace option is available only to workspace admins. * **Instructions** (required)\ The prompt Plane AI runs when the skill is invoked. Write it as clear instructions describing what you want done. You can include variables (see below). 3. Click **Save**. ## Use variables Variables let one skill handle different inputs each time it runs. Write a variable `{{ variable_name }}` anywhere in the instructions, for example: ``` Summarize the latest activity on {{ work_item }} and post a status update for {{ assignee }}. ``` When you run the skill, you supply the specific value for each variable. Two ways to add a variable in the editor: * Type `{{ }}` directly and name your own variable. * Click **Add variable**, or press `{`, to insert a Plane entity variable. The available Plane entities are: work item, project, workspace, initiative, cycle, module, view, teamspace, page, assignee, priority, due date, and state. Plane detects the variables in your instructions automatically. You do not declare them separately. ## Run a skill in chat 1. In the Plane AI chat input, type `/`. 2. A list of your available skills appears (personal, workspace, and system). Keep typing to filter by name. 3. Select the skill. Its instructions are added to your message. 4. Provide values for any variables the skill uses, then send. The skill list also includes a **Manage skills** shortcut back to the Skills page. ## Edit or delete a skill From the Skills page, use the **Edit** action to change a skill's name, description, scope, or instructions, and **Delete** to remove it. Deleting a skill cannot be undone. You can edit and delete your own personal skills. Editing and deleting workspace skills requires workspace admin access. System skills cannot be changed. ## Notes * A skill name must be unique within its scope: unique among your personal skills, unique within the workspace for workspace skills. * Instructions can be up to 8,000 characters. * Deactivating or deleting a skill removes it from the slash command list going forward; it does not affect past chats. --- --- url: 'https://docs.plane.so/ai/ai-usage.html' description: >- Monitor how much Plane AI your workspace and its members consume each month, view usage trends and breakdowns, and understand your monthly allowance and limits. --- # AI usage AI usage shows how much Plane AI your workspace consumes. It gives you a monthly meter, a usage trend over time, and a detailed breakdown of where AI is being used, so you can keep an eye on consumption and stay ahead of your monthly allowance. AI usage is read-only. It reports consumption, and it does not change any settings or data. ## Where to find it Open Plane AI and use the sidebar to reach two screens: * **Usage** shows your monthly meter and usage trend. * **Analytics** shows a detailed breakdown of consumption. ## Personal and workspace views Both screens have a **Personal** and a **Workspace** view: * **Personal** shows your own AI consumption. Any member can see this. * **Workspace** shows consumption across the whole workspace, including every member and any AI agents. Only **Admins** and **Owners** can see the Workspace view. ## The Usage screen **Monthly meter.** A meter shows how much of your monthly allowance has been used in the current period. On Plane Cloud this is shown as a **percentage** of your allowance. The meter can read above 100% because the limit is applied after a request completes, not partway through it. **Reset date.** Below the meter, Plane shows where you are in the current cycle (for example, the day within the month) and the date the allowance **resets**. Allowances reset monthly. **Usage trend.** A chart plots consumption over time. You can switch the interval between **Week** and **Month** and move between periods to see how usage is changing. On self-hosted deployments, usage is measured in **tokens** rather than a percentage, and the Usage screen also shows total **tokens in** and **tokens out**. ## The Analytics screen The Analytics screen breaks usage down so you can see exactly where AI is being spent. Choose a dimension to group by: * **Models** — which AI models were used * **Users** — consumption per member * **Agents** — consumption by AI agents * **Features** — which AI features were used (for example chat, page actions, or predictions) * **Projects** — consumption per project The breakdown is a table with the group's name, its **share of usage**, the **tokens used**, and the number of **requests**. The table is paginated, and you can **export** it to CSV for offline analysis. The Users, Agents, and Projects breakdowns are part of the Workspace view, so they require Admin or Owner access. ## Your monthly allowance and limits Each workspace has a monthly AI allowance that depends on your plan. Consumption counts against that allowance during the billing month and resets at the start of the next one. * **Nearing your limit.** When you reach about 80% of your allowance, Plane shows a warning so you can plan ahead. * **Reaching your limit.** When the allowance is used up, Plane AI features are **paused** for that subject (a member or the workspace's agents) until the next monthly reset. The request that crosses the limit still finishes; the next one is blocked. You will see a message that AI capabilities are temporarily disabled until the reset date. Because the limit is applied after a request rather than partway through, your meter can briefly show slightly over 100%. For how allowances are assigned per plan, what overage does, and how billing works, see [Plane AI credits](/ai/plane-ai-credits). ## Plane Cloud and self-hosted How usage is measured depends on where Plane runs: * **On Plane Cloud**, usage is shown as a **percentage** of a monthly allowance that scales with your plan. Members and AI agents each have their own allowance. * **On self-hosted deployments**, you connect your own AI provider, so **members are not metered**. Usage is reported in **tokens**, and only the shared pool used by AI agents is bounded, and only if your administrator has configured a token budget for it. If no agent budget is configured, agent features are unavailable rather than metered. ## Availability AI usage is part of **Plane AI** and appears only where Plane AI is enabled for your workspace. If Plane AI is not enabled, the Usage and Analytics screens are not available. See [Plane AI](/ai/plane-ai) for how to enable it. --- --- url: 'https://docs.plane.so/ai/plane-ai-credits.html' description: >- Understand how Plane AI credits work on Plane Cloud per-seat monthly allowances, what happens when they run out, workspace overage, and how to monitor usage. --- # Plane AI credits Plane AI credits measure how much Plane AI (Pi) your workspace uses on Plane Cloud. Your plan includes a monthly allowance, and AI features draw from it as your team uses them. To see how much of your allowance you have used, open the [AI usage](/ai/ai-usage) dashboard. It shows your consumption for the current month as a percentage of your allowance. ::: warning Credits apply only to Plane Cloud On self-hosted instances you connect your own AI provider [API key](https://developers.plane.so/self-hosting/govern/instance-admin#artificial-intelligence), so there are no Plane credits. All AI usage and costs are handled directly through your provider, and members are not metered by Plane. ::: ## How credits are assigned Credits are included with your plan and refresh every month. * Each active paid seat gets a monthly included allowance based on your plan. * The allowance is an entitlement tied to seats, so your total capacity scales with your team. * Allowances reset at the start of each monthly billing period. AI **agents** draw from a separate, workspace-level allowance rather than from any one member's. Automated agent activity does not consume a person's individual credits. For current included amounts by plan, see [Plane pricing](https://plane.so/pricing#ai-&-credits). ## Credits are not pooled by default Each member has their own monthly allowance. One member's unused credits are not automatically shared with the rest of the workspace. This keeps each person's available capacity predictable. ## What happens when credits run out As a member approaches their allowance, at around 80% used, Plane shows a warning so they can plan ahead. When the allowance is fully used for the month, what happens depends on whether workspace overage is enabled: * **Overage off (the default).** Plane AI features pause for that member until the allowance resets at the start of the next month. The request that reaches the limit still finishes, and the next one is paused. The member sees a message that AI is temporarily unavailable until the reset date. * **Overage on.** AI keeps working past the included allowance, and the additional usage is billed at the workspace level. The same applies to the workspace's agent allowance: agents pause when it is used up, unless overage is enabled. ## Workspace overage Overage is a workspace-level setting that keeps your team moving after included credits are used up. * When enabled, AI usage continues past the included allowance. * The additional usage is billed to the workspace. * Workspace admins decide whether to allow it, so cost stays in your control. If overage is off, AI pauses at the limit until credits reset or more capacity is added to the workspace. ## Monitor usage Track consumption from the [AI usage](/ai/ai-usage) dashboard: * A **monthly meter** shows how much of the allowance has been used, as a percentage. * A **usage trend** chart shows how consumption changes over time. * An **analytics breakdown** shows where AI is being used, by member, feature, project, model, and agent. Every member can see their own usage. Workspace admins and owners can also see workspace-wide usage. ## FAQs ::: details Are credits shared automatically across all users in my workspace? No. Credits are not pooled by default. Each member has their own monthly allowance. ::: ::: details Do I get credits for each seat? Yes. An included allowance is assigned per paid seat based on your plan. AI agents draw from a separate, workspace-level allowance. ::: ::: details Can we keep using AI after included credits are used up? Yes, if a workspace admin enables overage. Otherwise, AI pauses for that member until the allowance resets at the start of the next month. ::: ::: details How do I see how much AI we have used? Open the [AI usage](/ai/ai-usage) dashboard. It shows your usage as a percentage of your allowance, along with trends and a breakdown by member, feature, project, model, and agent. ::: ::: details Where can I see the latest included credit amounts? Visit [Plane pricing](https://plane.so/pricing#ai-&-credits) for the most up-to-date plan details. ::: --- --- url: 'https://docs.plane.so/ai/mcp-connectors.html' description: >- Connect GitHub, Sentry, Granola, and other tools to Plane AI using MCP connectors. Give the AI real-time context from your external services — no manual copy-paste required. --- # MCP connectors Plane AI works better when it has context beyond what's already in Plane. MCP connectors are how you give it that context. ::: info Looking for the other direction? MCP connectors bring external tools *into* Plane AI. To use Plane *from* Claude, ChatGPT, Cursor, or another AI tool, see [MCP server](/ai/mcp-server). ::: MCP stands for Model Context Protocol — an open standard for connecting AI models to external tools and data sources. When you connect Plane AI to an external service through an MCP connector, the AI can read and act on data from that service during a conversation. Connect your GitHub account and the AI can reference your pull requests and issues. Connect Sentry and it can pull in error data. Connect Granola and it can search your meeting notes. Each user connects to a connector independently using their own credentials. The connector is available to everyone in your workspace, but each person authenticates it with their own account. Your GitHub connection is yours — another workspace member needs to connect their own. Connectors are configured in **Workspace Settings → Integrations → Connectors** and used in Plane AI chat. *** ## Connect to a built-in connector ![Built-in connectors](https://media.docs.plane.so/mcp-connectors/built-in-mcp-connectors.webp#hero) 1. Go to **Workspace Settings → Integrations → Connectors**. 2. Find the connector you want to use. 3. Click **Connect**. 4. Follow the prompts for your connector's authentication method: * **OAuth connectors**: A browser window opens. Sign in and authorize access. Plane completes the connection automatically when you return. * **Header connectors**: A form appears. Enter your token or API key and click **Connect**. * **No-auth connectors**: Plane connects immediately. A **Connected** badge appears on the connector tile when authentication succeeds. ### How connection works Connecting to a connector authenticates you with the external service so Plane AI can access data on your behalf. The connection is per-user — no one else in the workspace shares your credentials or your connection state. Once you're connected, you can enable a connector for any Plane AI conversation. The AI can then call tools from that service as it works through your request. You stay in control of which connectors are active for each conversation. What happens when you connect depends on the connector's authentication method: #### No authentication The MCP server accepts requests without any credentials. Plane connects directly to the server URL. This is typically used for self-hosted MCP servers running inside a trusted network. #### Header authentication You provide one or more HTTP headers — usually an `Authorization: Bearer <token>` header — that Plane sends with every request to the MCP server. The connector form shows you the exact header fields required. For GitHub, this is a GitHub personal access token or GitHub Copilot token with the appropriate repository permissions. Your header values are encrypted before storage. Plane never exposes them after you save. #### OAuth Plane runs a standard OAuth 2.0 authorization flow with PKCE. You're redirected to the external service's login and authorization page, grant access, and are returned to Plane. Plane exchanges the authorization code for tokens and stores them securely. OAuth tokens are refreshed automatically in the background when they expire. You do not need to reconnect after a token expires. Your tokens are encrypted before storage. Plane never exposes them after the initial authorization. ### Disconnect from a connector 1. Go to **Workspace Settings → Integrations → Connectors**. 2. Find the connector you're connected to. 3. Click **Configure** and then **Disconnect**. Disconnecting removes your credentials from Plane. The connector itself stays available in the workspace — you can reconnect at any time. ### Use connectors in a Plane AI conversation Connectors are enabled per conversation. You choose which ones are active each time you start or continue a chat. ![Use connectors in Plane AI](https://media.docs.plane.so/mcp-connectors/use-connectors-in-plane-ai.webp#hero) 1. Open Plane AI and start a conversation in **Build** mode with a workspace context. 2. In the chat input bar, click the connectors pill. 3. Toggle on the connectors you want the AI to use for this conversation. The AI can now call tools from your connected services as it responds. If a connector you want to enable shows as not connected, go to Settings → Integrations → Connectors to connect it first. *Example: Granola in Plane AI* Once Granola is connected, Plane AI can pull meeting notes into conversations. This is useful when turning discussions into action items without manually searching notes. ![Granola example](https://media.docs.plane.so/mcp-connectors/granola-example.webp#hero) *** ## Create a custom connector Built-in connectors cover the most common integrations, but you can also add your own. If you run a service that exposes an MCP server, or if you use a tool that publishes an MCP endpoint that isn't in the marketplace, you can add it as a custom connector. Custom connectors you create are visible to other members of your workspace. 1. Go to **Workspace Settings → Integrations → Connectors**. 2. Click **Add connector**. 3. Fill in the fields: * **Name** (required) — a display name for the connector. * **MCP remote server URL** (required) — the full URL of the MCP server endpoint, e.g. `https://mcp.example.com/mcp`. * **Authentication type** (required) — choose None, Headers, or OAuth based on how your server expects to be called. * **Description** (optional) — a short description visible to other workspace members. * **Logo** (optional) — an icon for the connector tile. 4. Click **Add connector**. Plane attempts to reach the server and verify the connection. If it cannot connect, check that the URL is correct and publicly reachable. *** ## Managing custom connectors Only the person who created a custom connector can edit or delete it. Published marketplace connectors cannot be edited or deleted. ### Edit a custom connector 1. Go to **Workspace Settings → Integrations → Connectors**. 2. Find your custom connector and click **Configure**. 3. Update the name, URL, authentication type, description, or logo. 4. Save your changes. Changing the URL or authentication type of a connector invalidates existing connections. Anyone who was connected — including you — will need to reconnect. ### Delete a custom connector 1. Go to **Workspace Settings → Integrations → Connectors**. 2. Find your custom connector and click **Configure**. 3. Select **Delete Connector**. 4. Confirm deletion. Deleting a connector removes it from the workspace and disconnects all users who were connected to it. *** ## Available connectors These connectors are published in the Plane marketplace and available to all workspaces. | Connector | Authentication | What Plane AI can do with it | | ------------ | ------------------------------- | --------------------------------------------------------------------- | | **GitHub** | Headers (personal access token) | Read and manage repositories, issues, and pull requests; analyze code | | **Sentry** | OAuth | Access error events, logs, and performance data | | **Granola** | OAuth | Search meeting notes and transcripts | | **Postman** | OAuth | Create and manage API collections | | **PostHog** | OAuth | Query product analytics data | | **Evermuse** | OAuth | Process customer calls and extract insights | | **Intercom** | Headers (API token) | Access customer conversations and support data | You can also add custom connectors for any service that publishes an MCP endpoint. --- --- url: 'https://docs.plane.so/ai/mcp-server.html' description: >- Connect Claude, ChatGPT, Cursor, VS Code, and other AI tools to your Plane workspace with the hosted MCP server. Create and update work items, plan cycles, and query projects in natural language. --- # MCP server Use Plane from the AI tool you already work in. The Plane MCP server exposes your workspace to any client that speaks the Model Context Protocol, so you can create work items, plan cycles, and query projects in natural language. ::: tip Hosted server `https://mcp.plane.so/http/mcp` Paste this URL into your AI tool and sign in with your Plane account. No install, no API key. ::: ::: info Which MCP integration do I need? The MCP server connects your AI tools → Plane. [MCP connectors](/ai/mcp-connectors) connect Plane AI → other tools. ::: ::: warning Self-hosted Plane The hosted server only reaches Plane Cloud. For a self-hosted instance, use local mode or [run your own server](https://developers.plane.so/dev-tools/mcp-server#self-hosted-plane). ::: ## How it works 1. Connect once with OAuth. Your AI tool opens Plane's sign-in page, where you choose a workspace. 2. Your AI tool discovers what it can do in Plane, including working with work items, cycles, and projects. 3. It reads and writes as you, within your workspace and project roles. The server talks to Plane's API directly. It does not use Plane AI or Plane AI credits; the AI model belongs to your client. ## What you can do * Create, update, and search work items; comment, attach files, add links and relationships, create sub-items and epics, and log time. * Plan cycles, modules, and milestones; move unfinished work and track progress. * Manage projects, states, labels, work item types, and custom properties. * Organize projects into initiatives. * Plan releases and write changelogs. * Track customers and their requests. * Create and attach pages. * Triage intake submissions. Filter with [Plane Query Language](/core-concepts/issues/plane-query-language) — for example, find everything assigned to you that is overdue. Features that are not on your plan, such as time tracking, work item types, or custom properties, return a clear "not available on your plan" message instead of failing. ## Prerequisites * A Plane Cloud account and a workspace where you are a Member or Admin. * An AI tool that supports remote MCP. Every client below does. ## Connect your AI tool Every client below connects with OAuth to `https://mcp.plane.so/http/mcp`. Need an access token, a local server, or a self-hosted instance? See the [full setup guide](https://developers.plane.so/dev-tools/mcp-server#connect-a-client). ### Claude These steps work in Claude Desktop and on claude.ai. Free plans allow one custom connector. 1. Open **Settings → Connectors → Add custom connector**. 2. Paste `https://mcp.plane.so/http/mcp`, then select **Add → Connect**. 3. Sign in to Plane and choose your workspace. 4. In a chat, select **+ → Connectors** and enable Plane. On Team and Enterprise plans, an Owner first adds Plane under **Organization settings → Connectors**. Members can then select **Connect**. ### Claude Code Add the hosted server, then authenticate from a Claude Code session: ```bash claude mcp add --transport http plane https://mcp.plane.so/http/mcp ``` Run `/mcp` in the session and follow the authentication prompt. You can also run `claude mcp login plane`. ### ChatGPT ChatGPT supports custom connectors on Plus, Pro, Business, Enterprise, and Edu plans. The exact menu names may differ by workspace. 1. Open **Settings → Security and login** and turn on **Developer mode**. On Business, Enterprise, and Edu, a workspace admin must allow it. 2. Go to [chatgpt.com/plugins](https://chatgpt.com/plugins), select **+**, name the connector "Plane", and enter `https://mcp.plane.so/http/mcp` under **Connection**. Create it and sign in to Plane. 3. In a chat, open **+ → Developer mode** and enable Plane. ### Codex Codex CLI, the IDE extension, and the ChatGPT desktop app share the same connection: ```bash codex mcp add plane --url https://mcp.plane.so/http/mcp codex mcp login plane ``` Run `codex mcp list` or `/mcp` inside Codex to verify the connection. ### Cursor **[Install Plane in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=plane\&config=eyJ1cmwiOiJodHRwczovL21jcC5wbGFuZS5zby9odHRwL21jcCJ9)** — a one-click install link that opens Cursor with the server pre-filled. Cursor opens an OAuth prompt after installation. You can manage the server from Cursor's **Customize** page. As a fallback, add this to `~/.cursor/mcp.json` for all projects or `.cursor/mcp.json` for one project: ```json { "mcpServers": { "plane": { "url": "https://mcp.plane.so/http/mcp" } } } ``` ### VS Code Use a one-click installer: * [Install Plane in VS Code](https://vscode.dev/redirect/mcp/install?name=plane\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.plane.so%2Fhttp%2Fmcp%22%7D) * [Install Plane in VS Code Insiders](https://insiders.vscode.dev/redirect/mcp/install?name=plane\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.plane.so%2Fhttp%2Fmcp%22%7D\&quality=insiders) Trust the server when prompted, then complete OAuth in your browser. Verify it with **MCP: List Servers** and use Plane from Copilot Chat in **Agent** mode. Copilot Business and Enterprise organizations must enable the **MCP servers in Copilot** policy. ### Windsurf In Windsurf (now Devin Desktop), add Plane to `~/.codeium/windsurf/mcp_config.json`, then open the Cascade panel and select **MCPs → Manage MCPs** to refresh: ```json { "mcpServers": { "plane": { "serverUrl": "https://mcp.plane.so/http/mcp" } } } ``` If the OAuth sign-in does not complete, use the [access-token configuration](https://developers.plane.so/dev-tools/mcp-server#windsurf) instead. ### Zed In Zed, open **Settings → AI → MCP Servers → Add Server**, or add Plane to `~/.config/zed/settings.json`: ```json { "context_servers": { "plane": { "url": "https://mcp.plane.so/http/mcp" } } } ``` Choose **Add Remote Server** if you use the UI. Zed prompts you to sign in with OAuth. ### Antigravity Add Plane to `~/.gemini/config/mcp_config.json` for every workspace, or `.agents/mcp_config.json` for one workspace: ```json { "mcpServers": { "plane": { "serverUrl": "https://mcp.plane.so/http/mcp" } } } ``` In the IDE, select **… → MCP Servers → Manage MCP Servers** from the agent panel. Antigravity 2.0 uses **Settings → Customizations → Installed MCP Servers → Add MCP**. OAuth starts automatically. ### Other clients Any client with native remote-MCP support only needs the hosted URL. A stdio-only client can bridge to it with mcp-remote; see [Other clients in the full setup guide](https://developers.plane.so/dev-tools/mcp-server#other-clients). ## Example prompts **What's on my plate** ```text List work items assigned to me that are in progress or overdue, grouped by project. ``` **File a bug** ```text Create a high-priority bug in ENG called "Login times out on Safari 17". Description: the OAuth callback lands on a blank page. Assign it to me and add the "auth" label. ``` **Catch up on a work item** ```text Summarize what changed on ENG-42 this week: comments, state changes, and who is assigned now. ``` **Roll over a sprint** ```text Create Sprint 15 in ENG from June 2 to June 15, move everything unfinished from Sprint 14 into it, and give me a count by priority. ``` **Break down an epic** ```text Break the "Checkout redesign" epic in WEB into five sub-items with clear titles and acceptance criteria, then add them to the current cycle. ``` **Check an initiative** ```text Which projects under the "Q3 platform reliability" initiative still have overdue work items? Show counts per project. ``` **Close the loop** ```text Log 90 minutes on ENG-42 with the note "Implemented retry logic", mark it Done, and comment "Fixed in abc1234, needs QA". ``` **Cut a release** ```text Create release v1.8.0 with a release tag v1.8.0, add ENG-40 through ENG-45 to it, and draft the changelog from those items. ``` ## Permissions and security * The server acts as you. Your workspace and project roles apply to every read and write. * One connection is bound to one workspace. Reconnect to switch workspaces. * Disconnect from your AI tool's connector settings. If you used a token, revoke it under **Profile settings → Personal Access Tokens** or **Workspace settings → Access Tokens**. * Treat anything your AI reads from Plane — including titles, descriptions, comments, and attachments — as untrusted input to the model. Prefer clients that ask before writing. See the [security best practices](https://developers.plane.so/dev-tools/mcp-server#security-best-practices) for token storage, least privilege, and administrative controls. ## FAQ ::: details Is it free? The server is open source and free to use. What you can do follows your Plane plan. ::: ::: details Does it work with self-hosted Plane? Yes. Use local mode or [run your own server](https://developers.plane.so/dev-tools/mcp-server-self-host) so it can reach your instance. ::: ::: details Does it use Plane AI credits? No. The server calls Plane's API directly. The AI model and its usage belong to your MCP client. ::: ::: details How is this different from Plane AI and MCP connectors? Plane AI is the AI built into Plane. MCP connectors let Plane AI use other services, while the MCP server lets external AI tools use Plane. ::: ::: details Can I use several workspaces? One connection is bound to one workspace. Reconnect and choose another workspace when you need to switch. ::: ::: details How do I disconnect? Disconnect Plane from your AI tool's connector settings. If you connected with a token, revoke it under **Profile settings → Personal Access Tokens** or **Workspace settings → Access Tokens**. ::: ## Go further --- --- url: 'https://docs.plane.so/devices/mobile.html' description: Learn how to use Plane's mobile app for iOS and Android. --- # Plane Mobile App The Plane mobile app puts your work in your pocket. Create and update work items, comment and mention teammates, track cycles, and stay on top of notifications from your phone. It is available for iOS and Android, and works alongside the web app: anything you change on mobile syncs to the web and everywhere else you use Plane. This page covers what is specific to mobile: getting the app, signing in, finding your way around, and managing notifications. ## System requirements | Platform | Minimum version | | -------- | ----------------------------- | | iOS | iOS 14.0 or later | | Android | Android 10 or later (SDK 29+) | **Editions and plans** * Available on **Plane Cloud** and **self-hosted Commercial Edition** (from version `v1.12.0`). * Supported on **all plans, including Free**. ## Download and install Head over to [Download](https://plane.so/download) to install the app for Android or iOS. Once installed, open the app and sign in to your workspace. ## Sign in You can sign in to the mobile app with the same credentials you use on the web. Here’s how you can get started: * **For cloud users**\ Tap **Cloud sign in** and enter your credentials to log in. * **For self-Hosted users**\ Tap **Self hosted sign in**, then enter your Plane app URL. Once that’s done, log in with your credentials to access your workspace. ## Switching workspaces To switch between different workspaces, simply tap your workspace icon in the top left corner on the Home page and switch between them from the workspace switcher. Your data, projects, and notifications update to reflect the selected workspace. The app is built around a bottom bar with three tabs and a floating **+** create button. ## Get around the app ### The three tabs * **Home** - your starting point for the workspace. * **Inbox** - your notification center, with an unread badge. * **Search** - search across the workspace for projects, work items, cycles, modules, pages, and more. ### Create Tap the floating **+ Create** button to add new content from anywhere. Depending on your role and enabled features, you can create a project, work item, a page, or a sticky. ### Home Home mirrors the web and is organized into sections you can rearrange or hide (tap Manage widgets icon next to your profile to customize). At the top of Home is a row of quick-access tiles for Plane's products, mirroring the web. Tap a tile to open that product. * **Projects** - always available. Your projects and everything inside them: work items, cycles, modules, and pages. This is where most of your day-to-day work happens. * **Wiki** - your workspace's knowledge base of pages, kept separate from any single project. Appears when Wiki is enabled and you have permission to edit. * **Plane AI** - the Pi assistant, for chatting, asking questions about your work, and picking up your AI threads. Appears when AI is enabled for your workspace. Below the tiles are sections you can rearrange or hide. * Your work - assigned work items and pages you have created * Recent activity - projects, cycles, modules, pages, and work items you've opened recently * Favorites - the projects and items you've starred * Stickies - your quick notes (when enabled) The Home header also holds the workspace switcher and a catch-up card. ### Gestures * Pull down to refresh a list or screen. * Tap a work item to open its detail view. * Swipe on some list items for quick actions. * Long-press and drag to reorder items where supported. ### Appearance The app supports Light, Dark, and System themes. System follows your device's appearance setting automatically. ## Work on the go The mobile app supports the core of your day-to-day work. Each area links to its full documentation. ### Work items Create work items and edit their properties. Open a work item to manage its sub-work items, links, attachments, and more. See [Work items](/core-concepts/issues/overview). ### Comments and mentions Comment on any work item and @mention teammates to notify them. React to comments. Comments and mentions sync across web and mobile. See [Comments and mentions](/communication-and-collaboration/comments-and-activity). ### Cycles and modules View cycles and modules, open them to see their work items, and add or move work items between them. See [Cycles](/core-concepts/cycles) and [Modules](/core-concepts/modules). ### Pages Read and edit pages in the mobile editor, with rich-text formatting, images, and more. See [Pages](/core-concepts/pages/overview). ### Intake Review and manage incoming work items from intake. See [Intake](/intake/overview). ## Notifications Notifications are where the mobile app is especially useful, letting you respond to what needs your attention without opening your laptop. ### Push notifications ::: info Push notifications are currently available only for Plane Cloud users. ::: The app sends push notifications for events that involve you, such as new assignments, comments, and mentions on work items, epics, and intake items. Notifications appear on your device's lock screen and update your app badge count. Push notifications are delivered through your device's native system (Apple Push Notification service on iOS, Firebase Cloud Messaging on Android). To receive them, allow notifications for Plane when the app first asks, or enable them later in your device settings. ### Managing notification preferences Control which notifications you receive from your notification settings in the app. Adjust these to reduce noise or focus only on what matters most to you. ### The Inbox Open the Inbox tab to read notifications and tap to jump to the item; mark as read and filter your inbox (e.g. unread, snoozed, or archived only). Your inbox stays in sync across mobile and web. Your notification inbox stays in sync across mobile and web. See [Notifications](/communication-and-collaboration/notifications). ## Home-screen widgets and shortcuts On iOS/iPadOS, add Plane widgets for one-tap capture: Create Work Item and Create Page. You can also long-press the app icon for Quick Actions. :::info Home-screen widgets are not available on Android yet, but coming soon. We'll also be adding more widgets. ::: ## What's different on mobile The mobile app focuses on the work you are most likely to do away from your desk. Some capabilities available on the web are not present on mobile, or work differently. Feature availability also depends on your plan. Features such as Wiki and AI capabilities appear in the app only when they are enabled for your workspace. ## Privacy and security * Privacy Screen - blurs the app's contents in the app switcher and background so sensitive work isn't visible in previews. Enable it in your Profile settings. * Device integrity - Plane doesn't run on jailbroken or rooted devices. * Secure storage - all sensitive data is securely stored using the Android Keystore and iOS Keychain. ## Offline and syncing The app caches recently viewed data so those screens load quickly and stay viewable when your connection drops. Editing requires a connection - there is no offline edit queue. When back online, pull to refresh to sync. ## Troubleshooting ### Unable to log in to the mobile app This error occurs when attempting to log in to the mobile app with a self-hosted URL on the Community Edition or an outdated version of the Commercial Edition. * Ensure your Plane instance is running the Commercial Edition version `v1.5.0` or higher. If you are using an older version, [update to the latest version](https://developers.plane.so/self-hosting/manage/upgrade-plane#prerequisites). * If you are on the Community Edition, [upgrade to the Commercial Edition](https://developers.plane.so/self-hosting/upgrade-from-community) to access mobile app functionality. * Retry logging in and ensure the self-hosted URL is entered correctly in the app. ### Sign-in issues on Android If you're having trouble signing into the Plane app on your Android device, here are a few steps you can follow to get things working: **Sign-in button doesn’t open the app?**\ Make sure you have a browser (like Chrome, Firefox, or Edge) installed on your phone. **App still not opening, even with a browser installed?** 1. Check which profile the Plane app is installed under - Personal or Work. 2. Make sure the browser is also installed in the same profile. **Browser opens, but sign-in keeps looping?**\ This might be due to default browser settings. Try the following: 1. Open your device’s **Settings**. 2. Go to **Apps** or **Default Apps**. 3. Find and tap on the browser you're using. 4. Look for an option like **Clear defaults** or **Reset default app** 5. Clear the defaults, then try signing in again. You’ll be prompted to choose a browser. Choose one that's in the same profile as the Plane app. **Still stuck?**\ Try clearing site data: 1. When the web sign-in page opens, tap the three-dot menu (usually in the top-right corner of the browser). 2. Go to **Settings → Site settings → Clear data** (wording may vary slightly by browser). 3. Try the sign-in process again. ### Unable to log in using SSO Ensure the correct Redirect URI is configured in your OAuth service: * For Google Sign-In: Add the following URL to the Redirect URIs section in your Google Cloud Console: ```bash https://<plane.example.com>/auth/mobile/google/callback/ ``` * For GitHub Sign-In: Add the following URL to the Callback URL section in your GitHub OAuth app: ```bash https://<plane.example.com>/auth/mobile/github/callback/ ``` Verify that the `<plane.example.com>` part of the URL matches your self-hosted instance's domain. ### Link not opening iOS app If clicking links doesn't open the Plane iOS app and instead redirects to your browser, this is usually related to how iOS handles Universal Links. **Why this happens** 1. Your default browser may not be Safari. 2. You may have previously opened the web app (`https://app.plane.so`) in your browser, causing iOS to associate the domain with the browser instead of the app. **How to fix it** 1. Open the link in Safari. 2. A banner will appear at the top that says **Open** and stays for about a second. 3. Tap **Open** before the banner disappears to launch the Plane app. 4. Try clicking the link from any other app to verify that it now opens the Plane app directly. --- --- url: 'https://docs.plane.so/devices/desktop.html' description: >- Install and use the Plane desktop app for macOS, Windows, and Linux, including connecting to your instance, working in tabs and windows, notifications, and updates. --- # Plane Desktop App The Plane desktop app is a dedicated application for macOS and Linux. ![Desktop app](https://media.docs.plane.so/desktop/desktop-app.webp#hero) It runs Plane in its own window, separate from your browser, with desktop conveniences like browser-style tabs, multiple windows, an unread notification badge on your dock or taskbar, deep links, and automatic updates. The desktop app loads the full Plane web app, so everything you can do on the web you can do in the desktop app. This page covers what is specific to desktop: installing it, connecting to your instance, working with tabs and windows, and keeping the app updated. For how individual features work, follow the links to their full documentation. ## System requirements The desktop app runs on anything Electron 41 supports * **macOS** 12 or later * **Linux** — modern 64-bit distributions (Ubuntu 18.04+ or equivalent) To connect to a self-managed deployment, the instance must be on **Plane Commercial v3.0.0 or later**. Earlier versions do not support the desktop app. ## Download and install 1. Go to the [Plane download page](https://plane.so/download). 2. Download the build for your operating system. 3. Open the downloaded file and follow your operating system's install steps. 4. Launch Plane. The desktop app updates itself automatically. See [Automatic updates and What's New](#automatic-updates-and-whats-new). ## Connect to your instance The first time you open the app, you see a **Welcome to Plane** screen asking how you want to connect. This lets the same app work with Plane Cloud or a self-managed deployment. ![Connect to your instance](https://media.docs.plane.so/desktop/connect-to-your-instance.webp#hero) ### Cloud Click **Cloud** and enter your credentials to log in. ### Self-managed Click **Self-managed**, then enter your instance URL and click **Connect**. The app verifies the address before loading it. If the URL is empty, not a valid URL, or not a Plane instance, the app tells you so you can correct it. The app remembers your instance, so you go straight to it on future launches. To connect somewhere else later, use **Help → Change instance** (see [Switch instance or reset the app](#switch-instance-or-reset-the-app)). ## Sign in After connecting to an instance, you land on its sign-in page. Enter your email to begin. Depending on how the instance is configured, you then either enter a password or a magic code sent to your email. Any enabled OAuth providers (Google, GitHub, GitLab, Gitea) appear as buttons as well. When you sign in with an OAuth provider, authentication opens in your system's default web browser. Complete it there, and the browser returns you to the desktop app automatically. ### Signing in to a self-managed instance A few things are specific to self-managed deployments. * **Available sign-in methods depend on your instance.** Your administrator chooses which methods are enabled. The sign-in page only shows the ones they have turned on. * **SAML, OIDC, and LDAP are not yet available in the desktop app.** Even if your instance uses one of these, the desktop app supports only email and password, magic code, and the OAuth providers listed above. If your organization signs in exclusively through SAML, OIDC, or LDAP, use the Plane web app in a browser instead. * **Magic code requires email to be configured.** If your instance has magic code sign-in enabled but no email (SMTP) set up, the code cannot be sent. Use another method or contact your administrator. * **If you see "No authentication methods available,"** your administrator has not enabled any sign-in method yet. Contact them. * **If the instance has not been set up yet,** you see a "Welcome to Plane" setup screen instead of a sign-in page. The first administrator must complete instance setup before anyone can sign in. #### Configure OAuth for desktop If your instance uses Google, GitHub, GitLab, or Gitea for sign-in, an administrator must register the desktop callback URIs in each OAuth app before those buttons will work in the desktop app. Configure them in **God Mode → Authentication →** the relevant provider **→ Desktop** section. Add the following callback URIs, using your instance URL as the origin: * `/auth/desktop/google/callback/` * `/auth/desktop/github/callback/` * `/auth/desktop/gitlab/callback/` * `/auth/desktop/gitea/callback/` ## Tabs and windows The desktop app works like a browser, so you can keep several parts of Plane open at once. ### Tabs * **Open a new tab** with the **+** button at the end of the tab bar, or **New tab** (Cmd/Ctrl+T). * **Close a tab** with the **X** on the tab, or **Close tab** (Cmd/Ctrl+W). You cannot close the last remaining tab in a window. * **Reorder tabs** by dragging them along the tab bar. * **Go back and forward** Ctrl+Tab / Ctrl+Shift+Tab for next/previous tab. * **Right-click a tab** for quick actions: Copy link, Reload tab, Close tab, Close other tabs, and Close all tabs. * **Jump to a tab** with Cmd/Ctrl+1 through Cmd/Ctrl+8, or Cmd/Ctrl+9 for the last tab. * **Reopen a closed tab** with Cmd/Ctrl+Shift+T. ### Windows Open a new window with **File → New window** (Cmd/Ctrl+N). Each window has its own tabs and history, which is useful across multiple monitors. Your open windows and tabs are remembered between sessions and restored the next time you launch the app. ## Notifications The desktop app shows a badge with your unread notification count on the app icon: on the dock on macOS, and on the taskbar on Windows and Linux. This lets you see when something needs your attention without switching to the app. For how notifications work in Plane, see [Notifications](/communication-and-collaboration/notifications). ## Menus and keyboard shortcuts The app has a full menu bar. The most useful items for everyday work: | Menu | Item | Shortcut | | ---- | --------------------------- | ------------------------------------ | | File | New window | Cmd/Ctrl+N | | Tab | New tab | Cmd/Ctrl+T | | Tab | Close tab | Cmd/Ctrl+W | | Tab | Reopen closed tab | Cmd/Ctrl+Shift+T | | Tab | Reload tab | Cmd/Ctrl+R | | Tab | Next / previous tab | Ctrl+Tab / Ctrl+Shift+Tab | | View | Zoom in / out / actual size | Cmd/Ctrl++ / Cmd/Ctrl+- / Cmd/Ctrl+0 | | View | Toggle full screen | F11 (or Cmd+Control+F on macOS) | | Help | What's new | | | Help | Documentation | | | Help | Change instance | | ## Switch instance or reset the app Both actions are in the **Help** menu. **Change instance** clears the stored instance address and returns you to the Welcome screen so you can connect to a different Plane Cloud or self-managed instance. **Clear stored data** is a full reset. It removes your saved instance settings, windows, tabs, and signed-in session, then restarts the app. The app asks you to confirm first. Use this if the app gets into a bad state. ## Automatic updates and What's New The desktop app keeps itself up to date automatically. When a compatible update is available, it downloads in the background, and you are notified when it is ready with the option to restart now or later. Restarting applies the update. You can also check manually: **Check for updates** is in the Plane menu on macOS, and in the **Help** menu on Windows and Linux. After an update, the app shows a **What's New** screen the first time you open the new version, summarizing highlights, enhancements, and fixes. Dismiss it with **Got it** or the Escape key. You can reopen it anytime from **Help → What's New**. ### Compatibility The desktop app checks that its version works with the instance you connect to. If your app is too old for the instance, it updates itself before continuing. If the instance is older than your app supports, the app either switches to a compatible version or asks for the instance to be upgraded. This keeps the app and your instance in sync so nothing breaks mid-session. ## Deep links The desktop app registers the `plane://` link scheme. Plane links that use it open directly in the desktop app and navigate to the right place on your connected instance. If the app is closed or minimized when you open a link, it launches or comes to the front. ## What's different from the web Because the desktop app loads the full Plane web app, feature parity with the web is effectively complete. What the desktop app adds on top is the desktop experience itself: * A dedicated app window, separate from your browser * Tab bar icons reflect the current page/context so open tabs are easier to tell apart. * Browser-style tabs and multiple windows, remembered between sessions * An unread notification badge on your dock or taskbar * `plane://` deep links that open in the app * Automatic updates * The ability to connect to Plane Cloud or a self-managed instance from the same app The app does not have a separate settings panel. Desktop-level actions live in the menu bar (zoom, full screen, change instance, clear data); everything else is the Plane app you already know. --- --- url: 'https://docs.plane.so/support/get-help.html' description: >- Find support for Plane through in-app chat, email, community forum, and developer resources. Report bugs, request features, and get answers to your questions. --- # Get help Need assistance with Plane? We're here to help you get unstuck and make the most of your workspace. ## Chat with us The fastest way to get help is through our in-app support chat. ![Get help](https://media.docs.plane.so/support/get-help-plane.webp#hero-bl) Click the **?** icon in your Plane workspace to start a conversation with our team. We're available to answer questions, troubleshoot issues, and guide you through features. ## Join our community Connect with other Plane users, share tips, and get community support on the [Plane Forum](https://forum.plane.so). It's a great place to see how others are using Plane, get quick answers, and stay updated on what's new. ## Email support Prefer email? Reach us at <support@plane.so>. We'll get back to you as soon as possible with answers to your questions. ## Developer resources Working with Plane's API or self-hosting? Check out our [developer documentation](https://developers.plane.so/self-hosting/overview) for technical guides, API references, and self-hosting instructions. ## Report bugs Found a bug? Help us improve Plane by reporting it on [GitHub Issues](https://github.com/makeplane/plane/issues). Please include details about what happened, what you expected, and steps to reproduce the issue. ## Improve these docs Notice something unclear or missing in our documentation? Let us know on the [docs GitHub repository](https://github.com/makeplane/docs). Your feedback helps us create better resources for everyone. --- --- url: 'https://docs.plane.so/support/keyboard-shortcuts.html' description: >- Complete list of keyboard shortcuts in Plane. Speed up your workflow with shortcuts for work items, navigation, cycles, modules, pages, and more. Press Cmd+/ to access anytime. --- # Keyboard shortcuts Speed up your workflow in Plane with keyboard shortcuts. Access this list anytime by pressing `Cmd + /` (Mac) or `Ctrl + /` (Windows/Linux). ## Work item actions | Action | Shortcut | | -------------------------- | ----------- | | Change state | `S` | | Change priority | `P` | | Assign to | `A` | | Assign to me | `I` | | Change estimate | `⌘ + E` | | Add to cycle | `⌘ + C` | | Add to modules | `⌘ + M` | | Add labels | `L` | | Subscribe to notifications | `⌘ + S` | | Delete | `⌘ + ⌫` | | Copy ID | `⌘ + .` | | Copy title | `⌘ + ⇧ + '` | | Copy URL | `⌘ + ⇧ + ,` | ## Cycle actions | Action | Shortcut | | ---------------- | ----------- | | Add to favorites | `⌘ + F` | | Copy URL | `⌘ + ⇧ + ,` | ## Module actions | Action | Shortcut | | ------------------ | ----------- | | Add/remove members | `M` | | Change status | `S` | | Add to favorites | `⌘ + F` | | Copy URL | `⌘ + ⇧ + ,` | ## Page actions | Action | Shortcut | | ---------------- | ----------- | | Lock | `⌘ + L` | | Make public | `⌘ + A` | | Archive | `⌘ + R` | | Add to favorites | `⌘ + F` | | Copy URL | `⌘ + ⇧ + ,` | ## Initiative actions | Action | Shortcut | | ------------ | ----------- | | Change state | `S` | | Change lead | `L` | | Copy URL | `⌘ + ⇧ + ,` | ## Create | Action | Shortcut | | -------------- | ------------ | | New work item | `N` then `I` | | New page | `N` then `D` | | New view | `N` then `V` | | New cycle | `N` then `C` | | New module | `N` then `M` | | New project | `N` then `P` | | New teamspace | `N` then `T` | | New initiative | `N` then `N` | | New dashboard | `N` then `B` | | New customer | `N` then `U` | ## Navigate | Action | Shortcut | | ------------------------- | ------------ | | Open a cycle | `O` then `C` | | Open a module | `O` then `M` | | Open a project view | `O` then `V` | | Open a project setting | `O` then `S` | | Open a project | `O` then `P` | | Open a teamspace | `O` then `T` | | Open an initiative | `O` then `N` | | Open a customer record | `O` then `U` | | Open a workspace setting | `O` then `S` | | Open a workspace | `O` then `W` | | Go to home | `G` then `H` | | Go to inbox | `G` then `X` | | Go to your work | `G` then `Y` | | Go to work items | `G` then `I` | | Go to pages | `G` then `D` | | Go to cycles | `G` then `C` | | Go to modules | `G` then `M` | | Go to project views | `G` then `V` | | Go to intake | `G` then `K` | | Go to project settings | `G` then `S` | | Go to project archives | `G` then `R` | | Go to workspace analytics | `G` then `A` | | Go to workspace settings | `G` then `S` | | Go to workspace drafts | `G` then `J` | | Go to workspace archives | `G` then `R` | | Go to teamspaces | `G` then `T` | | Go to initiatives | `G` then `N` | | Go to dashboards | `G` then `B` | | Go to customer records | `G` then `U` | | Go to projects list | `G` then `P` | ## Miscellaneous | Action | Shortcut | | ----------------------- | ----------- | | Toggle app sidebar | `⌘ + B` | | Copy current page URL | `⌘ + ⇧ + C` | | Open keyboard shortcuts | `⌘ + /` | *** **Note:** `⌘` represents Command on Mac and Ctrl on Windows/Linux. `⇧` represents Shift, and `⌫` represents Delete/Backspace.