Overview Quick Start Beginners Troubleshoot Support Privacy

Beginners Guide

From zero to synced vault

No prior experience with GitHub, Git, or version control needed. This guide walks through every step, start to finish.

First — what is GitHub?

GitHub is a website that stores files online, like a cloud hard drive — but with one major advantage: it keeps a full history of every change you make. You can see exactly what changed, when, and restore any previous version.

For your Obsidian vault, this means your notes are safely backed up to the internet, accessible from any device, and recoverable even if you accidentally delete something.

You do not need to know how to use Git (the command-line tool). This plugin communicates with GitHub directly, so you never touch a terminal.

GitHub has a free tier that is fully sufficient for syncing personal Obsidian vaults, including private repositories.

Complete setup walkthrough

1

Create a GitHub account

Go to github.com and sign up for a free account. You will need an email address. Once created, verify your email.

Remember your username — you will need it in the plugin settings.

2

Create a new repository

A repository (or "repo") is essentially a folder on GitHub that will hold your vault. Think of it as the remote home for your notes.

To create one:

  1. Click the + icon in the top-right corner of GitHub
  2. Select New repository
  3. Give it a name (e.g., my-obsidian-vault) — no spaces
  4. Set it to Private if you want your notes kept private
  5. Leave Initialize this repository unchecked — the plugin will do this
  6. Click Create repository

Note the repository name. You will enter it exactly as written into the plugin settings.

3

Create a Personal Access Token

A Personal Access Token (PAT) is like a password specifically for the plugin to talk to GitHub on your behalf. It is more secure than using your actual password.

Follow these steps exactly:

  1. On GitHub, click your profile picture (top-right) → Settings
  2. Scroll down to the bottom of the left sidebar → click Developer settings
  3. Click Personal access tokens → Fine-grained tokens
  4. Click Generate new token
  5. Give the token a name like obsidian-sync
  6. Set an expiration (1 year is a good default)
  7. Under Repository access, select Only select repositories, then choose the repo you just created
  8. Under Permissions → Repository permissions, find Contents and set it to Read and write
  9. Click Generate token

Copy your token immediately after generating it. GitHub will never show it again. If you lose it, you will need to generate a new one.

Your token will look like: github_pat_xxxxxxxxxxxxxx or ghp_xxxxxxxxxxxxxxxx

4

Install Direct GitHub Sync in Obsidian

  1. Open Obsidian and go to Settings (gear icon, bottom-left)
  2. Click Community plugins
  3. If it says "Restricted Mode is on", click Turn on community plugins to allow them
  4. Click Browse
  5. Search for Direct GitHub Sync
  6. Click Install, then Enable
5

Configure the plugin

Go to Settings → Direct GitHub Sync and fill in the following fields:

FieldWhat to enter
Personal Access Token Paste the token you copied from GitHub
GitHub Username Your GitHub username (the one in your profile URL)
Repository Name The exact name of the repository you created (e.g., my-obsidian-vault)
Branch Leave as main unless you have a specific reason to change it
Ignore .obsidian folder Leave enabled (recommended) unless you want to sync plugin and theme settings across devices too

Leave everything else at its default value. Save the settings.

6

Push your vault for the first time

You are ready to sync. To push all your notes up to GitHub:

  1. Press Ctrl + P on Windows/Linux or Cmd + P on Mac to open the Command Palette
  2. Type Direct GitHub Sync
  3. Select Push vault to GitHub

A status indicator will appear at the bottom of Obsidian. Wait for it to complete. With a large vault this may take a few minutes.

Once done, visit your repository on GitHub to confirm your files are there. You should see your vault's folder structure.

7

Set up on another device

To access your vault on a second device (phone, tablet, another computer):

  1. Install Obsidian on the new device
  2. Create a new, empty vault on that device
  3. Install Direct GitHub Sync (same steps as above)
  4. Enter the same settings: the same token, username, repository name, and branch
  5. Run Direct GitHub Sync: Pull vault from GitHub from the Command Palette

Your notes will download to the new device.

Everyday use

After initial setup, your regular workflow is simple:

  • Before switching devices — run Push on the current device
  • After switching devices — run Pull on the new device before editing
  • Push and Pull are found in the Command Palette or via the ribbon icon (if enabled)

This plugin does not run in the background. You must manually trigger Push and Pull. Always push before switching devices and pull before starting work on a device you have not used recently.

Something not working? Check the troubleshooting guide.