docs: on-prem oauth

dstala · dstala · commit 29716d18ac74 · 2025-11-26T21:55:24.000+05:30
Signed-off-by: Raju Udava &lt;86527202+dstala@users.noreply.github.com&gt;
diff --git a/content/docs/noco-sync/index.mdx b/content/docs/noco-sync/index.mdx
@@ -8,25 +8,27 @@ keywords: ['NocoSync overview', 'NocoDB data sync', 'no-code data integration',
 
 <Callout type="info">Available on NocoDB Cloud Business plan onwards and Self-Hosted Enterprise Edition.</Callout>
 
+![NocoSync Banner](/img/v2/noco-sync/sync-banner.png)
+
 **NocoSync** is a built-in integration layer in NocoDB that allows you to bring data from external systems directly into your workspace. It keeps your NocoDB tables continuously updated by syncing records from third-party platforms, eliminating the need for manual imports or custom scripts.
 
-The first release introduces support for the **Ticketing** category, enabling you to connect with platforms such as **GitHub, GitLab, Bitbucket, Zendesk, Linear, Freshdesk, and Chatwoot**. Once connected, NocoSync pulls tickets, issues, conversations and related metadata into NocoDB, allowing teams to centralize reporting, automate workflows, and unlock insights across tools.
+Current release introduces support for the **Ticketing** category, enabling you to connect with platforms such as **GitHub, GitLab, Bitbucket, Zendesk, Linear, Freshdesk, and Chatwoot**. Once connected, NocoSync pulls tickets, issues, conversations and related metadata into NocoDB, allowing teams to centralize reporting, automate workflows, and unlock insights across tools.
 
-Additional sync categories—such as **CRM** and **File Storage**—will be added in future releases, expanding the types of systems you can bring into NocoDB.
+Additional sync categories—such as **CRM** (Customer Relationship Management), **HRIS** (Human Resources Information System, Accounting), **Accounting**, **ATS** (Application Tracking System) and **File Storage**—will be added in future releases, expanding the types of systems you can bring into NocoDB.
 
 NocoSync runs on a simple setup, supports scheduled syncs, and ensures high reliability, so your workspace always reflects the most recent data from your external sources. It is designed to be flexible, scalable, and accessible to both technical and non-technical users.
 
 ---
 
 ## How Sync Works
 
-NocoSync is designed around **predefined schemas** for each category, such as Ticketing, ensuring a consistent structure across all supported sources. When a sync is configured, NocoSync automatically creates multiple tables—such as Ticket, User, Comment, and Team. Essential tables are included by default and optional ones can be added based on need. All required relationships between these tables are generated automatically, mirroring the hierarchy and linkages of the connected source system.
+NocoSync is designed around **predefined schemas** for each category, such as Ticketing, ensuring a consistent structure across all supported sources. When a sync is configured, NocoSync automatically creates multiple tables (such as _Ticket_, _User_, _Comment_, and _Team_ in case of Ticketing). All required relationships between these tables are generated automatically, mirroring the hierarchy and linkages of the connected source system.
 
-Sync table fields created by NocoSync are **read-only**, as the sync operates strictly one-way—from the source system into NocoDB. Fields that originate from the external source are marked with a flash icon and cannot be removed, and sync tables themselves cannot be deleted. While schemas for each sync category are predefined, the actual fields available may vary by source. Different platforms use different naming conventions or may not expose all fields. NocoSync intelligently maps available fields from the source to the predefined schema to maintain consistency.
+Sync table fields created by NocoSync are **read-only**, as the sync operates strictly one-way—from the source system into NocoDB. Fields that originate from the external source are marked with a flash icon (⚡) and cannot be removed, and sync tables themselves cannot be deleted. While schemas for each sync category are predefined, the actual fields available may vary by source. Different platforms use different naming conventions or may not expose all fields. NocoSync intelligently maps available fields from the source to the predefined schema to maintain consistency.
 
-Users can extend sync tables by adding their own **custom fields** or modifying non-sync fields as needed. Beyond the read-only limitations on synced fields, sync tables behave like regular NocoDB tables. They can be shared with collaborators, used in views, and linked to other tables—allowing you to connect synced data with non-sync data for richer workflows and insights.
+Users can extend sync tables by adding their own **custom fields** as needed. Beyond the read-only limitations on synced fields, sync tables behave like regular NocoDB tables. They can be shared with collaborators, used in views, and linked to other tables.
 
-Currently, each sync category supports one external source at a time. When multi-source support is introduced, NocoDB will act as a **unified API** layer across all connected systems, allowing you to query, analyze, and build on top of data coming from multiple platforms through a single, consistent interface. This will significantly simplify integrations and expand the power of NocoSync across complex environments.
+Currently, each sync category supports one external source at a time. When multi-source support is introduced, NocoDB will act as a **Unified API** layer across all connected systems, allowing you to query, analyze, and build on top of data coming from multiple platforms through a single, consistent interface. This will significantly simplify integrations and expand the power of NocoSync across complex environments.
 
 Standard operations on Sync fields such as filtering, sorting, grouping, and searching are fully supported. You can create views, dashboards, and reports using synced data just like with any other NocoDB table.
 
@@ -42,7 +44,7 @@ Incremental sync fetches only the records that have been created or updated sinc
 
 ### **Full Sync**
 
-Full sync re-imports the entire dataset from the external source during each run. This mode is helpful in scenarios where the underlying data model has changed, historical data needs correction, or the source system does not reliably provide incremental change information. While full sync ensures complete data accuracy, it requires more time and can be resource-intensive—especially for large datasets. It is best used occasionally or in combination with incremental sync after significant schema updates or structural changes in the source system.
+Full sync re-imports the entire dataset from the external source during each run. This mode is helpful in scenarios where historical data needs correction, or the source system does not reliably provide incremental change information. While full sync ensures complete data accuracy, it requires more time and can be resource-intensive—especially for large datasets. It is best used occasionally or in combination with incremental sync.
 
 
 ## Sync Trigger
@@ -62,17 +64,17 @@ Scheduled sync automates data updates at regular intervals, ensuring your NocoDB
 
 ---
 
-## Source Delete Handling
+## Source Record Delete Handling
 
-NocoSync provides control over how deletions from the external source are reflected inside NocoDB. This setting helps you decide whether to maintain historical visibility or keep your tables strictly aligned with the source system.
+NocoSync provides control over how record deletions from the external source are reflected inside NocoDB. This setting helps you decide whether to maintain records for historical visibility or keep your tables strictly aligned with the source system.
 
 ### **Ignore**
 
 When set to *Ignore*, NocoDB **retains the record** even if it is deleted at the source. Instead of removing it, NocoSync marks the record to indicate that it has been deleted in the external system. This mode is useful when you want to preserve full history, maintain reporting continuity, or avoid breaking dependencies with linked records.
 
 ### **Delete**
 
-When set to *Delete*, NocoDB removes records when they are deleted at the source. This option keeps your NocoDB tables fully synchronized and consistent with the external platform.
+When set to *Delete*, NocoDB removes records in sync tables when they are deleted at the source. This option keeps your NocoDB tables fully synchronized and consistent with the external platform.
 
 ---
 
@@ -131,4 +133,4 @@ To delete an existing NocoSync integration, open sync tab from base overview pag
 
 <Callout type="warning">Deleting a sync integration is irreversible and will permanently remove all associated sync tables and data from your base. Ensure you have backed up any important information before proceeding.</Callout>
 
----
+---
diff --git a/content/docs/noco-sync/meta.json b/content/docs/noco-sync/meta.json
@@ -1,6 +1,7 @@
 {
   "title": "NocoSync",
   "pages": [
-    "ticketing"
+    "ticketing",
+    "on-premise-oauth"
   ]
 }
diff --git a/content/docs/noco-sync/on-premise-oauth/bitbucket.mdx b/content/docs/noco-sync/on-premise-oauth/bitbucket.mdx
@@ -0,0 +1,84 @@
+---
+title: "Bitbucket"
+description: "Instructions for setting up Bitbucket authentication integration for NocoDB"
+tags: ["Bitbucket", "OAuth2", "Integration"]
+keywords: ["Bitbucket OAuth2 setup", "NocoDB Bitbucket integration", "Bitbucket authentication"]
+---
+
+<Callout type="info">This page is intended for on-premise enterprise NocoDB installations.</Callout>
+
+This document provides instructions for setting up the Bitbucket authentication integration for NocoDB.
+
+## Environment Variables
+
+To enable OAuth2 authentication with Bitbucket, you need to configure the following environment variables.
+
+---
+
+## Step 1: Create a Bitbucket OAuth Consumer
+
+1. Log in to your Bitbucket account
+2. Navigate to Bitbucket Administration **Workspace settings → OAuth consumers**
+* (Bitbucket → left sidebar → click your workspace → **Workspace settings** → **OAuth consumers**)
+3. Click on **“Add consumer”**
+4. Fill out the form:
+
+* **Name**: Your application name (e.g., "NocoDB")
+* **Description**: Brief description of your application
+* **Callback URL**:
+`https://your-nocodb-instance.com/`
+* **Permissions**: Enable:
+
+* **Repositories**: Read & Write
+* **Pull requests**: Read & Write
+* **Issues**: Read & Write
+* **Account**: Read
+5. Click **Save**
+
+---
+
+## Step 2: Get Client ID and Client Secret
+
+After creating your OAuth consumer:
+
+1. Bitbucket will display:
+
+* **Key** → Client ID
+* **Secret** → Client Secret
+2. Copy both values (the Secret is shown **only once**)
+3. Store them safely for configuration
+
+---
+
+## Step 3: Set Environment Variables
+
+Configure your NocoDB instance with:
+
+```
+INTEGRATION_AUTH_BITBUCKET_CLIENT_ID=your_bitbucket_client_id
+INTEGRATION_AUTH_BITBUCKET_CLIENT_SECRET=your_bitbucket_client_secret
+INTEGRATION_AUTH_BITBUCKET_REDIRECT_URI=your_redirect_uri
+```
+
+Where:
+
+* `your_bitbucket_client_id` → The **Key (Client ID)** from Bitbucket
+* `your_bitbucket_client_secret` → The **Secret (Client Secret)**
+* `your_redirect_uri` → The callback URL used in the OAuth consumer
+(e.g., `https://your-nocodb-instance.com/`)
+
+---
+
+## OAuth Scopes Requested
+
+The integration will request these Bitbucket scopes:
+
+* `repository`
+* `repository:write`
+* `pullrequest`
+* `pullrequest:write`
+* `issue`
+* `issue:write`
+* `account`
+
+These permissions allow NocoDB to read/write repositories, issues, and pull requests as needed.
diff --git a/content/docs/noco-sync/on-premise-oauth/github.mdx b/content/docs/noco-sync/on-premise-oauth/github.mdx
@@ -0,0 +1,59 @@
+---
+title: "GitHub"
+description: "Instructions for setting up GitHub authentication integration for NocoDB"
+tags: ["GitHub", "OAuth2", "Integration"]
+keywords: ["GitHub OAuth2 setup", "NocoDB GitHub integration", "GitHub authentication"]
+---
+
+<Callout type="info">This page is intended for on-premise enterprise NocoDB installations.</Callout>
+
+This document provides instructions for setting up the GitHub authentication integration for NocoDB.
+
+## Environment Variables
+
+To enable OAuth2 authentication with GitHub, you need to set up the following environment variables:
+
+### Step 1: Create a GitHub OAuth App
+
+1. Log in to your GitHub account
+2. Navigate to Settings > Developer settings > OAuth Apps
+3. Click on "New OAuth App"
+4. Fill out the form:
+
+- **Application name**: Your application name (e.g., "NocoDB")
+- **Homepage URL**: Your application's homepage URL
+- **Application description**: (Optional) Brief description of your app
+- **Authorization callback URL**: The URL where GitHub will redirect users after authorization (e.g., `https://your-nocodb-instance.com/`)
+- **Icon**: (Optional) Upload an icon for your application
+
+5. Click "Register application"
+
+### Step 2: Get Client ID and Client Secret
+
+After registering your OAuth App, you'll be provided with:
+
+- Client ID
+- Client Secret (click "Generate a new client secret" to create one)
+
+### Step 3: Set Environment Variables
+
+Configure your NocoDB instance with the following environment variables:
+
+```
+INTEGRATION_AUTH_GITHUB_CLIENT_ID=your_github_client_id
+INTEGRATION_AUTH_GITHUB_CLIENT_SECRET=your_github_client_secret
+INTEGRATION_AUTH_GITHUB_REDIRECT_URI=your_redirect_uri
+```
+
+Where:
+
+- `your_github_client_id`: The Client ID from your GitHub OAuth App
+- `your_github_client_secret`: The Client Secret from your GitHub OAuth App
+- `your_redirect_uri`: The callback URL you specified when creating the OAuth App (e.g., `https://your-nocodb-instance.com/api/v1/integrations/auth/github/callback`)
+
+## OAuth Scopes
+
+This integration requests the following GitHub scopes:
+
+- `read:user`: Read-only access to user profile data
+- `repo`: Full control of repositories
diff --git a/content/docs/noco-sync/on-premise-oauth/gitlab.mdx b/content/docs/noco-sync/on-premise-oauth/gitlab.mdx
@@ -0,0 +1,53 @@
+---
+title: "GitLab"
+description: "Instructions for setting up GitLab authentication integration for NocoDB"
+tags: ["GitLab", "OAuth2", "Integration"]
+keywords: ["GitLab OAuth2 setup", "NocoDB GitLab integration", "GitLab authentication"]
+---
+
+<Callout type="info">This page is intended for on-premise enterprise NocoDB installations.</Callout>
+
+This document provides instructions for setting up the GitLab authentication integration for NocoDB.
+
+## Environment Variables
+
+To enable OAuth2 authentication with GitLab, you need to set up the following environment variables:
+
+### Step 1: Create a GitLab OAuth Application
+
+1. Log in to your GitLab account
+2. Navigate to User Settings > Applications (or for organization-wide application, go to your Group settings > Applications)
+3. Fill out the form:
+- **Name**: Your application name (e.g., "NocoDB")
+- **Redirect URI**: The URL where GitLab will redirect users after authorization (e.g., `https://your-nocodb-instance.com/`)
+- **Scopes**: Select the following scopes:
+- `api` (API access)
+- `read_user` (Read user information)
+4. Click "Save application"
+
+### Step 2: Get Application ID and Secret
+
+After creating your OAuth App, you'll be provided with:
+- Application ID (Client ID)
+- Secret (Client Secret)
+
+### Step 3: Set Environment Variables
+
+Configure your NocoDB instance with the following environment variables:
+
+```
+INTEGRATION_AUTH_GITLAB_CLIENT_ID=your_gitlab_client_id
+INTEGRATION_AUTH_GITLAB_CLIENT_SECRET=your_gitlab_client_secret
+INTEGRATION_AUTH_GITLAB_REDIRECT_URI=your_redirect_uri
+```
+
+Where:
+- `your_gitlab_client_id`: The Application ID from your GitLab OAuth App
+- `your_gitlab_client_secret`: The Secret from your GitLab OAuth App
+- `your_redirect_uri`: The callback URL you specified when creating the OAuth App (e.g., `https://your-nocodb-instance.com/`)
+
+## OAuth Scopes
+
+This integration requests the following GitLab scopes:
+- `api`: Access to the GitLab API
+- `read_user`: Read-only access to user profile data
diff --git a/content/docs/noco-sync/on-premise-oauth/linear.mdx b/content/docs/noco-sync/on-premise-oauth/linear.mdx
@@ -0,0 +1,70 @@
+---
+title: "Linear"
+description: "Instructions for setting up Linear authentication integration for NocoDB"
+tags: ["Linear", "OAuth2", "Integration"]
+keywords: ["Linear OAuth2 setup", "NocoDB Linear integration", "Linear authentication"]
+---
+
+<Callout type="info">This page is intended for on-premise enterprise NocoDB installations.</Callout>
+
+This document provides instructions for setting up the Linear authentication integration for NocoDB.
+
+## Environment Variables
+
+To enable OAuth2 authentication with Linear, you need to set up the following environment variables:
+
+### Step 1: Create a Linear OAuth App
+
+1. Log in to your Linear account
+2. Navigate to Settings > API > OAuth applications (or go directly to https://linear.app/settings/api/applications)
+3. Click on "New OAuth application"
+4. Fill out the form:
+- **Application Name**: Your application name (e.g., "NocoDB")
+- **Developer Name**: The person or company developing this application (e.g., "NocoDB")
+- **Developer URL**: Homepage or documentation for your application (e.g., "https://nocodb.com/")
+- **Description**: Brief description of your application
+- **Callback URIs**: The URL where Linear will redirect users after authorization (e.g., `https://your-nocodb-instance.com/`)
+- **Enable “Public”**: Turn ON to allow all Linear workspaces to authorize
+- **Icon**: (Optional) Upload an icon for your application
+5. Click "Create"
+
+### Step 2: Get Client ID and Client Secret
+
+After creating your OAuth application:
+1. You'll be shown the Client ID and Client Secret
+2. Copy these values as they will be needed for configuration
+
+### Step 3: Set Environment Variables
+
+Configure your NocoDB instance with the following environment variables:
+
+```
+INTEGRATION_AUTH_LINEAR_CLIENT_ID=your_linear_client_id
+INTEGRATION_AUTH_LINEAR_CLIENT_SECRET=your_linear_client_secret
+INTEGRATION_AUTH_LINEAR_REDIRECT_URI=your_redirect_uri
+```
+
+Where:
+- `your_linear_client_id`: The Client ID from your Linear OAuth App
+- `your_linear_client_secret`: The Client Secret from your Linear OAuth App
+- `your_redirect_uri`: The redirect URI you specified when creating the OAuth App (e.g., `https://your-nocodb-instance.com/api/v1/integrations/auth/linear/callback`)
+
+## API Key Authentication
+
+If you're using API Key authentication instead of OAuth:
+
+1. Log in to your Linear account
+2. Navigate to Settings > API > Personal API keys (or go directly to https://linear.app/settings/api)
+3. Under "Personal API keys", enter a name for your key
+4. Click "Create key"
+5. Copy the generated API key (you won't be able to see it again)
+
+You'll need to provide this API key when configuring the integration with the API Key authentication method.
+
+## OAuth Scopes
+
+This integration requests the following Linear scopes:
+- `read`: Read access to workspace data
+- `write`: Write access to workspace data
+
+These scopes allow the integration to read and modify issues, projects, and other data in your Linear workspace. 
diff --git a/content/docs/noco-sync/on-premise-oauth/meta.json b/content/docs/noco-sync/on-premise-oauth/meta.json
@@ -0,0 +1,9 @@
+{
+  "title": "On Premise Auth Integration",
+  "pages": [
+    "bitbucket",
+    "github",
+    "gitlab",
+    "linear"
+  ]
+}
diff --git a/public/img/v2/noco-sync/sync-banner.png b/public/img/v2/noco-sync/sync-banner.png
diff --git a/public/img/v2/noco-sync/sync-delete-1.png b/public/img/v2/noco-sync/sync-delete-1.png
diff --git a/public/img/v2/noco-sync/sync-delete-2.png b/public/img/v2/noco-sync/sync-delete-2.png

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"title": "NocoSync",`
`3`	`3`	`"pages": [`
`4`		`- "ticketing"`
	`4`	`+ "ticketing",`
	`5`	`+ "on-premise-oauth"`
`5`	`6`	`]`
`6`	`7`	`}`