Skip to main content

​
Overview

The Gitar Plane integration connects a Plane workspace, Cloud or self-hosted, to your pull requests. Gitar reads work items, creates and updates them, comments, and moves them between states.
Plane Cloud and self-hosted both work. On Cloud, enter https://app.plane.so as the base URL.

Read Linked Work Items

Resolve a PROJ-123 reference from a PR title, description, or branch name

Validate Against the Issue

Judge a PR against the objectives its work item asks for

Create and Update

Open follow-up work items and update existing ones from a rule

Comment and Transition

Post back to a work item and move it to a new state

​
Before you start

On Plane Cloud there is nothing to check: enter https://app.plane.so and skip to 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

1

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
2

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.
3

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.
4

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.
5

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
Enter the three values, then click Connect.

​
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 for how to write one. Gitar also reads Plane work items for 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.