You want to link your Notion workspace to your GitHub repository issue tracker so that new issues appear automatically in a Notion database. Notion offers a built-in GitHub integration that syncs issues, pull requests, and other events into a dedicated database. This article walks you through connecting your GitHub account, selecting a repository, and configuring the sync so your team can manage development tasks inside Notion. You will learn how to set up the integration, map fields, and avoid common sync failures.
Key Takeaways: Syncing Notion with GitHub Issues
- Settings & Members > Connections > GitHub: Initiates the OAuth connection between your Notion workspace and GitHub account.
- GitHub database template selection: Choose from Issue Tracker, Pull Requests, or a custom database to control which data syncs.
- Sync direction and field mapping: Understand that Notion pulls GitHub data one-way by default; you can map Notion properties to GitHub fields.
What the Notion-GitHub Integration Does and What You Need
The Notion-GitHub integration creates a linked database that mirrors GitHub issues, pull requests, and other repository events. When a new issue is created in GitHub, it appears as a row in your Notion database within minutes. You can also update issue status, assignees, and labels from Notion if the integration is set to two-way sync. This feature is part of Notion’s Connections system and works with public and private repositories.
Before you start, you need three things:
- A Notion workspace where you have admin or owner permissions. Only workspace owners can add and configure connections.
- A GitHub account with admin access to the repository you want to sync. The integration uses OAuth, so you must authorize Notion to read and write to your repositories.
- A Notion database that will hold the synced issues. You can use the pre-built Issue Tracker template or create a custom database with the required properties.
The integration supports one GitHub account per workspace connection. If you need multiple repositories, you can add each one as a separate linked database after the initial connection.
Steps to Connect GitHub and Set Up the Issue Sync
Follow these steps to configure the sync between your Notion workspace and a GitHub repository issue tracker. The process has two phases: connecting your GitHub account and then selecting the repository and database template.
- Open Notion workspace settings
Click on Settings & Members in the left sidebar. If you are on the Notion web app, click your profile icon in the top-right corner and select Settings & Members from the dropdown. This opens the workspace settings panel. - Navigate to the Connections tab
In the left panel of the settings window, click Connections. You will see a list of all third-party integrations currently linked to your workspace. Scroll down to find the GitHub integration option. - Click Add or Connect GitHub
Look for the GitHub logo and click the Connect button. A new browser tab or popup will open asking you to authorize Notion to access your GitHub account. Sign in to GitHub if you are not already logged in. - Authorize the Notion OAuth app in GitHub
GitHub displays a list of permissions the Notion app requests. These include reading and writing issues, pull requests, and repository metadata. Click Authorize Notion to grant access. You will be redirected back to Notion. - Select a repository in Notion
After authorization, Notion returns to the Connections page. Click the Configure button next to the GitHub integration. A dialog appears showing your GitHub repositories. Select the repository you want to sync with Notion. - Choose a database template
Notion offers three templates: Issue Tracker, Pull Requests, and Custom. Select Issue Tracker to sync issues and their metadata. This template creates a new database with preconfigured properties like Status, Assignee, Labels, and Milestone. - Set the sync direction
In the same dialog, choose whether the sync is one-way from GitHub to Notion or two-way. One-way sync means changes in GitHub appear in Notion but changes in Notion do not push back to GitHub. Two-way sync allows you to update issue status, assignees, and labels from Notion and have those changes reflected in GitHub. - Click Connect and wait for initial sync
Click the Connect button to finalize the setup. Notion immediately begins importing existing issues from the selected repository. Depending on the number of issues, this may take a few seconds to a few minutes. You will see the new database appear in your workspace sidebar.
After the initial sync, new issues created in GitHub will appear in the Notion database automatically. If you enabled two-way sync, you can edit properties like Status or Assignee directly in the Notion database and the changes will sync back to GitHub.
Common Issues When Syncing GitHub Issues to Notion
Issues do not appear in Notion after connecting
If no issues show up in the Notion database after the initial sync, check that the repository actually contains issues. Some repositories use Discussions or Projects instead of the Issues tab. Also confirm that the GitHub integration has read access to the repository. Go to GitHub > Settings > Applications > Authorized OAuth Apps and verify Notion appears in the list. If it does, revoke access and reconnect from Notion.
Two-way sync updates are not reflected in GitHub
Two-way sync requires that the Notion database property names exactly match the GitHub field names. For example, a property called “Status” in Notion must correspond to the GitHub issue status field. If you rename a property after the sync is configured, the connection breaks. Delete the linked database and reconnect with the correct template. Do not manually edit the property names in the Notion database after setup.
Sync stops working after a GitHub permission change
If you or a GitHub organization admin changes the OAuth app permissions, the sync may stop. Symptoms include stale data or error messages in the database. To fix this, go to Notion Settings & Members > Connections, click the three-dot menu next to GitHub, and select Reconnect. This reauthorizes the integration with the current permissions.
Notion Issue Tracker vs Pull Request Template vs Custom Database
| Item | Issue Tracker | Pull Requests | Custom Database |
|---|---|---|---|
| Data synced | GitHub issues with status, assignee, labels, milestone, comments | GitHub pull requests with status, reviewer, branch, merge status | You define which GitHub events and fields to sync |
| Preconfigured properties | Status, Assignee, Labels, Milestone, Repository, Issue Number | Status, Reviewer, Branch, Merge Status, Repository, PR Number | None — you create all properties manually |
| Best for | Bug tracking, feature requests, task management | Code review workflow, merge tracking | Advanced users who need only specific fields or multiple repositories in one database |
| Two-way sync support | Yes — status, assignee, labels sync back to GitHub | Limited — status and reviewer sync back | Depends on your property mapping; may require manual maintenance |
The Issue Tracker template is the recommended starting point because it includes all commonly used fields and supports full two-way sync. Switch to the Pull Requests template if your primary goal is tracking code reviews. Use the Custom database only if you need to combine data from multiple repositories or sync events that the templates do not cover.
You now have a working Notion database that syncs with your GitHub repository issue tracker. New issues created in GitHub will appear automatically, and you can update issue status from Notion if you enabled two-way sync. To extend this setup, try adding a linked view that filters issues by assignee or milestone. For teams using multiple repositories, consider creating a separate database for each repository to keep data organized.