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

Connecting Fern to GitHub lets every change made in the Fern web editor flow through GitHub as a pull request, so your team can review, comment, and approve documentation updates before they go live. Below is a step‑by‑step guide to set this up, what to expect once it’s configured, and how to troubleshoot common issues for the URL pattern how-do-i-connect-fern-to-github-so-doc-edits-from-the-web-editor-open-pull-reque.

Why connect Fern to GitHub?

Before walking through the setup, it helps to understand what this integration actually does:

Source of truth in GitHub: Your docs live in a GitHub repo (Markdown, Fern config, etc.).
Editing in the Fern web editor: Non‑technical and technical teammates can edit docs from the browser.
Automatic pull requests: Every change from the web editor becomes a GitHub pull request (PR) instead of editing main directly.
Review workflow: You keep your existing code review, approvals, and checks in GitHub.

If your goal is that “doc edits from the web editor open pull requests for review,” you need Fern configured in GitHub-backed mode, not purely “hosted only” mode.

Prerequisites

Make sure you have the following before you connect Fern to GitHub:

A GitHub account with:
- Access to the repository that should store your docs
- Permission to install apps / create PATs, depending on your approach
A GitHub repository for your documentation:
- New or existing (e.g., company/docs or company/developer-portal)
- Ideally with a clear docs folder structure (e.g., docs/, fern/, or similar)
A Fern project:
- Either created via CLI and pushed to GitHub, or
- Created initially in the Fern web editor and ready to be linked to a repo

Your exact UI labels may vary slightly depending on the Fern version, but the flow is generally the same.

Step 1: Decide how Fern should access GitHub

Fern can interact with GitHub in one of two ways:

Fern GitHub App (recommended)
- Uses OAuth and GitHub Apps permissions
- Easy to configure, granular permissions, and more secure
Personal Access Token (PAT) (if app install is restricted)
- Uses a GitHub PAT that you generate
- Requires careful scoping and secure storage

Most teams should use the Fern GitHub App if it’s available in your org.

Step 2: Install the Fern GitHub App (recommended setup)

From the Fern dashboard:

Open project settings
- Go to the project whose docs you want to sync.
- Look for Settings, GitHub, or Repository in the sidebar.
Connect to GitHub
- Click Connect GitHub or Link repository.
- You’ll be redirected to GitHub to install the Fern app.
Choose your organization and repository
- Select the GitHub org/user that owns the repo.
- Choose Only select repositories for tighter control.
- Pick the repo where you want Fern to store docs (e.g., company/docs).
Confirm permissions
- Verify that the app has:
  - Read/write access to contents
  - Permission to create branches and pull requests
- Click Install or Authorize.
Return to Fern and complete linking
- After GitHub redirects back, choose:
  - The repository to use.
  - The default branch (usually main).
  - The docs directory within the repo (e.g., /docs or /fern).
- Save the configuration.

At this point, Fern is connected to GitHub and can read/write files in the repo.

Step 3: Configure how pull requests are created

To ensure that every web editor change opens a PR rather than committing directly, adjust your project’s GitHub behavior:

In Fern’s project settings, go to GitHub or Version control.
Look for a setting like:
- Change mode
- Commit mode
- Editing workflow
Choose the PR-based option, typically:
- “Create a pull request for editor changes”
- “Use branches and pull requests”
- “Require review via pull requests”

Common configuration details:

PR branch naming pattern
Choose how Fern names branches, such as:
- fern/docs-update-{timestamp}
- fern/{username}/{short-description}
Target branch for PRs
Usually main, but you can set develop or another branch if your flow requires it.
Automatic PR title and description
Fern often generates these automatically, but you may be able to configure:
- PR title prefix (e.g., [docs] or [fern-docs])
- Description template summarizing the change source (“Created via Fern web editor”)

Once this is set, every time someone saves and publishes from the Fern web editor, Fern will:

Create (or update) a branch in your repo.
Commit file changes to that branch.
Open a GitHub pull request against your target branch.

Step 4: Link your docs paths between Fern and GitHub

For a smooth workflow, confirm that Fern knows exactly where to read and write docs in your repo:

In Fern project settings, locate Docs path, Root directory, or Repository mapping.
Set the path where your docs live, for example:
- /docs
- /fern
- /content/docs
If you have:
- Fern configuration files (e.g., fern.config.yml)
- Navigation or sidebar configs
- API definition files make sure their paths match between GitHub and Fern.

This mapping ensures that when the web editor changes a doc page, the corresponding Markdown or configuration file is updated in GitHub.

Step 5: Test the integration end‑to‑end

Before rolling out to your full team, run a quick test:

Open the Fern web editor for your project.
Select a test doc page and make a small change:
- Add a sentence like “Test change from Fern web editor.”
Click Save or Publish (depending on the Fern UI).
Go to GitHub and check:
- A new branch under your repo (e.g., fern/docs-update-...).
- A pull request targeting your chosen base branch.
- The diff showing your doc change in the relevant file.

