Megan Sullivan

Sync your Obsidian Vault on iOS with GitHub, Working Copy, and Apple Shortcuts

February 20th, 2023

(24-minute read)

Introduction

Obsidian is my favorite note-taking app. Since I started using it in 2021, I've been stuffing my vault full of notes, ideas, and reminders.

At first, I was only using Obsidian on my MacBook. But I quickly realized that I needed a way to capture my thoughts while I was on the go and away from my computer. Luckily, there's an Obsidian app that works on both iOS and iPad. But Obsidian works with local Markdown files. How do you connect multiple devices to the same Obsidian vault?

The Obsidian team offers a product called Obsidian Sync, which is a monthly or annual subscription that you can use to sync your vaults across devices. If you're not comfortable with Git, Obsidian Sync is a great way to get the same functionality while also supporting the Obsidian creators!

But for developers (or folks who would rather avoid paying for another monthly subscription), you can achieve a similar result using a GitHub repo, an app called Working Copy, and the built-in Shortcuts app on your Apple device.

In this post, I'll show you how to synchronize your Obsidian vault across Apple devices so that you can easily take notes wherever you are.

Prerequisites

Before you begin this tutorial, you should have the following materials:

  • ✅ An existing Obsidian vault, backed up to a GitHub repository
    • On my MacBook, I use the obsidian-git plugin, which I've configured to back up my vault every 30 minutes.
  • ✅ An iPhone or iPad, with the following applications installed:
  • Obsidian
  • Working Copy: a Git client for working with repositories from a mobile device
    • You'll need to upgrade to the Pro version, which you can do from within the app.
  • Shortcuts: an Apple app for creating automations on your device
    • (As of iOS/iPadOS 13+, the Shortcuts app comes pre-installed as a default app on your device.)

The Big Picture

Let's take a step back to understand the overall setup you'll be building:

A diagram of the systems involved in this architecture. On top, there's the GitHub logo, with a desktop computer and an iPhone/iPad below it. Bidirectional arrows connect the GitHub logo to each of the devices.

Your GitHub repo will be the source of truth for your vault. You'll want to make sure any changes you make to your local Obsidian vault get pushed to GitHub so that they can be accessed from your other devices.

Now let's zoom in a bit and take a closer look at the tools we'll use to enable this setup:

A diagram that builds on the one above, showing the different pieces in each system. Detailed description below.
Expand for detailed image description

GitHub:

  • Has a repo called "my-vault"

Desktop:

  • Stores files in a local copy of the "my-vault" repo
  • Uses the Obsidian application, with the Obsidian Git plugin

iPhone/iPad:

  • Stores files in a local copy of the "my-vault" repo
  • Uses the Obsidian, Working Copy, and Shortcuts applications

For the rest of this post, we'll focus on the iPhone/iPad setup.

Scenarios

In order to keep your Obsidian vault synchronized with your iPhone or iPad, you'll need to handle the two following scenarios:

  1. Pull changes from the remote vault repo on GitHub into the local vault on your device.
    • This syncs any changes you've made to your notes from another device.
  2. Push changes from the local vault on your device into the remote vault repo on GitHub.
    • This makes changes from your iPhone/iPad available on other devices.
A pair of diagrams, illustrating the two scenarios. Scenario 1 shows an arrow pointing from the GitHub logo to the iPhone/iPad. Scenario 2 shows an arrow pointing from the iPhone/iPad to the GitHub logo.

Let's get started!

1) Connect your local Obsidian vault to the GitHub repo

First things first, you'll need to create a new empty Obsidian vault on your iPhone/iPad.

  1. Open the Obsidian app on your device. Select "Create new vault".

    iPad screenshot of the Obsidian app home screen. A box is drawn around the "Create new vault" menu option.
  2. Give your vault a name. (I call mine "Second Brain".) Leave the "Store in iCloud" setting turned off. Then click "Create".

    iPad screenshot of the Obsidian app "Create new vault" form. "Vault name" is set to "Second Brain", "Store in iCloud" toggle is off.
  3. A new empty vault will be created on your device.

    iPad screenshot of a new empty vault in the Obsidian app.

