Skip to content
← Back to homeOpen source plugin

Obsidian · GitHub · 2026

GitHub
Vault Relay.

A conservative GitHub sync bridge for Obsidian Mobile and desktop, prioritizing explicit failure and preserving ambiguous state for review.

ObsidianGitHub Data APIMobile-firstOpen source
View on Obsidian GitHub
Editorial cover for GitHub Vault Relay
Portfolio cover, not a screenshot of the plugin UI.

1.0.5

Stable release

1.11.4

Minimum Obsidian

44

Test files

478

Passing tests

Product boundary

Explicit sync, without the bigger promise

One configured target

The bridge serves one configured vault, repository and branch at a time. Sync is user-triggered, not scheduled or sync-on-save.

GitHub over HTTPS

The client uses requestUrl() and GitHub REST or Git Data API calls. It avoids native Git on mobile and has no intermediary relay service.

Secrets stay in Obsidian

SecretStorage is the active PAT backend. Token patterns and configured tokens are redacted from sanitized errors.

Runtime architecture

A sync flow with a check at every step

01

Inventory

Visible Vault files and adapter-enumerated hidden user files.

02

Classify

Local entries, remote blobs and state.json become one explicit sync state.

03

Pull

Verified remote changes are applied with recovery journals.

04

Rescan

UnifiedSyncEngine checks the Vault again after Pull.

05

Push

Blobs, tree and commit are built against the remote base.

06

Baseline

StorageManager advances state only after checks permit it.

Classifier

Ten states instead of guessing user intent

LOCAL_ONLY

Local file has no remote or baseline entry.

REMOTE_ONLY

Remote file has no local or baseline entry.

LOCAL_CHANGED

Local differs from baseline while remote still matches.

REMOTE_CHANGED

Remote differs from baseline while local still matches.

POTENTIAL_CONFLICT

Both sides diverged, or no usable base exists.

UNCHANGED

Canonical local and remote SHAs remain aligned.

LOCAL_DELETED

Local is absent while remote still has baseline content.

REMOTE_DELETED

Remote is absent while local still has baseline content.

DELETE_CONFLICT

One side deleted while the other side changed.

DELETED

Both sides are absent and the old baseline can be removed.

Safety model

Preserve before mutate

Pull verifies blobs and writes recovery evidence before overwriting or deleting. Push uses one commit/ref boundary, force: false, and rereads the authoritative ref before reporting success.

Blob verification

Recovery journals

Optimistic concurrency

Explicit conflict review

Verification

A release with evidence to return to

npm run verify

ESLint, typecheck, Vitest and production build in the quality gate.

1.0.5

Release tag with SHA-256 verified assets and attestation.

Windows + iPhone

Manual release-gate acceptance recorded for settings, hidden paths, normal files and restart.

Non-goals

Not everything needs to sync

These limits are part of the product boundary, not gaps to hide in a portfolio.

Background or scheduled sync
Sync-on-save
Fuzzy rename inference
Empty-directory sync
Alternative Git forges
Multi-account switching
Force-push behavior

GitHub Vault Relay

Explore the plugin and source

Obsidian GitHub