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

# Integrate with GitHub

> Pro

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, enhancing collaboration and streamlining your workflow. Whether you're managing code, tasks, or both, this integration ensures your team stays in sync without the hassle of switching between platforms.

## Set up GitHub integration[​](#set-up-github-integration "Direct link to Set up GitHub integration")

<Warning>
  If you're running a self-hosted instance of Plane, you'll need to set up a few extra configurations to get GitHub integration working. Check out the [setup guide](https://developers.plane.so/self-hosting/govern/integrations/github) first before diving into the steps on this page.
</Warning>

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. [Add repository mappings](/integrations/github#add-repository-mappings)

### Connect GitHub organization[​](#connect-github-organization "Direct link to Connect GitHub organization")

Link your GitHub organization to your Plane workspace to start syncing repositories. This step is crucial for enabling the full range of GitHub-Plane integrations.

<img src="https://mintcdn.com/onestack/4HoiF2FbNysKRwdw/images/integrations/integrations/github/connect-github.webp?fit=max&auto=format&n=4HoiF2FbNysKRwdw&q=85&s=30df9300b13fa851d489f81b4709ed49" alt="Connect GitHub" width="3352" height="1020" data-path="images/integrations/integrations/github/connect-github.webp" />

1. Navigate to [Workspace settings](/core-concepts/workspaces/overview#workspace-settings) in Plane.
2. On the right pane, select **Integrations**.
3. Find the **GitHub** integration and click **Configure**.
4. In the **Connect Organization** section, click **Connect**.
5. On the GitHub app installation page, choose the organization you want to connect.
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.

### Connect personal GitHub account[​](#connect-personal-github-account "Direct link to Connect personal GitHub account")

This step allows you to make comments on issues and pull requests in GitHub through your Plane account, using your personal GitHub identity.

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.

#### From Workspace settings[​](#from-workspace-settings "Direct link to From Workspace settings")

Workspace admins can connect their personal GitHub accounts from Workspace settings.

<img src="https://mintcdn.com/onestack/4HoiF2FbNysKRwdw/images/integrations/integrations/github/connect-personal-account.webp?fit=max&auto=format&n=4HoiF2FbNysKRwdw&q=85&s=b0120012caf1571ebb26ba03cb6f8a39" alt="Connect personal account" width="3366" height="648" data-path="images/integrations/integrations/github/connect-personal-account.webp" />

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.

<Info>
  Only one Workspace Admin can connect their GitHub account via Workspace Settings. Others can connect their accounts through [Profile Settings](/integrations/github#from-profile-settings).
</Info>

#### From Profile settings[​](#from-profile-settings "Direct link to From Profile settings")

If you don’t have admin access, you can still connect your personal GitHub account through your profile settings.

<img src="https://mintcdn.com/onestack/4HoiF2FbNysKRwdw/images/integrations/integrations/github/connect-personal-account-member.webp?fit=max&auto=format&n=4HoiF2FbNysKRwdw&q=85&s=c77bb5322300b06664e7f1238656aab4" alt="Connect member personal account" width="3552" height="824" data-path="images/integrations/integrations/github/connect-personal-account-member.webp" />

1. Go to [Profile settings](/core-concepts/account/settings).
2. Select the **Connections** tab in the sidebar.
3. Choose the workspace where you want to connect your GitHub personal account.
4. Click **Connect** in the GitHub section, which will redirect you to GitHub for authentication.
   <Info>
     If your workspace doesn’t have GitHub integration enabled, you won’t be able to connect your personal account. In this case, contact your Workspace Admin.
   </Info>
5. Once connected, your GitHub account will be listed in Plane.

### Add repository mappings[​](#add-repository-mappings "Direct link to Add repository mappings")

Once GitHub is connected to Plane, workspace admins can map GitHub repositories to Plane projects. This ensures issues and pull requests sync correctly.

<img src="https://mintcdn.com/onestack/4HoiF2FbNysKRwdw/images/integrations/integrations/github/repository-mapping.webp?fit=max&auto=format&n=4HoiF2FbNysKRwdw&q=85&s=88b32f53ab477603a95037313dfeee99" alt="Repository mapping" width="3372" height="1106" data-path="images/integrations/integrations/github/repository-mapping.webp" />

1. Go to the **Repository Mapping** section under **Integrations**.

2. Click **Add** to create a new mapping. <img src="https://mintcdn.com/onestack/4HoiF2FbNysKRwdw/images/integrations/integrations/github/sync-repo-and-project.webp?fit=max&auto=format&n=4HoiF2FbNysKRwdw&q=85&s=dbc24023f027fdf9adf587ce67285d7e" alt="Sync repo and project" width="1798" height="1280" data-path="images/integrations/integrations/github/sync-repo-and-project.webp" />

3. In the modal that appears, select:

   * The GitHub repository you want to sync.
   * The Plane project to map it to.
   * The Plane states to map the state of the pull requests.

4. Click **Continue**.

All linked repositories will appear in a list, where you can edit or remove them as needed.

## Sync issues[​](#sync-issues "Direct link to Sync issues")

With the GitHub integration setup, you can start syncing issues between Plane and GitHub. The synchronization is bi-directional and label-based, so issues are updated automatically on both platforms when certain labels are applied.

### Github -> Plane[​](#github---plane "Direct link to Github -> Plane")

1. Add the `Plane` label to an issue in GitHub to create and sync the issue in Plane. <img src="https://mintcdn.com/onestack/4HoiF2FbNysKRwdw/images/integrations/integrations/github/add-plane-label.webp?fit=max&auto=format&n=4HoiF2FbNysKRwdw&q=85&s=18e582be705960064eca9b8d1b20050a" alt="Add Plane label" width="2862" height="1040" data-path="images/integrations/integrations/github/add-plane-label.webp" />
2. Plane posts a link back to the GitHub issue, confirming the connection. <img src="https://mintcdn.com/onestack/4HoiF2FbNysKRwdw/images/integrations/integrations/github/synced-issue-from-github.webp?fit=max&auto=format&n=4HoiF2FbNysKRwdw&q=85&s=cf907b14a588440cf3c3bbf751222ad5" alt="Synced issue from GitHub" width="1878" height="392" data-path="images/integrations/integrations/github/synced-issue-from-github.webp" />
3. A new work item is created in Plane with a link to the GitHub issue. <img src="https://mintcdn.com/onestack/4HoiF2FbNysKRwdw/images/integrations/integrations/github/creates-plane-issue.webp?fit=max&auto=format&n=4HoiF2FbNysKRwdw&q=85&s=ac2628d1a34c9e1c95782d42243ed292" alt="Creates issue in Plane" width="3394" height="1262" data-path="images/integrations/integrations/github/creates-plane-issue.webp" />

### Plane -> GitHub[​](#plane---github "Direct link to Plane -> GitHub")

1. Add the `GitHub` label to a work item in Plane to sync it to GitHub. <img src="https://mintcdn.com/onestack/4HoiF2FbNysKRwdw/images/integrations/integrations/github/add-github-label.webp?fit=max&auto=format&n=4HoiF2FbNysKRwdw&q=85&s=e1c67c9306991e01db07d5e2e861771f" alt="Add GitHub label" width="3352" height="982" data-path="images/integrations/integrations/github/add-github-label.webp" />
2. A new issue is created in GitHub. <img src="https://mintcdn.com/onestack/4HoiF2FbNysKRwdw/images/integrations/integrations/github/create-github-issue.webp?fit=max&auto=format&n=4HoiF2FbNysKRwdw&q=85&s=0a73b695de1a394fca8a606daa8a868b" alt="Creates issue in GitHub" width="2708" height="1210" data-path="images/integrations/integrations/github/create-github-issue.webp" />
3. The GitHub issue is also linked back to Plane.

### What gets synced?[​](#what-gets-synced "Direct link to What gets synced?")

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      | GitHub → Plane   | Changes in Plane do not update GitHub states. However, if an issue is closed in GitHub, it automatically moves to the Done state in Plane.                                                                                                                          |
| 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.                                                                                                         |

## Sync pull requests[​](#sync-pull-requests "Direct link to Sync pull requests")

Pull requests (PRs) are also synchronized with Plane to ensure issue tracking remains accurate throughout the development lifecycle.

#### Closing references and auto-updates[​](#closing-references-and-auto-updates "Direct link to Closing references and auto-updates")

When a pull request includes closing references to GitHub issues (e.g., `closes #14`), any linked Plane work items will automatically update with the PR link. If the PR is merged or closed, the Plane work item state updates based on the configured workflow in [Repository mappings](/integrations/github#add-repository-mappings).

#### Magic words for issue references[​](#magic-words-for-issue-references "Direct link to Magic words for issue references")

You can use specific keywords in GitHub pull requests to manage how Plane work items are updated.

* **Closing references** These keywords close linked issues when the PR is merged or closed. **Keywords** `close`, `closes`, `closed`, `closing`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`, `complete`, `completes`, `completed`.

* **Non-closing references** These keywords maintain the state mappings of linked issues but don’t close them. **Keywords** `ref`, `references`, `reference to`, `part of`, `related to`.

#### PR lifecycle mapping[​](#pr-lifecycle-mapping "Direct link to PR lifecycle mapping")

The lifecycle of a pull request can be [mapped](/integrations/github#add-repository-mappings) 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.

#### Issue backlinks in pull requests[​](#issue-backlinks-in-pull-requests "Direct link to Issue backlinks in pull requests")

When a PR references Plane work items (using closing or non-closing reference keywords), 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.