[devin-ai-integration]

Triggering Context

Run triggered by: A connector commit merged to master: feat(source-hubspot): add opt-in prefix for custom objects that collide with built-in stream names (6.13.0), which the autodoc workflow flagged for documentation review. This is the deterministic per-connector docs branch, so it also carries earlier sessions' unmerged work (6.8.0 Web Analytics, 6.8.1 concurrency, 6.8.2 startup crash, 6.9.0 schema additions, 6.9.2 custom object identifier errors, 6.10.0 task pipelines, 6.11.0 property history filters, 6.12.0 flows), rebased onto current master.

Relevant context:

• Triggering commit: 57cdbfd
• Triggering PR: feat(source-hubspot): add opt-in prefix for custom objects that collide with built-in stream names #88415
• Earlier connector PRs covered by this branch: feat(source-hubspot): add experimental Automation v4 flows stream #85854, feat(source-hubspot): allow limiting property_history streams to a configured property list #87604, feat(source-hubspot): add new stream engagements_task_pipelines #86415, fix(source-hubspot): report invalid custom object association identifier as config_error #86350, feat(source-hubspot): declare marketing_emails testing.isAbVariation and owners teams[].primary #82769, chore(source-hubspot): update CDK to 7.28.0 to fix association-stream startup crash #84917, fix(source-hubspot): honor num_worker concurrency config field #84411, feat(source-hubspot): restore 12 Web Analytics streams removed in v5.8.0 #80806

Confidence impact: 6.13.0 is a merged, additive, off-by-default config option with a clear scope and unit tests, and the connector PR already added a first pass at the docs. This revision restructures that text, adds the setup steps, and fixes the changelog date.

Documentation Confidence Assessment

Overall Confidence: 3/5

Dimension	Score	Rationale
Code Comprehension of the Documented Surface	4/5	The 6.13.0 surface is entirely declarative (spec field plus a Jinja ComponentMappingDefinition in manifest.yaml); carried-forward content touches small custom components.
API Documentation Quality	4/5	HubSpot documents the CRM schemas and custom objects APIs well; the name collision is an Airbyte-side naming issue, not an API behavior.
Change Scope & Risk	2/5	~157 lines changed on the branch overall; this revision changes ~25 lines.
Existing Doc Maturity	5/5	The doc is ~800 lines and covers prerequisites, scopes, setup, streams, rate limits, and troubleshooting.
Connector Sensitivity	1/5	HubSpot is a top-tier certified connector (ql: 400, sl: 300).
Triggering Context	4/5	Triggered from a moderate merged PR (new config option) with clear scope.
Inference Ratio	4/5	The rename rule, default, and setting title come straight from the manifest and tests; the read-time override and the "clear the stream's data" advice come from the connector PR's analysis, not my own run.

raw_score = 0.154 + 0.154 + 0.252 + 0.105 + 0.151 + 0.104 + 0.10*4 = 3.15 -> confidence 3.

Adjustments based on code comprehension

Baseline 4 (low-code connector with custom Python components). No net adjustment:

• Declarative surface area: upward: the 6.13.0 behavior is spec.prefix_colliding_custom_objects and definitions.custom_object_stream_name in manifest.yaml, with no components.py changes.
• Test coverage of the documented claim: upward: test_custom_object_colliding_with_builtin_stream_name_is_unchanged_by_default, test_custom_object_colliding_with_builtin_stream_name_is_prefixed, and test_custom_object_prefixed_stream_reads_from_fully_qualified_entity cover default behavior, the rename, and that only colliding names change.
• Carried-forward custom components: downward: the rest of the branch documents behavior in custom components (HubspotFlowDetailsTransformation, schema loaders), so I kept the baseline for the PR overall.

What I Verified vs. What I Inferred

• Verified from code: prefix_colliding_custom_objects is an optional boolean, default false, titled Prefix custom objects that share a name with a built-in stream, placed after treat_numbers_and_booleans_as_strings and before num_worker in the spec; the stream name becomes custom_object_<name> only when the flag is on and components_values.name is in the built-in list; the name, full_refresh_stream.name, and incremental_stream.name mappings all use the same definition; the entity parameter is unchanged.
• Verified from tests: with the flag off, discover still emits two form_submissions streams; with it on, it emits one form_submissions, custom_object_form_submissions, and an unchanged cars.
• Verified from the merge record: feat(source-hubspot): add opt-in prefix for custom objects that collide with built-in stream names #88415 merged 2026-10-20 (UTC), not 2026-10-14. deps(source-hubspot): 🐙 update dependencies [2026-10-20] #89246 (2026-10-20) and deps(source-hubspot): 🐙 update dependencies [2026-10-13] #87204 (2026-10-13) dates match.
• Inferred / taken from the connector PR: that, with the flag off, a connection syncing the built-in stream name actually gets the custom object's records (the PR's CDK analysis says the CDK resolves streams by name and dynamic streams come last; I didn't trace the CDK myself). The advice to clear that stream's data after enabling the setting follows from that.

