GitHub Sync

Connect your GitHub account to import documentation directly from your repositories into the Workestra Knowledge Base. This is perfect for teams that already maintain docs in GitHub.

Prerequisites

Before you begin, ensure you have:

• A GitHub account (personal or organization)
• Access to repositories containing documentation
• Repositories should contain markdown (.md or .mdx) files
• Appropriate permissions to install GitHub apps or OAuth integrations

Connecting GitHub

Step 1: Start the Connection

1. Navigate to Knowledge Base in the sidebar
2. Click the ... (more actions) menu in the top right
3. Select Import from GitHub
4. The GitHub OAuth modal opens

Step 2: Authorize Workestra

1. Review the permissions Workestra is requesting:
   • Read repositories — To list and access your repos
   • Read repository contents — To import markdown files
2. Click Authorize Workestra
3. If prompted, sign in to your GitHub account

Step 3: Select Repositories

After authorization:

1. You'll see a list of accessible repositories
2. Use the search box to find specific repos
3. Select the repository containing your documentation
4. Choose the branch (usually main, master, or docs)

Step 4: Select Files and Folders

Drill down into the repository to select what to import:

1. Navigate through the folder structure
2. Check folders to import entire directories
3. Or check individual files for selective import
4. Common documentation folders: /docs, /wiki, /guides

How Sync Works

The Sync Process

When you import from GitHub:

1. Edge Function Activation — The sync-github-docs edge function processes your request
2. File Fetching — Markdown files are retrieved from GitHub's API
3. Content Conversion — Files are converted to Knowledge Base documents
4. Metadata Extraction — Frontmatter (YAML headers) is parsed
5. Document Creation — Documents are created in your Knowledge Base

What's Imported

Supported File Types

• .md — Markdown files
• .mdx — MDX files (JSX components are stripped)

Other file types are ignored during import.

After Import

Where Documents Appear

Imported documents appear in your Knowledge Base with:

• Title — From frontmatter title or filename
• Tags — From frontmatter tags + folder path
• Scope — Based on your import selection (workspace/team)
• Source — "GitHub" indicator shows it was imported

Editing Imported Documents

You can edit imported documents just like any other Knowledge Base doc:

• Changes are saved in Workestra
• Changes do not sync back to GitHub
• The original GitHub file remains unchanged

Re-Syncing After Changes

If your GitHub documentation changes and you want to update Workestra:

Option 1: Re-Import

1. Delete the existing imported documents (optional)
2. Run the import process again
3. New documents will be created with the latest content

Option 2: Manual Update

For small changes, it may be easier to:

1. View the updated file on GitHub
2. Copy the new content
3. Paste into the existing Workestra document

Troubleshooting

Permission Issues

Problem: Private repositories don't appear in the list

Solutions:

• Ensure you granted access to private repositories during OAuth
• For organization repos, an admin may need to approve the app
• Check that your GitHub token has repo scope

Import Failures

Problem: Files aren't importing

Solutions:

• Verify files have .md or .mdx extensions
• Check that files are under 1MB (large files may timeout)
• Ensure the branch name is correct

Formatting Problems

Problem: Documents don't look right after import

Solutions:

• GitHub-flavored markdown tables should convert correctly
• Complex HTML in markdown may not render perfectly
• Embedded scripts and iframes are stripped for security

Rate Limits

GitHub API rate limits apply:

• Unauthenticated: 60 requests/hour
• Authenticated: 5,000 requests/hour

Large imports may hit these limits. If you see rate limit errors:

1. Wait an hour and try again
2. Import in smaller batches
3. Contact support for enterprise assistance

Security & Privacy

Data Handling

• Repository contents are fetched directly to your workspace
• We don't store your GitHub credentials
• Access tokens are encrypted and scoped
• Imported content follows your workspace's security settings

Revoking Access

To disconnect GitHub:

1. Go to Settings > Connected Accounts
2. Find GitHub in the list
3. Click Disconnect
4. Or revoke access from your GitHub account settings

Best Practices

Organize Before Importing

1. Clean up your GitHub docs folder structure
2. Remove outdated or draft files
3. Ensure frontmatter is consistent
4. Use meaningful filenames

Example Frontmatter

---
title: Onboarding Guide
description: Steps for new team members
tags: [hr, onboarding, getting-started]
author: Jane Doe
date: 2024-03-15
---

Maintain a Single Source of Truth

Decide on your primary documentation location:

• GitHub as source: Regularly re-import to Workestra
• Workestra as source: Edit docs in Workestra, reference from GitHub

Next Steps

• Knowledge Base — Learn more about managing documents
• Connected Accounts — Manage your GitHub connection