Skip to content

README.md

Latest commit

 

History

History
81 lines (69 loc) · 3.68 KB

README.md

File metadata and controls

81 lines (69 loc) · 3.68 KB

Project GitHub Sync

Mirror GitHub Issues and Pull Requests into Obsidian project folders, with explicit write actions for comments, close/reopen, and optional body pushes guarded by optimistic concurrency.

Features

  • Project registration stored in the vault config at .obsidian/plugins/project-github-sync/projects/<project>.json.
  • Metadata sync for Issues/PRs into dedicated project folders.
  • Full refresh for a single Issue/PR (includes comments).
  • Optional DeepWiki documentation sync into a per-project docs folder (one note per page).
  • Explicit write actions only: push draft comment, close/reopen, optional push body.
  • Local analysis sections are preserved during sync.

Installation (dev build)

  1. Clone this repo into a local folder.
  2. Run npm install.
  3. Run npm run build.
  4. Copy manifest.json, main.js, and styles.css (if added) into your vault plugin folder: Vault/.obsidian/plugins/project-github-sync/
  5. Enable the plugin in Obsidian settings.

GitHub PAT

Create a fine-grained personal access token with:

  • Issues: read/write
  • Pull requests: read
  • Metadata: read

Never commit your token. Obsidian stores settings in your vault config.

Register a Project

Command: Project GitHub Sync: Register repos for current project

  • Run while a project note is open under 05-Projects/<ProjectName>/.
  • Provide repos, issues folder, PRs folder, and filters.
  • Optionally set a DeepWiki docs folder for per-page notes.
  • Config saved to .obsidian/plugins/project-github-sync/projects/<project>.json.
  • If a config already exists, registration pre-fills the fields so you can update it.
  • Repo overrides: in the repos list you can use owner/name|issuesFolder|prsFolder per line to store items in different folders per repo.
  • Use “Search repos” to pull your accessible repos and filter via search.
  • Use “Pick issues folder” / “Pick PRs folder” to choose folders from the vault.
  • Use “Pick project folder” to select the project root under 05-Projects/.

Sync Commands

  • Project GitHub Sync: Sync all projects (metadata only)
    • Runs metadata sync for every project config stored by the plugin.
  • Project GitHub Sync: Refresh current issue/PR (full)
    • Refresh metadata and comments for the current note.

Write Actions (explicit)

  • Project GitHub Sync: Push draft comment
    • Reads content under ## Draft comment (local) and posts it.
  • Project GitHub Sync: Close issue
  • Project GitHub Sync: Reopen issue
  • Project GitHub Sync: Push body (optimistic concurrency)
    • Only if enabled in settings.
    • Blocks if remote_updated_at differs from GitHub.

Overwrite Rules

The plugin overwrites only:

  • ## Description (mirrored)
  • ## Metadata (mirrored)
  • ## Discussion (mirrored)

The plugin preserves:

  • ## Draft comment (local)
  • ## Local analysis / manuscript relevance (local)
  • Any other local content outside mirrored sections

Troubleshooting

  • 401/403: Token missing or lacks required permissions.
  • 404: Repo or issue not found; double-check owner/name.
  • 403 with rate limit headers: wait and retry; the plugin backs off briefly.
  • DeepWiki shows "missing": open the repo page on DeepWiki and index it, then sync again.

Manual Test Plan

  1. Add a fine-grained PAT in settings.
  2. Open a project note under 05-Projects/<ProjectName>/.
  3. Run registration and verify project.json is created.
  4. Run project sync and confirm issue/PR notes appear.
  5. Open an issue note and run refresh; verify comments populate.
  6. Add text under ## Draft comment (local) and push it.
  7. Close and reopen an issue, verify state updates.
  8. (Optional) Edit Description and use push body, confirm optimistic concurrency blocking if remote changed.