Areas of Concern

• Check the wording in Custom objects that share a name with a built-in stream about clearing data. It's the step a user with an existing colliding connection most needs, and it rests on the connector PR's analysis.
• Carried-forward concerns from earlier revisions still apply: the flows tier list omits crmHub, and the property history backfill note and Sync concurrency tuning advice are reasoned rather than measured.

---

What

Documents the prefix_colliding_custom_objects setting added in 6.13.0 and fixes the 6.13.0 changelog date. Carries forward the earlier unmerged work on this branch.

How

New in this revision (6.13.0)

• Setup steps (Cloud and OSS): added an optional step for Prefix custom objects that share a name with a built-in stream, in spec order, and renumbered the following steps.
• Custom objects: moved the collision text that 6.13.0 added (it ran into the previous paragraph without a line break) into its own FieldAnchor-wrapped subsection, Custom objects that share a name with a built-in stream. It explains why the error happens, what the setting renames, that it's off by default, and what to do if a connection was already syncing the colliding built-in stream.
• Changelog: 6.13.0 date 2026-10-14 -> 2026-10-20; shortened the subject.

Carried forward from earlier commits on this branch (rebased onto master; one changelog conflict resolved)

• 6.12.0 flows stream docs and date fix (2026-10-10), 6.11.0 property history filters (2026-10-09), 6.10.0 engagements_task_pipelines (2026-10-05), custom object association identifier errors, Avro/Parquet troubleshooting, Sync concurrency, Web Analytics stream docs, line_items scope row, and earlier changelog date fixes.

Review guide

• docs/integrations/sources/hubspot.md is the only file changed.
• New in this revision: step 11 (Cloud) and step 10 (OSS) in Step 3, the Custom objects that share a name with a built-in stream subsection under Notes on the Custom CRM Objects, and the 6.13.0 changelog row.

User Impact

If connection setup fails with a duplicate stream name error because a custom object shares a built-in stream's name, you can find the fix from the setup steps and know what to clean up afterward. No connector behavior changes.

Verification

• markdownlint-cli2 on hubspot.md: no findings on changed lines (the remaining MD032/MD022/MD029/MD060 findings are pre-existing).
• Docusaurus build: not run. pnpm install failed with ERR_PNPM_LOCKFILE_BREAKING_CHANGE because the local pnpm version doesn't match the lockfile (environment issue, unrelated to this change). Relying on the CI docs build and Vercel preview for link and anchor checks. Vale not run.

Can this PR be safely reverted and rolled back?

• YES 💚
• NO ❌

---

Note: I am an AI assistant (Devin) and have proposed these documentation updates based on a review of the connector source code and HubSpot's API documentation, triggered by recent changes to the HubSpot connector. Reviewers may merge, modify, or close this PR as they see fit. Ian Alton (@ian-at-airbyte), please review.

Link to Devin session: https://app.devin.ai/sessions/d4791a8c95794b9ead2cd2a8d8522adc
Open in Devin Desktop: https://app.devin.ai/desktop/session/d4791a8c95794b9ead2cd2a8d8522adc?variant=devin

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

• 🛠️ Quick Fixes
  • /format-fix - Fixes most formatting issues.
  • /bump-version - Bumps connector versions, scraping changelog description from the PR title.
    • Bump types: patch (default), minor, major, major_rc, rc, promote.
    • The rc type is a smart default: applies minor_rc if stable, or bumps the RC number if already RC.
    • The promote type strips the RC suffix to finalize a release.
    • Example: /bump-version type=rc or /bump-version type=minor
  • /bump-progressive-rollout-version - Alias for /bump-version type=rc. Bumps with an RC suffix and enables progressive rollout.
• ❇️ AI Testing and Review (internal link: AI-SDLC Docs):
  • /ai-prove-fix - Runs prerelease readiness checks, including testing against customer connections.
  • /ai-canary-prerelease - Rolls out prerelease to 5-10 connections for canary testing.
  • /ai-review - AI-powered PR review for connector safety and quality gates.
