Docs for new orgs and workspaces redesign aka Org Landing Page #66550

ian-at-airbyte · 2025-09-19T23:44:41Z

What

This PR updates docs.airbyte.com to be consistent with the new sidebar/org landing page changes in Airbyte. This is a very large PR that touches almost every section of the docs site.

How

New "Organizations and workspaces" section: Created a new section to improve and expand the discussion of what these objects are in Airbyte. Pays particular regard to Enterprise Flex, data residency, and self-managed data planes. Moved most organization and workspace settings discussions to be children of that new section. In limited cases, a topic seemed thematically more relevant to another part of the docs, so I left it alone. Completely removed the "Account Management" section, because it was almost entirely about orgs and workspaces.
Updated instructions and screenshots: Updated all user, organization, and workspace settings tasks and instructions. Content now passes checks with MarkDownLint. Almost all of this info needed some level of rewrite, which is why this PR touches so many files. Where screenshots seemed valuable, I kept them and updated them. Several seemed unimportant on review, so I just removed them.
Mermaid diagram visual improvement: Added some color and spacing configuration to Mermaid diagrams so I could write some supporting flow diagrams. These changes aren't perfect, but they make the diagrams slightly more appealing than before. More work is needed on Mermaid's appearance, it just wasn't the focus of this task. These changes were applied in the main Docusaurus configuration file, so they would apply globally.
Consolidation of redundant content: Many connector migration guides had the same instructions. Instead of updating them all, I've added instructions on how to pin and update connectors to the Upgrading Connectors page. Then, updated connector migration guides to link to those instructions instead of reproducing them. This triggers review from Breaking Change Reviewers.
General cleanup of random problem areas, misspellings, typos, etc. that I noticed along the way.
Made a few additions to Vale's controlled vocabulary, to avoid linting those words.

Not part of this PR

This PR does not include new Arcades/interactive demos. I'll do this as a separate set of changes.

Review guide

The crux of the change is the creation of the new orgs and workspaces section. This is probably the area that should receive the most scrutiny.
Breaking change reviewers should ensure the changes to the migration guides are satisfactory.
It might be helpful to spot check the steps in other pages

User Impact

Accurate documentation and screenshots.
No changes to page URLs. This is a low risk set of changes.

Can this PR be safely reverted and rolled back?

YES 💚
NO ❌

…s under it, update content under Organizations.

… colors for Mermaid diagrams

…update all connector migration guides to reference these steps instead of writing their own

github-actions · 2025-09-19T23:45:04Z

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

Helpful Resources

PR Slash Commands

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

/format-fix - Fixes most formatting issues.
/bump-version - Bumps connector versions.
- You can specify a custom changelog by passing changelog. Example: /bump-version changelog="My cool update"
- Leaving the changelog arg blank will auto-populate the changelog from the PR title.
/run-cat-tests - Runs legacy CAT tests (Connector Acceptance Tests)
/build-connector-images - Builds and publishes a pre-release docker image for the modified connector(s).
/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.

📝 Edit this welcome message.

github-actions · 2025-09-19T23:50:44Z

Deploy preview for airbyte-docs ready!

✅ Preview
https://airbyte-docs-6q6ftii0r-airbyte-growth.vercel.app

Built with commit 360af8a.
This pull request is being automatically deployed with vercel-action

…. Also fixed and linted a PostgresSQL Cloud topic that was behaving strangely.

…ion in code font.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

…cy.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

docs/integrations/sources/postgres/cloud-sql-postgres.md

docs/platform/access-management/rbac.md

docs/platform/cloud/managing-airbyte-cloud/assets/cloud-status-page.png

docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-add-webhook.png

bgroff · 2025-09-23T02:08:35Z

docs/platform/cloud/managing-airbyte-cloud/manage-airbyte-cloud-notifications.md

 # Manage notifications

-This page provides guidance on how to manage notifications for Airbyte, allowing you to stay up-to-date on the activities in your workspace.
+If you want Airbyte to notify you about important events, use its built-in notification system.


Someone with more understanding of our notification system should review this.

docs/platform/cloud/managing-airbyte-cloud/manage-data-residency.md

docs/platform/enterprise-setup/assets/enterprise-applications-creation.png

docs/platform/images/organization-switch.png

bgroff · 2025-09-23T02:18:10Z

docs/platform/managing-airbyte/connector-updates.md

+### Airbyte Open Source (OSS) and Self-Managed Enterprise (SME)

-Airbyte recommends using an updated version of Airbyte when updating connections. 
+Airbyte recommends using an updated version of Airbyte when updating connections.


I know you did not write this on this PR but does Airbyte recommends using the latest version of Airbyte read better? I think that is what that is trying to say.

bgroff

Some questions and comments but nothing blocking.

joeykmh · 2025-09-24T08:59:33Z

docs/platform/access-management/sso-providers/azure-entra-id.md

+    :::info
+    Currently, this portion of the setup requires an Airbyte employee. Contact Support to proceed.
+    :::


Is this correct? Don't the following steps describe a self-serve SSO configuration?

For the moment, yeah. People were locking themselves out of their org so we had to shut this down temporarily until we had better validation.

