Updated the GitHub integrations page

[danciaclara]

Description

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• Feature (non-breaking change which adds functionality)
• Improvement (change that would cause existing functionality to not work as expected)
• Code refactoring
• Performance improvements
• Documentation update

Screenshots and Media (if applicable)

Test Scenarios

References

---

Note

Revamps GitHub integration docs with project-level issue sync (state/direction mapping) and PR state automation via reference formats, plus clarified sync behavior and defaults.

• Documentation (GitHub integration)
  • Issue sync
    • Introduces project-level work item sync setup with mapped states and selectable sync direction (unidirectional or bidirectional).
    • Adds flows for syncing issues both ways via labels (Plane and GitHub) with linked comments and cross-links.
    • Details “How issue syncing works”: state synchronization, creating synced issues, and continuous updates.
    • Updates “What gets synced?” table with an important warning: default sync is unidirectional (GitHub → Plane) and overwrites Plane data unless bidirectional is enabled.
  • PR state automation
    • Adds configurable PR state mapping to Plane work item states and a setup flow.
    • Defines reference formats: bracketed IDs enable automation; unbracketed IDs link only (no automation), with example.
    • Retains/clarifies PR lifecycle mappings and issue backlink comments.

^{Written by Cursor Bugbot for commit 7da56bd. This will update automatically on new commits. Configure here.}

Summary by CodeRabbit

• Documentation
  • Replaced repository-centric mappings with a project-level “Sync issues” flow, including an “Add project work item sync” modal and project-level sync listing with edit/remove.
  • Added “How issue syncing works” and expanded “What gets synced?” with property-level details and an inline warning about default unidirectional overwrites.
  • Expanded PR coverage: PR state mapping, automation setup, reference formats, lifecycle mapping, and issue backlinks.
  • Standardized terminology and updated visuals/navigation.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
docs	Ready	Preview	Comment	Oct 1, 2025 2:10pm

[coderabbitai]

Walkthrough

Documentation for the GitHub integration is restructured from repository-level mappings to project-level issue sync and expanded PR automation flows, adding a unified “How issue syncing works” section, property-level sync behavior, explicit warnings about default unidirectional overwrite, and updated UI/media references.

Changes

Cohort / File(s)

Summary

GitHub integration docs overhaul docs/integrations/github.mdx

Replaces repository mappings with a project-level “Sync issues” flow and an “Add project work item sync” modal; consolidates and expands “How issue syncing works” and “What gets synced?” with detailed property table and warnings; restructures PR content into PR mapping, state automation, reference formats, lifecycle mapping, and issue backlinks; updates terminology, navigation, UI screenshots, and media references.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant Plane as Plane (Project)
  participant GitHub as GitHub

  rect rgb(240,248,255)
    note over User,Plane: Configure project-level issue sync
    User->>Plane: Open "Add project work item sync" modal
    User->>Plane: Select GitHub repo, mapping, direction (Uni/Bi), Start Sync
    Plane-->>User: Show project sync listing (edit / remove)
  end

  rect rgb(245,255,245)
    note over Plane,GitHub: Issue synchronization runtime
    alt Unidirectional
      GitHub->>Plane: Push updates (if configured)
      Plane->>GitHub: (no outbound updates)
    else Bidirectional
      GitHub->>Plane: Push updates
      Plane->>GitHub: Push updates (per mapping & rules)
    end
    note over Plane,GitHub: Mapped fields: Title, Description, Assignees, Labels, States, Comments, Mentions, Issue Links
  end

Loading

sequenceDiagram
  autonumber
  actor User
  participant Plane as Plane (Project)
  participant GitHub as GitHub

  rect rgb(255,250,240)
    note over User,Plane: Configure PR mapping & automation
    User->>Plane: Add PR mapping (repo ↔ project)
    User->>Plane: Define PR state automation, reference formats, lifecycle mapping
  end

  rect rgb(245,245,255)
    note over GitHub,Plane: PR lifecycle & automation
    GitHub->>Plane: PR events (open/update/merge/close)
    Plane->>Plane: Map PR state to work item state
    Plane-->>GitHub: Optional comments/backlinks per automation rules
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• sriramveeraghanta

Poem

I twitch my whiskers at the docs' new tune,
Projects sync up under the syncing moon.
Issues hop across with labels bright,
PRs march in, mapped states alight.
A rabbit nods — docs tidy, neat, and spry. 🐇✨

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title Check	❓ Inconclusive	The title “Updated the GitHub integrations page” is accurate but overly broad and does not convey the primary changes such as the introduction of project-level issue syncing and new PR automation workflows, making it difficult for team members to quickly grasp the scope of the update.	Please revise the title to specifically highlight the key enhancements, for example “Add project-level issue sync and PR automation to GitHub integration docs,” so that it clearly reflects the main updates in the changeset.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch github-ux-changes

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3211ff3 and 7da56bd.

📒 Files selected for processing (1)

• docs/integrations/github.mdx (3 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Cursor Bugbot
• GitHub Check: Cursor Bugbot

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}