• 📝 AI Documentation:
  • /ai-docs-review - AI-powered documentation review for PRs with connector changes.
  • /ai-create-docs-pr - Creates a documentation PR for connector changes, stacked on the current PR.
• 🚀 Connector Releases:
  • /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-preview.{git-sha}) for all modified connectors in the PR.
  • /enable-autopilot-rollouts - Enables autopilot progressive rollouts for the modified connector(s) in the PR, remediating "autopilot rollouts not enabled for {connector-name}" auto-merge blockers. Sets defaultRolloutMode: autopilot and enableProgressiveRollout: true, preserving any existing autopilotConfig.
    • Optional args: connector=<CONNECTOR_NAME> (defaults to the modified connectors in the PR), strategy=fast|slow|default (defaults to fast).
    • Example: /enable-autopilot-rollouts or /enable-autopilot-rollouts connector=source-faker strategy=slow
• ☕️ JVM connectors:
  • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
    Example: /update-connector-cdk-version connector=destination-bigquery
• 🐍 Python connectors:
  • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
  • /poe source example lock - Alias for /poe connector source-example lock.
  • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
  • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.
• ⚙️ Admin commands:
  • /force-merge reason="<REASON>" - Force merges the PR using admin privileges, bypassing CI checks. Requires a reason.
    Example: /force-merge reason="CI is flaky, tests pass locally"

📚 Show Repo Guidance

Helpful Resources

• Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

📝 Edit this welcome message.

[github-actions]

Deploy preview for airbyte-docs ready!

Project:	airbyte-docs
Status:	✅  Deploy successful!
Preview URL:	https://airbyte-docs-mwugopsrc-airbyte-growth.vercel.app
Latest Commit:	bb0ed2e

Deployed with vercel-action

[Copilot]

Pull request overview

Updates the HubSpot source connector documentation to reflect recent connector changes: documenting the now-functional num_worker concurrency setting, expanding/clarifying Web Analytics (experimental) stream guidance, and correcting changelog dates to match merge history.

Changes:

• Add a Sync concurrency section (1–40 threads, default 10) and reference it from both Cloud and OSS setup steps.
• Expand Experimental streams documentation for Web Analytics (stream mapping table, access requirements, sync behavior, record shape) and update supported streams list.
• Fix changelog dates for 6.8.0 and 6.8.1; clarify 6.8.1 behavior change description.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

[github-actions]

[markdownlint-fix] _{reported by reviewdog 🐶}

airbyte/docs/integrations/sources/hubspot.md

Lines 509 to 510 in 2cbedeb

	| Version | Date | Pull Request | Subject |
	|:------------|:-----------|:---------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

[devin-ai-integration]

🚫 Not fixing. This is the changelog table's column padding, which is cosmetic and pre-existing throughout the table — every earlier row is unpadded the same way. markdownlint-cli2 on this file reports 30 findings on this branch and the same 30 with identical signatures on master, and the Docs / MarkDownLint check passes, so nothing new was introduced. Reflowing the whole table would add churn to a docs-only diff without changing rendered output.

[Copilot]

🟡 Changes recommended

Clarify concurrency, backfill, Web Analytics parent-discovery, and startup-crash guidance.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (3)

docs/integrations/sources/hubspot.md:206

• As written, this estimates every sync from the configured Start date, but after the initial run DatetimeBasedCursor starts each partition from its persisted occurredAt state. Clarify that the Start date × 30-day estimate applies to the initial backfill; otherwise users may overestimate recurring daily usage.

These streams sync incrementally on the `occurredAt` timestamp, and Airbyte keeps a separate cursor for each parent record. Because HubSpot returns events for one object at a time, each stream issues at least one request per parent record, per event type, per 30-day window between your **Start date** and now. On a portal with tens of thousands of contacts, that adds up quickly against your account's [daily API limit](#rate-limiting).

docs/integrations/sources/hubspot.md:211

• These Web Analytics streams use the object stream as a SubstreamPartitionRouter parent, so the same start_date also filters which parent records are discovered (for example, contacts are filtered by lastmodifieddate). Recommending the event date alone can omit events for older parent records that still have activity; document this parent-discovery constraint.

- Set **Start date** to the earliest date you actually need events for. If you leave it empty, the connector backfills from `2006-06-01T00:00:00Z`.