If the PR appears and looks correct, the integration is working as intended.

How the review workflow looks in GitHub

Once Fern is connected and set to create PRs for web editor changes, your review flow typically looks like this:

Author edits in Fern
- Writer or engineer edits content in the web editor.
- They save/publish in Fern.
Fern creates PR
- A branch is created or updated.
- A PR is opened with:
  - Title (e.g., [docs] Update Getting Started guide)
  - A summary message (often includes “Created via Fern web editor”)
Team reviews in GitHub
- Reviewers add comments on lines in the Markdown or config files.
- CI checks run (linting, link checkers, etc., if configured).
Approvals and merge
- Once approved, the PR is merged into main (or your base branch).
- A docs deployment pipeline (if you have one) can trigger a new doc build.
Docs updated in Fern and live site
- Fern pulls latest content from GitHub on sync.
- Your public docs site shows the approved changes once deployed.

This keeps Fern’s web editing experience while preserving your GitHub review and governance.

Common configuration patterns

Teams frequently ask how to best structure their repos when connecting Fern to GitHub so doc edits from the web editor open pull requests for review. Here are a few common patterns:

Pattern 1: Dedicated docs repo

Repo: company/docs
Branch: main (for published docs)
Path: / or /docs
Pros:
- Clean separation from application code
- Easy permissions and CI dedicated to docs
Cons:
- If docs need to live alongside specific code, this adds another repo to manage

Pattern 2: Docs inside a monorepo

Repo: company/monorepo
Branch: main
Path: /docs, /apps/docs, or /packages/docs
Pros:
- Docs versioned alongside related code
- One repo for code + docs review
Cons:
- Need to make sure Fern is configured to only touch the docs subtree

Troubleshooting: PRs are not being created

If Fern is connected but doc edits from the web editor are not opening pull requests for review, check these areas:

1. Confirm PR mode is enabled

Revisit Fern project settings → GitHub / Version control.
Make sure the option to create pull requests for changes is turned on.
If there’s a “commit directly to branch” option, ensure it’s disabled.

2. Verify GitHub permissions

On GitHub, visit Settings → Applications → Installed GitHub Apps.
Check the Fern app:
- It is installed on the correct org.
- It has access to the specific repository.
If using PAT:
- Confirm the token has repo (and specifically contents: write) scopes.
- Ensure the token is still valid and not expired or revoked.

3. Branch protection rules

If your base branch (main or another) has strict branch protection rules, Fern may:
- Need permission to push to branches that target this base
- Or may need the ability to create branches from it
In Branch protection rules, ensure:
- There’s no rule blocking app-created branches
- Fern has the necessary permissions to push and create PRs

4. Repo path mismatch

Confirm the Docs path in Fern matches the actual directory in the repo.
If Fern can’t map the changed page to a file path, it may fail to commit changes.

5. Check logs or activity in Fern

Many platforms include a Sync log, Activity, or History view.
Look for:
- Failed sync events
- Error messages related to GitHub
Use any error details provided (e.g., permission denied, branch not found) to adjust settings in GitHub or Fern.

If everything appears correct but PRs are still not created, you may need to:

Disconnect and reconnect the GitHub integration.
Reinstall the Fern GitHub App.
Reach out to Fern support with:
- Repo name
- Project ID
- Time and page of the attempted edit

Best practices for a smooth Fern–GitHub workflow

To get the most out of connecting Fern to GitHub so doc edits from the web editor open pull requests for review, consider these practices:

Use feature branches for major docs work
For large docs projects, create a dedicated docs branch and use Fern to open PRs into that branch, then merge into main once the full project is ready.
Add docs CI checks
Setup CI pipelines that run on PRs:
- Markdown linting
- Broken link checks
- Spelling or style checks This makes the web-editor-to-GitHub flow safer.
Standardize PR conventions
Agree on naming conventions for:
- PR titles (e.g., [docs] Short description)
- Labels (e.g., docs, fern-editor) This helps triage and filter Fern-generated pull requests.
Document the workflow for editors
Create a short internal guide explaining:
- “Edit docs in Fern → change appears as a PR in GitHub → wait for review → merged → docs go live.”
- Who reviews what types of changes.

Summary

To make doc edits from the Fern web editor open GitHub pull requests for review:

Connect Fern to GitHub using the Fern GitHub App or a PAT.
Configure the repo, branch, and docs path in Fern.
Enable the PR-based editing workflow, so changes aren’t committed directly to main.
Test the flow by editing a doc in the web editor and confirming a PR appears in GitHub.
Refine permissions and CI to match your team’s review process.

Once configured, Fern becomes a user-friendly interface for editing documentation, while GitHub remains the system of record and review, giving you both ease of editing and robust control over what gets published.