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

Tasks: Git Integration Plugin

Feature: Git Integration for Dashboard Development Status: Completed Total Tasks: 43

Phase 1: Setup

Goal: Initialize project structure and dependencies.

• T001 Install GitPython dependency in backend/requirements.txt
• T002 Create backend directory structure (routes, models, plugins, services)
• T003 Create frontend directory structure (components, routes, services)

Phase 2: Foundational

Goal: Implement core data models and service skeletons. Prerequisites: Phase 1

• T004 Create Git Pydantic models (Branch, Commit, DashboardChange) in backend/src/api/routes/git_schemas.py
• T005 Create GitServerConfig and Environment SQLAlchemy models in backend/src/models/git.py
• T006 Implement GitService class skeleton with GitPython init in backend/src/services/git_service.py
• T007 Implement GitPlugin class skeleton inheriting PluginBase in backend/src/plugins/git_plugin.py

Phase 3: User Story 1 - Configure Git Server (P1)

Goal: Enable users to configure and validate Git server connections. Prerequisites: Phase 2

• T008 [US1] Implement GitService.test_connection method in backend/src/services/git_service.py
• T009 [US1] Implement GET/POST /api/git/config endpoints in backend/src/api/routes/git.py
• T010 [US1] Create frontend/src/services/gitService.js API client
• T011 [US1] Create frontend/src/components/tools/ConnectionForm.svelte (or similar) for Git config
• T012 [US1] Implement Settings page at frontend/src/routes/settings/git/+page.svelte

Phase 4: User Story 2 - Branch Management (P1)

Goal: Enable creating and switching branches for dashboards. Prerequisites: Phase 3

• T013 [US2] Implement GitService branch operations (list, create, checkout) in backend/src/services/git_service.py
• T014 [US2] Implement GitService.init_repo (clone/init strategy) in backend/src/services/git_service.py
• T015 [US2] Implement GET/POST /api/git/branches endpoints in backend/src/api/routes/git.py
• T016 [US2] Implement POST /api/git/checkout endpoint in backend/src/api/routes/git.py
• T017 [US2] Create frontend/src/components/git/BranchSelector.svelte component
• T018 [US2] Update Dashboard page to include Git controls container

Phase 5: User Story 3 - Synchronization (P1)

Goal: Enable committing, pushing, and pulling changes. Prerequisites: Phase 4

• T019 [US3] Implement Dashboard export/unpack logic (using SupersetClient/superset_tool) in backend/src/plugins/git_plugin.py
• T020 [US3] Implement GitService status and diff generation methods in backend/src/services/git_service.py
• T021 [US3] Implement GitService commit, push, and pull methods in backend/src/services/git_service.py
• T022 [US3] Implement /api/git/sync, /commit, /push, /pull endpoints in backend/src/api/routes/git.py
• T023 [US3] Create frontend/src/components/git/CommitModal.svelte with diff viewer
• T024 [US3] Create frontend/src/components/git/ConflictResolver.svelte (Keep Mine/Theirs UI)

Phase 6: User Story 4 - Deployment (P2)

Goal: Deploy dashboard versions to target environments. Prerequisites: Phase 5

• T025 [US4] Implement Environment CRUD endpoints in backend/src/api/routes/git.py
• T026 [US4] Implement deployment logic (zip packing + Import API) in backend/src/plugins/git_plugin.py
• T027 [US4] Implement POST /api/git/deploy endpoint in backend/src/api/routes/git.py
• T028 [US4] Create Deployment modal/interface in frontend/src/components/git/DeploymentModal.svelte

Phase 7: User Story 5 - History (P3)

Goal: View commit history and audit changes. Prerequisites: Phase 5

• T029 [US5] Implement GitService.get_history method in backend/src/services/git_service.py
• T030 [US5] Implement GET /api/git/history endpoint in backend/src/api/routes/git.py
• T031 [US5] Create frontend/src/components/git/CommitHistory.svelte component
• T032 [US5] Integrate History viewer into Dashboard page

Phase 8: Polish & Cross-Cutting

Goal: Finalize error handling, UI feedback, and performance.

• T033 Add comprehensive error handling for Git operations (timeouts, auth failures)
• T034 Add loading states and progress indicators to all Git UI components
• T035 Verify offline mode behavior and graceful degradation

Dependencies

• US1 -> US2 -> US3 -> US4
• US3 -> US5
• US1 is the critical path.

Implementation Strategy

• MVP: Complete US1, US2, and US3 (Configure, Branch, Sync). This allows local-only versioning if remote is optional, or full sync if remote is configured.
• Incremental: Add Deployment (US4) and History (US5) after core sync workflow is stable.

Phase 9: Operational Debug (2026-03-08)

Goal: Validate mismatch between configured Git server URL and repository origin URL during push flow.

