GitHub Vault Relay.

A conservative, resilient GitHub sync bridge for Obsidian Mobile and Desktop, prioritizing explicit transaction failures and preserving ambiguous states for manual review.

Obsidian PluginGitHub REST APIGit Data APIMobile-FirstOpen SourceTypeScript

Obsidian Community GitHub

Editorial cover for GitHub Vault Relay — Technical snapshot: Obsidian Community Plugin enabling direct GitHub git-tree synchronization.

1.2.1

Stable release

≥ 1.11.4

Minimum Obsidian

Test suite files

478

Passing test cases

Runtime Execution Pipeline

6-Stage State Machine with Strict Invariant Verification

Every transition in the sync lifecycle produces explicit verifiable artifacts before state advances, preventing note truncation during intermittent network conditions.

01 / 06

Inventory

Discovery & Tree Traversal

Recursively enumerates visible Vault files and adapter-enumerated hidden user notes to build an in-memory SHA-256 state.

Local SHA-256 Map

02 / 06

Reconciliation

Three-Way State Comparison

Compares local entries, remote GitHub tree objects, and state.json baseline into explicit classified sync states without blind overwrites.

Three-Way Diff Matrix

03 / 06

Pull Stage

Verified Remote Ingestion

Downloads modified remote blobs with transactional recovery journals, staging diverged files into review buckets if conflict is detected.

Rollback Journal

04 / 06

Verification

Post-Pull Integrity Invariant

UnifiedSyncEngine re-scans the disk after Pull to ensure physical storage strictly mirrors expected state before proceeding.

Integrity Assertion

05 / 06

Push Stage

Atomic Git Commit & Tree Push

Constructs missing blobs, builds a new Git tree object against the remote branch base, and crafts an atomic signed Git commit.

Git Tree SHA & Commit

06 / 06

State Advance

Atomic Baseline Cursor Advance

StorageManager atomically commits the new remote commit SHA to state.json only after all preceding checks succeed.

state.json Updated

State Classification

Unambiguous 3-Way State Classification

LOCAL_ONLY

Local file has no remote or baseline entry. Staged for push.

REMOTE_ONLY

Remote file has no local or baseline entry. Staged for pull.

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 from base. Requires manual review.

UNCHANGED

Canonical local and remote SHA-256 remain perfectly aligned.

Product Boundaries

Explicit Guarantees Over Generic Sync

Single Configured Repository Target

The sync bridge operates strictly against one configured vault, repository and branch at a time. All synchronizations are user-directed, eliminating unexpected background background conflicts.

Direct HTTPS via GitHub Git Data API

The client utilizes Obsidian's native requestUrl() and GitHub REST / Git Data APIs. It runs without native Git binaries on iOS/Android and requires zero intermediate relay servers.

Zero Secret Leakage — Local PAT Storage

Personal Access Tokens (PAT) are stored securely inside Obsidian's SecretStorage backend. All tokens and credentials are aggressively redacted from error logs before display.