Skip to content

Git-native issue mirroring — local mirrors of GitHub/GitLab issues in notio

Problem

git clone only includes the Git object graph (commits, trees, blobs, refs). Platform-layer artifacts — issues, PRs/MRs, project boards, review comments, CI metadata — live in the hosting platform's database and are not available locally or to agents.

This means: - Agents cannot query project management context without API calls to external services - Offline work loses access to issue context - Knowledge is split across two layers: Git (distributed, local) vs. Forge (centralized, mutable)

Proposal

Add a forge sync capability to projio/notio that mirrors GitHub/GitLab issues, PRs, and project management artifacts as structured local markdown, making them:

  • Local — available in any clone
  • Versioned — tracked in git history
  • Queryable — accessible via MCP tools and RAG
  • Agent-operable — no external API needed at query time

Design considerations

What to mirror

  • Issues (title, body, comments, labels, status)
  • Pull/merge requests (description, review comments, approval state)
  • Milestones / project boards (as structured metadata)
  • Wikis (already separate git repos — <repo>.wiki.git)

Sync strategy

  • API-based pull (GitHub REST/GraphQL, GitLab API) via gh / glab CLI or direct API
  • Incremental sync (track last-synced timestamp)
  • Bidirectional optional: create issues from local notes, push status changes back

Storage format

  • Markdown files with YAML frontmatter (fits existing notio patterns)
  • Stored under e.g. docs/log/forge/ or .projio/forge/
  • Indexed by notio for search and MCP access

Edge cases

  • PRs partially exist in Git (code changes as branches/refs) but review discussion does not
  • GitLab wikis are separate git repos — could be cloned as a submodule
  • Self-hosted GitLab backups include DB but aren't portable via clone

Relationship to existing stack

Projio/notio is already converging on git-native knowledge systems that beat platform-native ones for agents: - notio replaces "issues" with structured markdown + MCP access - worklog provides cross-project task orchestration - Everything is local, queryable, versioned, agent-operable

This feature formalizes and extends that pattern to ingest external forge artifacts rather than only supporting natively-created notes.

Tasks

  • [ ] Design forge sync spec (storage format, sync protocol, conflict resolution)
  • [ ] Implement GitHub issue pull via gh CLI
  • [ ] Implement GitLab issue pull via glab CLI or API
  • [ ] Add MCP tools: forge_sync, forge_status, forge_search
  • [ ] Integrate with notio indexing and RAG
  • [ ] Consider bidirectional sync (local → forge)