Skip to main content
All Guides

Set Up GitHub Sync

Automatically commit your project documentation as Markdown files to a GitHub repository every time you save. Available on Pro and Organisation plans.

What GitHub Sync Does

Auto-Commit on Save

Every time you save a document in a linked project, it is automatically committed to your GitHub repository as a Markdown file.

Configurable Base Path

Choose the directory in your repository where documents are committed — for example docs/ or wiki/.

Non-Blocking

Sync happens in the background. If GitHub is temporarily unreachable, your workflow continues uninterrupted — the sync retries silently.

Before You Start

  • You are on the Pro or Organisation plan. View pricing
  • You have a GitHub account with at least one repository you want to sync to.
  • You have at least one project created in Noteble.

Step-by-Step Setup

1

Install the Noteble GitHub App

The Noteble GitHub App is what allows Noteble to commit files to your repositories on your behalf. Click the button below to install it on the GitHub organisation or personal account that owns the repositories you want to sync to.

Install Noteble GitHub App

During installation, GitHub will ask you to choose which repositories Noteble can access:

  • All repositories — Noteble can sync to any repository in the account. Simplest if you plan to use GitHub Sync across multiple projects.
  • Only select repositories — restrict access to specific repositories. You can add more later.

Permissions requested

The Noteble GitHub App only requests read and write access to repository contents. It does not access your code, issues, pull requests, or any other data.

If you are installing on an organisation, you may need organisation owner permissions. If your org requires admin approval for apps, an owner will need to approve the request.

You can review or change repository access at any time in your GitHub settings under Settings → Integrations → Applications → Installed GitHub Apps.

2

Open Your Project Settings

Go to the Projects page in Noteble. Switch to Edit mode using the toggle in the toolbar, then click the edit button on the project you want to connect.

This opens the project modal where you can configure the name, type, description, metadata, and — on Pro and Organisation plans — the GitHub Sync section at the bottom.

3

Connect to GitHub

In the GitHub Sync card at the bottom of the project modal, click Connect to GitHub .

Select your GitHub organisation — if you installed the Noteble app on multiple accounts, pick the one that owns the target repository.

Select the repository — choose the repository where you want documentation files to be committed.

Set the base path — this is the directory inside the repository where files will be placed. The default is docs/. You can change it to any directory structure you prefer, such as documentation/noteble/.

4

Click Connect

Click the Connect button. Once linked, you will see a green Connected badge and the linked repository name in the GitHub Sync card.

From this point on, every time you save or update a document in this project, it will be automatically committed to the repository as a Markdown file under the base path you chose.

After Setup

Project Card

Connected projects show a green git branch icon with the repository name (e.g. acme/docs) directly on the project card, so you can see the sync status at a glance.

Recent Syncs

Open the project settings to see a list of recently synced documents with their file paths and dates. This helps you verify that sync is working as expected.

Disconnecting

To stop syncing a project, open the project settings and click Disconnect in the GitHub Sync card. This removes the link between the project and the repository.

Files already committed to GitHub are not deleted when you disconnect. They remain in the repository as regular Markdown files.

Ready to Sync Your Docs?

GitHub Sync is available on Pro and Organisation plans. Start your free trial to try it out.

Start Free Trial View Pricing