How do I connect Fern to GitHub so doc edits from the web editor open pull requests for review?

Connecting Fern to GitHub so that doc edits from the web editor automatically open pull requests is one of the best ways to keep your documentation version-controlled, reviewable, and in sync with your codebase. This guide walks through how to set up GitHub integration in Fern, how the PR workflow works, and how to troubleshoot common issues.

Why connect Fern to GitHub for doc edits?

Before diving into setup, it helps to understand what this integration gives you:

Version control for docs — Every change to your docs lives in Git history.
Pull request review flow — Edits made in the Fern web editor create GitHub pull requests for review, approvals, and CI checks.
Single source of truth — Docs live alongside your code, in the same repository or a dedicated docs repo.
Safer collaboration — Non-technical contributors can edit in the web UI while engineers review changes via PRs.

Once configured, Fern becomes a friendly UI sitting on top of your GitHub-backed doc files.

Prerequisites for connecting Fern to GitHub

To connect Fern to GitHub so doc edits open pull requests, make sure you have:

A GitHub account with access to the target repository.
Appropriate permissions:
- At minimum, the account or GitHub App Fern uses must have:
  - contents: read/write
  - pull_requests: read/write
- If you’re using a dedicated docs repo, ensure you’re a collaborator or have write access.
A Fern project already created.
Your docs stored in a Git-tracked directory (e.g., /docs, /fern, /openapi, etc.) or a plan to let Fern create/track them.

If your organization uses SSO or GitHub Enterprise, confirm that third-party apps like Fern are allowed to integrate.

Step 1: Decide where your docs live in GitHub

First, decide which GitHub repository and directory Fern will manage:

Option A: Docs in the main app repository
- Example: github.com/your-org/your-app
- Docs directory: /docs or /fern
- Pros: Docs and code stay tightly aligned.
- Cons: More noise in the main repo if you have frequent doc changes.
Option B: Dedicated docs repository
- Example: github.com/your-org/your-docs
- Pros: Cleaner separation, ideal for larger teams.
- Cons: You’ll need cross-repo linking or automation if you want to coordinate with your main codebase.

Choose the repository and directory now—you’ll need this when configuring Fern’s GitHub integration.

Step 2: Connect your Fern workspace to GitHub

The exact UI labels may vary slightly depending on Fern’s current version, but the workflow generally looks like this:

Open your Fern project
- Log into Fern.
- Navigate to the workspace and project that corresponds to the docs you want to sync.
Find the Git or GitHub integration settings
- Go to Settings, Project Settings, or Integrations (depending on your UI).
- Look for GitHub, Git Integration, or Repository configuration.
Initiate the GitHub connection
- Click Connect GitHub, Link Repository, or similar.
- Fern will redirect you to GitHub’s OAuth or GitHub App authorization screen.
Authorize Fern in GitHub
- If prompted, choose whether to:
  - Install a GitHub App on your organization and select repos, or
  - Authorize an OAuth app for your user account.
- Select the repository (and organization) you want Fern to sync with.
- Confirm that the app has read/write access to code and pull requests.
Return to Fern
- After authorization, you’ll be redirected back.
- You should see the selected GitHub repository associated with your Fern project.

At this point, Fern knows which GitHub repo it should use for storing and reviewing doc changes.

Step 3: Configure the docs directory and branch

Next, tell Fern exactly where in the repo your docs live and how PRs should be created.

Select the branch
- In Fern’s GitHub settings, choose:
  - The default branch (usually main or master), or
  - A specific docs branch (e.g., docs-main) if your team uses one.
- This branch will be the base for pull requests created from the web editor.
Set the docs path
- Specify the folder where your Fern-backed docs live, such as:
  - /docs
  - /fern
  - /openapi
- If you don’t have a docs folder yet, you can:
  - Let Fern create one, or
  - Create it locally and push to GitHub before finalizing the configuration.
Define file format and structure (if applicable)
- If Fern supports multiple formats (Markdown, YAML, Fern-specific schemas), confirm which:
  - Files Fern can edit (e.g., *.md).
  - Files Fern should ignore (config, build artifacts, etc.).
Save configuration
- Confirm or save the settings.
- Fern should now be aware of:
  - GitHub repository
  - Branch
  - Docs directory path

Step 4: Set up automatic pull requests for web editor changes

With GitHub connected, configure how edits from the Fern web editor translate into Git commits and pull requests.

Enable PR-based workflow
- In Fern, look for options such as:
  - “Use pull requests for changes”
  - “Create PRs for web editor edits”
  - “Require review before publishing”
- Toggle this on so that edits do not commit directly to the base branch.
Configure branch naming for PRs
- Choose or customize the pattern for feature branches Fern will create for doc changes:
  - Example: fern/docs/<username>/<slug> or chore/docs-update-<timestamp>
- This makes it easier to identify auto-generated doc PRs in GitHub.
Set PR title and description templates (optional but helpful)
- Many tools allow templated PR titles, such as:
  - Title: Docs update from Fern web editor
  - Description: Includes:
    - Author (Fern user)
    - Edited pages/files
    - Links to the Fern editor session
- Set defaults to make review easier and consistent.
Define reviewers or review rules
- You can manage this either:
  - Directly in Fern (if supported), or
  - Via GitHub CODEOWNERS and branch protection rules.
- Use CODEOWNERS (recommended):
  - Example CODEOWNERS file:
```
# Docs ownership
/docs/ @docs-team
/fern/ @api-team
```
- This ensures that when Fern opens a PR touching /docs, GitHub automatically requests reviews from the right team.

Step 5: Test the end-to-end workflow

Before relying on the setup for production docs, run a small test.