• D001 Diagnose source-of-truth mismatch for server URL in push flow
• D002 Validate diagnosis with backend push diagnostics logs
• D003 Apply behavioral fix only after diagnosis confirmation

Phase 10: Operational Debug (2026-03-08)

Goal: Diagnose unexpected 409 on pull caused by unfinished merge detection.

• D004 Add pull diagnostics logs for merge marker, repo path, branch, and binding metadata
• D005 Confirm root cause hypothesis from new diagnostics before applying any behavior fix
• D006 Implement richer 409 API response for unfinished merge (repo path, branch, explicit manual steps)

Phase 11: Operational Debug (2026-03-08)

Goal: Add GitManager remediation dialog for unfinished merge 409 with actionable guidance.

• D007 Implement unresolved-merge resolution dialog in frontend/src/components/git/GitManager.svelte
• D008 Add frontend contract test for unfinished-merge dialog behavior in frontend/src/components/git/__tests__/git_manager.unfinished_merge.integration.test.js

Phase 12: Branch Naming Convention Update (2026-05-27)

Goal: Переименование ветки main → prod для соответствия environment stages. Status: Completed

Backend Changes

• B001 Update _ensure_gitflow_branches to create prod, dev, preprod instead of main, dev, preprod
• B002 Update create_branch default parameter from main to prod
• B003 Update remote providers (GitHub, GitLab, Gitea) to use prod as default_branch

Frontend Changes

• F001 Update BranchSelector.svelte default currentBranch from main to prod
• F002 Update GitManager.svelte initial state from main to prod
• F003 Update GitReleasePanel.svelte UI label from PROD (main) to PROD (prod)
• F004 Update git-utils.js promote defaults: preprod → prod instead of preprod → main

Tests

• T001 Update all test fixtures from main to prod in gitService.test.js

Phase 13: Feature & Hotfix Branch Support (Planned)

Goal: Расширить модель веток для поддержки параллельной разработки нескольких фич и срочных исправлений. Status: Planned Priority: P2 Estimated Effort: 25-30 hours Prerequisites: Phase 12 completed, stable base Git workflow

Backend Implementation

• B010 Implement merge_branch method in GitService for merging source_branch into target_branch
• B011 Add conflict detection and handling in merge_branch (abort on conflicts, return status)
• B012 Implement delete_branch method with protection for environment branches (dev/preprod/prod)
• B013 Extend list_branches to group branches by type (Environment / Feature / Hotfix)
• B014 Add branch name validation (regex: ^[a-zA-Z0-9._\/-]+$, no .., no leading /)
• B015 Implement branch protection rules (optional: require MR for prod)
• B016 Add POST /api/git/merge endpoint for branch merging
• B017 Add DELETE /api/git/branches/{name} endpoint for branch deletion
• B018 Add unit tests for merge_branch with conflict scenarios
• B019 Add integration tests for feature branch workflow (create → commit → merge → delete)

Frontend Implementation

• F010 Redesign BranchSelector.svelte with grouped dropdown (Environment / Feature / Hotfix)
• F011 Create CreateBranchDialog.svelte with type selection (feature/hotfix/bugfix), name validation, source branch selection
• F012 Add merge button to GitManager.svelte for feature branches (visible when currentBranch starts with feature/)
• F013 Create MergeDialog.svelte with diff preview, conflict handling, auto-delete option
• F014 Extend GitReleasePanel.svelte to support merge from feature branches to dev
• F015 Add branch type badges (Environment / Feature / Hotfix) with color coding
• F016 Implement branch deletion UI with confirmation dialog
• F017 Add i18n keys for new branch management features (en/ru)
• F018 Add UX tests for branch creation and merge workflows
• F019 Add integration tests for feature branch lifecycle

Documentation

• D010 Update user guide with feature branch workflow
• D011 Add branch naming conventions to documentation
• D012 Create troubleshooting guide for merge conflicts

Dependencies

• B010 → B011 → B016 (merge implementation chain)
• B012 → B017 (delete implementation)
• B013 → F010 (grouped list → UI)
• F011 → F013 (create dialog → merge dialog)
• All backend tasks should be completed before frontend tasks

Risks & Mitigations

• Risk: Merge conflicts in YAML files may be complex
  • Mitigation: Use existing ConflictResolver component, provide clear error messages
• Risk: Branch protection may slow down workflow for small teams
  • Mitigation: Make protection rules optional via GitServerConfig settings
• Risk: Auto-delete may cause work loss if misconfigured
  • Mitigation: Require explicit confirmation, add "undo" option for 5 minutes

Success Criteria

• Users can create feature branches from dev with proper naming validation
• Users can merge feature branches back to dev with conflict resolution
• Users can delete feature branches after successful merge
• Branch list is grouped by type for easy navigation
• Merge conflicts are handled gracefully with clear user guidance