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.