Guides
How to sync GitHub with Notion: 4 ways compared
Notion's GitHub sync, automation tools, a GitHub Action with the Notion API, and keeping Notion docs correct after a release. What each does and where it stops.
Last checked:
People who search for a GitHub Notion integration usually want one of four things. They want to see pull requests and issues in Notion. They want a task to close when its pull request merges. They want release notes to land on a Notion page. Or they want the Notion docs to stay correct when the code changes.
These are different jobs, and no single tool does all four. This post covers each one, what it costs you in setup, and where it stops. I build Amendary, which does the fourth, so read that section with that in mind. Facts about Notion come from its help pages, checked on 17 November 2026.
Which one do you need?
| You want | Use | Writes to Notion pages? |
|---|---|---|
| Pull requests and issues as a Notion database | Notion's own GitHub sync | No, it fills a read-only database |
| Tasks that close when a pull request merges | Notion's GitHub Pull Requests property | Only the task status |
| A new page or row for every release | An automation tool, or a GitHub Action with the Notion API | Yes, it adds new content |
| Existing Notion docs corrected when the code changes | Amendary | Yes, it edits the stale sentence after review |
1. Notion's own GitHub sync
Notion can sync pull requests, issues, or both from the repositories you give its GitHub App access to. Each one becomes a row in a Notion database, with its title, number, state, author, labels, branches and dates. Notion checks for new and updated records on a schedule, even when nobody has Notion open.
- It needs a Notion Business plan. Notion's help page says the sync is not available on other plans.
- Synced properties are read-only. You change a pull request in GitHub, not in Notion. Columns you add yourself stay editable.
- Pull request comments and review details are not synced. The description comes across as plain text.
- If you pick a time window instead of all history, records that fall outside it are removed, along with the values in your own columns.
- The old version of this integration stopped updating on 30 October 2026. If your GitHub database in Notion has gone quiet, set up the new sync.
Use it when you want engineering work visible next to plans and specs. It does not touch the text of any Notion page.
Notion also has a GitHub connector for Notion AI. Notion's guide says it lets Notion AI search GitHub Markdown files, READMEs, pull requests and issues from the past year. That helps you ask questions across code and docs. It reads GitHub; it does not edit your Notion pages.
Notion help: Connect GitHub2. Linking tasks to pull requests
In a Notion task database you can add a GitHub Pull Requests property. Mention the task in a pull request and Notion links the two. Notion's guide says a task can be marked done when its pull request merges, and that GitHub comments can show up on the linked Notion task.
This is the right fit for a team that plans in Notion and ships in GitHub. It keeps the status of the work current. It does not change what your docs say about the product.
Notion guide: Bring your codebase into context3. Release notes into Notion, with an automation tool or a GitHub Action
Tools like Zapier, Make and Unito connect a GitHub event to a Notion action. A common setup is a new row in a changelog database for each release. Check which GitHub triggers and Notion actions your tool offers before you plan around it. No code is needed, and you pay per task or per sync.
If you would rather keep it in the repo, a GitHub Action can call the Notion API directly. This one adds the release name and notes to the end of a Notion page each time you publish a release.
# .github/workflows/release-to-notion.yml
on:
release:
types: [published]
jobs:
notion:
runs-on: ubuntu-latest
steps:
- name: Append the release to a Notion page
env:
NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
PAGE_ID: ${{ vars.NOTION_RELEASES_PAGE_ID }}
NAME: ${{ github.event.release.name }}
NOTES: ${{ github.event.release.body }}
run: |
# One rich text item holds at most 2,000 characters.
jq -n --arg name "$NAME" --arg notes "${NOTES:0:2000}" '{children: [
{type: "heading_2", heading_2: {rich_text: [{type: "text", text: {content: $name}}]}},
{type: "paragraph", paragraph: {rich_text: [{type: "text", text: {content: $notes}}]}}
]}' > body.json
curl -sf -X PATCH "https://api.notion.com/v1/blocks/$PAGE_ID/children" \
-H "Authorization: Bearer $NOTION_TOKEN" \
-H "Notion-Version: 2022-06-28" \
-H "Content-Type: application/json" \
--data @body.json- Create an internal integration in Notion, store its token as the NOTION_TOKEN secret, and connect the integration to the page.
- Release notes arrive as plain text. Turning Markdown into Notion blocks needs a converter step.
Both routes add new content. Neither one reads your existing pages, so the setup guide that still says the old default stays as it is.
4. Keeping existing Notion docs correct
This is the job the other three skip. A release raises a limit from 60 to 120 requests per minute. The release note is in Notion, the pull request is in your synced database, and the help page still says 60.
Amendary does this part. You connect GitHub and Notion and choose the pages to watch. Each page follows a repo. You choose what counts as shipped: commits on the default branch, GitHub releases, or a public changelog. Checks run daily.
- When a change makes a sentence on a watched page wrong, Amendary drafts a correction and links the change behind it.
- You review it in the Queue. If the change is about another plan or endpoint, you dismiss it.
- Update in Notion edits that block in place. When an edit cannot be placed safely, it adds a comment instead.
- For 30 days, Undo writes the old text back, unless someone has edited the block since.
Where it stops: each Notion page is checked on its own, so a fix is not carried into translated copies of the page. It does not write release notes or new pages. It also needs a person to own the docs, since some corrections need judgment a release note cannot give.
Using them together
These do not compete. A team can sync pull requests into a Notion database, close tasks on merge, post each release to a changelog page, and still have Amendary check the help pages. Each one keeps a different thing current. Start with the one that matches the question your team asks most often: what is in flight, what shipped, or which page is now wrong.