Next, use Working Copy to connect this new empty vault to your existing vault repo on GitHub.

  1. Open the Working Copy app on your device. The first time you load Working Copy, it will look something like this:

    iPad screenshot of the Working Copy app's home screen. There's a "Repository" sidebar with a single repo called, "welcome to working copy". The main section of the screen says "No repository selected. You can create new Git repositories by initializing new ones or by cloning from remote."
  1. Click the "+" icon in the sidebar, then select "Clone repository".

    iPad screenshot of the Working Copy app, with a box drawn around the "+" icon in the left sidebar. Someone has pressed the "+" icon, which opened a selection menu. A box is drawn around the "Clone repository" menu option.
  2. Open the "GitHub" tab, then click "Sign In".

    iPad screenshot of Working Copy, in the "Clone repository" modal. The GitHub tab is highlighted, and a box is drawn around the "Sign In" link.
  3. Enter your GitHub credentials to give Working Copy access to your repositories.

    iPad screenshot of Working Copy, in the GitHub authentication modal. There's a form to "Sign in to GitHub to continue to Working Copy", with fields to enter a username and password.
  4. Now, Working Copy should display a list of your GitHub repositories. Locate and click on the one for your existing Obsidian vault.

    iPad screenshot of Working Copy. The "Clone repository" modal has been updated to show a list of repositories from the user's GitHub account. A box is drawn around the repo called "second-brain".
  5. If you want, you can configure the settings for cloning the repo, but I kept the default settings. Then click "Clone". This will download a copy of your existing vault repo from GitHub to your device.

    iPad screenshot of Working Copy. In the "Clone repository" modal, the URL tab is selected. "Protocol" is set to "ssh", "User" is set to "git", "Host" is set to "github.com", "Port" is empty, "Path" is set to "meganesu/second-brain.git", and "LFS" is set to "Auto".
  6. When you're done, you should see the contents of your vault repo in Working Copy.

    iPad screenshot of Working Copy. The "second-brain" repo is selected in the sidebar, and the app now shows the files and commits for that repo.
  7. Click the share icon (the up arrow coming out of a box) on the right, then select "Link Repository to Folder".

    iPad screenshot of Working Copy, inside the "second-brain" repo. The share icon has been clicked, which opened a menu of share options. The "Link Repository to Folder" menu option is highlighted.
  1. Under the "On My iPad" folder, open the "Obsidian" directory, and then select the folder for the new vault you created earlier. Then click "Done". This tells Working Copy to store the local copy of your repo in your Obsidian vault folder.

    iPad screenshot of Working Copy. There's a folder selection modal open. The "On My iPad" / "Obsidian" / "Second Brain" folder is selected.
  2. Back in Obsidian, validate that the files from your existing remote vault now appear in your new vault.

    iPad screenshot of Obsidian. The Files sidebar is open, and now shows folders and files from the GitHub repo.

2) Pull changes from GitHub into your local vault

Now that you've got your local vault set up, it's time to handle the first scenario from earlier: pulling changes from the remote vault repo into your local vault.

The Scenario 1 diagram from before. It shows an arrow pointing from the GitHub logo to an iPhone/iPad.

You'll do this work in two stages:

  • Create a shortcut to pull changes.
  • Automate the shortcut to run when the Obsidian app opens.

Create a shortcut to pull changes

  1. Open the Shortcuts app, and navigate to the "All Shortcuts" page. Click the "+" icon to create a new shortcut.

    iPad screenshot of the Shortcuts app. The "All Shortcuts" page is selected from the sidebar, and the "+" icon is highlighted.
  2. Name your new shortcut "Pull Changes From Remote Obsidian Vault".

    iPad screenshot of Shortcuts. On the screen for creating a new shortcut, the shortcut has been renamed to "Pull Changes From Remote Obsidian Vault".
  3. Use the search bar to find the Working Copy action to "Pull Repository". Tap the action to add it to your shortcut.

    iPad screenshot of Shortcuts. In the sidebar on the right, the user has entered "Working copy pull" into the search bar, which brings up actions for the Working Copy app. The "Pull Repository" action is highlighted.
  4. Checkpoint: So far, your shortcut should look like this:

    iPad screenshot of Shortcuts. The new shortcut has one action, "Pull from [Repository] remote". The word "Repository" is clickable.
  5. Tap on the "Repository" placeholder to fill in a value. Choose your vault repo from the list of Working Copy repos.

    iPad screenshot of Shortcuts. The user clicked on the "Repository" placeholder value, and a modal appeared, showing the repositories available in the Working Copy app. The "second-brain" repo is highlighted.
  6. Checkpoint: Your final shortcut should look like the one below. Click "Done" to save your changes.

    iPad screenshot of Shortcuts. The new shortcut is named "Pull Changes From Remote Obsidian Vault", and it contains one action: "Pull from second-brain remote".
  7. Now you have a shortcut that you can trigger by tapping it in the Shortcuts menu. (To edit your shortcut, click on the three dots in the corner of the grid item.)

    iPad screenshot of the Shortcuts "All Shortcuts" page. There's now a new shortcut box in the grid for the pull changes shortcut the user just created.