joeykmh · 2025-09-24T09:00:43Z

docs/platform/access-management/sso-providers/azure-entra-id.md

-:::
-
-1. In Airbyte, click **Settings**.
+1. In Airbyte, click **Organization settings** > **General**.


Not sure if we want to call out when things require certain roles, but this setup is only visible to Org Admins. Maybe that's intuitive enough that it does not require an explicit mention here 🤷

I made a slight wording change that should make this more clear, but this requirement is established in the introduction of the Okta and Entra ID articles. So I think we're good here.

joeykmh · 2025-09-24T09:04:28Z

docs/platform/cloud/managing-airbyte-cloud/manage-airbyte-cloud-notifications.md

+If you want Airbyte to notify you of source schema changes, enable the following notifications.

-To set up email notifications, click **Settings** and navigate to **Workspace** > **Notifications**.
+- `Automatic Connection Updates`


I think this should be Connection updates, also the capitalization in the table vs. the items in this list is inconsistent. In the UI we capitalize all words, e.g. Connection Updates Requiring Action

joeykmh · 2025-09-24T09:05:12Z

docs/platform/cloud/managing-airbyte-cloud/manage-airbyte-cloud-notifications.md

+If these are off, even if you turned on schema update notifications in a connection's settings, Airbyte won't send notifications about schema changes.

-![](./assets/notifications-email.png)
+To edit this setting, click **Connections** and select the connection you want to receive notifications for. Click the **Settings** tab on the Connection page. In the **Advanced Settings**, toggle **Schema update notifications**.


This is named slightly different in the connection advanced settings:

joeykmh · 2025-09-24T09:10:07Z

docs/platform/enterprise-setup/api-access-config.md

 ## Step 1: Create an Application

-While logged into the Airbyte UI, go to the `settings/applications` page, then create an application to get a pair of `client_id` and `client_secret` credentials. This can be exchanged anytime to get an access token to make requests to the API. These credentials do not expire, but may be deleted at any time.
+1. In the navigation bar, click your user name > **Applications**.


I think this needs to be your user name > **User settings** > **Applications**

Thank you. Fixed.

joeykmh · 2025-09-24T09:14:22Z

docs/platform/managing-airbyte/connector-updates.md

+
+Self-Managed users must manually update the connector image in their local registry before proceeding with the migration. To do so:
+
+1. In the navigation bar, click **Workspace settings** > **Sources**/**Destinations**.


In SME we actually have the source/destination pages under Organization Settings:

I think the rationale is that in SME, connector updates affect all workspaces, so it makes more sense to have them at the org level. In OSS, users only have a single workspace (and no organization settings) so we have to put it in the workspace settings. In Cloud, workspaces can have their own connector version overrides, so it makes sense to keep connector versions there.

I did not realize this. Thank you!

joeykmh · 2025-09-24T09:15:52Z

docs/platform/operator-guides/telemetry.md

  
-  - In Airbyte, go to **Settings** > **User Settings** > **Cookie Preferences**.
-  - On Airbyte's website, click **Cookie Preferences** in the footer of our [homepage](https://airbyte.com).
+  - In the navigation bar, click your user name > **Cookie Preferences**.


Again here you need to click your user name, then "User settings", then "Cookie Preferences". Not sure if you intentionally left out that middle step or not.

Nope, just an omission. Thanks for catching it.

joeykmh · 2025-09-24T09:17:43Z

docs/platform/using-airbyte/workspaces.md

+You can create, manage, and delete workspaces, and control access to them.

-## Add users to your workspace
+## Create a new workspace


Might be worth noting that you need an Organization Editor or Organization Admin role to do this.

I've added the role requirements for each action.

joeykmh · 2025-09-24T09:19:53Z

docusaurus/sidebar-platform.js

+        {
+          type: "category",
+          label: "Organizations and workspaces",
+          link: {
+            type: "doc",
+            id: "organizations-workspaces/readme",
+          },


Is the Vercel deploy preview supposed to be showing the latest commit? It seems like it should, but I'm seeing this:

...which looks like an old version.

https://airbyte-docs-cfep36vq6-airbyte-growth.vercel.app/platform/

Yeah.

My guess is you might be viewing the 1.8 docs (you can see this in the version switcher in the nav bar).

https://airbyte-docs-py1nbmbqz-airbyte-growth.vercel.app/platform/next/organizations-workspaces/ should show the latest one.

joeykmh

Nice! Left some comments, but nothing blocking

…tead of a link. The UX in the app requires the user to click a link to get to the migration page, so we judged it a bad experience to then immediately ask them to go to another page again. This way still allows for a reusable set of text that can be easily updated, but the end user UX is less demanding.

docs/integrations/sources/asana-migrations.md

ian-at-airbyte

All review comments have been addressed and/or responded to. Thank you!

docs/integrations/sources/postgres/cloud-sql-postgres.md

docs/platform/cloud/managing-airbyte-cloud/assets/notification-slack-add-webhook.png

docs/platform/cloud/managing-airbyte-cloud/manage-data-residency.md

ian-at-airbyte · 2025-09-24T21:13:36Z

docusaurus/sidebar-platform.js

+        {
+          type: "category",
+          label: "Organizations and workspaces",
+          link: {
+            type: "doc",
+            id: "organizations-workspaces/readme",
+          },


Yeah.

My guess is you might be viewing the 1.8 docs (you can see this in the version switcher in the nav bar).

https://airbyte-docs-py1nbmbqz-airbyte-growth.vercel.app/platform/next/organizations-workspaces/ should show the latest one.

ian-at-airbyte · 2025-09-24T21:15:34Z

docs/platform/access-management/sso-providers/azure-entra-id.md

+    :::info
+    Currently, this portion of the setup requires an Airbyte employee. Contact Support to proceed.
+    :::


For the moment, yeah. People were locking themselves out of their org so we had to shut this down temporarily until we had better validation.

ian-at-airbyte · 2025-09-24T22:21:01Z

docs/platform/access-management/sso-providers/azure-entra-id.md

-:::
-
-1. In Airbyte, click **Settings**.
+1. In Airbyte, click **Organization settings** > **General**.


I made a slight wording change that should make this more clear, but this requirement is established in the introduction of the Okta and Entra ID articles. So I think we're good here.

ian-at-airbyte · 2025-09-24T22:25:56Z

docs/platform/cloud/managing-airbyte-cloud/manage-airbyte-cloud-notifications.md

+If you want Airbyte to notify you of source schema changes, enable the following notifications.

-To set up email notifications, click **Settings** and navigate to **Workspace** > **Notifications**.
+- `Automatic Connection Updates`


ian-at-airbyte · 2025-09-24T22:29:43Z

docs/platform/operator-guides/telemetry.md

  
-  - In Airbyte, go to **Settings** > **User Settings** > **Cookie Preferences**.
-  - On Airbyte's website, click **Cookie Preferences** in the footer of our [homepage](https://airbyte.com).
+  - In the navigation bar, click your user name > **Cookie Preferences**.


Nope, just an omission. Thanks for catching it.

ian-at-airbyte · 2025-09-25T00:53:12Z

docs/platform/using-airbyte/workspaces.md

+You can create, manage, and delete workspaces, and control access to them.

-## Add users to your workspace
+## Create a new workspace


I've added the role requirements for each action.

ian-at-airbyte · 2025-09-25T00:59:37Z

docs/platform/managing-airbyte/connector-updates.md

+
+Self-Managed users must manually update the connector image in their local registry before proceeding with the migration. To do so:
+
+1. In the navigation bar, click **Workspace settings** > **Sources**/**Destinations**.