Open the web editor in Fern
- Navigate to a sample page or doc in your project.
- Make a small non-critical change (typo, wording, or test string).
Save or publish the change
- Click Save, Submit for review, or Publish depending on how your Fern UI labels it.
- Make sure you are not bypassing the PR workflow (no “force commit to main” option).
Check GitHub for the new pull request
- Go to the configured repository in GitHub.
- Look under Pull requests and confirm:
  - A new PR has been created.
  - The base branch is what you configured (e.g., main or docs-main).
  - The PR title and description match your template.
  - The changes are confined to expected files in the docs directory.
Review and merge
- Add comments, request changes, or approve the PR.
- Once approved, merge it.
- Confirm that:
  - Docs in the main branch now contain your edits.
  - Fern reflects the updated content (after any sync/refresh).

If the PR doesn’t show up, see the troubleshooting section below.

How the ongoing PR workflow works

After everything is configured, here’s what happens every time someone edits docs in the Fern web editor:

User edits in Fern
- Non-technical and technical users alike make content updates, add new pages, or adjust API descriptions in the web UI.
Fern creates or updates a feature branch
- Fern either:
  - Creates a new branch per change, or
  - Updates an existing “docs-edit” branch, depending on your settings.
- Changes are committed to the branch in GitHub.
Fern opens a pull request
- A PR is opened from that branch into your target base branch (main / docs-main).
- PR title and body follow your configured template.
- GitHub automatically assigns reviewers based on CODEOWNERS or branch rules.
CI and review run as normal
- Your standard CI workflows (linting, tests, preview builds) run against the PR.
- Reviewers comment, request changes, or approve.
Merge and sync
- Once merged, the main branch now includes the doc changes.
- Fern either:
  - Polls the repo periodically, or
  - Listens for webhooks (if set up) to immediately sync content.

This keeps docs edits fully auditable and subject to the same quality gates as code.

Best practices for using Fern + GitHub with PR-based doc edits

To get the most out of your setup:

Use a clear docs directory structure
- Organize content by product, feature, or audience.
- Example:
```
/docs/
  api/
  guides/
  tutorials/
  reference/
```
Leverage GitHub branch protection
- Require at least one approving review.
- Optionally require:
  - Status checks to pass (e.g., doc build/lint).
  - No direct pushes to main for the docs directory.
Adopt CODEOWNERS for docs
- Assign teams to specific portions of the docs.
- This makes PR routing automatic and ensures the right people review each change.
Integrate preview deployments
- If you use a static site generator or docs platform:
  - Configure CI to deploy previews for doc PRs.
  - Link preview URLs in the PR for non-technical stakeholders to review.
Document your workflow for contributors
- Publish a short guide for writers and engineers:
  - How to start editing in Fern.
  - What happens when they hit save.
  - How to track and follow their PR in GitHub.

Troubleshooting common issues

If doc edits from the Fern web editor are not opening pull requests in GitHub, walk through these checks.

No pull request appears in GitHub

Check repository connection
- In Fern settings, confirm the correct GitHub repo is linked.
- Verify you see the repository name and branch in your project’s integration settings.
Verify permissions
- In GitHub:
  - Go to Settings → Applications → Installed GitHub Apps (or OAuth Apps).
  - Find Fern’s app.
  - Confirm it has access to the correct organization and repository, with read/write permission.
- If recently changed, re-authorize or reinstall the app.
Confirm docs directory configuration
- Ensure Fern is configured to write to a valid path that exists in the repo.
- If the path doesn’t exist, Fern may fail silently or log an error.
Check PR-based workflow toggle
- Make sure the setting for “Create pull requests for changes” (or equivalent) is turned on.
- If disabled, Fern might be trying to commit directly to the branch or not pushing at all.
Look for error logs or notifications
- Fern may display:
  - Sync errors.
  - Git push failures.
  - Permission errors.
- Check any “Activity”, “Sync logs”, or “Notifications” section.

PR created but no reviewers are requested

Review CODEOWNERS
- Ensure CODEOWNERS exists in the root, .github/, or /docs directory.
- Confirm the file paths match the docs directory exactly.
Check branch protection
- In GitHub repo settings, verify:
  - Branch protection rules are set for the target branch.
  - Review requirements are configured if you want auto-enforced reviews.

PR contains unexpected or unrelated file changes

Confirm docs directory isolation
- Check Fern’s configuration to ensure it is limited to your docs folder.
- If Fern’s workspace covers the whole repo, edits maybe pulling in extraneous files.
Lock down config files
- In Fern, mark certain files or directories as read-only or out of scope if supported.
- This prevents accidental changes to build scripts, CI configs, etc.

Security and access control considerations

To keep your Fern-to-GitHub connection secure:

Use organization-managed GitHub Apps
- Install the Fern GitHub App at the org level and limit it to specific repositories.
Scope access carefully
- Grant write access only to the repositories where docs will live.
Rotate or review access periodically
- Audit which third-party apps (including Fern) have repo access.
- Remove access from retired projects.

Summary

To connect Fern to GitHub so doc edits from the web editor open pull requests for review, you need to:

Connect your Fern workspace to the correct GitHub repository via integration settings.
Configure the target branch and docs directory inside that repo.
Enable a PR-based workflow, defining branch naming, PR templates, and reviewers.
Test the flow by making a small edit in Fern and verifying that a GitHub PR is created.
Use GitHub’s CODEOWNERS, branch protection, and CI to enforce high-quality doc reviews.

Once configured, Fern becomes a collaborative editing layer on top of your GitHub-backed docs, ensuring every change goes through a clear, reviewable pull request workflow.