Automate the shortcut to run when the Obsidian app opens

Now that you can pull updates from GitHub into your local vault, it's time to set up an automation to run that shortcut automatically! To avoid merge conflicts, pull changes from the remote repo every time you open the Obsidian app on your device. Let's set that up:

  1. In the Shortcuts app, open the Automation page, and create a new personal automation.

    iPad screenshot of the Shortcuts app. The "Automation" page is selected in the sidebar, and the "Create Personal Automation" button is highlighted.
  2. In the "New Automation" menu, choose the event that you want to trigger your automation. Scroll down and select "App".

    iPad screenshot of Shortcuts. In the "New Automation" modal, the "App" menu item is highlighted. (The subtitle for the menu item says: "Ex. 'When "Weather" is opened or closed'".)
  3. Choose "Obsidian" for the App, and make sure "Is Opened" is checked. Then click "Next".

    iPad screenshot of Shortcuts. In the "New Automation" modal, the "App" setting has been changed to "Obsidian". The "Is Opened" box is checked, and the "Is Closed" box is unchecked.
  4. Now you'll set up the action you want to trigger when Obsidian is opened. Click the "Add Action" button.

    iPad screenshot of Shortcuts. In the "Actions" modal, the "Add Action" button is highlighted.
  5. Use the search bar to find the "Run Shortcut" action. Click it to add it to your automation.

    iPad screenshot of Shortcuts. In the "Actions" modal, the user has typed "Shortcut" into the search bar. The search results show an option called "Run Shortcut", which is highlighted.
  6. Click the "Shortcut" placeholder to fill in a value. Select the "Pull Changes From Remote Obsidian Vault" shortcut you created earlier. Then click "Next".

    iPad screenshot of Shortcuts. In the "Actions" modal, the list of actions now says "Run Pull Changes From Remote Obsidian Vault".
  7. Review your automation settings. Turn off the "Ask Before Running" setting, so that you won't need to confirm the automation every time it runs.

    iPad screenshot of Shortcuts. In the "New Automation" modal, the "Ask Before Running" toggle is highlighted.
  8. Turning off the "Ask Before Running" setting will require a second confirmation that you really don't want to ask before running the automation. Confirm by selecting "Don't Ask".

    iPad screenshot of Shortcuts. A confirmation alert says, "Don't ask before running? Whenever this automation is triggered, it will perform actions on your behalf without asking first." The "Don't Ask" option is highlighted.
  9. Now you should see an additional setting, "Notify When Run". Turn that setting on, so that you'll get a notification whenever your automation is run. (This will help you validate that the automation is working as expected. You can turn this setting off later if you'd prefer not to see a notification every time you open the app.)

    Click "Done" to save your changes.

    iPad screenshot of Shortcuts. In the "New Automation" modal, the "Ask Before Running" toggle is turned off, and the "Notify When Run" toggle is turned on.
  10. Your new automation should appear under "Personal" on the Automation page.

    iPad screenshot of Shortcuts. The Automation page is selected from the sidebar, which shows one Personal automation called "When 'Obsidian' is opened".

And that should do it! Test out your automation by opening the Obsidian app. You should see a notification telling you that your "Opened Obsidian" shortcut was run.

iPad screenshot of a note in Obsidian. There's an iPad notification at the top of the screen that says "Opened 'Obsidian'. Running your automation."

3) Push changes from your local vault to GitHub

Now you're ready to tackle the second scenario: pushing changes from your local vault into the remote repo on GitHub.

The Scenario 2 diagram from before. An arrow points from an iPhone/iPad to the GitHub logo.

Like before, you'll do this work in two stages:

  • Create a shortcut to push local changes.
  • Automate the shortcut to run when the Obsidian app closes.

Create a shortcut to push local changes

  1. In the Shortcuts app, navigate back to the "All Shortcuts" page. Click the "+" icon to create a new shortcut.

    iPad screenshot of Shortcuts. The "All Shortcuts" page is selected in the sidebar, and the "+" icon to create a new shortcut is highlighted.
  2. Name your shortcut "Back Up Obsidian Vault".

    iPad screenshot of Shortcuts. The new shortcut has been renamed to "Back Up Obsidian Vault".
  3. If you plan on running these shortcuts across multiple devices, it helps to specify in your commit message which device you're making changes from. (For example, I use the free iCloud tier to sync my Shortcuts across Apple devices, so this shortcut could run from either my iPad or my iPhone. Knowing which device a commit came from helps me troubleshoot if something goes wrong or I start getting merge conflicts.)

    To set that up, use the search bar to find the Scripting action called "Set Variable". Tap the action to add it to your shortcut.

    iPad screenshot of Shortcuts. The user entered "Variable" into the search bar in the sidebar, which shows a search result called "Set Variable".
  4. Checkpoint: Now your shortcut should look like this:

    iPad screenshot of Shortcuts. The new shortcut has a single action, called "Set variable [Variable Name] to [Input]". "Variable Name" and "Input" are both clickable placeholder values.
  5. Give your variable a name by tapping on "Variable Name". You can call this whatever you want; I called mine "Device".

    iPad screenshot of Shortcuts. The user clicked on the "Variable Name" placeholder and typed "Device".
  6. Now set the value of your variable by tapping "Input" and choosing "Device Details".

    iPad screenshot of Shortcuts. The user clicked on the "Input" placeholder, which opened a menu of options to choose from. The "Device Details" menu option is highlighted.
  7. Checkpoint: This is what your action should look like so far:

    iPad screenshot of Shortcuts. The new action now has a single action that says, "Set variable Device to Device Details".
  8. Tap on "Device Details", and scroll down to select "Device Type". When your shortcut runs, this value will be something like "iPhone" or "iPad", depending on what kind of device you're using.

    iPad screenshot of Shortcuts. The user tapped on "Device Type", which opened a menu of more specific options to choose from. The "Device Type" option is checked.
  9. Use the search bar to find the Working Copy action called "Commit Repository". Tap the action to add it to your shortcut.

    iPad screenshot of Shortcuts. In the sidebar's search bar, the user entered "Working copy commit", which brings up a search result of a Working Copy action called "Commit Repository".
  10. Checkpoint: Now your shortcut should look like this:

    iPad screenshot of Shortcuts. At the bottom of the actions list, there's a new action: "Commit [Repository] with [Message]". "Repository" and "Message" are clickable placeholder values.
  11. Tap "Repository" to fill in a value for which Working Copy repo you want to commit to. Choose your vault repo from the menu.

    iPad screenshot of Shortcuts. The user clicked the "Repository" placeholder, which opened a modal showing the available repos from Working Copy. The "second-brain" repo is highlighted.
  12. Next, tap "Message" to fill in what you want your commit message to be.

    iPad screenshot of Shortcuts. The "Message" placeholder in the Commit action is highlighted.
  13. You can use the menu at the bottom of the screen to add the Device variable into your commit message. I set my commit message to: "Vault autocommit on <Device>" (which will end up being either "Vault autocommit on iPad" or "Vault autocommit on iPhone", depending on which device I'm using).

    iPad screenshot of Shortcuts. The "Message" placeholder has been replaced with, "Vault autocommit on [Device]", where "Device" is the value of the Device variable. At the bottom of the screen, there's a menu where users can select a variable to insert into the message string.
  14. Click the arrow icon in the commit action to expand the advanced options menu.

    • Set the "What to Commit" option to "modified".
    • Turn off the "Fail when nothing to Commit" toggle.
    iPad screenshot of Shortcuts. The user has clicked the arrow to show advanced options on the Commit action. "What to Commit" is set to "modified", and the "Fail when nothing to Commit" toggle is turned off.
  15. Use the search bar to find the Working Copy action called "Push Repository". Tap the action to add it to your shortcut.

    iPad screenshot of Shortcuts. In the sidebar search box, the user typed "Working copy push", which shows one search result: a Working Copy action called "Push Repository".
  16. Checkpoint: Now your shortcut should look like this:

    iPad screenshot of Shortcuts. The new shortcut's list of actions shows a new action at the bottom: "Push [Repository] to remote". The word "Repository" is a clickable placeholder.
  17. Tap "Repository" to fill in a value for which Working Copy repo to push to its remote. Select your vault repo from the menu.

    iPad screenshot of Shortcuts. The user clicked the "Repository" placeholder, which opened a modal showing the available repositories from Working Copy. The "second-brain" repo is highlighted.
  18. Your final "Back Up Obsidian Vault" shortcut should look like this:

    iPad screenshot of Shortcuts. The actions list for the new shortcut contains the following actions: "Set variable [Device] to [Device Type]." "Commit [second-brain] with [Vault autocommit on Device]." "Push [second-brain] to remote."
  19. Click "Done" to save your new shortcut. You should now see it appear on the "All Shortcuts" page. Tap the shortcut to run it. (To edit your shortcut, click on the three dots in the corner of the grid item.)

    iPad screenshot of Shortcuts. On the "All Shortcuts" page, there's a new shortcut for backing up an Obsidian vault.

Automate the shortcut to run when the Obsidian app closes

Now that your shortcut is set up, it's time to automate it! To make sure your latest changes are always pushed up to the remote repo, run your shortcut every time you close the Obsidian app. Let's set that up next:

  1. In the Shortcuts app, navigate to the "Automation" page. Click the "+" icon to create a new automation.

    iPad screenshot of Shortcuts. On the "Automation" page, the "+" icon to create a new automation is highlighted.
  2. Choose "Create Personal Automation".

    iPad screenshot of Shortcuts. In the "New Automation" modal, the "Create Personal Automation" button is highlighted.
  3. Next, choose which event you want to trigger your automation. Scroll down and select "App".

    iPad screenshot of Shortcuts. In the "New Automation" modal, the "App" option is highlighted. (The menu item has a subtitle that says, "Ex. 'When "Weather" is opened or closed'".)
  4. For "App", choose Obsidian. Uncheck the "Is Opened" toggle, and check "Is Closed" instead. Then click "Next".

    iPad screenshot of Shortcuts. In the "New Automation" modal, "App" is set to "Obsidian", the "Is Opened" box is unchecked, and the "Is Closed" box is checked.
  5. Now it's time to specify what action you want to run when your automation is triggered. Click the "Add Action" button.

    iPad screenshot of Shortcuts. In the "Actions" modal, the "Add Action" button is highlighted.
  6. Use the search bar to find the "Run Shortcut" action. Tap the action to add it to your automation.

    iPad screenshot of Shortcuts. In the "Actions" modal, the user has entered "Shortcut" in the search bar. The search result called "Run Shortcut" is highlighted.
  7. Tap the "Shortcut" placeholder to add in a value.

    iPad screenshot of Shortcuts. In the "Actions" modal, there's an action listed called "Run [Shortcut]", where "Shortcut" is a clickable placeholder.
  8. Select your "Back Up Obsidian Vault" shortcut from the menu.

    iPad screenshot of Shortcuts. The user clicked the "Shortcut" placeholder, which opened a menu of available shortcuts to run. The "Back Up Obsidian Vault" option is highlighted.
  9. Checkpoint: Your actions should look like this. Click "Next" to continue.

    iPad screenshot of Shortcuts. In the "Actions" modal, there's a single action listed: "Run [Back Up Obsidian Vault]".
  10. Review your automation settings. Turn off the "Ask Before Running" setting, so that you won't need to confirm the automation every time it runs.

    iPad screenshot of Shortcuts. In the "New Automation" modal, the "Ask Before Running" toggle is highlighted.
  11. Turning off the "Ask Before Running" setting will require a second confirmation that you really don't want to ask before running the automation. Confirm by selecting "Don't Ask".

    iPad screenshot of Shortcuts. A confirmation alert says, "Don't ask before running? Whenever this automation is triggered, it will perform actions on your behalf without asking first." The "Don't Ask" button is highlighted.
  12. Now you should see an additional setting, "Notify When Run". Turn that setting on, so that you'll get a notification whenever your automation is run. (This will help you validate that the automation is working as expected. You can turn this setting off later if you'd prefer not to see a notification every time you close Obsidian.)

    iPad screenshot of Shortcuts. In the "New Automation" modal, the "Ask Before Running" toggle is turned off, and the "Notify When Run" toggle is turned on.
  13. Click "Done" to save your changes. Your new automation should appear under "Personal" on the Automation page.

    iPad screenshot of Shortcuts. On the "Automation" page, there's a new Personal automation listed, "When 'Obsidian' is closed".

And you're done!

Test out your new automation by opening the Obsidian app (which triggers a notification that your "Opened Obsidian" automation is running), making some changes, and then closing the Obsidian app (by going back to your home screen). You should see a notification that your "Closed Obsidian" automation ran.

iPad screenshot of the home screen, with a notification at the top of the screen that says, "Closed 'Obsidian'. Running your automation."

Wrap It Up

Obsidian has become a huge part of my day-to-day workflow. By syncing my vault across all my devices, I have the flexibility to capture notes on whichever device I have on hand.

Want to learn how to make the most of your new note-taking freedom? I've learned a ton about Obsidian by watching Ben Hong's YouTube channel, BenCodeZen. You can also check out the official Obsidian Community page, which has links to a dedicated Discord server and online forum.

If you like this post, reach out on Mastodon and let me know! You can also subscribe to my newsletter (below) to get updates when I post new content.

Resources

This tutorial was inspired by the following resources:

Join the newsletter!

Subscribe to get email updates about new content! (No spam. Unsubscribe at any time.)