ss-tools/specs/011-git-integration-dashboard/research.md

Research: Git Integration Plugin

Unknowns & Clarifications

1. Git Library: Should we use GitPython or call git CLI directly?

   • Decision: Use GitPython.
   • Rationale: It provides a high-level API for Git operations, making it easier to handle branches, commits, and remotes programmatically compared to parsing CLI output.
   • Alternatives considered: pygit2 (faster but requires libgit2), subprocess.run(["git", ...]) (simple but brittle).

2. Git Provider API Integration: How to handle different providers (GitHub, GitLab, Gitea) for connection testing?

   • Decision: Use a unified provider interface with provider-specific implementations.
   • Rationale: While Git operations are standard, testing connections and potentially creating repositories might require provider-specific REST APIs.
   • Alternatives considered: Generic Git clone test (slower, requires local disk space).

3. Superset Export/Import: How to handle the "unpacked" requirement?

   • Decision: Use the existing superset_tool logic or similar to export as ZIP and then unpack to the Git directory.
   • Rationale: Superset's native export is a ZIP. To fulfill FR-019, we must unpack this ZIP into the repository structure.

4. Merge Conflict UI: How to implement "Keep Mine/Theirs" in a web UI?

   • Decision: Implement a file-based conflict resolver in the Frontend.
   • Rationale: Since the data is YAML, we can show a list of conflicting files and let the user pick the version.
   • Alternatives considered: Full 3-way merge UI (too complex for MVP).

Best Practices

• Security: Never store PATs in plain text in logs. Use environment variables or encrypted storage if possible (though SQLite is the current project standard).
• Concurrency: Git operations on the same repository should be serialized to avoid index locks.
• Repository Isolation: Each dashboard gets its own directory/repository to prevent cross-dashboard pollution.

Findings Consolidations

• Decision: Use GitPython for core Git logic.
• Decision: Use Provider-specific API clients for connection validation.
• Decision: Unpack Superset exports into dashboard/, charts/, datasets/, databases/ directories.