I did not realize this. Thank you!

ian-at-airbyte · 2025-09-25T01:07:07Z

Just need approval from @katmarkham or @tybernstein as code owners and then I think we're good to merge.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

ian-at-airbyte added 9 commits September 11, 2025 14:20

Create orgs and workspaces section

003a499

Create the new organizaton and workspace section, move relevant topic…

6635155

…s under it, update content under Organizations.

Refined the organization explanation a bit, and added somewhat better…

15f4dea

… colors for Mermaid diagrams

Update workspace subsection

31c6eb1

Add actual connector update steps to the connector update page, then …

8667abd

…update all connector migration guides to reference these steps instead of writing their own

Update a variety of other pages that referenced the old Settings UI

c3a4106

Merge branch 'master' into docs-orgs-and-workspaces

8a58653

Fix a technical error with Cloud

5fbe3d4

Fix two broken links

960799c

ian-at-airbyte and others added 10 commits September 19, 2025 18:43

Fix a few more references to the old UI

99580ba

Update screenshots

29fce44

Remaining platform screenshot updates or deletions

cd06e5b

Updated and deleting remaining screenshots in the integrations folder…

19e5d74

…. Also fixed and linted a PostgresSQL Cloud topic that was behaving strangely.

Update Embedded screenshots

483f863

Update steps for platform docs that referenced the old "Settings" opt…

d57a646

…ion in code font.

Merge branch 'master' into docs-orgs-and-workspaces

012ef1f

Update docs/integrations/sources/zendesk-chat-migrations.md

6ba0a33

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update docs/platform/cloud/managing-airbyte-cloud/manage-data-residen…

c933970

…cy.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update docs/platform/managing-airbyte/connector-updates.md

db6334c

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

ian-at-airbyte changed the title ~~Docs for new orgs and workspaces redesign [WIP DO NOT MERGE]~~ Docs for new orgs and workspaces redesign Sep 22, 2025

ian-at-airbyte changed the title ~~Docs for new orgs and workspaces redesign~~ Docs for new orgs and workspaces redesign aka Org Landing Page Sep 22, 2025

ian-at-airbyte and others added 4 commits September 22, 2025 16:15

Update docs/platform/contributing-to-airbyte/developing-locally.md

c95ae2e

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update docs/platform/managing-airbyte/connector-updates.md

b6ec358

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update docs/platform/contributing-to-airbyte/developing-locally.md

f36dcb8

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Update docs/platform/managing-airbyte/connector-updates.md

f000947

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

ian-at-airbyte marked this pull request as ready for review September 22, 2025 23:18

ian-at-airbyte requested a review from a team as a code owner September 22, 2025 23:18