> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Plane

> Connect a Plane workspace so Gitar can read and update work items

export const ThemeImage = ({src, alt, width}) => {
  let lightSrc, darkSrc;
  if (src.includes("-light.")) {
    lightSrc = src;
    darkSrc = src.replace("-light.", "-dark.");
  } else if (src.includes("-dark.")) {
    darkSrc = src;
    lightSrc = src.replace("-dark.", "-light.");
  } else {
    lightSrc = src;
    darkSrc = src;
  }
  const style = width ? {
    maxWidth: width,
    marginInline: "auto"
  } : undefined;
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} style={style} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} style={style} />
    </span>;
};

## Overview

The Gitar Plane integration connects a [Plane](https://plane.so) workspace, Cloud or self-hosted, to your pull requests. Gitar reads work items, creates and updates them, comments, and moves them between states.

<Note>
  Plane Cloud and self-hosted both work. On Cloud, enter `https://app.plane.so` as the base URL.
</Note>

<CardGroup cols={2}>
  <Card title="Read Linked Work Items" icon="link">
    Resolve a `PROJ-123` reference from a PR title, description, or branch name
  </Card>

  <Card title="Validate Against the Issue" icon="list-check">
    Judge a PR against the objectives its work item asks for
  </Card>

  <Card title="Create and Update" icon="plus-circle">
    Open follow-up work items and update existing ones from a rule
  </Card>

  <Card title="Comment and Transition" icon="message-square">
    Post back to a work item and move it to a new state
  </Card>
</CardGroup>

## Before you start

On Plane Cloud there is nothing to check: enter `https://app.plane.so` and skip to [Connect Plane](#connect-plane).

Self-hosted, check your instance against three requirements:

* **Version v0.28.0 or later.** Earlier versions have no route for looking up a work item by its display key, which is how Gitar resolves `PROJ-123`.
* **HTTPS on port 443 with a publicly trusted certificate.** A self-signed certificate does not work.
* **Reachable from Gitar.** If you enforce an inbound allowlist, add Gitar's egress IP addresses.

Plane needs no outbound access to Gitar. No webhook is registered, so traffic runs one direction: Gitar reaching your instance on 443.

## Connect Plane

<Steps>
  <Step title="Create a service account">
    Gitar acts as a dedicated user, so its activity stays attributable and survives staff changes.

    1. Create a Plane user account named `gitar-service`
    2. Invite it to the workspace Gitar should read
  </Step>

  <Step title="Add the account to your projects">
    Plane scopes access by project membership rather than by token, so Gitar reaches only the projects you add the account to.

    1. Open each project Gitar should work with
    2. Add `gitar-service` as a **Member**

    **Member** is the minimum role that permits writes: commenting, creating, updating, and transitioning. Use **Guest** for read-only access.
  </Step>

  <Step title="Generate an API token">
    1. Sign in as `gitar-service`
    2. Go to **Workspace Settings** → **API tokens**
    3. Click **Add API token** and name it `gitar`
    4. Copy the token

    Plane shows the token once. Record its expiry date so you can rotate it before it lapses.
  </Step>

  <Step title="Raise the API rate limit (self-hosted only)">
    Plane throttles each API token at `60/minute` by default, which is low for an organization with several active repositories. The budget is per token, so every Gitar run in your organization shares it. On Plane Cloud this cap is fixed - skip this step.

    1. Set `API_KEY_RATE_LIMIT=600/minute` in your Plane environment
    2. Restart the `api` container

    Restart the container even if you only edited the environment. Plane reads the rate at startup.
  </Step>

  <Step title="Connect Plane in Gitar">
    1. Go to your organization's **Settings** in the Gitar dashboard
    2. Open the **Integrations** section
    3. Find the **Plane** card under **Ticketing & Documentation** and click **Connect**

    <ThemeImage src="/assets/images/integrations/plane-connect-light.png" alt="Plane connection dialog in Gitar settings, with fields for base URL, workspace slug, and API token" />

    Enter the three values, then click **Connect**.

    | Field           | Value                                                         | Example                                 |
    | --------------- | ------------------------------------------------------------- | --------------------------------------- |
    | Plane Base URL  | Your instance, HTTPS only, or `https://app.plane.so` on Cloud | `https://plane.your-company.com`        |
    | Workspace Slug  | The slug in your Plane URL                                    | `acme` for `https://app.plane.so/acme/` |
    | Plane API Token | The token you copied earlier                                  | `plane_api_...`                         |
  </Step>
</Steps>

## Using Plane in rules

Ask for Plane by name in a custom rule and the agent picks it up. Gitar can look up a work item by key, search, list a project, create, update, comment, and transition. See [Rules](/features/rules) for how to write one.

Gitar also reads Plane work items for [functional validation](/features/functional-validation), which checks a PR against the objectives its work item asks for. That needs no rule.

## Frequently asked questions

### Does this work with Plane Cloud?

Yes. Enter `https://app.plane.so` as the base URL and mint the API token the same way, under workspace settings. Cloud caps API calls at 60 per minute per token with no override, where a self-hosted admin can raise the limit.

### Can I give Gitar read-only access?

Yes. Add `gitar-service` to your projects as a **Guest** instead of a Member. Gitar reads work items and every write fails, which is enough for functional validation.

### Which projects can Gitar see?

Only the projects `gitar-service` belongs to. A Plane API token reaches every workspace its user can access, so project membership is what limits Gitar. Add the account to a single project to scope Gitar to it.

### Can I use Plane alongside Jira or Linear?

Connect one ticket tracker per organization. A key like `PROJ-123` looks identical across all three, so Gitar cannot tell which tracker it belongs to. Jira takes precedence over Linear, and Linear over Plane. Disconnect the other tracker before connecting Plane.

### What happens when my token expires?

Gitar's Plane calls start failing. Generate a new token in Plane, then update it under **Settings** → **Integrations** → **Plane**.

### Why was my base URL rejected?

Gitar accepts HTTPS only, with no exception for a hostname on your internal network.