Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

[DOCS-1422] feat: create GitHub workflow or script to fetch troubleshooting (#51365)

Jeremias Menichelli05396e337887
diff --git a/.agents/skills/ask-the-docs/reference/app-map.md b/.agents/skills/ask-the-docs/reference/app-map.md
index bd50f01240a..009653bd6fc 100644
--- a/.agents/skills/ask-the-docs/reference/app-map.md
+++ b/.agents/skills/ask-the-docs/reference/app-map.md
@@ -53,8 +53,7 @@ flowchart TB
| -------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `app/` | Next.js App Router — thin route files that delegate to feature modules | Slug-based catch-alls per section, e.g. `guides/auth/[[...slug]]/page.tsx` |
| `apps/docs/content/guides/` | Source MDX for `/docs/guides/...` pages | One file per page; `_partials/` for shared blocks |
-| `apps/docs/content/_partials/` | Reusable MDX snippets included via `<$Partial path="..." />` | Recursion supported |
-| `apps/docs/content/troubleshooting/` | Troubleshooting articles | Some synced from GitHub issues via `Troubleshooting.script.mjs` |
+| `apps/docs/content/_partials/` | Reusable MDX snippets included via `<$Partial path="..." />` | Recursion supported | |
| `apps/docs/components/` | React components used inside MDX | One folder per component or component family |
| `apps/docs/data/` | Typed data modules consumed by components | `.data.ts` suffix; lookup helpers live in `.utils.ts`, not here |
| `apps/docs/lib/` | Pure library code shared across pipelines | Schemas (zod), helpers (`.utils.ts`), tests |
@@ -218,14 +217,10 @@ Wraps the app with:
- `DocsCommandProvider` / `DocsCommandMenu`
- `SiteLayout` from `layouts/`
-## Troubleshooting page subtree
-- `features/docs/Troubleshooting.page.tsx` — entry-level page renderer.
-- `features/docs/Troubleshooting.utils.ts` — TS utils.
-- `features/docs/Troubleshooting.utils.common.mjs` — `.mjs` because it's
- consumed by both the Next.js build _and_ a Node sync script with import
- resolution quirks. **Don't convert to `.ts`** without checking the sync
- script.
+- `features/docs/Troubleshooting.utils.common.mjs` — `.mjs`, shared between
+ the Next.js build and other scripts that read troubleshooting entries
+ (e.g. search embeddings generation).
- Topics enum in `TroubleshootingSchema` (the `topics` field) is the source
of truth for product tag values.
diff --git a/.agents/skills/ask-the-docs/reference/build-pipeline.md b/.agents/skills/ask-the-docs/reference/build-pipeline.md
index 74f0318bb3f..1c79a09f2d1 100644
--- a/.agents/skills/ask-the-docs/reference/build-pipeline.md
+++ b/.agents/skills/ask-the-docs/reference/build-pipeline.md
@@ -140,8 +140,6 @@ pnpm dev # http://localhost:3001/docs
```
- **`predev`** runs GraphQL and reference codegen plus example copy.
-- A concurrent watcher syncs troubleshooting content
- (`dev:watch:troubleshooting`).
- Community contributors: set `NEXT_PUBLIC_IS_PLATFORM=false` in `.env`.
- Supabase employees: `pnpm run dev:secrets:pull` for internal env vars
(AWS profile + `scripts/getSecrets.js`).
diff --git a/.agents/skills/ask-the-docs/reference/gotchas.md b/.agents/skills/ask-the-docs/reference/gotchas.md
index 54cbd296a64..ca659d7eee4 100644
--- a/.agents/skills/ask-the-docs/reference/gotchas.md
+++ b/.agents/skills/ask-the-docs/reference/gotchas.md
@@ -76,15 +76,6 @@ Specific traps to watch for. One-liner per item.
URLs are passed through. Use it consistently in markdown output to avoid
broken links.
-## Troubleshooting subtree
-
-- `Troubleshooting.utils.common.mjs` is `.mjs` because the troubleshooting
- sync script can't resolve `.ts` imports cleanly. Don't convert it.
-- Rebasing can resurrect a **stale** version of this file when you reset
- unrelated changes — verify against current `master` after
- `git checkout master -- <path>`.
-- The `topics` enum in `TroubleshootingSchema` is hand-maintained. Adding a
- new product means updating that enum.
## Build / CI
diff --git a/.github/workflows/docs-sync-troubleshooting.yml b/.github/workflows/docs-sync-troubleshooting.yml
deleted file mode 100644
index 4b671232b4e..00000000000
--- a/.github/workflows/docs-sync-troubleshooting.yml
+++ /dev/null
@@ -1,59 +0,0 @@
-name: '[Docs] Sync troubleshooting guides to GitHub Discussions'
-
-on:
- push:
- branches:
- - master
- paths:
- - 'apps/docs/content/troubleshooting/**'
- workflow_dispatch:
-
-permissions:
- contents: write
- pull-requests: write
-
-jobs:
- update-troubleshooting:
- runs-on: blacksmith-4vcpu-ubuntu-2404
-
- env:
- DOCS_GITHUB_APP_ID: ${{ secrets.SEARCH_GITHUB_APP_ID }}
- DOCS_GITHUB_APP_INSTALLATION_ID: ${{ secrets.SEARCH_GITHUB_APP_INSTALLATION_ID }}
- DOCS_GITHUB_APP_PRIVATE_KEY: ${{ secrets.SEARCH_GITHUB_APP_PRIVATE_KEY }}
- NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.SEARCH_SUPABASE_URL }}
- SUPABASE_SECRET_KEY: ${{ secrets.SEARCH_SUPABASE_SERVICE_ROLE_KEY }}
-
- steps:
- - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- with:
- persist-credentials: false
- sparse-checkout: |
- apps/docs
- patches
-
- - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
- name: Install pnpm
- with:
- run_install: false
-
- - name: Use Node.js
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
- with:
- node-version-file: '.nvmrc'
- cache: 'pnpm'
-
- - name: Install dependencies
- run: pnpm install --frozen-lockfile
-
- - name: Run Troubleshooting script
- run: pnpm run --filter docs troubleshooting:sync
-
- - name: Create Pull Request
- uses: peter-evans/create-pull-request@5e914681df9dc83aa4e4905692ca88beb2f9e91f # v7.0.5
- with:
- commit-message: '[bot] sync troubleshooting guides to db'
- title: '[bot] sync troubleshooting guides to db'
- author: 'github-docs-sync-bot <[email protected]>'
- branch: 'bot/docs-sync-troubleshooting'
- branch-suffix: 'random'
- labels: 'documentation'
diff --git a/.github/workflows/kb-troubleshooting-sync.yml b/.github/workflows/kb-troubleshooting-sync.yml
new file mode 100644
index 00000000000..0b8d235f677
--- /dev/null
+++ b/.github/workflows/kb-troubleshooting-sync.yml
@@ -0,0 +1,56 @@
+name: 'KB Troubleshooting Sync'
+
+on:
+ push:
+ branches:
+ - master
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ sync:
+ runs-on: blacksmith-4vcpu-ubuntu-2404
+
+ env:
+ KB_GITHUB_APP_ID: ${{ secrets.KB_GITHUB_APP_ID }}
+ KB_GITHUB_APP_INSTALLATION_ID: ${{ secrets.KB_GITHUB_APP_INSTALLATION_ID }}
+ KB_GITHUB_APP_PRIVATE_KEY: ${{ secrets.KB_GITHUB_APP_PRIVATE_KEY }}
+ NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}
+ SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}
+
+ steps:
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+ with:
+ persist-credentials: false
+ sparse-checkout: |
+ apps/kb
+ packages
+ patches
+
+ - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+ name: Install pnpm
+ with:
+ run_install: false
+
+ - name: Use Node.js
+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+ with:
+ node-version-file: '.nvmrc'
+ cache: 'pnpm'
+
+ - name: Install dependencies
+ run: pnpm install --frozen-lockfile
+
+ - name: Backfill legacy troubleshooting slugs
+ run: pnpm run --filter kb sync:legacy-slugs
+
+ - name: Fetch federated troubleshooting content
+ run: pnpm run --filter kb fetch:federated-content
+
+ - name: Sync new troubleshooting entries
+ run: pnpm run --filter kb sync:troubleshooting-entries
+
+ - name: Sync troubleshooting entry updates
+ run: pnpm run --filter kb sync:troubleshooting-updates
diff --git a/apps/docs/features/docs/Troubleshooting.script.mjs b/apps/docs/features/docs/Troubleshooting.script.mjs
deleted file mode 100644
index ff6e9eda6c7..00000000000
--- a/apps/docs/features/docs/Troubleshooting.script.mjs
+++ /dev/null
@@ -1,502 +0,0 @@
-// @ts-check
-
-/* eslint-disable turbo/no-undeclared-env-vars */
-
-/**
- * Sync new troubleshooting entries from the GitHub repo with GitHub
- * Discussions.
- */
-
-import '../../scripts/utils/dotenv.js'
-
-import { createAppAuth } from '@octokit/auth-app'
-import { Octokit } from '@octokit/core'
-import { createClient } from '@supabase/supabase-js'
-import { createHash } from 'crypto'
-import matter from 'gray-matter'
-import { fromMarkdown } from 'mdast-util-from-markdown'
-import { gfmFromMarkdown, gfmToMarkdown } from 'mdast-util-gfm'
-import { mdxFromMarkdown, mdxToMarkdown } from 'mdast-util-mdx'
-import { toMarkdown } from 'mdast-util-to-markdown'
-import { gfm } from 'micromark-extension-gfm'
-import { mdxjs } from 'micromark-extension-mdxjs'
-import { readFile, writeFile } from 'node:fs/promises'
-import { parse, stringify } from 'smol-toml'
-
-import {
- getAllTroubleshootingEntriesInternal as getAllTroubleshootingEntries,
- getArticleSlug,
-} from './Troubleshooting.utils.common.mjs'
-
-const REPOSITORY_ID = 'MDEwOlJlcG9zaXRvcnkyMTQ1ODcxOTM='
-const TROUBLESHOOTING_CATEGORY_ID = 'DIC_kwDODMpXOc4CUvEr'
-const REPOSITORY_OWNER = 'supabase'
-const REPOSITORY_NAME = 'supabase'
-
-/**
- * @typedef {import('./Troubleshooting.utils.common.mjs').TroubleshootingEntry} TroubleshootingEntry
- * @typedef {import('./Troubleshooting.utils.common.mjs').TroubleshootingMetadata} TroubleshootingMetadata
- */
-
-/**
- * @type {import('@octokit/core').Octokit}
- */
-let octokitInstance
-/**
- * @type {import('@supabase/supabase-js').SupabaseClient<import('../../../../packages/common').Database>}
- */
-let supabaseAdminClient
-
-function octokit() {
- if (!octokitInstance) {
- octokitInstance = new Octokit({
- authStrategy: createAppAuth,
- auth: {
- appId: process.env.DOCS_GITHUB_APP_ID,
- installationId: process.env.DOCS_GITHUB_APP_INSTALLATION_ID,
- privateKey: process.env.DOCS_GITHUB_APP_PRIVATE_KEY,
- },
- })
- }
-
- return octokitInstance
-}
-
-export function supabaseAdmin() {
- if (!supabaseAdminClient) {
- supabaseAdminClient = createClient(
- /** @type {string} */ (process.env.NEXT_PUBLIC_SUPABASE_URL),
- /** @type {string} */ (process.env.SUPABASE_SECRET_KEY)
- )
- }
-
- return supabaseAdminClient
-}
-
-async function syncTroubleshootingEntries() {
- console.log('[START] Syncing troubleshooting entries to GitHub')
-
- const [troubleshootingEntries, discussions] = await Promise.all([
- getAllTroubleshootingEntries(),
- getAllTroubleshootingDiscussions(),
- ])
-
- console.log(`[INFO] Found ${troubleshootingEntries.length} existing entries`)
-
- const tasks = troubleshootingEntries.map(async (entry) => {
- const databaseId = entry.data.database_id
- if (databaseId.startsWith('pseudo-')) {
- // The database entry is faked, so we may need to create a new one.
- // There's also an edge case we need to check for: the entry has already
- // been created, but the new database ID hasn't been written to the file
- // yet.
- if (await entryExists(entry)) return
-
- const discussion = entry.data.github_url
- ? await getGithubIdForDiscussion(discussions, entry)
- : await createGithubDiscussion(entry)
-
- let id
- try {
- id = await insertNewTroubleshootingEntry(entry, discussion)
- } catch (error) {
- console.error(`[ERROR] Failed to insert new entry for ${entry.data.title}: %O`, error)
- console.log(
- `[INFO] Rolling back discussion creation for ${entry.data.title} (GitHub ID ${discussion.id})`
- )
- await rollbackGithubDiscussion(discussion.id)
- throw error
- }
-
- await updateFileId(entry, id)
- } else {
- // The database entry already exists, so check for updates.
- const contentHasChanged = await updateChecksumIfNeeded(entry)
- if (contentHasChanged) {
- await updateGithubDiscussion(entry)
- }
- }
- })
-
- const results = await Promise.allSettled(tasks)
- let hasErrors = false
- results.forEach((result, index) => {
- if (result.status === 'rejected') {
- console.error(
- `[ERROR] Failed to insert and/or update for ${troubleshootingEntries[index].filePath}:\n%O`,
- result.reason?.errors ?? result.reason
- )
- hasErrors = true
- }
- })
-
- return hasErrors
-}
-
-/**
- * @param {TroubleshootingEntry} entry
- * @throws If the database check fails for some unknown reason
- */
-async function entryExists(entry) {
- const checksum = calculateChecksum(entry.content)
- const { error } = await supabaseAdmin()
- .from('troubleshooting_entries')
- .select('id')
- .eq('checksum', checksum)
- .single()
-
- if (error) {
- if (error.code === 'PGRST116') {
- // No entry found
- return false
- }
- throw error
- }
-
- console.log(
- `[INFO] Entry for ${entry.data.title} already exists. Not creating a new one to prevent duplicates.`
- )
- return true
-}
-
-/**
- * @param {string} content
- */
-function calculateChecksum(content) {
- // Normalize to ignore changes that don't affect the final displayed content.
- const mdast = fromMarkdown(content, {
- extensions: [gfm(), mdxjs()],
- mdastExtensions: [gfmFromMarkdown(), mdxFromMarkdown()],
- })
- const bodyNormalized = toMarkdown(mdast, { extensions: [gfmToMarkdown(), mdxToMarkdown()] })
-
- const { data, content: body } = matter(bodyNormalized, {
- language: 'toml',
- engines: { toml: parse },
- })
- const newFrontmatter = stringify(data)
- const normalized = `---\n${newFrontmatter}\n---\n${body}`
-
- return createHash('sha256').update(normalized).digest('base64')
-}
-
-/**
- * @param {TroubleshootingEntry} entry
- *
- * @param {Object} discussion
- * @param {string} discussion.id
- * @param {string} discussion.url
- *
- * @throws If the database insertion fails
- */
-async function insertNewTroubleshootingEntry(entry, discussion) {
- console.log(`[INFO] Inserting entry for ${entry.data.title} into DB`)
-
- const now = new Date().toISOString()
- const checksum = calculateChecksum(entry.content)
-
- const { data, error } = await supabaseAdmin()
- .from('troubleshooting_entries')
- .insert({
- api: entry.data.api,
- checksum,
- date_created: entry.data.date_created?.toISOString() ?? now,
- date_updated: now,
- errors: entry.data.errors,
- github_id: discussion.id,
- github_url: discussion.url,
- keywords: entry.data.keywords,
- title: entry.data.title,
- topics: entry.data.topics,
- })
- .select('id')
- .single()
- if (error) {
- throw error
- }
-
- return data.id
-}
-
-/**
- * @param {TroubleshootingEntry} entry
- *
- * @throws If the database update fails
- */
-async function updateChecksumIfNeeded(entry) {
- const { data, error } = await supabaseAdmin()
- .from('troubleshooting_entries')
- .select('checksum')
- .eq('id', entry.data.database_id)
- .single()
- if (error) {
- throw error
- }
-
- const newChecksum = calculateChecksum(entry.content)
- if (data.checksum !== newChecksum) {
- console.log(`[INFO] Content changed for ${entry.data.title}. Updating checksum.`)
-
- const now = new Date().toISOString()
- const { error } = await supabaseAdmin()
- .from('troubleshooting_entries')
- .update({
- checksum: newChecksum,
- date_updated: now,
- })
- .eq('id', entry.data.database_id)
-
- if (error) {
- throw error
- }
-
- return true
- }
-
- return false
-}
-
-/**
- * Converts relative links to absolute URLs for GitHub discussions using MDAST
- * @param {string} content - The markdown content to process (already stripped of JSX)
- */
-function rewriteRelativeLinks(content) {
- const baseUrl = 'https://supabase.com'
-
- // Parse the markdown to AST
- const mdast = fromMarkdown(content, {
- extensions: [gfm()],
- mdastExtensions: [gfmFromMarkdown()],
- })
-
- // Walk the tree and modify link nodes
- /**
- * @param {import('mdast').Root|import('mdast').Content} node
- */
- function visitNode(node) {
- if (node.type === 'link' && node.url && node.url.startsWith('/')) {
- // Convert relative URL to absolute
- node.url = `${baseUrl}${node.url}`
- }
-
- // Recursively visit children
- if ('children' in node) {
- node.children.forEach(visitNode)
- }
- }
-
- visitNode(mdast)
-
- // Convert back to markdown
- return toMarkdown(mdast, { extensions: [gfmToMarkdown()] })
-}
-
-/**
- * @param {TroubleshootingEntry} entry
- */
-function addCanonicalUrl(entry) {
- const docsUrl = 'https://supabase.com/docs/guides/troubleshooting/' + getArticleSlug(entry)
- const contentWithAbsoluteLinks = rewriteRelativeLinks(entry.contentWithoutJsx)
- const content =
- `_This is a copy of a troubleshooting article on Supabase's docs site. It may be missing some details from the original. View the [original article](${docsUrl})._\n\n` +
- contentWithAbsoluteLinks
- return content
-}
-
-/**
- * @param {TroubleshootingEntry} entry
- */
-async function createGithubDiscussion(entry) {
- console.log(`[INFO] Creating GitHub discussion for ${entry.data.title}`)
- const content = addCanonicalUrl(entry)
-
- const mutation = `
- mutation CreateDiscussionMutation(
- $repository: ID!,
- $category: ID!,
- $title: String!,
- $body: String!
- ) {
- createDiscussion(input: {
- repositoryId: $repository,
- categoryId: $category,
- body: $body,
- title: $title
- }) {
- discussion {
- id
- url
- }
- }
- }
- `
-
- const {
- createDiscussion: { discussion },
- } = await octokit().graphql(mutation, {
- repository: REPOSITORY_ID,
- category: TROUBLESHOOTING_CATEGORY_ID,
- body: content,
- title: entry.data.title,
- })
- console.log(`[INFO] Created GitHub discussion for ${entry.data.title}: %s`, discussion.url)
- return discussion
-}
-
-/**
- * @returns {Promise<{id: string, url: string}[]>}
- */
-async function getAllTroubleshootingDiscussions() {
- const query = `
- query getDiscussions($cursor: String) {
- repository(owner: "${REPOSITORY_OWNER}", name: "${REPOSITORY_NAME}") {
- discussions(first: 100, after: $cursor, categoryId: "${TROUBLESHOOTING_CATEGORY_ID}") {
- pageInfo {
- hasNextPage
- endCursor
- }
- nodes {
- id
- url
- }
- }
- }
- }
- `
-
- const discussions = []
- let hasNextPage = true
- let cursor
-
- while (hasNextPage) {
- const {
- repository: {
- discussions: { nodes: moreDiscussions, pageInfo },
- },
- } = await octokit().graphql(query, { cursor })
-
- discussions.push(...moreDiscussions)
- hasNextPage = pageInfo.hasNextPage
- cursor = pageInfo.endCursor
- }
-
- return discussions
-}
-
-/**
- * @param {{id: string, url: string}[]} discussions
- * @param {TroubleshootingEntry} entry
- *
- * @throws If matching discussion not found
- */
-async function getGithubIdForDiscussion(discussions, entry) {
- const matchingDiscussion = discussions.find(
- (discussion) => discussion.url === entry.data.github_url
- )
- if (!matchingDiscussion) {
- throw new Error(`No matching discussion found for URL: ${entry.data.github_url}`)
- }
- return matchingDiscussion
-}
-
-/**
- * @param {TroubleshootingEntry} entry
- *
- * @throws If stored discussion ID for entry not found
- */
-async function updateGithubDiscussion(entry) {
- console.log(`[INFO] Updating discussion content for ${entry.data.title}`)
-
- const { data, error } = await supabaseAdmin()
- .from('troubleshooting_entries')
- .select('github_id')
- .eq('id', entry.data.database_id)
- .single()
- if (error) {
- throw error
- }
-
- const content = addCanonicalUrl(entry)
- const mutation = `
- mutation UpdateDiscussionMutation(
- $discussionId: ID!,
- $body: String!
- ) {
- updateDiscussion(input: {
- discussionId: $discussionId,
- body: $body
- }) {
- discussion {
- id
- }
- }
- }
- `
- try {
- await octokit().graphql(mutation, { discussionId: data.github_id, body: content })
- console.log(`[INFO] Updated discussion content for ${entry.data.title}`)
- } catch (err) {
- console.error('[DEBUG] Failed GraphQL mutation:\n', mutation)
- throw err
- }
-}
-
-/** @param {string} id */
-async function rollbackGithubDiscussion(id) {
- try {
- const mutation = `
- mutation DeleteDiscussionMutation(
- $discussionId: ID!
- ) {
- deleteDiscussion(input: {
- discussionId: $discussionId,
- }) {
- discussion {
- id
- }
- }
- }
- `
-
- await octokit().graphql(mutation, { discussionId: id })
- console.log(`[INFO] Rolled back discussion creation for ${id}`)
- } catch (error) {
- console.error(`[ERROR] Failed to rollback discussion creation for ${id}: %O`, error)
- }
-}
-
-/**
- * @param {TroubleshootingEntry} entry
- * @param {string} id
- *
- * @throws Passes through readFile and writeFile errors without catching
- */
-async function updateFileId(entry, id) {
- console.log(`[INFO] Writing database ID to file for ${entry.filePath}`)
-
- const fileContents = await readFile(entry.filePath, 'utf-8')
- const { data, content } = matter(fileContents, {
- language: 'toml',
- engines: { toml: parse },
- })
- data.database_id = id
-
- const newFrontmatter = stringify(data)
- const newContent = `---\n${newFrontmatter}\n---\n${content}`
-
- await writeFile(entry.filePath, newContent)
-}
-
-async function main() {
- try {
- const hasErrors = await syncTroubleshootingEntries()
- if (hasErrors) {
- process.exit(1)
- }
- } catch (error) {
- console.error(`[ERROR] %O`, error)
- process.exit(1)
- }
-}
-
-main()
diff --git a/apps/docs/features/docs/Troubleshooting.utils.common.mjs b/apps/docs/features/docs/Troubleshooting.utils.common.mjs
index de3e1028e48..21b35392026 100644
--- a/apps/docs/features/docs/Troubleshooting.utils.common.mjs
+++ b/apps/docs/features/docs/Troubleshooting.utils.common.mjs
@@ -1,11 +1,10 @@
// @ts-check
/**
- * This file is for utils needed in both the Next.js app build and the
- * troubleshooting sync script. Because of unsolved problems with imports, the
- * script is a mjs file instead of a ts file. Any dependencies that are needed
- * in both places are defined here, and then typed in Troubleshooting.utils.ts
- * as required.
+ * This file is for utils needed in both the Next.js app build and other
+ * scripts that read troubleshooting entries (e.g. search embeddings
+ * generation). Any dependencies that are needed in both places are defined
+ * here, and then typed in Troubleshooting.utils.ts as required.
*/
import matter from 'gray-matter'
diff --git a/apps/docs/package.json b/apps/docs/package.json
index c0c615f6dff..2dbce4280e0 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -22,10 +22,8 @@
"codegen:references:new": "pnpm run codegen:references:new:ensure && tsx scripts/build-reference-content.ts",
"codegen:references:legacy": "tsx features/docs/Reference.generated.script.ts",
"codegen:references": "pnpm codegen:references:legacy && pnpm codegen:references:new",
- "dev": "run-p --race dev:next dev:watch:troubleshooting",
- "dev:next": "next dev --port 3001",
+ "dev": "next dev --port 3001",
"dev:secrets:pull": "AWS_PROFILE=supa-dev node ../../scripts/getSecrets.js -n local/docs",
- "dev:watch:troubleshooting": "node ./scripts/troubleshooting/watch.mjs",
"embeddings": "tsx --conditions=react-server scripts/search/generate-embeddings.ts",
"embeddings:nimbus": "ENABLED_FEATURES_OVERRIDE_DISABLE_ALL=true pnpm run embeddings",
"embeddings:refresh": "pnpm run embeddings --refresh",
@@ -50,7 +48,6 @@
"test:local": "vitest --exclude \"**/*.smoke.test.ts\"",
"test:local:unwatch": "vitest --exclude \"**/*.smoke.test.ts\" --run",
"test:smoke": "pnpm run codegen:references && vitest -t \"prod smoke test\"",
- "troubleshooting:sync": "node features/docs/Troubleshooting.script.mjs",
"typecheck": "tsc --noEmit"
},
"dependencies": {
@@ -63,7 +60,6 @@
"@octokit/auth-app": "^7.0.0",
"@octokit/core": "^7.0.6",
"@octokit/graphql": "^8.0.0",
- "@octokit/plugin-paginate-graphql": "^4.0.0",
"@octokit/plugin-retry": "^8.1.0",
"@sentry/nextjs": "catalog:",
"@supabase/supabase-js": "catalog:",
@@ -161,14 +157,12 @@
"amaro": "^1.1.5",
"api-types": "workspace:*",
"cheerio": "^1.0.0-rc.12",
- "chokidar": "^4.0.3",
"config": "workspace:*",
"dotenv": "^16.0.3",
"ejs": "^3.1.10",
"fast-glob": "^3.3.3",
"globby": "^13.2.2",
"graphiql": "^4.0.2",
- "npm-run-all": "^4.1.5",
"openapi-types": "^12.1.3",
"postcss": "catalog:",
"remark-frontmatter": "^5.0.0",
diff --git a/apps/docs/scripts/search/sources/github-discussion.ts b/apps/docs/scripts/search/sources/github-discussion.ts
deleted file mode 100644
index fc29ce7e7c8..00000000000
--- a/apps/docs/scripts/search/sources/github-discussion.ts
+++ /dev/null
@@ -1,147 +0,0 @@
-import { createAppAuth } from '@octokit/auth-app'
-import { Octokit } from '@octokit/core'
-import { paginateGraphql } from '@octokit/plugin-paginate-graphql'
-import crypto, { createHash } from 'node:crypto'
-import { BaseLoader, BaseSource } from './base.js'
-
-export const ExtendedOctokit = Octokit.plugin(paginateGraphql)
-export type ExtendedOctokit = InstanceType<typeof ExtendedOctokit>
-
-export type Discussion = {
- id: string
- updatedAt: string
- url: string
- title: string
- body: string
- databaseId: number
-}
-
-export type DiscussionsResponse = {
- repository: {
- discussions: {
- totalCount: number
- nodes: Discussion[]
- }
- }
-}
-
-const appId = process.env.DOCS_GITHUB_APP_ID
-const installationId = process.env.DOCS_GITHUB_APP_INSTALLATION_ID
-const privateKey = process.env.DOCS_GITHUB_APP_PRIVATE_KEY
-
-/**
- * Fetches GitHub discussions for a repository + category
- */
-export async function fetchDiscussions(owner: string, repo: string, categoryId: string) {
- const octokit = new ExtendedOctokit({
- authStrategy: createAppAuth,
- auth: {
- appId,
- installationId,
- privateKey: crypto.createPrivateKey(privateKey!).export({ type: 'pkcs8', format: 'pem' }),
- },
- })
-
- const {
- repository: {
- discussions: { nodes: discussions },
- },
- } = await octokit.graphql.paginate<DiscussionsResponse>(
- `
- query troubleshootDiscussions($cursor: String, $owner: String!, $repo: String!, $categoryId: ID!) {
- repository(owner: $owner, name: $repo) {
- discussions(first: 100, after: $cursor, categoryId: $categoryId) {
- totalCount
- nodes {
- id
- updatedAt
- url
- title
- body
- databaseId
- }
- pageInfo {
- hasNextPage
- endCursor
- }
- }
- }
- }
- `,
- {
- owner,
- repo,
- categoryId,
- }
- )
-
- return discussions
-}
-
-export class GitHubDiscussionLoader extends BaseLoader {
- type = 'github-discussions' as const
-
- constructor(
- source: string,
- public discussion: Discussion
- ) {
- super(source, discussion.url)
- }
-
- async load() {
- return [new GitHubDiscussionSource(this.source, this.path, this.discussion)]
- }
-}
-
-export class GitHubDiscussionSource extends BaseSource {
- type = 'github-discussions' as const
-
- constructor(
- source: string,
- path: string,
- public discussion: Discussion
- ) {
- super(source, path)
- }
-
- async process() {
- const { id, title, updatedAt, body, databaseId } = this.discussion
-
- const checksum = createHash('sha256').update(updatedAt).digest('base64')
-
- const meta = { id, title, updatedAt }
-
- // Currently the discussion post itself is being considered as the answer
- // (as opposed to a comment marked as answer)
- // So we link the slug to the initial discussion post rather than a comment answer
- const slug = `discussion-${databaseId}`
-
- // Format the discussion title + body as markdown for better embeddings + LLM response
- const content = `# ${title}\n${body}`
-
- // For now, only a single section is created for GH discussions
- // Consider adding multiple if we want to include comments/answers
- const sections = [
- {
- heading: title,
- slug,
- content,
- },
- ]
-
- this.checksum = checksum
- this.meta = meta
- this.sections = sections
-
- return {
- checksum,
- meta,
- sections,
- }
- }
-
- extractIndexedContent(): string {
- const sections = this.sections ?? []
- return sections.map(({ heading, content }) => `${heading}\n\n${content}`).join('\n')
- }
-}
diff --git a/apps/docs/scripts/troubleshooting/watch.mjs b/apps/docs/scripts/troubleshooting/watch.mjs
deleted file mode 100644
index 304954500bf..00000000000
--- a/apps/docs/scripts/troubleshooting/watch.mjs
+++ /dev/null
@@ -1,61 +0,0 @@
-// @ts-check
-
-import chokidar from 'chokidar'
-import { closeSync, openSync, readFileSync, writeSync } from 'node:fs'
-import { basename, join } from 'node:path'
-
-const TROUBLESHOOTING_DIRECTORY = join(import.meta.dirname, '../../content/troubleshooting')
-
-let __template = ''
-
-function getTemplate() {
- if (!__template) {
- __template = readFileSync(join(TROUBLESHOOTING_DIRECTORY, '_template.mdx'), 'utf8')
- }
- return __template
-}
-
-const watcher = chokidar
- .watch(TROUBLESHOOTING_DIRECTORY, { ignoreInitial: true })
- .on('add', (path, stats) => {
- if (!stats?.isFile() || basename(path).startsWith('_')) return
-
- console.log(`File ${path} has been added.`)
-
- if (stats?.size !== 0) {
- console.log(`File ${path} already has content. Skipping template writing.`)
- return
- }
-
- try {
- console.log(`Writing template to ${path}...`)
- const fd = openSync(path, 'w')
- writeSync(fd, getTemplate())
- closeSync(fd)
- } catch (err) {
- console.error(`Error writing template to ${path}:`, err)
- }
- })
-
-// Keep the process alive
-const interval = setInterval(() => {}, 1000)
-
-const shutdown = () => {
- console.log(`\nShutting down watcher...`)
- clearInterval(interval)
- watcher
- .close()
- .then(() => {
- console.log('Watcher closed. Exiting process.')
- process.exit(0)
- })
- .catch((err) => {
- console.error('Error closing watcher:', err)
- process.exit(1)
- })
-}
-
-process.on('SIGINT', shutdown)
-process.on('SIGTERM', shutdown)
-process.on('SIGHUP', shutdown)
-process.on('SIGQUIT', shutdown)
diff --git a/apps/kb/.env.example b/apps/kb/.env.example
new file mode 100644
index 00000000000..3280c46f155
--- /dev/null
+++ b/apps/kb/.env.example
@@ -0,0 +1,20 @@
+# GitHub auth for scripts/federated-content/fetch-federated-content.ts (pulls
+# troubleshooting content from the private supabase/troubleshooting repo).
+# Same credentials as apps/docs — that GitHub App must also be granted
+# access to supabase/troubleshooting.
+#
+# Preferred: a GitHub App installation. Set all three or none.
+KB_GITHUB_APP_ID=
+KB_GITHUB_APP_INSTALLATION_ID=
+KB_GITHUB_APP_PRIVATE_KEY=
+
+# Fallback for local dev if the App isn't configured: a personal access
+# token, e.g. `export GH_TOKEN=$(gh auth token)`.
+GH_TOKEN=
+
+# Supabase project backing troubleshooting_entries (same project apps/www and
+# apps/studio use — supabase/config.toml's `[remotes.prod]`). The Astro page
+# only reads (anon key); the sync scripts also write (service role key).
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_ANON_KEY=
+SUPABASE_SERVICE_ROLE_KEY=
diff --git a/apps/kb/.gitignore b/apps/kb/.gitignore
index 557757712a2..57a0cf1c109 100644
--- a/apps/kb/.gitignore
+++ b/apps/kb/.gitignore
@@ -4,6 +4,9 @@ dist/
# generated markdown export (scripts/generate-markdown.mjs)
public/markdown/
+# federated troubleshooting content (scripts/federated-content), regenerated on every prebuild
+src/content/troubleshooting/
+
# generated types
.astro/
@@ -25,3 +28,6 @@ pnpm-debug.log*
# jetbrains setting folder
.idea/
+
+# jetbrains setting folder
+src/content/troubleshooting
diff --git a/apps/kb/AGENTS.md b/apps/kb/AGENTS.md
index de2bb5975a3..e333f62d860 100644
--- a/apps/kb/AGENTS.md
+++ b/apps/kb/AGENTS.md
@@ -50,13 +50,14 @@ Content lives under `src/content/guides/*.{md,mdx}`. Keep it plain GitHub-Flavor
## Pages and markdown export
Each content collection renders through a matching catch-all page — e.g. `src/content/guides/**` →
-`src/pages/guides/[...slug].astro` → `GuideLayout`. Topic pages (`src/pages/topics/[topic].astro`) are
-generated from the `TOPICS` list in `src/lib/topics.ts`, not from content files.
+`src/pages/guides/[...slug].astro` → `ArticleLayout` (shared with `troubleshooting`, see below). Topic pages
+(`src/pages/topics/[topic].astro`) are generated from the `TOPICS` list in `src/lib/topics.ts`, not from
+content files, and read from every collection.
Separately, `scripts/generate-markdown.mjs` runs as a `prebuild` step and exports every content file — plus
one page per topic, listing its guides — as a plain `.md` file under the gitignored `public/markdown/`,
mirroring the page's URL with a `.md` extension. `vercel.json` permanently redirects `<page>.md` requests to
-these generated files, one redirect entry per route section (`guides`, `topics`).
+these generated files, one redirect entry per route section (`guides`, `topics`, `troubleshooting`).
If you add a new content collection or top-level route, add a matching redirect in `vercel.json`
(`/kb/<section>/:path+.md` → `/kb/markdown/<section>/:path+.md`), and check whether `generate-markdown.mjs`
@@ -66,3 +67,30 @@ per-topic-style listing pages don't.
## Topic-specific guidance
Articles tagged with the `Comparison` topic are primarily oriented towards LLM crawlers (and not human readers). Because of this, these articles are hidden from the main site navigation.
+
+## Federated troubleshooting content
+
+`src/content/troubleshooting/` is never hand-authored — it's gitignored and regenerated every `prebuild` by
+`scripts/federated-content/fetch-federated-content.ts`, which fetches it from the private
+`supabase/troubleshooting` repo. It has its own collection and route (`src/pages/troubleshooting/[...slug].astro`),
+separate from `guides`.
+
+A few things here are intentional, not bugs to fix:
+
+- Most source files use TOML frontmatter, which the script can't parse — those are filtered out (not written
+ to disk) and summarized in a build warning, rather than guessed at.
+- No link rewriting or markdown reprocessing — body content is written exactly as fetched.
+- Output is `.md`, not `.mdx` — this source isn't MDX-safe (e.g. GFM autolinks break MDX's JSX parser).
+- `topics` are passed through verbatim from the source, unvalidated against `TOPIC_NAMES` — unlike `guides`.
+ `description` is optional too, since the source doesn't provide one.
+
+Auth reuses the docs GitHub App env vars (`KB_GITHUB_APP_ID`/`_INSTALLATION_ID`/`_PRIVATE_KEY`), falling back
+to `GH_TOKEN`/`GITHUB_TOKEN` for local dev — see `.env.example`.
+
+Syncing guides to GitHub Discussions (`scripts/federated-content/sync-troubleshooting-entries.ts` and
+`sync-troubleshooting-updates.ts`) is a separate concern from fetching — see `.github/workflows/kb-troubleshooting-sync.yml`
+and the README's "Workflows" section. Those scripts are CI-only, never part of `prebuild`.
+
+`backfill-legacy-slugs.ts` is a one-time migration aid for the 278 pre-existing (apps/docs-origin) rows in
+`troubleshooting_entries` — safe to delete (with its JSON file, package.json script, and workflow step) once
+those rows are all backfilled; see the comment at the top of that file.
diff --git a/apps/kb/README.md b/apps/kb/README.md
index 414a13a6619..1927fb48bc0 100644
--- a/apps/kb/README.md
+++ b/apps/kb/README.md
@@ -44,3 +44,17 @@ All commands are run from the root of the project, from a terminal:
## 👀 Want to learn more?
Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).
+
+## Federated troubleshooting content
+
+`src/content/troubleshooting/` isn't hand-written — it's fetched from a private repo by
+`scripts/federated-content/fetch-federated-content.ts` as part of the build (`pnpm run fetch:federated-content`)
+and is gitignored. See `AGENTS.md` for how it works and what's intentionally left out for now.
+
+## Workflows
+
+`.github/workflows/kb-troubleshooting-sync.yml` runs on every push to `master`: it fetches troubleshooting
+content, creates a GitHub Discussion for any guide that doesn't have one yet
+(`sync:troubleshooting-entries`), and pushes title/content updates to discussions whose guide has since
+changed (`sync:troubleshooting-updates`). This is separate from kb's own build — it has real side effects
+(creating/updating Discussions, writing DB rows), so it never runs as part of `pnpm build`/`prebuild`.
diff --git a/apps/kb/astro.config.mjs b/apps/kb/astro.config.mjs
index c8f0b142188..8715ce6f940 100644
--- a/apps/kb/astro.config.mjs
+++ b/apps/kb/astro.config.mjs
@@ -8,6 +8,7 @@ import react from '@astrojs/react'
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'astro/config'
+import { BASE_PATH } from './src/lib/constants.ts'
import rehypeAdmonitions from './src/lib/mdx/rehype-admonitions.js'
import supabaseTheme from '../learn/lib/themes/supabase-2.json' with { type: 'json' }
@@ -44,7 +45,7 @@ const ssrLodashEs = {
// https://astro.build/config
export default defineConfig({
site: 'https://supabase.com',
- base: '/kb',
+ base: BASE_PATH,
trailingSlash: 'ignore',
integrations: [react(), // rehype-admonitions is a custom rehype plugin and Astro's default pipeline is
// satteri, so .mdx gets its own unified processor. Plain .md stays on satteri.
@@ -58,6 +59,7 @@ export default defineConfig({
noExternal: ['lodash'],
},
plugins: [tailwindcss(), ssrLodashEs],
+ logLevel: 'error',
},
markdown: {
shikiConfig: {
diff --git a/apps/kb/package.json b/apps/kb/package.json
index 9a43679d20c..029eaf745dd 100644
--- a/apps/kb/package.json
+++ b/apps/kb/package.json
@@ -7,9 +7,13 @@
},
"scripts": {
"dev": "astro dev --port 3008",
- "prebuild": "pnpm run generate:markdown",
+ "prebuild": "pnpm run fetch:federated-content && pnpm run generate:markdown",
"build": "astro build",
- "generate:markdown": "node --experimental-strip-types ./scripts/generate-markdown.mjs",
+ "fetch:federated-content": "tsx ./scripts/federated-content/fetch-federated-content.ts",
+ "generate:markdown": "tsx ./scripts/generate-markdown.mjs",
+ "sync:legacy-slugs": "tsx ./scripts/federated-content/backfill-legacy-slugs.ts",
+ "sync:troubleshooting-entries": "tsx ./scripts/federated-content/sync-troubleshooting-entries.ts",
+ "sync:troubleshooting-updates": "tsx ./scripts/federated-content/sync-troubleshooting-updates.ts",
"preview": "astro preview",
"astro": "astro",
"test": "vitest --run"
@@ -19,8 +23,13 @@
"@astrojs/mdx": "^7.0.7",
"@astrojs/react": "^6.0.4",
"@astrojs/sitemap": "^3.7.4",
+ "@octokit/auth-app": "^7.0.0",
+ "@octokit/core": "^7.0.6",
+ "@octokit/plugin-retry": "^8.1.0",
+ "@supabase/supabase-js": "catalog:",
"astro": "^7.2.6",
"common": "workspace:*",
+ "gray-matter": "^4.0.3",
"lucide-react": "*",
"react": "catalog:",
"react-dom": "catalog:",
@@ -40,8 +49,10 @@
"@types/react": "catalog:",
"@types/react-dom": "catalog:",
"config": "workspace:*",
+ "dotenv": "^16.5.0",
"lodash-es": "catalog:",
"tailwindcss": "catalog:",
+ "tsx": "catalog:",
"vitest": "catalog:"
},
"allowScripts": {
diff --git a/apps/kb/public/img/troubleshooting/0e7f6842-78fd-44f9-b463-425507815fb6.png b/apps/kb/public/img/troubleshooting/0e7f6842-78fd-44f9-b463-425507815fb6.png
new file mode 100644
index 00000000000..b75cf3c3b3a
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/0e7f6842-78fd-44f9-b463-425507815fb6.png differ
diff --git a/apps/kb/public/img/troubleshooting/10950be3-264b-4a41-bc71-3d431c2756b2.png b/apps/kb/public/img/troubleshooting/10950be3-264b-4a41-bc71-3d431c2756b2.png
new file mode 100644
index 00000000000..6b62f61329f
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/10950be3-264b-4a41-bc71-3d431c2756b2.png differ
diff --git a/apps/kb/public/img/troubleshooting/152d65ad-f0ed-47cf-8dcb-1e31c6221e71.png b/apps/kb/public/img/troubleshooting/152d65ad-f0ed-47cf-8dcb-1e31c6221e71.png
new file mode 100644
index 00000000000..348f6b063a1
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/152d65ad-f0ed-47cf-8dcb-1e31c6221e71.png differ
diff --git a/apps/kb/public/img/troubleshooting/18ed2c88-332e-4e66-b9b4-c37e99a39104.png b/apps/kb/public/img/troubleshooting/18ed2c88-332e-4e66-b9b4-c37e99a39104.png
new file mode 100644
index 00000000000..274d1fd2604
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/18ed2c88-332e-4e66-b9b4-c37e99a39104.png differ
diff --git a/apps/kb/public/img/troubleshooting/224379580-fa77bd31-bb58-47e6-90ce-64e140f32579.png b/apps/kb/public/img/troubleshooting/224379580-fa77bd31-bb58-47e6-90ce-64e140f32579.png
new file mode 100644
index 00000000000..f236805dbbc
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/224379580-fa77bd31-bb58-47e6-90ce-64e140f32579.png differ
diff --git a/apps/kb/public/img/troubleshooting/3eeb2435-dd1c-41bc-9557-44cabff38f59.png b/apps/kb/public/img/troubleshooting/3eeb2435-dd1c-41bc-9557-44cabff38f59.png
new file mode 100644
index 00000000000..6e99baedca4
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/3eeb2435-dd1c-41bc-9557-44cabff38f59.png differ
diff --git a/apps/kb/public/img/troubleshooting/401_edge_functions_toggle_off_JWT_check.png b/apps/kb/public/img/troubleshooting/401_edge_functions_toggle_off_JWT_check.png
new file mode 100644
index 00000000000..34be98771e2
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/401_edge_functions_toggle_off_JWT_check.png differ
diff --git a/apps/kb/public/img/troubleshooting/401_in_the_logs.png b/apps/kb/public/img/troubleshooting/401_in_the_logs.png
new file mode 100644
index 00000000000..77aaac43325
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/401_in_the_logs.png differ
diff --git a/apps/kb/public/img/troubleshooting/46f59019-6ff1-4bfb-9acd-d5b7bd282f89.png b/apps/kb/public/img/troubleshooting/46f59019-6ff1-4bfb-9acd-d5b7bd282f89.png
new file mode 100644
index 00000000000..66c1a0b5a53
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/46f59019-6ff1-4bfb-9acd-d5b7bd282f89.png differ
diff --git a/apps/kb/public/img/troubleshooting/47685206-7914-440e-a010-da62f5c38186.png b/apps/kb/public/img/troubleshooting/47685206-7914-440e-a010-da62f5c38186.png
new file mode 100644
index 00000000000..ffa3f78d0bf
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/47685206-7914-440e-a010-da62f5c38186.png differ
diff --git a/apps/kb/public/img/troubleshooting/47998bed-0b77-433a-bfed-63222beb2aee.png b/apps/kb/public/img/troubleshooting/47998bed-0b77-433a-bfed-63222beb2aee.png
new file mode 100644
index 00000000000..2eb18732d1d
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/47998bed-0b77-433a-bfed-63222beb2aee.png differ
diff --git a/apps/kb/public/img/troubleshooting/49e11154-296b-42b9-8036-8a7288e49b8a.png b/apps/kb/public/img/troubleshooting/49e11154-296b-42b9-8036-8a7288e49b8a.png
new file mode 100644
index 00000000000..d56aedf13e5
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/49e11154-296b-42b9-8036-8a7288e49b8a.png differ
diff --git a/apps/kb/public/img/troubleshooting/49e175d9-6338-4b17-97be-4bf7853e319f.png b/apps/kb/public/img/troubleshooting/49e175d9-6338-4b17-97be-4bf7853e319f.png
new file mode 100644
index 00000000000..cf96e93ce90
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/49e175d9-6338-4b17-97be-4bf7853e319f.png differ
diff --git a/apps/kb/public/img/troubleshooting/54428354-a1f4-4c44-bd03-d87f4b925d94.png b/apps/kb/public/img/troubleshooting/54428354-a1f4-4c44-bd03-d87f4b925d94.png
new file mode 100644
index 00000000000..ea112beea61
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/54428354-a1f4-4c44-bd03-d87f4b925d94.png differ
diff --git a/apps/kb/public/img/troubleshooting/546_chart.png b/apps/kb/public/img/troubleshooting/546_chart.png
new file mode 100644
index 00000000000..59d11c0a059
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/546_chart.png differ
diff --git a/apps/kb/public/img/troubleshooting/546_errors_by_hour.png b/apps/kb/public/img/troubleshooting/546_errors_by_hour.png
new file mode 100644
index 00000000000..dcb97dfa03d
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/546_errors_by_hour.png differ
diff --git a/apps/kb/public/img/troubleshooting/565c96e0-cbb9-4e7a-b0aa-5b423afc0ada.png b/apps/kb/public/img/troubleshooting/565c96e0-cbb9-4e7a-b0aa-5b423afc0ada.png
new file mode 100644
index 00000000000..2b0270cbfef
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/565c96e0-cbb9-4e7a-b0aa-5b423afc0ada.png differ
diff --git a/apps/kb/public/img/troubleshooting/5b55ddbc-abfc-4c66-a012-b8e4d23cd438.png b/apps/kb/public/img/troubleshooting/5b55ddbc-abfc-4c66-a012-b8e4d23cd438.png
new file mode 100644
index 00000000000..f8742c40f46
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/5b55ddbc-abfc-4c66-a012-b8e4d23cd438.png differ
diff --git a/apps/kb/public/img/troubleshooting/627c1a3e-153e-40b5-9a91-a4f7bd7673a4.png b/apps/kb/public/img/troubleshooting/627c1a3e-153e-40b5-9a91-a4f7bd7673a4.png
new file mode 100644
index 00000000000..81c666ad573
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/627c1a3e-153e-40b5-9a91-a4f7bd7673a4.png differ
diff --git a/apps/kb/public/img/troubleshooting/6c284180-0ffd-432d-b86b-e9fbcfe23868.png b/apps/kb/public/img/troubleshooting/6c284180-0ffd-432d-b86b-e9fbcfe23868.png
new file mode 100644
index 00000000000..ddba69bc5b2
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/6c284180-0ffd-432d-b86b-e9fbcfe23868.png differ
diff --git a/apps/kb/public/img/troubleshooting/7fe991ac-40ea-4628-a5e3-181d706225ea.png b/apps/kb/public/img/troubleshooting/7fe991ac-40ea-4628-a5e3-181d706225ea.png
new file mode 100644
index 00000000000..8b04c2bf89a
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/7fe991ac-40ea-4628-a5e3-181d706225ea.png differ
diff --git a/apps/kb/public/img/troubleshooting/800448a1-0245-4a26-855f-3be8f44adf03.png b/apps/kb/public/img/troubleshooting/800448a1-0245-4a26-855f-3be8f44adf03.png
new file mode 100644
index 00000000000..2296a7fa06a
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/800448a1-0245-4a26-855f-3be8f44adf03.png differ
diff --git a/apps/kb/public/img/troubleshooting/830b81aa-ae52-44a4-aa49-32c2a6296af7.png b/apps/kb/public/img/troubleshooting/830b81aa-ae52-44a4-aa49-32c2a6296af7.png
new file mode 100644
index 00000000000..626d84d8fce
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/830b81aa-ae52-44a4-aa49-32c2a6296af7.png differ
diff --git a/apps/kb/public/img/troubleshooting/8ba54441-2057-4dc0-8add-a8eaab9f2d93.png b/apps/kb/public/img/troubleshooting/8ba54441-2057-4dc0-8add-a8eaab9f2d93.png
new file mode 100644
index 00000000000..bcede723b46
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/8ba54441-2057-4dc0-8add-a8eaab9f2d93.png differ
diff --git a/apps/kb/public/img/troubleshooting/90cb6a70-fc67-4666-9217-6fa37cfacf82.png b/apps/kb/public/img/troubleshooting/90cb6a70-fc67-4666-9217-6fa37cfacf82.png
new file mode 100644
index 00000000000..b7f8c7c5950
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/90cb6a70-fc67-4666-9217-6fa37cfacf82.png differ
diff --git a/apps/kb/public/img/troubleshooting/9b88a738-65d6-4be4-8fa0-bc3f13a9a408.png b/apps/kb/public/img/troubleshooting/9b88a738-65d6-4be4-8fa0-bc3f13a9a408.png
new file mode 100644
index 00000000000..e8600fb6064
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/9b88a738-65d6-4be4-8fa0-bc3f13a9a408.png differ
diff --git a/apps/kb/public/img/troubleshooting/9c00830a-8901-abcd-ef12-34567890abcd.png b/apps/kb/public/img/troubleshooting/9c00830a-8901-abcd-ef12-34567890abcd.png
new file mode 100644
index 00000000000..fc4b16a8a6f
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/9c00830a-8901-abcd-ef12-34567890abcd.png differ
diff --git a/apps/kb/public/img/troubleshooting/9c6e0f9c-f842-463b-b214-1a9e31de3b2c.png b/apps/kb/public/img/troubleshooting/9c6e0f9c-f842-463b-b214-1a9e31de3b2c.png
new file mode 100644
index 00000000000..033951c6a4f
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/9c6e0f9c-f842-463b-b214-1a9e31de3b2c.png differ
diff --git a/apps/kb/public/img/troubleshooting/a360b417-e0cc-4706-8df4-89af63dcdc70.png b/apps/kb/public/img/troubleshooting/a360b417-e0cc-4706-8df4-89af63dcdc70.png
new file mode 100644
index 00000000000..c8a0bebbf7a
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/a360b417-e0cc-4706-8df4-89af63dcdc70.png differ
diff --git a/apps/kb/public/img/troubleshooting/ade24c85-50b5-47ca-a2ce-c3f77a0e128a.png b/apps/kb/public/img/troubleshooting/ade24c85-50b5-47ca-a2ce-c3f77a0e128a.png
new file mode 100644
index 00000000000..7c7accbc092
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/ade24c85-50b5-47ca-a2ce-c3f77a0e128a.png differ
diff --git a/apps/kb/public/img/troubleshooting/c4e7b193-4567-8901-abcd-ef1234567890.png b/apps/kb/public/img/troubleshooting/c4e7b193-4567-8901-abcd-ef1234567890.png
new file mode 100644
index 00000000000..10649da3517
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/c4e7b193-4567-8901-abcd-ef1234567890.png differ
diff --git a/apps/kb/public/img/troubleshooting/c6e228b8-fa64-47a9-bdf6-f1f6405b9cf9.png b/apps/kb/public/img/troubleshooting/c6e228b8-fa64-47a9-bdf6-f1f6405b9cf9.png
new file mode 100644
index 00000000000..cd27655527a
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/c6e228b8-fa64-47a9-bdf6-f1f6405b9cf9.png differ
diff --git a/apps/kb/public/img/troubleshooting/c7ac0f69-6fb9-4ff2-8aab-5cda6bada3f6.png b/apps/kb/public/img/troubleshooting/c7ac0f69-6fb9-4ff2-8aab-5cda6bada3f6.png
new file mode 100644
index 00000000000..11ea0ee5608
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/c7ac0f69-6fb9-4ff2-8aab-5cda6bada3f6.png differ
diff --git a/apps/kb/public/img/troubleshooting/cf450bca-aad3-4783-ae3b-5cc83e0afa54.png b/apps/kb/public/img/troubleshooting/cf450bca-aad3-4783-ae3b-5cc83e0afa54.png
new file mode 100644
index 00000000000..19c5a6b1aec
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/cf450bca-aad3-4783-ae3b-5cc83e0afa54.png differ
diff --git a/apps/kb/public/img/troubleshooting/d756aeb0-515f-425d-b737-75a935935b73.png b/apps/kb/public/img/troubleshooting/d756aeb0-515f-425d-b737-75a935935b73.png
new file mode 100644
index 00000000000..10fb585b240
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/d756aeb0-515f-425d-b737-75a935935b73.png differ
diff --git a/apps/kb/public/img/troubleshooting/da70bc33-f123-4567-8901-abcdef123456.png b/apps/kb/public/img/troubleshooting/da70bc33-f123-4567-8901-abcdef123456.png
new file mode 100644
index 00000000000..2cea7ebe885
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/da70bc33-f123-4567-8901-abcdef123456.png differ
diff --git a/apps/kb/public/img/troubleshooting/download-edge-function-via-dashboard.gif b/apps/kb/public/img/troubleshooting/download-edge-function-via-dashboard.gif
new file mode 100644
index 00000000000..58f19698fa0
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/download-edge-function-via-dashboard.gif differ
diff --git a/apps/kb/public/img/troubleshooting/e7d78109-b09d-48ca-8cc6-e4913693e163.png b/apps/kb/public/img/troubleshooting/e7d78109-b09d-48ca-8cc6-e4913693e163.png
new file mode 100644
index 00000000000..b75cf3c3b3a
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/e7d78109-b09d-48ca-8cc6-e4913693e163.png differ
diff --git a/apps/kb/public/img/troubleshooting/e8f50ef1-2b3c-4d5e-9f8a-1234567890ab.png b/apps/kb/public/img/troubleshooting/e8f50ef1-2b3c-4d5e-9f8a-1234567890ab.png
new file mode 100644
index 00000000000..50b480e0cc8
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/e8f50ef1-2b3c-4d5e-9f8a-1234567890ab.png differ
diff --git a/apps/kb/public/img/troubleshooting/ec5ed538-985b-411d-a0d7-be718b28d367.png b/apps/kb/public/img/troubleshooting/ec5ed538-985b-411d-a0d7-be718b28d367.png
new file mode 100644
index 00000000000..4273e62922a
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/ec5ed538-985b-411d-a0d7-be718b28d367.png differ
diff --git a/apps/kb/public/img/troubleshooting/edge-function-504-timestamp-1.png b/apps/kb/public/img/troubleshooting/edge-function-504-timestamp-1.png
new file mode 100644
index 00000000000..5b246a57c36
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/edge-function-504-timestamp-1.png differ
diff --git a/apps/kb/public/img/troubleshooting/edge_function_404_redeploy.png b/apps/kb/public/img/troubleshooting/edge_function_404_redeploy.png
new file mode 100644
index 00000000000..04f971711b4
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/edge_function_404_redeploy.png differ
diff --git a/apps/kb/public/img/troubleshooting/edge_function_404_set_timeframe.png b/apps/kb/public/img/troubleshooting/edge_function_404_set_timeframe.png
new file mode 100644
index 00000000000..57465225be1
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/edge_function_404_set_timeframe.png differ
diff --git a/apps/kb/public/img/troubleshooting/edge_function_404_test_call.png b/apps/kb/public/img/troubleshooting/edge_function_404_test_call.png
new file mode 100644
index 00000000000..85fd737effc
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/edge_function_404_test_call.png differ
diff --git a/apps/kb/public/img/troubleshooting/edge_functions_401_verify_jwt.png b/apps/kb/public/img/troubleshooting/edge_functions_401_verify_jwt.png
new file mode 100644
index 00000000000..dc8ca2b3037
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/edge_functions_401_verify_jwt.png differ
diff --git a/apps/kb/public/img/troubleshooting/f294a4d6-ef12-3456-7890-abcdef123456.png b/apps/kb/public/img/troubleshooting/f294a4d6-ef12-3456-7890-abcdef123456.png
new file mode 100644
index 00000000000..7761da27ba5
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/f294a4d6-ef12-3456-7890-abcdef123456.png differ
diff --git a/apps/kb/public/img/troubleshooting/failed-to-run-sql-query-connection-terminated-due-to-connection-timeout.jpg b/apps/kb/public/img/troubleshooting/failed-to-run-sql-query-connection-terminated-due-to-connection-timeout.jpg
new file mode 100644
index 00000000000..05ac0011045
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/failed-to-run-sql-query-connection-terminated-due-to-connection-timeout.jpg differ
diff --git a/apps/kb/public/img/troubleshooting/ff01bba8-abcd-ef12-3456-7890abcdef12.png b/apps/kb/public/img/troubleshooting/ff01bba8-abcd-ef12-3456-7890abcdef12.png
new file mode 100644
index 00000000000..c781daef2bf
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/ff01bba8-abcd-ef12-3456-7890abcdef12.png differ
diff --git a/apps/kb/public/img/troubleshooting/filter_503.png b/apps/kb/public/img/troubleshooting/filter_503.png
new file mode 100644
index 00000000000..efa0f647959
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/filter_503.png differ
diff --git a/apps/kb/public/img/troubleshooting/identify-lovable-cloud-or-supabase-backend-0.png b/apps/kb/public/img/troubleshooting/identify-lovable-cloud-or-supabase-backend-0.png
new file mode 100644
index 00000000000..5fbc641c570
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/identify-lovable-cloud-or-supabase-backend-0.png differ
diff --git a/apps/kb/public/img/troubleshooting/identify-lovable-cloud-or-supabase-backend-1.png b/apps/kb/public/img/troubleshooting/identify-lovable-cloud-or-supabase-backend-1.png
new file mode 100644
index 00000000000..c2eea9a364d
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/identify-lovable-cloud-or-supabase-backend-1.png differ
diff --git a/apps/kb/public/img/troubleshooting/identify-lovable-cloud-or-supabase-backend-2.png b/apps/kb/public/img/troubleshooting/identify-lovable-cloud-or-supabase-backend-2.png
new file mode 100644
index 00000000000..68fcfa2c9b5
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/identify-lovable-cloud-or-supabase-backend-2.png differ
diff --git a/apps/kb/public/img/troubleshooting/limit_in_logs.png b/apps/kb/public/img/troubleshooting/limit_in_logs.png
new file mode 100644
index 00000000000..f4a4524453c
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/limit_in_logs.png differ
diff --git a/apps/kb/public/img/troubleshooting/limit_logs.png b/apps/kb/public/img/troubleshooting/limit_logs.png
new file mode 100644
index 00000000000..afde11ed385
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/limit_logs.png differ
diff --git a/apps/kb/public/img/troubleshooting/migrations-failed-status.png b/apps/kb/public/img/troubleshooting/migrations-failed-status.png
new file mode 100644
index 00000000000..0b4a86184b4
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/migrations-failed-status.png differ
diff --git a/apps/kb/public/img/troubleshooting/postgres-logs-migration-failed.png b/apps/kb/public/img/troubleshooting/postgres-logs-migration-failed.png
new file mode 100644
index 00000000000..d2e8c7b44ab
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/postgres-logs-migration-failed.png differ
diff --git a/apps/kb/public/img/troubleshooting/project-status-unhealthy-services.png b/apps/kb/public/img/troubleshooting/project-status-unhealthy-services.png
new file mode 100644
index 00000000000..0cfa6ca94cd
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/project-status-unhealthy-services.png differ
diff --git a/apps/kb/public/img/troubleshooting/query_results_546.png b/apps/kb/public/img/troubleshooting/query_results_546.png
new file mode 100644
index 00000000000..bc37b3f8113
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/query_results_546.png differ
diff --git a/apps/kb/public/img/troubleshooting/rebase-image.png b/apps/kb/public/img/troubleshooting/rebase-image.png
new file mode 100644
index 00000000000..f164eb83486
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/rebase-image.png differ
diff --git a/apps/kb/public/img/troubleshooting/reports-page-egress.png b/apps/kb/public/img/troubleshooting/reports-page-egress.png
new file mode 100644
index 00000000000..8801fc6fd8e
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/reports-page-egress.png differ
diff --git a/apps/kb/public/img/troubleshooting/upload-edge-function-via-dashboard.gif b/apps/kb/public/img/troubleshooting/upload-edge-function-via-dashboard.gif
new file mode 100644
index 00000000000..b8835bb201b
Binary files /dev/null and b/apps/kb/public/img/troubleshooting/upload-edge-function-via-dashboard.gif differ
diff --git a/apps/kb/scripts/federated-content/backfill-legacy-slugs.ts b/apps/kb/scripts/federated-content/backfill-legacy-slugs.ts
new file mode 100644
index 00000000000..de4aab586b8
--- /dev/null
+++ b/apps/kb/scripts/federated-content/backfill-legacy-slugs.ts
@@ -0,0 +1,63 @@
+// One-time migration aid: troubleshooting_entries has 278 rows pre-dating kb
+// (apps/docs' own discussions), all with slug = NULL. legacy-troubleshooting-slugs.json
+// maps each row's id (docs' own `database_id` frontmatter field) to the slug
+// of the docs content file it came from, extracted once from
+// apps/docs/content/troubleshooting/*.mdx (that content isn't checked out by
+// this workflow and doesn't need to be — these ids never change).
+//
+// Stored as the bare slug, not prefixed: as these files get migrated into the
+// federated supabase/troubleshooting repo under the same slug, sync-troubleshooting-entries.ts
+// needs to match them by slug against these rows' existing github_url — otherwise
+// it treats the guide as new and creates a duplicate discussion, orphaning the
+// original (with its comments and links).
+//
+// Delete this file, legacy-troubleshooting-slugs.json, its package.json script,
+// and its workflow step once all legacy rows are backfilled — safe to remove
+// as a unit, nothing else depends on it.
+import '../utils/dotenv.js'
+
+import { createClient } from '@supabase/supabase-js'
+
+import legacySlugs from './legacy-troubleshooting-slugs.json' with { type: 'json' }
+
+const DRY_RUN = process.argv.includes('--dry-run')
+
+async function backfillLegacySlugs() {
+ if (DRY_RUN) {
+ for (const [databaseId, slug] of Object.entries(legacySlugs)) {
+ console.log(` - ${databaseId} -> ${slug}`)
+ }
+ return
+ }
+
+ const db = createClient(
+ process.env.NEXT_PUBLIC_SUPABASE_URL as string,
+ process.env.SUPABASE_SERVICE_ROLE_KEY as string
+ )
+
+ let backfilled = 0
+ let alreadyDone = 0
+
+ for (const [databaseId, slug] of Object.entries(legacySlugs)) {
+ // .is('slug', null) makes this idempotent/concurrency-safe: a duplicate
+ // run updates 0 rows instead of racing.
+ const { data, error } = await db
+ .from('troubleshooting_entries')
+ .update({ slug })
+ .eq('id', databaseId)
+ .is('slug', null)
+ .select('id')
+ if (error) throw error
+
+ if (data.length > 0) backfilled++
+ else alreadyDone++
+ }
+
+ console.log(
+ `[backfill-legacy-slugs] Backfilled ${backfilled}, already done ${alreadyDone}, total ${Object.keys(legacySlugs).length}.`
+ )
+}
+
+backfillLegacySlugs().catch((error) => {
+ throw error
+})
diff --git a/apps/kb/scripts/federated-content/fetch-federated-content.ts b/apps/kb/scripts/federated-content/fetch-federated-content.ts
new file mode 100644
index 00000000000..35bc1db748a
--- /dev/null
+++ b/apps/kb/scripts/federated-content/fetch-federated-content.ts
@@ -0,0 +1,118 @@
+// Fetches every troubleshooting article from the private supabase/troubleshooting
+// repo's `guides` folder into src/content/troubleshooting/ (gitignored,
+// regenerated on every prebuild — see content.config.ts's `troubleshooting`
+// collection). No content processing: body text is written as fetched.
+import '../utils/dotenv.js'
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Octokit } from '@octokit/core'
+import { retry } from '@octokit/plugin-retry'
+import matter from 'gray-matter'
+
+import { githubAuthOptions } from './github-auth.ts'
+
+const SOURCE = { org: 'supabase', repo: 'troubleshooting', branch: 'main', dir: 'guides' }
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+const TROUBLESHOOTING_DIRECTORY = join(SCRIPT_DIR, '../../src/content/troubleshooting')
+
+const RetryOctokit = Octokit.plugin(retry)
+let octokitInstance: InstanceType<typeof RetryOctokit>
+
+function octokit() {
+ if (!octokitInstance) octokitInstance = new RetryOctokit(githubAuthOptions())
+ return octokitInstance
+}
+
+async function listMarkdownFiles(path: string): Promise<string[]> {
+ const response = await octokit().request('GET /repos/{owner}/{repo}/contents/{path}', {
+ owner: SOURCE.org,
+ repo: SOURCE.repo,
+ path,
+ ref: SOURCE.branch,
+ })
+ if (!Array.isArray(response.data))
+ throw new Error(`${path} in ${SOURCE.org}/${SOURCE.repo} is not a directory`)
+ return response.data
+ .filter((entry) => entry.type === 'file' && /\.mdx?$/.test(entry.name))
+ .map((entry) => entry.name)
+}
+
+async function getFileContents(path: string): Promise<string> {
+ const response = await octokit().request('GET /repos/{owner}/{repo}/contents/{path}', {
+ owner: SOURCE.org,
+ repo: SOURCE.repo,
+ path,
+ ref: SOURCE.branch,
+ })
+ if (
+ Array.isArray(response.data) ||
+ !('content' in response.data) ||
+ response.data.type !== 'file'
+ ) {
+ throw new Error(`Unexpected response for ${path} in ${SOURCE.org}/${SOURCE.repo}`)
+ }
+ return Buffer.from(response.data.content, 'base64').toString('utf-8')
+}
+
+// Local slug: strip the extension and the random hex suffix some filenames
+// carry (e.g. `foo-bar-94a76b.mdx` -> `foo-bar`).
+function slugFromFilename(filename: string): string {
+ return filename.replace(/\.mdx?$/, '').replace(/-[0-9a-f]{6}$/i, '')
+}
+
+// Most source files use TOML frontmatter (`title = "..."`), which gray-matter
+// can't parse (it assumes YAML) — it either throws or silently returns
+// garbage. Detected here by gray-matter failing to produce a `title` string,
+// and skipped entirely rather than guessed at.
+function parseGuide(raw: string): { title: string; topics: string[]; body: string } | null {
+ let data: Record<string, unknown>
+ let body: string
+ try {
+ ;({ data, content: body } = matter(raw))
+ } catch {
+ return null
+ }
+ if (typeof data.title !== 'string') return null
+ return { title: data.title, topics: Array.isArray(data.topics) ? data.topics : [], body }
+}
+
+async function fetchPage(filename: string): Promise<'fetched' | 'legacy-toml'> {
+ const raw = await getFileContents(`${SOURCE.dir}/${filename}`)
+ const guide = parseGuide(raw)
+ if (!guide) return 'legacy-toml'
+
+ const frontmatter = {
+ title: guide.title,
+ topics: guide.topics,
+ }
+ const output = matter.stringify(guide.body, frontmatter)
+ await writeFile(join(TROUBLESHOOTING_DIRECTORY, `${slugFromFilename(filename)}.md`), output)
+ return 'fetched'
+}
+
+async function fetchFederatedContent() {
+ await mkdir(TROUBLESHOOTING_DIRECTORY, { recursive: true })
+
+ const filenames = await listMarkdownFiles(SOURCE.dir)
+ const results = await Promise.all(filenames.map((filename) => fetchPage(filename)))
+
+ const legacyTomlFiles = filenames.filter((_, i) => results[i] === 'legacy-toml')
+ if (legacyTomlFiles.length > 0) {
+ console.warn(
+ `[fetch-federated-content.ts]: ${legacyTomlFiles.length} troubleshooting guide(s) contained TOML frontmatter syntax and were ignored:`
+ )
+ for (const filename of legacyTomlFiles) console.warn(` - ${filename}`)
+ }
+
+ const fetchedCount = filenames.length - legacyTomlFiles.length
+ console.log(
+ `Fetched ${fetchedCount}/${filenames.length} troubleshooting page(s) into src/content/troubleshooting/`
+ )
+}
+
+fetchFederatedContent().catch((error) => {
+ throw error
+})
diff --git a/apps/kb/scripts/federated-content/github-auth.ts b/apps/kb/scripts/federated-content/github-auth.ts
new file mode 100644
index 00000000000..41c5f1bddc0
--- /dev/null
+++ b/apps/kb/scripts/federated-content/github-auth.ts
@@ -0,0 +1,44 @@
+import crypto from 'node:crypto'
+import { createAppAuth } from '@octokit/auth-app'
+
+/**
+ * Prefers the docs GitHub App. Falls back to `GH_TOKEN` / `GITHUB_TOKEN` for
+ * local runs. A partially configured App is an error rather than a token
+ * fall-back, to avoid silently authenticating as the wrong identity.
+ */
+export function githubAuthOptions() {
+ const appId = process.env.KB_GITHUB_APP_ID
+ const installationId = process.env.KB_GITHUB_APP_INSTALLATION_ID
+ const privateKey = process.env.KB_GITHUB_APP_PRIVATE_KEY
+
+ if (appId && installationId && privateKey) {
+ return {
+ authStrategy: createAppAuth,
+ auth: {
+ appId,
+ installationId,
+ privateKey: crypto
+ .createPrivateKey(privateKey)
+ .export({ type: 'pkcs8', format: 'pem' })
+ .toString(),
+ },
+ }
+ }
+
+ const appVars: Array<[string, string | undefined]> = [
+ ['KB_GITHUB_APP_ID', appId],
+ ['KB_GITHUB_APP_INSTALLATION_ID', installationId],
+ ['KB_GITHUB_APP_PRIVATE_KEY', privateKey],
+ ]
+ const missing = appVars.filter(([, value]) => !value).map(([name]) => name)
+ if (missing.length < appVars.length) {
+ throw new Error(`Incomplete GitHub App configuration: ${missing.join(', ')} not set.`)
+ }
+
+ const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN
+ if (token) return { auth: token }
+
+ throw new Error(
+ 'Missing GitHub credentials. Set KB_GITHUB_APP_ID/_INSTALLATION_ID/_PRIVATE_KEY, or GH_TOKEN / GITHUB_TOKEN.'
+ )
+}
diff --git a/apps/kb/scripts/federated-content/legacy-troubleshooting-slugs.json b/apps/kb/scripts/federated-content/legacy-troubleshooting-slugs.json
new file mode 100644
index 00000000000..bee60c2b163
--- /dev/null
+++ b/apps/kb/scripts/federated-content/legacy-troubleshooting-slugs.json
@@ -0,0 +1,172 @@
+{
+ "97923126-7d0b-4bf0-bb65-55dae289a8a3": "42501--permission-denied-for-table-httprequestqueue-KnozmQ",
+ "ba593989-12b5-464f-8ede-a525e1ca2ffb": "all-about-supabase-egress-a_Sg_e",
+ "7183351e-dba3-484d-83b3-bb89a027e36a": "an-invalid-response-was-received-from-the-upstream-server-error-when-querying-auth-RI4Vl-",
+ "ce8c04e4-d493-4e15-832a-e59bdcf2b093": "app-store-rejection-tls-error-in-ipv6-only-environments-4e9c62",
+ "03854567-8838-4f12-8a6c-095fc1671d9f": "are-all-features-available-in-self-hosted-supabase-THPcqw",
+ "e90ca9e0-0376-4313-b32b-b9a4ae81bf7a": "auth-error-401-invalid-claim-missing-sub--AFwMR",
+ "c1de4561-e95f-41e3-b298-fac9ae331a54": "auth-hooks-invalid-payload-when-anonymous-users-attempt-phone-changes-022c47",
+ "a931b8af-3210-4188-bb03-87452923a498": "autovacuum-stalled-due-to-inactive-replication-slot-d55aa2",
+ "8bb130d5-d298-49c7-8cfb-dd7a3f231154": "avoiding-timeouts-in-long-running-queries-6nmbdN",
+ "4a41e734-6883-452f-bc8e-82ff4ac22a81": "canceling-statement-due-to-statement-timeout-581wFv",
+ "f7f2d68b-f336-4578-9541-17ca37aaa327": "cant-access-supabase-project-lovable-cloud",
+ "df9518df-d019-42bb-8d91-918c6d57b452": "certain-operations-are-too-complex-to-perform-directly-using-the-client-libraries-8JaphH",
+ "6de3c3a9-8614-48d7-827e-cf41d6a1ce23": "change-email-associated-with-supabase-account-T5eHNT",
+ "fd711d33-9703-402f-84b2-8e74034e7690": "change-project-region-eWJo5Z",
+ "1759134d-a98d-4bfa-9501-71e06180700e": "check-usage-for-monthly-active-users-mau-MwZaBs",
+ "a60ee728-3add-438d-b8bf-433f1746cb3e": "cloudflare-origin-error-1016-on-custom-domain-a57af4",
+ "94c6e33b-cc05-49b3-b010-7480f8dde843": "converted-github-account-to-organisation---lost-supabase-account-access-5wsE_1",
+ "2ebc2849-0cf7-4c94-ac13-22167a196a92": "customizing-emails-by-language-KZ_38Q",
+ "c5d8260b-c17a-4f6c-ab20-801f953f6c94": "dashboard-errors-when-managing-users-N1ls4A",
+ "49b51a3a-9753-4747-a24e-8afcb075792b": "database-api-42501-errors",
+ "b3a73631-0b8d-460d-8033-28df88d26d75": "database-error-remaining-connection-slots-are-reserved-for-non-replication-superuser-connections-3V3nIb",
+ "5d1c44ed-b2f6-4509-9312-1eeb8838e701": "database-error-saving-new-user-RU_EwB",
+ "58c0cb7c-50a0-4a96-9551-bc97c28b7393": "deprecated-rls-features-Pm77Zs",
+ "04801b69-e7eb-4f40-8d41-81110397bbc2": "disabling-prepared-statements-qL8lEL",
+ "188986c9-019d-4f26-baaf-6f58cec8fa7a": "discovering-and-interpreting-api-errors-in-the-logs-7xREI9",
+ "1e02e989-fc12-4838-b304-c7d1356f6d2c": "do-i-need-to-expose-security-definer-functions-in-row-level-security-policies-iI0uOw",
+ "91ae4c49-bf22-4b8c-b96b-cd11f1c38158": "download-logical-backups",
+ "a3cfff33-d640-4395-99bc-a110b7fb637c": "edge-function-404-error-response",
+ "4e6ff2e4-2abb-4fba-8233-5883b3d56fb0": "edge-function-546-error-response",
+ "aaf9e673-64ae-460a-88e0-b83ea4963382": "edge-function-bundle-size-issues",
+ "1765884f-81d6-415a-a78f-7085f7b7ddbf": "edge-function-cpu-limits",
+ "e079a9d0-419a-4e31-b7ec-1206d9012d0b": "edge-function-dependency-analysis",
+ "30b3f7a4-a2b7-4430-8176-31aa4d92b2e9": "edge-function-fails-deploy",
+ "33e8e407-951b-4f7d-b8b4-8e9085cd4d10": "edge-function-monitoring-resource-usage",
+ "109b964f-c28c-4554-b059-cd8b165c63f8": "edge-function-shutdown-reasons-explained",
+ "89b868a9-17fe-4c6d-86f6-0b04e5794678": "edge-function-takes-too-long-to-respond",
+ "5a3a0125-84c7-463b-a886-ca53edfba5f4": "edge-function-wall-clock-time-limit-reached-Nk38bW",
+ "f988e832-b0c3-4b30-8e20-8d5854943b32": "email-password-login-disabled-supabase-vercel-marketplace-a7dd36",
+ "47c4e2c7-0ff3-48e7-8c8a-912494ff8c24": "email-template-not-updating",
+ "02f5f200-3c1c-425e-945f-b80b3fce3ec0": "enabling-ipv4-addon",
+ "9d8b179c-ff4d-4072-b9e6-2d16e63b2aaa": "error-connection-refused-when-trying-to-connect-to-supabase-database-hwG0Dr",
+ "da3aa582-b115-44e2-97e3-9ab76206f0db": "error-index-row-size-exceeds-btree-version-4-maximum-for-index-LMmoeU",
+ "12128731-0af6-4c57-9aa2-66e177f0c3f4": "error-invalid-byte-sequence-for-encoding-utf8-0x00-when-accessing-triggers-or-webhooks-e78cf8",
+ "58d5a2de-2f7e-45fc-8dfa-7fb36da41ca8": "error-invalid-totp-code-entered-CukLCj",
+ "0739256c-1b25-46ec-963b-2f8e4dccedc7": "error-no-pghbaconf-entry-for-host-xxxxxxxxxxx-user-postgres-database-postgres-ssl-off-GOt5Ja",
+ "8688dad6-3dce-4912-9b90-4f128daf79d7": "error-prepared-statement-xxx-already-exists-3laqeM",
+ "6083c9eb-b9fc-4d19-bc64-bb4b7efeecdd": "error-target-organization-is-not-managed-by-vercel-marketplace-during-project-transfer-5262c3",
+ "4844905d-1456-44a1-858e-7a4995e5054c": "exhaust-disk-io",
+ "a589d411-ee50-455a-892e-526914ddb40d": "exhaust-ram",
+ "2db43a09-792b-484b-b97d-5d96a405b525": "exhaust-swap",
+ "23c4e1b5-c7e7-497f-acf8-006133e243a4": "failed-to-fetch-in-dashboard-and-other-areas----browser-extension-dyDTRU",
+ "aa5fda82-5838-4975-b0ac-ba4d7fb9e638": "failed-to-restore-from-backup-all-subscriptions-and-replication-slots-must-be-dropped-before-a-backup-can-be-restored-L-rCvt",
+ "095da77f-b97f-455c-88d1-b6a0341452b1": "failed-to-retrieve-tables",
+ "7529ca12-114b-485c-9b64-bca3b2dc744b": "failed-to-run-sql-query-connection-terminated-due-to-connection-timeout",
+ "6f19b113-09cb-45ce-8141-0d6dc10ea464": "fetch-requests-to-api-endpoints-arent-showing-the-session-UbUwRs",
+ "6ec0c9a3-b52b-49b9-ba6e-c91984f7f9bf": "fixing-520-errors-in-the-database-rest-api-Ur5-B2",
+ "b095c3ed-23e7-4a17-9e33-d811af25ba67": "forbidden-resource-error-from-the-cli-L6rm6l",
+ "2c33968e-26c0-4613-aee1-5de36d068394": "get-detailed-storage-metrics-with-the-aws-cli-587a7d",
+ "1ea7b605-dc1d-43d8-a365-5bc2801dd90e": "google-auth-fails-for-some-users-XcFXEu",
+ "76a4099e-450f-4b5b-a539-224760348c18": "grafana-not-displaying-data-sXJrMj",
+ "23668386-7a72-44ff-a412-4cd8a005fa18": "high-cpu-and-slow-queries-with-error-must-be-a-superuser-to-terminate-superuser-process",
+ "3d1bb799-453f-4a6c-9fdc-056f15bec88c": "high-cpu-usage",
+ "a715c0d3-8636-41b7-a6da-6d49f1b1777c": "high-latency-with-supabase-client-z0pZzR",
+ "b7edb30b-beee-40ae-9b4f-666ef6411bb6": "how-can-i-revoke-execution-of-a-postgresql-function-2GYb0A",
+ "74972531-f2fc-4d68-a745-21f9c75761e6": "how-do-i-check-gotrueapi-version-of-a-supabase-project-lQAnOR",
+ "cdaa76a4-3e5b-4c8f-82f0-b713c4cf19ab": "how-do-i-make-the-cookies-httponly-vwweFx",
+ "6e4a515c-5e70-4b92-808c-f076d47d4e35": "how-do-i-reset-my-supabase-database-password-oTs5sB",
+ "dfefd00c-31d8-4969-86a4-03d586110f4c": "how-do-i-update-connection-pool-settings-in-my-dashboard-wAxTJ_",
+ "4017d331-0b24-439a-9231-793801395ca2": "how-do-you-troubleshoot-nextjs---supabase-auth-issues-riMCZV",
+ "cc852935-510f-4beb-9f70-b4582505a863": "how-long-does-it-take-to-restore-a-database-from-a-point-in-time-backup-pitr-qO8gOG",
+ "e7671f20-2639-442e-9df9-4f6fa3766598": "how-postgres-chooses-which-index-to-use-_JHrf4",
+ "6f6a34a6-ac3f-4fba-9c70-4f4b8c7aeda7": "how-to-bypass-cooldown-period",
+ "78f06ca5-6a69-4536-89fc-ed2e6ff334e5": "how-to-change-max-database-connections-_BQ8P5",
+ "990ed738-2e00-42ce-9892-77c16f870cdc": "how-to-check-if-my-queries-are-being-blocked-by-other-queries-NSKtR1",
+ "085d7649-0b5d-4c3c-b6a1-f2da4b9f33dd": "how-to-delete-a-role-in-postgres-8-AvxY",
+ "aafe6f52-de09-44ec-b329-1bbbf26146dd": "how-to-delete-vercel-linked-projects-9d08aa",
+ "8b000bb4-180b-4a6c-b280-ba02965060f6": "how-to-interpret-and-explore-the-postgres-logs-OuCIOj",
+ "273b79ad-b8ff-4669-8544-b99920e2d3c8": "how-to-migrate-from-supabase-auth-helpers-to-ssr-package-5NRunM",
+ "da2d95e5-abc5-47c8-8389-1554d12abf91": "how-to-view-database-metrics-uqf2z_",
+ "e9fb853f-a37f-442a-b180-4aefd234a385": "http-api-issues",
+ "b98c7288-8c38-4dc2-8591-d18ea9eb4cbc": "http-status-codes",
+ "ec816bde-1a27-461f-89ef-211e96810dd9": "i-am-not-receiving-password-reset-emails-for-supabase-dashboard--cO5yf",
+ "37244f4a-cf99-4b1d-b7f2-ee70c3a126ab": "identify-lovable-cloud-or-supabase-backend",
+ "225cb141-f442-47cf-834d-1d82d703748a": "importing-stripe-or-other-modules-from-esmsh-on-deno-edge-functions-throws-an-error-TmbB5p",
+ "7d755701-747f-4c3a-b8be-236c5518e4eb": "increase-vector-lookup-speeds-by-applying-an-hsnw-index-ohLHUM",
+ "a1156bbe-289e-4462-a32d-2b0ca03691e4": "inserting-into-sequenceserial-table-causes-duplicate-key-violates-unique-constraint-error-pi6DnC",
+ "f47c9b0e-f537-4908-8d35-5dd3dc4c5627": "inspecting-edge-function-environment-variables-wg5qOQ",
+ "1da315be-38ac-487a-b178-f865a1a73c09": "insufficient-privilege-when-accessing-pgstatstatements-e5M_EQ",
+ "ef05da0a-f8bc-44a4-9719-5ae811dba104": "interpreting-supabase-grafana-cpu-charts-9JSlkC",
+ "0056cd40-df04-4045-bbfb-c245cb15b85d": "interpreting-supabase-grafana-io-charts-MUynDR",
+ "1cff12df-7ad6-48c5-b518-5ea468b54bab": "issues-serving-edge-functions-locally",
+ "362840be-a99c-4a98-bf4b-6e44a399af12": "jwt-expired-error-in-supabase-dashboard-F06k3x",
+ "449482fb-6e21-4a25-99ee-1ce6fffbc975": "keeping-free-projects-after-pro-upgrade-Kf9Xm2",
+ "60bd4a35-fc2e-4e42-bcf6-a430d380c930": "lost-accessforgot-the-mfa-device-nAPT-7",
+ "f6420e72-ea67-4825-b3f7-e722ea5c0d96": "manually-created-databases-are-not-visible-in-the-supabase-dashboard-4415aa",
+ "43b62743-252c-4069-a719-0c0737839fd9": "memory-and-swap-usage-explained-aPNgm0",
+ "7bd3de18-a4ab-4b76-85e4-b72924dacd2a": "migrating-auth-users-between-projects",
+ "bdd39473-ae02-41f5-b75d-877a79f361f6": "monitor-supavisor-postgres-connections",
+ "c5dae428-8dd0-4879-b312-df7f7da25986": "new-branch-doesnt-copy-database",
+ "f5cabb97-aae3-4fb5-b597-4e7857821753": "new-variable-is-null-in-a-trigger-function--l9AOZ",
+ "9be3727b-c3ea-4dda-b30c-55f3c8aa8f35": "nextjs-1314-stale-data-when-changing-rls-or-table-data-85b8oQ",
+ "a1bb1131-dd11-4a76-8a70-98a666c08286": "no-toast-messages-on-the-dashboard-BrvP8h",
+ "98e3b318-ad9a-41f5-ada0-44b61970ab4f": "not-receiving-auth-emails-from-the-supabase-project-OFSNzw",
+ "3e9246cb-d592-4051-93c8-53e4e555711c": "oauth-sign-in-isnt-redirecting-on-the-server-side-ShGMtr",
+ "25eddb73-3cca-485b-b87f-7279dd46b7a7": "otp-verification-failures-token-has-expired-or-otp_expired-errors-5ee4d0",
+ "3142f418-028e-4ab1-8f82-a7096be90422": "partitioning-an-existing-table-with-same-name-VEnbzK",
+ "76b2e2b6-8f1d-448a-a3dd-cdf68755d1a9": "pausing-pro-projects-vNL-2a",
+ "0d3389c0-5e75-473c-a18b-0699d0911fb2": "performing-administration-tasks-on-the-server-side-with-the-servicerole-secret-BYM4Fa",
+ "c000b4ea-23e2-4e19-af54-63ccd00c4904": "pg_cron-launcher-crashes-with-duplicate-key-value-violates-unique-constraint-cc6472",
+ "9a55c946-877f-46ae-8b57-51934e02a36c": "pgcron-debugging-guide-n1KTaz",
+ "91dda1aa-52f7-4a1c-9248-92fad9f3dec7": "pgrst106-the-schema-must-be-one-of-the-following-error-when-querying-an-exposed-schema",
+ "f9f9842b-e66c-4ea3-a45b-713895d8b7c6": "pkce-flow-errors-cannot-parse-response-or-zgotmplz-in-magic-link-emails-433665",
+ "c3481097-1a32-4e94-b4f6-7aeb88132a41": "postgrest-not-recognizing-new-columns-or-functions-bd75f5",
+ "28d842fd-8ba3-46f0-a307-082d946e0d94": "prisma-error-management-Cm5P_o",
+ "357e90d6-58a7-4347-a6c0-00622fcf9c81": "project-status-reports-unhealthy-services",
+ "0dab3e43-2ba9-4421-9af3-b97e45123069": "rclone-error-s3-protocol-error-received-listing-v1-with-istruncated-set-no-nextmarker-and-no-contents-e64d34",
+ "01e0dd67-5208-4e65-b489-2afd5a0b2af3": "realtime-concurrent-peak-connections-quota-jdDqcp",
+ "b99fac0e-09da-4a31-93a1-6375ed8ce041": "realtime-connections-timed_out-status",
+ "4112ff74-dd74-4003-9f4f-479590afed3c": "realtime-debugging-with-logger",
+ "b826b34a-f7c0-405e-a836-54c543198964": "realtime-handling-silent-disconnections-in-backgrounded-applications-592794",
+ "e882c2a2-b04c-48d3-9aae-615ec3458477": "realtime-heartbeat-messages",
+ "3f5acb57-2ccd-4bd7-86c2-df8e23fe2685": "realtime-project-suspended-for-exceeding-quotas",
+ "dee93cc3-0ab1-4101-8ad4-31d8682c8844": "realtime-too-many-channels-error",
+ "027fba24-c7bc-4c54-9e6b-6f13ec85ad56": "realtime-warn-sending-broadcast-message",
+ "b76ac13f-db24-4d19-9d00-af60c978cd26": "refresh-postgrest-schema",
+ "72e93bc8-597d-4c72-8d86-4997679196fd": "resolving-42p01-relation-does-not-exist-error-W4_9-V",
+ "031ba6d7-4928-4d95-a2da-bff8dbb740ec": "resolving-500-status-authentication-errors-7bU5U8",
+ "c89147f8-a66a-4c04-a1a7-45442fd7f2ee": "resolving-database-hostname-and-managing-your-ip-address-pVlwE0",
+ "bb06ff88-e0a9-41bc-b00b-9afde10468a5": "rls-performance-and-best-practices-Z5Jjwv",
+ "5b8a5115-f81a-4a1f-bcc3-fdc2a2672e80": "rls-simplified-BJTcS8",
+ "caa72a34-696c-47c6-8976-e50cf7fb396e": "rotating-anon-service-and-jwt-secrets-1Jq6yd",
+ "1d62cace-c0f6-47a0-8690-002a797da33b": "running-explain-analyze-on-functions",
+ "02a26b95-3029-49a1-9319-161cf1c4c21d": "scan-error-on-column-confirmation_token-converting-null-to-string-is-unsupported-during-auth-login-a0c686",
+ "46bab0a2-9780-4e4f-99f5-fcc9fa51c496": "security-of-anonymous-sign-ins-iOrGCL",
+ "9faf3ed3-d373-41c8-a083-ccc83dfc16d7": "seeing-no-pghbaconf-entry-for-host-errors-in-postgres-and-they-come-from-an-ip-address-that-i-dont-recognize-4gds9f",
+ "e51bedf0-cdc4-4880-865b-e39c06dfe497": "should-i-set-a-shorter-max-age-parameter-on-the-cookies-8sbF4V",
+ "571d4ad9-b596-44bc-b8a4-a3115b862436": "slow-execution-of-alter-table-on-large-table-when-changing-column-type-qmZRpZ",
+ "c1ca57fb-91ab-4526-987b-65106dc63a2f": "soft-deletes-with-supabase-js",
+ "37d147df-caa7-4b0b-82b5-eab6852f2cff": "sso-error-you-do-not-have-permissions-to-join-this-organization-or-prompts-to-create-new-organization",
+ "fb1cbd42-e172-44b2-af2b-fda5aecde5c2": "steps-to-improve-query-performance-with-indexes-q8PoC9",
+ "f27145c7-0ff5-4621-a364-5d5704bce0ff": "supabase--your-network-ipv4-and-ipv6-compatibility-cHe3BP",
+ "4a32736f-1d7f-4c41-9c96-ab84e35ad394": "supabase-cli-failed-sasl-auth-or-invalid-scram-server-final-message",
+ "9d3377c9-fa79-4734-9fa9-8ccc99415f7f": "supabase-dashboard-not-loading-project-not-loading-on-dashboard-LfMq9F",
+ "179d70f3-1e26-4346-9ee8-d340fad382a3": "supabase-grafana-memory-charts",
+ "d64f5f5d-ef80-4423-ba24-1a79b4e69ce6": "supabase-project-provisioned-via-bolt-not-visible-in-dashboard-7188fc",
+ "3b52daf2-d78d-4630-8e9f-8bf5d90208bf": "supabase-storage-inefficient-folder-operations-and-hierarchical-rls-challenges-b05a4d",
+ "e008e056-453d-44b5-8a8a-27c2d70681fe": "supavisor-and-connection-terminology-explained-9pr_ZO",
+ "f252ba39-e540-462b-868f-42eb31a5d40c": "supavisor-faq-YyP5tI",
+ "83446166-2539-44ce-bde5-9252ce59d2e3": "transfer-edge-function-from-one-project-to-another",
+ "c6b6ae3c-1b5b-4ba8-a40f-5f2ca1f007e2": "transferring-from-cloud-to-self-host-in-supabase-2oWNvW",
+ "cd298838-6f13-4b70-a198-a8bd26b2c0bd": "unable-to-call-edge-function",
+ "68bb6df6-6a07-40fa-ad4d-dfa5e21d7e9c": "unable-to-deploy-edge-function",
+ "0ce5b1e4-bd0a-439e-9fb1-8e27bad2ef10": "understanding-postgresql-explain-output-Un9dqX",
+ "10186830-8cce-4f10-8cb9-7cbf39310763": "understanding-postgresql-logging-levels-and-how-they-impact-your-project-KXiJRm",
+ "f379a628-6821-40b0-9793-4bf819b8c085": "understanding-the-usage-summary-on-the-dashboard-D7Gnle",
+ "e3ad9b0e-0533-444b-a998-c8e65171b529": "unused-external-import-warning-vite-rollup",
+ "3b0aa0f2-9608-4691-94d6-4fca8a32130e": "upload-file-size-restrictions-Y4wQLT",
+ "4d5390a0-445d-4e0a-ae7e-9b713b7cc4f6": "using-google-smtp-with-supabase-custom-smtp-ZZzU4Y",
+ "da4efcda-cd02-4001-965b-f0294300152f": "using-sqlalchemy-with-supabase-FUqebT",
+ "a5524182-9dc4-4470-86fe-45ace109a53a": "webhook-debugging-guide-M8sk47",
+ "d4b45e90-9c52-4781-8cc2-d936e8f4edeb": "why-am-i-being-redirected-to-the-wrong-url-when-using-auth-redirectto-option-_vqIeO",
+ "0c0369db-2968-4ea7-9f99-c5f5ce55acad": "why-are-there-gaps-in-my-postgres-id-sequence-Frifus",
+ "8abd4a38-041b-4620-95af-53673f698dea": "why-cant-i-uploadlistetc-my-public-bucket-Z6CmGt",
+ "f85935d8-e871-4463-8288-f118f4e24afd": "why-do-i-see-auth--api-requests-in-the-dashboard-my-app-has-no-users-CyadiO",
+ "9dbcf760-7b1f-4cc4-8653-4e884fd02dad": "why-is-my-camelcase-name-not-working-in-postgres-functions-or-rls-policies-EJMzVd",
+ "6fa68831-6db8-4836-a1b4-e9e51296d529": "why-is-my-select-returning-an-empty-data-array-and-i-have-data-in-the-table-xvOPgx",
+ "677f0a69-e454-4718-ad92-91053d40c085": "why-is-my-service-role-key-client-getting-rls-errors-or-not-returning-data-7_1K9z",
+ "0a6f6d33-7331-4b47-87ec-7ade7a6a5924": "why-is-my-supabase-api-call-not-returning-PGzXw0",
+ "99b56e92-62f2-4602-8e13-d38caf7aff4c": "why-supabase-edge-functions-cannot-provide-static-egress-ips-for-whitelisting-3d78b0",
+ "fa5bb840-a5ac-447f-b9bb-e319cbe0797e": "will-backups-be-accessible-from-the-dashboard-immediately-after-upgrading-to-a-paid-plan-hXY4rs"
+}
diff --git a/apps/kb/scripts/federated-content/sync-troubleshooting-entries.ts b/apps/kb/scripts/federated-content/sync-troubleshooting-entries.ts
new file mode 100644
index 00000000000..5f144b90cac
--- /dev/null
+++ b/apps/kb/scripts/federated-content/sync-troubleshooting-entries.ts
@@ -0,0 +1,160 @@
+// Creates a GitHub Discussion for every troubleshooting guide that doesn't
+// have a troubleshooting_entries row yet. Run after fetch-federated-content.ts,
+// from CI only (never kb's own prebuild — this has real side effects). Pass
+// --dry-run to log what would be created without creating anything.
+import '../utils/dotenv.js'
+
+import { createHash } from 'node:crypto'
+import { readdir, readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Octokit } from '@octokit/core'
+import { retry } from '@octokit/plugin-retry'
+import { createClient, type SupabaseClient } from '@supabase/supabase-js'
+import matter from 'gray-matter'
+
+import { githubAuthOptions } from './github-auth.ts'
+
+const REPOSITORY_ID = 'MDEwOlJlcG9zaXRvcnkyMTQ1ODcxOTM=' // supabase/supabase
+const TROUBLESHOOTING_CATEGORY_ID = 'DIC_kwDODMpXOc4CUvEr' // "Troubleshooting" discussion category
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+const TROUBLESHOOTING_DIRECTORY = join(SCRIPT_DIR, '../../src/content/troubleshooting')
+
+const DRY_RUN = process.argv.includes('--dry-run')
+
+const RetryOctokit = Octokit.plugin(retry)
+const octokit = new RetryOctokit(githubAuthOptions())
+
+async function readLocalGuides(): Promise<Array<{ slug: string; title: string; body: string }>> {
+ const filenames = (await readdir(TROUBLESHOOTING_DIRECTORY)).filter((f) => f.endsWith('.md'))
+ return Promise.all(
+ filenames.map(async (filename) => {
+ const raw = await readFile(join(TROUBLESHOOTING_DIRECTORY, filename), 'utf-8')
+ const { data, content: body } = matter(raw)
+ return { slug: filename.replace(/\.md$/, ''), title: data.title as string, body }
+ })
+ )
+}
+
+function computeChecksum(title: string, body: string): string {
+ return createHash('sha256').update(JSON.stringify({ title, body })).digest('hex')
+}
+
+async function createDiscussion(title: string, body: string): Promise<{ id: string; url: string }> {
+ const mutation = `
+ mutation CreateDiscussionMutation($repository: ID!, $category: ID!, $title: String!, $body: String!) {
+ createDiscussion(input: { repositoryId: $repository, categoryId: $category, title: $title, body: $body }) {
+ discussion { id url }
+ }
+ }
+ `
+ const result = await octokit.graphql<{
+ createDiscussion: { discussion: { id: string; url: string } }
+ }>(mutation, { repository: REPOSITORY_ID, category: TROUBLESHOOTING_CATEGORY_ID, title, body })
+ return result.createDiscussion.discussion
+}
+
+async function deleteDiscussion(id: string): Promise<void> {
+ const mutation = `
+ mutation DeleteDiscussionMutation($discussionId: ID!) {
+ deleteDiscussion(input: { discussionId: $discussionId }) { discussion { id } }
+ }
+ `
+ await octokit.graphql(mutation, { discussionId: id })
+}
+
+// Small sequential batches, not one unbounded Promise.all — stays clear of
+// GitHub's secondary rate limits when many guides are new at once (e.g. the
+// first run). Isolates failures per guide instead of letting one abort the
+// rest; failures are collected and reported (non-zero exit) at the end.
+async function createNewGuides(
+ db: SupabaseClient,
+ guides: Array<{ slug: string; title: string; body: string }>
+): Promise<string[]> {
+ const failures: string[] = []
+ const batchSize = 5
+
+ for (let i = 0; i < guides.length; i += batchSize) {
+ const batch = guides.slice(i, i + batchSize)
+ const results = await Promise.allSettled(
+ batch.map(async (guide) => {
+ console.log(` - ${guide.slug}`)
+ if (DRY_RUN) return
+
+ const discussion = await createDiscussion(guide.title, guide.body)
+ // upsert, not insert: a row can already exist here (matched by slug,
+ // just without a github_id yet) — onConflict updates it in place
+ // instead of colliding with the slug unique constraint.
+ const { error } = await db.from('troubleshooting_entries').upsert(
+ {
+ slug: guide.slug,
+ github_url: discussion.url,
+ github_id: discussion.id,
+ checksum: computeChecksum(guide.title, guide.body),
+ },
+ { onConflict: 'slug' }
+ )
+ if (error) {
+ console.error(
+ `[sync-troubleshooting-entries] DB upsert failed for ${guide.slug}, rolling back discussion`
+ )
+ await deleteDiscussion(discussion.id)
+ throw error
+ }
+ })
+ )
+ results.forEach((result, j) => {
+ if (result.status === 'rejected') {
+ console.error(`[sync-troubleshooting-entries] Failed for ${batch[j].slug}:`, result.reason)
+ failures.push(batch[j].slug)
+ }
+ })
+ }
+
+ return failures
+}
+
+async function syncNewDiscussions() {
+ const guides = await readLocalGuides()
+ const db = createClient(
+ process.env.NEXT_PUBLIC_SUPABASE_URL as string,
+ process.env.SUPABASE_SERVICE_ROLE_KEY as string
+ )
+
+ const { data: existing, error } = await db
+ .from('troubleshooting_entries')
+ .select('slug, github_id')
+ .in(
+ 'slug',
+ guides.map((guide) => guide.slug)
+ )
+ if (error) throw error
+
+ // github_id present means a discussion already exists for that slug — the
+ // actual "already synced" signal, not mere row presence (a backfilled
+ // legacy row's slug can exist before it has a discussion).
+ const githubIdBySlug = new Map((existing ?? []).map((row) => [row.slug, row.github_id]))
+ const newGuides = guides.filter((guide) => !githubIdBySlug.get(guide.slug))
+
+ if (newGuides.length === 0) {
+ console.log('[sync-troubleshooting-entries] No new troubleshooting guides to sync.')
+ return
+ }
+
+ console.log(
+ `[sync-troubleshooting-entries] ${newGuides.length} new guide(s)${DRY_RUN ? ' (dry run)' : ''}:`
+ )
+ const failures = await createNewGuides(db, newGuides)
+
+ console.log(
+ `[sync-troubleshooting-entries] Synced ${newGuides.length - failures.length}/${newGuides.length} new guide(s).`
+ )
+ if (failures.length > 0) {
+ throw new Error(`Failed to sync: ${failures.join(', ')}`)
+ }
+}
+
+syncNewDiscussions().catch((error) => {
+ throw error
+})
diff --git a/apps/kb/scripts/federated-content/sync-troubleshooting-updates.ts b/apps/kb/scripts/federated-content/sync-troubleshooting-updates.ts
new file mode 100644
index 00000000000..5201c9b7652
--- /dev/null
+++ b/apps/kb/scripts/federated-content/sync-troubleshooting-updates.ts
@@ -0,0 +1,115 @@
+// Pushes title/content updates to already-synced GitHub Discussions when the
+// local troubleshooting guide has changed. Compares a stored checksum against
+// a freshly computed one — never the discussion's live content — so this is
+// immune to whatever GitHub does internally to stored title/body. A null
+// checksum (a row created before this column existed) always counts as
+// changed. Updates target the discussion directly via the row's stored
+// github_id — no need to list/paginate the category's discussions. Run after
+// sync-troubleshooting-entries.ts, from CI only. Pass --dry-run to log
+// without writing anything.
+import '../utils/dotenv.js'
+
+import { createHash } from 'node:crypto'
+import { readdir, readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Octokit } from '@octokit/core'
+import { retry } from '@octokit/plugin-retry'
+import { createClient } from '@supabase/supabase-js'
+import matter from 'gray-matter'
+
+import { githubAuthOptions } from './github-auth.ts'
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+const TROUBLESHOOTING_DIRECTORY = join(SCRIPT_DIR, '../../src/content/troubleshooting')
+
+const DRY_RUN = process.argv.includes('--dry-run')
+
+const RetryOctokit = Octokit.plugin(retry)
+const octokit = new RetryOctokit(githubAuthOptions())
+
+async function readLocalGuides(): Promise<Array<{ slug: string; title: string; body: string }>> {
+ const filenames = (await readdir(TROUBLESHOOTING_DIRECTORY)).filter((f) => f.endsWith('.md'))
+ return Promise.all(
+ filenames.map(async (filename) => {
+ const raw = await readFile(join(TROUBLESHOOTING_DIRECTORY, filename), 'utf-8')
+ const { data, content: body } = matter(raw)
+ return { slug: filename.replace(/\.md$/, ''), title: data.title as string, body }
+ })
+ )
+}
+
+function computeChecksum(title: string, body: string): string {
+ return createHash('sha256').update(JSON.stringify({ title, body })).digest('hex')
+}
+
+async function updateDiscussion(discussionId: string, title: string, body: string): Promise<void> {
+ const mutation = `
+ mutation UpdateDiscussionMutation($discussionId: ID!, $title: String!, $body: String!) {
+ updateDiscussion(input: { discussionId: $discussionId, title: $title, body: $body }) {
+ discussion { id }
+ }
+ }
+ `
+ await octokit.graphql(mutation, { discussionId, title, body })
+}
+
+async function syncDiscussionUpdates() {
+ const guides = await readLocalGuides()
+ const db = createClient(
+ process.env.NEXT_PUBLIC_SUPABASE_URL as string,
+ process.env.SUPABASE_SERVICE_ROLE_KEY as string
+ )
+
+ const { data: rows, error } = await db
+ .from('troubleshooting_entries')
+ .select('slug, github_id, checksum')
+ .in(
+ 'slug',
+ guides.map((guide) => guide.slug)
+ )
+ if (error) throw error
+
+ const rowBySlug = new Map((rows ?? []).map((row) => [row.slug, row]))
+
+ let updatedCount = 0
+ const failures: string[] = []
+
+ for (const guide of guides) {
+ const row = rowBySlug.get(guide.slug)
+ if (!row) continue // not synced yet — sync-troubleshooting-entries.ts handles that
+
+ const newChecksum = computeChecksum(guide.title, guide.body)
+ if (row.checksum !== null && row.checksum === newChecksum) continue
+
+ console.log(
+ `[sync-troubleshooting-updates] Content changed for ${guide.slug}${DRY_RUN ? ' (dry run)' : ''}`
+ )
+ if (DRY_RUN) {
+ updatedCount++
+ continue
+ }
+
+ try {
+ await updateDiscussion(row.github_id, guide.title, guide.body)
+ const { error: updateError } = await db
+ .from('troubleshooting_entries')
+ .update({ checksum: newChecksum })
+ .eq('slug', guide.slug)
+ if (updateError) throw updateError
+ updatedCount++
+ } catch (err) {
+ console.error(`[sync-troubleshooting-updates] Failed to update ${guide.slug}:`, err)
+ failures.push(guide.slug)
+ }
+ }
+
+ console.log(`[sync-troubleshooting-updates] Updated ${updatedCount} discussion(s).`)
+ if (failures.length > 0) {
+ throw new Error(`Failed to sync: ${failures.join(', ')}`)
+ }
+}
+
+syncDiscussionUpdates().catch((error) => {
+ throw error
+})
diff --git a/apps/kb/scripts/generate-markdown.mjs b/apps/kb/scripts/generate-markdown.mjs
index ddd6f0237a7..1fa5d27e7e0 100644
--- a/apps/kb/scripts/generate-markdown.mjs
+++ b/apps/kb/scripts/generate-markdown.mjs
@@ -14,16 +14,16 @@ import { unified } from 'unified'
import { visit } from 'unist-util-visit'
import YAML from 'yaml'
+import { BASE_PATH } from '../src/lib/constants.ts'
import { TOPICS, topicToSlug } from '../src/lib/topics.ts'
const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url))
const CONTENT_DIR = path.join(SCRIPT_DIR, '..', 'src', 'content')
const OUTPUT_DIR = path.join(SCRIPT_DIR, '..', 'public', 'markdown')
-// Production origin + Astro `base` — used to turn root-relative links into
-// full URLs so the exported file still makes sense read on its own.
+// Used to turn root-relative links into full URLs so the exported file still
+// makes sense read on its own.
const SITE_ORIGIN = 'https://supabase.com'
-const BASE_PATH = '/kb'
// Single processor reused for every file: parses GFM markdown to an mdast
// tree and serializes it back, same extensions on both ends so nothing
diff --git a/apps/kb/scripts/utils/dotenv.js b/apps/kb/scripts/utils/dotenv.js
new file mode 100644
index 00000000000..7913e8a5b00
--- /dev/null
+++ b/apps/kb/scripts/utils/dotenv.js
@@ -0,0 +1,8 @@
+// Must be a .js not a .ts so it can be imported outside of the scripts
+// directory without having to compile
+
+import dotenv from 'dotenv'
+
+dotenv.config({ path: '.env.local' })
+
+export default undefined
diff --git a/apps/kb/src/content.config.ts b/apps/kb/src/content.config.ts
index 404b2365ed3..7f62410d221 100644
--- a/apps/kb/src/content.config.ts
+++ b/apps/kb/src/content.config.ts
@@ -18,12 +18,24 @@ const formatDate = (date: Date): string => {
}
// Every entry here is rendered through GuideLayout by
+// Shared by every article-like collection (guides, troubleshooting) so their
+// schemas can't drift on these fields — both render through ArticleLayout via
+// a matching catch-all page and need the same base fields. `description` and
+// `topics` are NOT shared: each collection validates those differently below.
+const articleFields = {
+ title: z.string(),
+ // Surfaces the guide in the homepage's "Featured Guides" section.
+ pinned: z.boolean().default(false),
+ github_url: z.string().optional(),
+}
+
+// Every entry here is rendered through ArticleLayout by
// src/pages/guides/[...slug].astro — dropping a new file in
// src/content/guides doesn't need any per-file layout wiring.
const guides = defineCollection({
loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/guides' }),
schema: z.object({
- title: z.string(),
+ ...articleFields,
description: z.string(),
// z.enum (not z.string) so a guide referencing a topic outside TOPICS
// fails content validation instead of silently rendering an orphaned tag.
@@ -38,4 +50,23 @@ const guides = defineCollection({
}),
})
-export const collections = { guides }
+// Fetched from the private supabase/troubleshooting repo by
+// scripts/federated-content/fetch-federated-content.ts (a prebuild step) —
+// entirely generated, never hand-authored, see .gitignore. Rendered through
+// ArticleLayout by src/pages/troubleshooting/[...slug].astro.
+const troubleshooting = defineCollection({
+ loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/troubleshooting' }),
+ schema: z.object({
+ ...articleFields,
+ // The source has no description field, and ArticleLayout already
+ // renders this conditionally — optional rather than synthesized.
+ description: z.string().optional(),
+ // Passed through verbatim from the source repo's own frontmatter, not
+ // validated against TOPIC_NAMES — this collection's topic vocabulary is
+ // the source repo's, not kb's, so entries won't all match a kb Topic
+ // (ArticleLayout and the topic pages degrade gracefully for those).
+ topics: z.array(z.string()).default([]),
+ }),
+})
+
+export const collections = { guides, troubleshooting }
diff --git a/apps/kb/src/layouts/GuideLayout.astro b/apps/kb/src/layouts/ArticleLayout.astro
similarity index 65%
rename from apps/kb/src/layouts/GuideLayout.astro
rename to apps/kb/src/layouts/ArticleLayout.astro
index 4cdee3914b3..f77d33a416d 100644
--- a/apps/kb/src/layouts/GuideLayout.astro
+++ b/apps/kb/src/layouts/ArticleLayout.astro
@@ -3,12 +3,15 @@ import { ExternalLink, Github } from 'lucide-react'
import { Badge } from 'ui'
import Layout from './Layout.astro'
-import { getTopicDescription, type Topic, topicToSlug } from '../lib/topics'
+import { getTopicDescription, type Topic, TOPIC_NAMES, topicToSlug } from '../lib/topics'
interface Props {
title: string
description?: string
- topics?: Topic[]
+ // string[], not Topic[]: federated collections (e.g. troubleshooting) pass
+ // through their source's own topic tags unprocessed, which aren't
+ // guaranteed to be members of kb's fixed Topic list.
+ topics?: string[]
github_url?: string
viewGitHubLink?: string
date?: string
@@ -16,6 +19,9 @@ interface Props {
const { title, description, topics = [], github_url, viewGitHubLink, date } = Astro.props
+function isKnownTopic(topic: string): topic is Topic {
+ return (TOPIC_NAMES as readonly string[]).includes(topic)
+}
---
<Layout title={title} description={description}>
@@ -26,14 +32,18 @@ const { title, description, topics = [], github_url, viewGitHubLink, date } = As
{
topics.length > 0 && (
<div class="flex flex-wrap gap-2">
- {topics.map((topic) => (
- <a
- href={`${import.meta.env.BASE_URL}/topics/${topicToSlug(topic)}`}
- title={getTopicDescription(topic)}
- >
+ {topics.map((topic) =>
+ isKnownTopic(topic) ? (
+ <a
+ href={`${import.meta.env.BASE_URL}/topics/${topicToSlug(topic)}`}
+ title={getTopicDescription(topic)}
+ >
+ <Badge>{topic}</Badge>
+ </a>
+ ) : (
<Badge>{topic}</Badge>
- </a>
- ))}
+ )
+ )}
</div>
)
}
diff --git a/apps/kb/src/lib/constants.ts b/apps/kb/src/lib/constants.ts
new file mode 100644
index 00000000000..0ae595b3b3f
--- /dev/null
+++ b/apps/kb/src/lib/constants.ts
@@ -0,0 +1,4 @@
+// Matches astro.config.mjs's `base` — the single source of truth for this
+// value. Astro pages get it via `import.meta.env.BASE_URL`; anything running
+// outside Astro's own pipeline (prebuild scripts) imports it from here.
+export const BASE_PATH = '/kb'
diff --git a/apps/kb/src/lib/troubleshooting-db.ts b/apps/kb/src/lib/troubleshooting-db.ts
new file mode 100644
index 00000000000..60174048b60
--- /dev/null
+++ b/apps/kb/src/lib/troubleshooting-db.ts
@@ -0,0 +1,25 @@
+import { createClient } from '@supabase/supabase-js'
+
+/**
+ * Looks up each slug's `github_url` from `troubleshooting_entries` (build
+ * time only — kb is fully static, no SSR). Returns an empty map on any
+ * failure instead of throwing: this is an optional enhancement (the "Go to
+ * the GitHub discussion" link), not worth failing the whole build over.
+ */
+export async function getGithubUrlsBySlug(slugs: string[]): Promise<Map<string, string>> {
+ try {
+ const supabase = createClient(
+ process.env.NEXT_PUBLIC_SUPABASE_URL as string,
+ process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY as string
+ )
+ const { data: rows, error } = await supabase
+ .from('troubleshooting_entries')
+ .select('slug, github_url')
+ .in('slug', slugs)
+ if (error) throw error
+ return new Map((rows ?? []).map((row) => [row.slug, row.github_url]))
+ } catch (error) {
+ console.warn('[troubleshooting] Failed to look up github_url from the database:', error)
+ return new Map()
+ }
+}
diff --git a/apps/kb/src/pages/guides/[...slug].astro b/apps/kb/src/pages/guides/[...slug].astro
index 982f19576d8..1b1b208f64f 100644
--- a/apps/kb/src/pages/guides/[...slug].astro
+++ b/apps/kb/src/pages/guides/[...slug].astro
@@ -2,7 +2,7 @@
import { getCollection, render } from 'astro:content'
import { Admonition } from 'ui-patterns/Admonition'
-import GuideLayout from '../../layouts/GuideLayout.astro'
+import ArticleLayout from '../../layouts/ArticleLayout.astro'
export async function getStaticPaths() {
const guides = await getCollection('guides')
@@ -20,6 +20,6 @@ const { Content } = await render(guide)
const viewGitHubLink = `https://github.com/supabase/supabase/blob/master/apps/kb/${guide.filePath}`
---
-<GuideLayout title={title} description={description} topics={topics} github_url={github_url} viewGitHubLink={viewGitHubLink} date={date}>
+<ArticleLayout title={title} description={description} topics={topics} github_url={github_url} viewGitHubLink={viewGitHubLink} date={date}>
<Content components={{ Admonition }} />
-</GuideLayout>
+</ArticleLayout>
diff --git a/apps/kb/src/pages/topics/[topic].astro b/apps/kb/src/pages/topics/[topic].astro
index aa741118dc0..7e29d2afdaf 100644
--- a/apps/kb/src/pages/topics/[topic].astro
+++ b/apps/kb/src/pages/topics/[topic].astro
@@ -6,6 +6,11 @@ import { TOPICS, topicToSlug } from '../../lib/topics'
export async function getStaticPaths() {
const guides = await getCollection('guides')
+ const troubleshooting = await getCollection('troubleshooting')
+ const entries = [
+ ...guides.map((guide) => ({ data: guide.data, href: `/guides/${guide.id}` })),
+ ...troubleshooting.map((entry) => ({ data: entry.data, href: `/troubleshooting/${entry.id}` })),
+ ]
// One page per topic in TOPICS — not just topics a guide already uses —
// so every link on the "Topics" nav resolves instead of 404ing.
@@ -14,7 +19,7 @@ export async function getStaticPaths() {
props: {
topic: topic.name,
description: topic.description,
- guides: guides.filter((guide) => guide.data.topics?.includes(topic.name)),
+ guides: entries.filter((entry) => entry.data.topics?.includes(topic.name)),
},
}))
}
@@ -33,7 +38,7 @@ const { topic, description, guides } = Astro.props
<ul>
{guides.map((guide) => (
<li>
- <a href={`${import.meta.env.BASE_URL}/guides/${guide.id}`}>{guide.data.title}</a>
+ <a href={`${import.meta.env.BASE_URL}${guide.href}`}>{guide.data.title}</a>
</li>
))}
</ul>
diff --git a/apps/kb/src/pages/troubleshooting/[...slug].astro b/apps/kb/src/pages/troubleshooting/[...slug].astro
new file mode 100644
index 00000000000..f3e810e7fc3
--- /dev/null
+++ b/apps/kb/src/pages/troubleshooting/[...slug].astro
@@ -0,0 +1,29 @@
+---
+import { getCollection, render } from 'astro:content'
+import { Admonition } from 'ui-patterns/Admonition'
+
+import ArticleLayout from '../../layouts/ArticleLayout.astro'
+import { getGithubUrlsBySlug } from '../../lib/troubleshooting-db'
+
+export async function getStaticPaths() {
+ const troubleshooting = await getCollection('troubleshooting')
+
+ // github_url lives in the DB, not the fetched frontmatter — looked up here
+ // (build time; kb is fully static, no SSR) rather than baked into the
+ // fetched files.
+ const githubUrlBySlug = await getGithubUrlsBySlug(troubleshooting.map((entry) => entry.id))
+
+ return troubleshooting.map((entry) => ({
+ params: { slug: entry.id },
+ props: { entry, githubUrl: githubUrlBySlug.get(entry.id) },
+ }))
+}
+
+const { entry, githubUrl } = Astro.props
+const { title, description, topics } = entry.data
+const { Content } = await render(entry)
+---
+
+<ArticleLayout title={title} description={description} topics={topics} github_url={githubUrl}>
+ <Content components={{ Admonition }} />
+</ArticleLayout>
diff --git a/apps/kb/vercel.json b/apps/kb/vercel.json
index e8aa76781b3..1b5f675311a 100644
--- a/apps/kb/vercel.json
+++ b/apps/kb/vercel.json
@@ -11,6 +11,11 @@
"source": "/kb/topics/:path+.md",
"destination": "/kb/markdown/topics/:path+.md",
"permanent": true
+ },
+ {
+ "source": "/kb/troubleshooting/:path+.md",
+ "destination": "/kb/markdown/troubleshooting/:path+.md",
+ "permanent": true
}
],
"rewrites": [
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7401a0647d8..daa119338a4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -374,9 +374,6 @@ importers:
'@octokit/graphql':
specifier: ^8.0.0
version: 8.2.1
- '@octokit/plugin-paginate-graphql':
- specifier: ^4.0.0
- version: 4.0.0(@octokit/[email protected])
'@octokit/plugin-retry':
specifier: ^8.1.0
version: 8.1.0(@octokit/[email protected])
@@ -663,9 +660,6 @@ importers:
cheerio:
specifier: ^1.0.0-rc.12
version: 1.2.0
- chokidar:
- specifier: ^4.0.3
- version: 4.0.3
dotenv:
specifier: ^16.0.3
version: 16.3.1
@@ -681,9 +675,6 @@ importers:
graphiql:
specifier: ^4.0.2
- npm-run-all:
- specifier: ^4.1.5
- version: 4.1.5
openapi-types:
specifier: ^12.1.3
version: 12.1.3
@@ -756,12 +747,27 @@ importers:
'@astrojs/sitemap':
specifier: ^3.7.4
version: 3.7.4
+ '@octokit/auth-app':
+ specifier: ^7.0.0
+ version: 7.1.5
+ '@octokit/core':
+ specifier: ^7.0.6
+ version: 7.0.6
+ '@octokit/plugin-retry':
+ specifier: ^8.1.0
+ version: 8.1.0(@octokit/[email protected])
+ '@supabase/supabase-js':
+ specifier: 'catalog:'
+ version: 2.117.3(@opentelemetry/[email protected])
astro:
specifier: ^7.2.6
common:
specifier: workspace:*
version: link:../../packages/common
+ gray-matter:
+ specifier: ^4.0.3
+ version: 4.0.3
lucide-react:
specifier: '*'
version: 0.436.0([email protected])
@@ -814,12 +820,18 @@ importers:
config:
specifier: workspace:*
version: link:../../packages/config
+ dotenv:
+ specifier: ^16.5.0
+ version: 16.5.0
lodash-es:
specifier: ^4.18.1
version: 4.18.1
tailwindcss:
specifier: 'catalog:'
version: 4.2.4
+ tsx:
+ specifier: 'catalog:'
+ version: 4.22.4
vitest:
specifier: 'catalog:'
@@ -1843,7 +1855,7 @@ importers:
version: 21.1.1
'@sentry/nextjs':
specifier: 'catalog:'
'@supabase/ssr':
specifier: 'catalog:'
version: 0.12.7(@supabase/[email protected](@opentelemetry/[email protected]))
@@ -2114,10 +2126,10 @@ importers:
version: 14.0.0
vite:
specifier: 'catalog:'
vitest:
specifier: 'catalog:'
zod:
specifier: 'catalog:'
version: 3.25.76
@@ -2693,10 +2705,10 @@ importers:
version: 6.0.2
vite:
specifier: 'catalog:'
vitest:
specifier: 'catalog:'
packages/shared-data:
dependencies:
@@ -19003,9 +19015,6 @@ packages:
resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
- resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}
-
resolution: {integrity: sha512-v5l/aFXZQeai4awLbOpSoHecE9UiMrnfx75tEXLjNonXVARxQ5mOeipTjROUchszUNCqnE+hqAMujRsRHsut2Q==}
@@ -19213,7 +19222,7 @@ snapshots:
dependencies:
- '@babel/generator': 7.29.7
+ '@babel/generator': 7.29.8
'@babel/parser': 7.29.8
'@babel/runtime': 7.26.10
chalk: 4.1.2
@@ -22282,7 +22291,7 @@ snapshots:
'@modelcontextprotocol/[email protected]':
dependencies:
'@modelcontextprotocol/core': 2.0.0
- zod: 4.4.3
+ zod: 4.6.5
'@monaco-editor/[email protected]':
dependencies:
@@ -23000,10 +23009,6 @@ snapshots:
dependencies:
'@octokit/core': 6.1.4
- '@octokit/[email protected](@octokit/[email protected])':
- dependencies:
- '@octokit/core': 7.0.6
-
'@octokit/[email protected](@octokit/[email protected])':
dependencies:
'@octokit/core': 6.1.4
@@ -24764,7 +24769,7 @@ snapshots:
- vite
- webpack
dependencies:
'@opentelemetry/api': 1.9.1
'@rollup/plugin-commonjs': 28.0.1([email protected])
@@ -24772,7 +24777,7 @@ snapshots:
'@sentry/bundler-plugin-core': 5.3.0([email protected])([email protected])
'@sentry/conventions': 0.12.0
'@sentry/core': 10.59.0
'@sentry/opentelemetry': 10.59.0(@opentelemetry/[email protected])(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))
'@sentry/react': 10.59.0([email protected])
'@sentry/vercel-edge': 10.59.0
@@ -24845,6 +24850,23 @@ snapshots:
- supports-color
- vite
+ dependencies:
+ '@opentelemetry/api': 1.9.1
+ '@opentelemetry/core': 2.8.0(@opentelemetry/[email protected])
+ '@opentelemetry/instrumentation': 0.214.0(@opentelemetry/[email protected])([email protected])
+ '@opentelemetry/sdk-trace-base': 2.8.0(@opentelemetry/[email protected])
+ '@opentelemetry/semantic-conventions': 1.41.1
+ '@sentry/core': 10.59.0
+ '@sentry/node-core': 10.59.0(@opentelemetry/[email protected])(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected])([email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))
+ '@sentry/opentelemetry': 10.59.0(@opentelemetry/[email protected])(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))
+ import-in-the-middle: 3.1.0
+ transitivePeerDependencies:
+ - '@opentelemetry/exporter-trace-otlp-http'
+ - supports-color
+ - vite
+
'@sentry/[email protected](@opentelemetry/[email protected])(@opentelemetry/[email protected](@opentelemetry/[email protected]))(@opentelemetry/[email protected](@opentelemetry/[email protected]))':
dependencies:
'@opentelemetry/api': 1.9.1
@@ -24892,6 +24914,19 @@ snapshots:
transitivePeerDependencies:
- supports-color
+ dependencies:
+ '@apm-js-collab/code-transformer': 0.15.0
+ '@apm-js-collab/code-transformer-bundler-plugins': 0.5.0
+ '@apm-js-collab/tracing-hooks': 0.10.0([email protected])
+ '@sentry/conventions': 0.12.0
+ '@sentry/core': 10.59.0
+ magic-string: 0.30.21
+ optionalDependencies:
+ transitivePeerDependencies:
+ - supports-color
+
dependencies:
'@opentelemetry/api': 1.9.1
@@ -27107,7 +27142,7 @@ snapshots:
dependencies:
'@jridgewell/trace-mapping': 0.3.31
'@vitest/spy': 5.0.0
@@ -27115,7 +27150,7 @@ snapshots:
magic-string: 1.2.3
optionalDependencies:
'@vitest/[email protected]':
dependencies:
@@ -27845,7 +27880,7 @@ snapshots:
xxhash-wasm: 1.1.0
yargs-parser: 22.0.0
- zod: 4.4.3
+ zod: 4.6.5
optionalDependencies:
'@astrojs/markdown-remark': 7.2.4([email protected])
sharp: 0.35.4(@types/[email protected])
@@ -31913,7 +31948,7 @@ snapshots:
tinyglobby: 0.2.17
unbash: 4.0.10
yaml: 2.9.0
- zod: 4.4.3
+ zod: 4.6.5
@@ -38101,6 +38136,23 @@ snapshots:
tsx: 4.22.4
yaml: 2.9.0
+ dependencies:
+ lightningcss: 1.33.0
+ picomatch: 4.0.7
+ postcss: 8.5.28
+ rolldown: 1.2.9
+ tinyglobby: 0.2.17
+ optionalDependencies:
+ '@types/node': 24.19.0
+ esbuild: 0.28.1
+ fsevents: 2.3.3
+ jiti: 2.7.0
+ sass: 1.77.4
+ terser: 5.48.0
+ tsx: 4.22.4
+ yaml: 2.9.0
+
optionalDependencies:
@@ -38157,10 +38209,10 @@ snapshots:
transitivePeerDependencies:
- msw
dependencies:
'@types/chai': 5.2.2
chai: 6.2.2
es-module-lexer: 2.3.2
expect-type: 1.4.0
@@ -38171,11 +38223,11 @@ snapshots:
tinybench: 6.1.4
tinyexec: 1.3.0
tinyglobby: 0.2.17
why-is-node-running: 2.3.0
optionalDependencies:
'@opentelemetry/api': 1.9.1
- '@types/node': 22.13.14
+ '@types/node': 24.19.0
'@vitest/coverage-v8': 5.0.0([email protected])
'@vitest/ui': 5.0.0([email protected])
happy-dom: 20.14.5
@@ -38596,8 +38648,6 @@ snapshots:
-
diff --git a/supabase/migrations/20261002221413_trim_troubleshooting_entries.sql b/supabase/migrations/20261002221413_trim_troubleshooting_entries.sql
new file mode 100644
index 00000000000..05bbeb52728
--- /dev/null
+++ b/supabase/migrations/20261002221413_trim_troubleshooting_entries.sql
@@ -0,0 +1,10 @@
+alter table troubleshooting_entries
+ drop column if exists title,
+ drop column if exists topics,
+ drop column if exists keywords,
+ drop column if exists api,
+ drop column if exists errors;
+
+-- Nullable: 278 existing rows predate kb and have no sensible slug value.
+alter table troubleshooting_entries
+ add column slug text unique;
diff --git a/supabase/migrations/20261006194306_add_troubleshooting_entries_checksum.sql b/supabase/migrations/20261006194306_add_troubleshooting_entries_checksum.sql
new file mode 100644
index 00000000000..478653906d8
--- /dev/null
+++ b/supabase/migrations/20261006194306_add_troubleshooting_entries_checksum.sql
@@ -0,0 +1,6 @@
+-- Replaces the legacy `checksum` column from the old GitHub-sync workflow
+-- (20241002215612_troubleshooting_validation.sql), which that workflow's
+-- removal left behind. Dropped and re-added nullable: existing rows should
+-- start out as unsynced, not carry over the old column's stale values.
+alter table troubleshooting_entries drop column if exists checksum;
+alter table troubleshooting_entries add column checksum text;