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.
1.2.1
Stable release
≥ 1.11.4
Minimum Obsidian
0
Test suite files
0
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.
Discovery & Tree Traversal
Recursively enumerates visible Vault files and adapter-enumerated hidden user notes to build an in-memory SHA-256 state.
Three-Way State Comparison
Compares local entries, remote GitHub tree objects, and state.json baseline into explicit classified sync states without blind overwrites.
Verified Remote Ingestion
Downloads modified remote blobs with transactional recovery journals, staging diverged files into review buckets if conflict is detected.
Post-Pull Integrity Invariant
UnifiedSyncEngine re-scans the disk after Pull to ensure physical storage strictly mirrors expected state before proceeding.
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.
Atomic Baseline Cursor Advance
StorageManager atomically commits the new remote commit SHA to state.json only after all preceding checks succeed.
State Classification
Unambiguous 3-Way State Classification
Local file has no remote or baseline entry. Staged for push.
Remote file has no local or baseline entry. Staged for pull.
Local differs from baseline while remote still matches.
Remote differs from baseline while local still matches.
Both sides diverged from base. Requires manual review.
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.