Repository navigation
docs(source-notion): update setup for Notion connections, document record format and troubleshooting - #78154
Draft
devin-ai-integration[bot] wants to merge 1 commit into
Draft
docs(source-notion): update setup for Notion connections, document record format and troubleshooting#78154devin-ai-integration[bot] wants to merge 1 commit into
devin-ai-integration[bot] wants to merge 1 commit into
Conversation
Contributor
Author
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
Contributor
👋 Greetings, Airbyte Team Member!Here are some helpful tips and reminders for your convenience. 💡 Show Tips and TricksPR Slash CommandsAirbyte Maintainers (that's you!) can execute the following slash commands on your PR:
📚 Show Repo GuidanceHelpful Resources
|
devin-ai-integration
Bot
added
area/documentation
Contributor
|
Deploy preview for airbyte-docs ready!
Deployed with vercel-action |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
|
|
||
| ## Supported sync modes | ||
|
|
||
| The Notion source connector supports the following [sync modes](https://docs.airbyte.com/cloud/core-concepts#connection-sync-modes): |
Contributor
Author
There was a problem hiding this comment.
Acknowledged. This was a real markdownlint warning caused by editing a list item after an intervening block. I moved the Start Date sentence up into the uninterrupted setup list and pushed a follow-up commit so markdownlint no longer flags this line.
devin-ai-integration
Bot
force-pushed
the
docs/auto/source-notion
branch
2 times, most recently
from
May 26, 2026 20:15
6bb11a4 to
1763987
Compare
devin-ai-integration
Bot
changed the title
devin-ai-integration
Bot
force-pushed
the
docs/auto/source-notion
branch
from
June 1, 2026 21:06
66f0c42 to
e77f149
Compare
devin-ai-integration
Bot
changed the title
devin-ai-integration
Bot
force-pushed
the
docs/auto/source-notion
branch
from
June 1, 2026 22:49
e77f149 to
ceb8aa5
Compare
devin-ai-integration
Bot
changed the title
…ent record format, concurrency, and troubleshooting; fix changelog Co-Authored-By: bot_apk <apk@cognition.ai>
devin-ai-integration
Bot
force-pushed
the
docs/auto/source-notion
branch
from
October 13, 2026 15:25
ceb8aa5 to
c9b8036
Compare
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| 6. (Optional) You may optionally provide a **Start Date** using the provided datepicker, or by programmatically entering a UTC date and time in the format: `YYYY-MM-DDTHH:mm:ss.SSSZ`. During incremental syncs, only data generated after this date is replicated. If left blank, the start date defaults to two years before the current date. | ||
| 7. Click **Set up source** and wait for the tests to complete. | ||
| 6. (Optional) Enter a **Start Date** in UTC, in the format `YYYY-MM-DDTHH:mm:ss.SSSZ`. The connector doesn't sync records last edited before this date. If you leave it blank, the start date defaults to two years before the current date. |
Contributor
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
error MD029/ol-prefix Ordered list item prefix [Expected: 1; Actual: 6; Style: 1/2/3]
| 6. (Optional) You may optionally provide a **Start Date** using the provided datepicker, or by programmatically entering a UTC date and time in the format: `YYYY-MM-DDTHH:mm:ss.SSSZ`. During incremental syncs, only data generated after this date is replicated. If left blank, the start date defaults to two years before the current date. | ||
| 7. Click **Set up source** and wait for the tests to complete. | ||
| 6. (Optional) Enter a **Start Date** in UTC, in the format `YYYY-MM-DDTHH:mm:ss.SSSZ`. The connector doesn't sync records last edited before this date. If you leave it blank, the start date defaults to two years before the current date. | ||
| 7. (Optional) Set **Number of concurrent workers** to control how many requests the connector makes in parallel. The default is 3 and the maximum is 10. For guidance, see [Performance considerations](#performance-considerations). |
Contributor
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
error MD029/ol-prefix Ordered list item prefix [Expected: 2; Actual: 7; Style: 1/2/3]
| 7. Click **Set up source** and wait for the tests to complete. | ||
| 6. (Optional) Enter a **Start Date** in UTC, in the format `YYYY-MM-DDTHH:mm:ss.SSSZ`. The connector doesn't sync records last edited before this date. If you leave it blank, the start date defaults to two years before the current date. | ||
| 7. (Optional) Set **Number of concurrent workers** to control how many requests the connector makes in parallel. The default is 3 and the maximum is 10. For guidance, see [Performance considerations](#performance-considerations). | ||
| 8. Click **Set up source** and wait for the tests to complete. |
Contributor
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
error MD029/ol-prefix Ordered list item prefix [Expected: 3; Actual: 8; Style: 1/2/3]
devin-ai-integration
Bot
changed the title
Comment on lines
+84
to
+86
| 6. (Optional) Enter a **Start Date** in UTC, in the format `YYYY-MM-DDTHH:mm:ss.SSSZ`. The connector doesn't sync records last edited before this date. If you leave it blank, the start date defaults to two years before the current date. | ||
| 7. (Optional) Set **Number of concurrent workers** to control how many requests the connector makes in parallel. The default is 3 and the maximum is 10. For guidance, see [Performance considerations](#performance-considerations). | ||
| 8. Click **Set up source** and wait for the tests to complete. |
Contributor
There was a problem hiding this comment.
[markdownlint-fix] reported by reviewdog 🐶
Suggested change
| 6. (Optional) Enter a **Start Date** in UTC, in the format `YYYY-MM-DDTHH:mm:ss.SSSZ`. The connector doesn't sync records last edited before this date. If you leave it blank, the start date defaults to two years before the current date. | |
| 7. (Optional) Set **Number of concurrent workers** to control how many requests the connector makes in parallel. The default is 3 and the maximum is 10. For guidance, see [Performance considerations](#performance-considerations). | |
| 8. Click **Set up source** and wait for the tests to complete. | |
| 1. (Optional) Enter a **Start Date** in UTC, in the format `YYYY-MM-DDTHH:mm:ss.SSSZ`. The connector doesn't sync records last edited before this date. If you leave it blank, the start date defaults to two years before the current date. | |
| 2. (Optional) Set **Number of concurrent workers** to control how many requests the connector makes in parallel. The default is 3 and the maximum is 10. For guidance, see [Performance considerations](#performance-considerations). | |
| 3. Click **Set up source** and wait for the tests to complete. |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Triggering Context
Run triggered by: Merged PR on
master(autodoc workflow)Relevant context: Commit ed0252ec from #88131, which replaced the connector's custom record transformations with declarative
AddFields(v4.0.28, no change to record output).Confidence impact: The trigger is a small, merged refactor with a clear scope, so Triggering Context scores 5. Most changes in this PR address gaps in the existing doc rather than the refactor itself.
Documentation Confidence Assessment
Overall Confidence: 3/5
manifest.yaml, with unit tests for the transformations.externalDocumentationUrlsonly lists 2 entries.ql400,sl200).Raw score: 0.15·4 + 0.15·4 + 0.25·3 + 0.10·3 + 0.15·2 + 0.10·5 + 0.10·4 = 3.45, floored to 3. No hard caps apply.
Adjustments based on code comprehension
properties_to_name_value_list,bot_owner_to_info),concurrency_level, thenum_workersspec, error handlers, andclient_side_incremental_syncare all inmanifest.yaml.unit_tests/test_record_transformations.py(added in refactor(source-notion): replace custom record transformations with declarativeAddFields#88131) covers thepropertiesandbot.owner.inforeshaping.BlocksRetriever; I relied on the existing doc and the manifest for the 30-level depth and excluded block types rather than re-tracing the retriever.What I Verified vs. What I Inferred
num_workers(1–10, default 3) controlsdefault_concurrency; Pages and Data Sources usePOST /searchwith an object filter; Comments are partitioned by page ID; incremental sync is client-side onlast_edited_time; 404 responses containing "Make sure the relevant pages and databases are shared with your integration." are ignored; the Users stream fails with "Notion integration lacks read user information for the Users stream..." onrestricted_resource;propertiesis converted to a[{name, value}]array; bot owner details move frombot.owner.<type>tobot.owner.info.app.notion.com/developers/connections), with Configuration (API token, capabilities, OAuth client ID/secret) and Content access tabs; page sharing via ••• > Connections > + Add connection; per-connection rate limits of 180 requests/min on most plans and 600/min on Business and Enterprise, plus a shared per-workspace limit; List comments returns un-resolved comments only; List all users excludes guests; personal access tokens can't list workspace users; the authorization guide anchor#public-connection-auth-flow-set-up.Areas of Concern
{#step-1-create-an-integration-in-notion},{#step-2-set-permissions-and-acquire-authorization-credentials}) so the links in the connector spec's field descriptions resolve. Previously those anchors didn't match any heading.What
Updates the Notion source docs so the setup steps match Notion's current UI and the doc covers configuration, record format, and troubleshooting details that were missing.
How
Corrections
Additions
propertiesarray andbot.owner.inforeshaping.Review guide
docs/integrations/sources/notion.md– Setup guide (Steps 1–3), the new "Record format" section, "Performance considerations", and "Troubleshooting".User Impact
Readers get setup steps that match Notion's current UI, and an explanation of how
propertiesand bot owner fields look in their destination.Can this PR be safely reverted and rolled back?
Phase 2 note:
markdownlint-cli2reports only MD029 (ordered list numbering around the env blocks in Step 3, same pattern as before) and MD060 in the existing changelog table. Vale isn't installed in this environment.Docusaurus build:
pnpm buildsucceeded with no Notion-related errors or broken-link/anchor warnings. Note:docusaurus/package.jsondeclaresnode >=20, butmermaid@12.2.0requires Node>=22.12.0, so the build needed Node 22.Link to Devin session: https://app.devin.ai/sessions/1bc66047676543a89a41a8d56ea740f9
Open in Devin Desktop: https://app.devin.ai/desktop/session/1bc66047676543a89a41a8d56ea740f9?variant=devin