docs/integrations/sources/hubspot.md:491

• The crash also occurs when a full-refresh association stream is changed to incremental, not only when it is deselected. Users in that state will see the same startup error but will not match this troubleshooting entry; mention both ways the stream can leave the full-refresh set.

  - Versions 6.6.0 through 6.8.1 crash at startup, failing the whole sync, if your connection deselects an association stream whose parent object stream syncs incrementally.

• Files reviewed: 1/1 changed files
• Comments generated: 2
• Review effort level: Lite

[devin-ai-integration]

☑️ Resolved in a245752. Also applied the three suppressed comments from the latest Copilot review, since all three checked out against the code:

• Web Analytics request estimate (:206) — the per-parent × per-event-type × per-30-day-window fanout now describes the initial backfill, with a sentence noting that later syncs resume from each parent record's saved occurredAt cursor and only request the windows after that record's last event.
• start_date and parent discovery (:211) — documented that Start date also bounds which parent records get discovered: the SubstreamPartitionRouter lists parents from the parent object stream, which filters on the parent's own last-modified date, so a recent start date omits events for older records that haven't been modified since then.
• Association-stream startup crash (:491) — broadened the trigger. The connector version-bump PR (chore(source-hubspot): update CDK to 7.28.0 to fix association-stream startup crash #84917) described it as "a full-refresh association stream … is deselected", but the CDK fix (fix(declarative): ignore full-refresh sentinel in parent state seeding airbyte-python-cdk#1079) is keyed on the child stream's saved full-refresh sentinel state being re-keyed onto the parent's datetime cursor, and its regression test covers the "stream converted to incremental" case explicitly. The entry now covers both paths and states the mechanism.

markdownlint is at parity with master (30 findings, identical signatures) after the change.

[Copilot]

🔵 Needs a closer look

Three unresolved documentation nit comments remain.

Review details

Suppressed comments (3)

Previously missed (1) — in code that hasn't changed since the last review.

docs/integrations/sources/hubspot.md:495

• This statement is too broad for legacy blob-destination versions: the S3 migration guide says the schema-driven drop behavior was introduced in destination-s3 1.0.0, while older Avro/Parquet writers accumulated undeclared fields in _airbyte_additional_properties; the GCS migration likewise documents legacy 0.4.x output. Qualify the affected destinations as V2/current S3/GCS formats (or link the migration guide), otherwise users on legacy versions may be told their fields were dropped when they were retained in the catch-all.

docs/integrations/sources/hubspot.md:202

• Re-authentication is not sufficient for Airbyte Cloud's managed OAuth unless the shared HubSpot OAuth app is also registered for these scopes. The Web Analytics PR notes that without the shared app's business-intelligence registration, re-auth cannot grant the scope and these streams continue to fail with 403; please document that prerequisite or provide the own-OAuth-app/private-app alternative.

If you authenticate with OAuth, `business-intelligence` and `crm.objects.line_items.read` were added to the scopes Airbyte requests in version 6.8.0. Sources authorized before that version don't have them. Open the HubSpot source's settings and re-authenticate, then refresh the source schema, or these streams return 403 errors.

docs/integrations/sources/hubspot.md:206

• Each Web Analytics request is partitioned by both the parent ID and the event_type router, so the cursor is not solely per parent record. Describing later syncs as resuming from “that record's last event” can imply that one event type's cursor applies to the other and misstates the backfill/resume behavior; document the parent/event-type partition instead.

These streams sync incrementally on the `occurredAt` timestamp, and Airbyte keeps a separate cursor for each parent record. Because HubSpot returns events for one object at a time, the initial backfill issues at least one request per parent record, per event type, per 30-day window between your **Start date** and now. On a portal with tens of thousands of contacts, that first sync adds up quickly against your account's [daily API limit](#rate-limiting). Later syncs resume from each parent record's saved cursor, so they only request the windows after that record's last event.

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[github-actions]

[markdownlint] _{reported by reviewdog 🐶}
error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]

[github-actions]

[markdownlint] _{reported by reviewdog 🐶}
error MD060/table-column-style Table column style [Table pipe does not align with header for style "aligned"]

[github-actions]

[markdownlint-fix] _{reported by reviewdog 🐶}

Suggested change

	| Version | Date | Pull Request | Subject |
	|:------------|:-----------|:---------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
	| Version | Date | Pull Request | Subject |
	| :------------ | :----------- | :--------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |