Obsidian Source

Obsidian Source

Sync your Obsidian vault into Outrun so AI agents and workflows can search and reference your notes. This integration uses GitHub as a transport layer — Outrun's existing GitHub source handles the sync automatically on every push.

A tool loved by the Outrun team. Sometimes, however much we'd like to, other developers don't give us the tools to build native integrations — Obsidian Sync is end-to-end encrypted with no API by design. So instead of waiting, we're sharing our play for making it work. We think Obsidian in a workflow like this provides an excellent interface for growing the knowledge of your agents. We use it ourselves.

GitHub-backed vaults only

This integration requires your Obsidian vault to be backed by a GitHub repository. Obsidian Sync (the paid cloud product) uses end-to-end encryption and does not expose an API — GitHub is the recommended path for external sync.

Prerequisites

  • Obsidian desktop app installed
  • Obsidian Git community plugin installed in your vault
  • A GitHub account (free tier works)
  • Outrun workspace with GitHub source access

How it works

Obsidian vault → Obsidian Git plugin → GitHub repo → Outrun GitHub source → Knowledge base

Every time you commit and push from Obsidian Git, Outrun picks up the changes via the GitHub source webhook and updates your knowledge base automatically.

Step 1 — Set up Obsidian Git

  1. Open Obsidian and go to Settings → Community plugins → Browse
  2. Search for Obsidian Git and install it
  3. Enable the plugin
  4. Go to Settings → Obsidian Git and configure:
    • Auto pull interval: how often to pull from GitHub (e.g. 10 minutes)
    • Auto push interval: how often to push to GitHub (e.g. 10 minutes), or push manually

First-time setup

If your vault isn't already a Git repo, initialise it first. In Obsidian Git, open the command palette (Cmd/Ctrl+P) and run Obsidian Git: Initialise a new repo. Then create an empty repo on GitHub and add it as a remote.

Step 2 — Create a GitHub repository for your vault

  1. Go to github.com/new and create a new repository
    • Visibility: Private is recommended for personal notes
    • Initialise with README: No (your vault will push the initial content)
  2. Copy the repository URL (e.g. https://github.com/yourname/my-vault)
  3. In Obsidian Git settings, set the remote to this repository

To verify the connection is working, run Obsidian Git: Push from the command palette and check that files appear in your GitHub repo.

Step 3 — Connect GitHub to Outrun

  1. In Outrun, go to Sources → Add source → GitHub
  2. Authenticate with GitHub if you haven't already
  3. Select the repository that contains your vault
  4. Configure the source:
    • File filter: .md (to sync only markdown files)
    • Folders: optionally restrict to a subfolder (e.g. notes/ to exclude attachments)
  5. Save and run an initial sync

Separate repos recommended

If you already have a GitHub source connected for a code repository, add your vault as a separate GitHub source. Each source can have its own file filters and sync schedule.

Step 4 — Attach to a knowledge base

  1. Go to Knowledge Bases and create a new KB (or open an existing one)
  2. Under Sources, add your Obsidian vault GitHub source
  3. Set Object types to file_contents
  4. Optionally filter by file path prefix to target specific folders (e.g. notes/, projects/)
  5. Run a KB build

Your notes are now chunked, embedded, and searchable by AI agents.

Supported content

Content Synced Notes
Markdown notes (.md) ✓ Full text content
Frontmatter (YAML) ✓ Title, tags, and custom fields
Tags ✓ Via frontmatter tags: field
Folder structure ✓ Preserved as filePath metadata
Wikilinks ([[...]]) Partial Stored as text, not resolved
Embedded images ✗ Binary files excluded by .md filter
Canvas files (.canvas) ✗ JSON format, not markdown
PDF attachments ✗ Use a separate source for documents

Sync frequency

Sync happens on every GitHub push. The latency is:

  1. Obsidian Git pushes to GitHub (configurable interval, e.g. every 10 minutes)
  2. GitHub sends a webhook to Outrun (near-instant)
  3. Outrun processes the changed files (seconds)
  4. KB rebuild triggers if configured (minutes, depending on vault size)

For most use cases, notes are available to AI agents within 5–15 minutes of saving in Obsidian.

Field mappings

Outrun stores each note as a file_contents object with the following fields:

Outrun field Source Description
title Filename or frontmatter title: Note display name
body Full markdown content Searchable text
filePath Repo path (e.g. notes/projects/q2.md) Used for folder filtering
sourceType github Origin system
objectType file_contents Content classification
createdAt GitHub commit timestamp First seen date
updatedAt GitHub commit timestamp Last modified date

Troubleshooting

Notes aren't appearing in the knowledge base

  • Check the GitHub source sync status in Outrun — look for errors on the source detail page
  • Verify the file filter is set to .md and not something more restrictive
  • Confirm Obsidian Git has pushed at least once (check your GitHub repo directly)

Only some notes are syncing

  • The .md filter excludes non-markdown files. Canvas (.canvas), images, and PDFs won't sync
  • Check if a folder filter is active on the source that excludes certain paths
  • Large vaults may take several minutes for the initial sync to complete

Changes in Obsidian aren't reflected in Outrun

  • Obsidian Git only pushes on its configured interval or manually — check the plugin settings
  • If the GitHub webhook isn't firing, check the webhook delivery logs in your GitHub repo under Settings → Webhooks

Obsidian Git won't push on mobile

  • The Obsidian Git plugin has limited and unstable mobile support. For mobile vaults, consider using iCloud or Obsidian Sync to keep your desktop vault in sync, then let the desktop push to GitHub.

Related

Copyright 2023 - LOON SHOOT PTY LTD.

terms | privacy | dpa | sitemap