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

Feature Specification: Git Integration Plugin for Dashboard Development

Feature Branch: 011-git-integration-dashboard
Created: 2026-01-18
Status: In Progress Input: User description: "Нужен плагин интеграции git в разработку дашбордов. Требования - возможность настройки целевого git сервера (базово - интеграция с gitlab), хранение и синхронизация веток разработки дашбордов, возможность публикацию в другое целевое окружение после коммита"

User Scenarios & Testing (mandatory)

User Story 1 - Configure Git Server Connection (Priority: P1)

A dashboard developer needs to connect the system to their Git server (GitLab, GitHub, or Gitea) to enable version control for dashboard development. They want to configure the Git server provider, URL, authentication credentials, and repository details through a simple form interface.

Why this priority: This is the foundational requirement - without Git server configuration, no other Git functionality can work. It's the entry point for all Git operations.

Independent Test: Can be fully tested by configuring a Git server connection (e.g., GitHub) and verifying the connection test succeeds, delivering the ability to establish Git server connectivity.

Acceptance Scenarios:

1. Given a user is on the Git integration settings page, When they select a provider (GitLab/GitHub/Gitea) and enter valid server URL and PAT, Then the system successfully validates the connection
2. Given a user enters invalid Git credentials, When they test the connection, Then the system displays a clear error message indicating authentication failure
3. Given a user has configured a Git server, When they save the settings, Then the configuration is persisted and can be retrieved later

---

User Story 2 - Dashboard Branch Management (Priority: P1)

A dashboard developer needs to create, switch between, and manage different development branches for their dashboards. They want to see available branches, create new feature branches, and switch between branches to work on different dashboard versions.

Why this priority: This is core to the Git workflow - developers need to manage branches to work on different features or versions of dashboards simultaneously.

Independent Test: Can be fully tested by creating a new branch, switching to it, and verifying the branch operations work correctly, delivering basic Git branch workflow capabilities.

Acceptance Scenarios:

1. Given a Git server is configured, When a user views the branch list, Then they see all available branches from the remote repository
2. Given a user wants to create a new feature branch, When they specify a branch name, Then the system creates the branch both locally and pushes it to the remote repository
3. Given multiple branches exist, When a user switches to a different branch, Then the dashboard content updates to reflect the selected branch's state

---

User Story 3 - Dashboard Synchronization with Git (Priority: P1)

A dashboard developer needs to synchronize their local dashboard changes with the Git repository. They want to commit changes, push to remote branches, and pull updates from other developers working on the same dashboard.

Why this priority: This enables collaborative development and ensures changes are properly tracked and shared between team members.

Independent Test: Can be fully tested by making dashboard changes, committing them, and pushing to the remote repository, delivering complete Git workflow integration.

Acceptance Scenarios:

1. Given a user has made changes to a dashboard, When they commit the changes with a message, Then the changes are committed to the current branch
2. Given local changes exist, When a user pushes to the remote repository, Then the changes are successfully pushed and visible to other team members
3. Given remote changes exist, When a user pulls from the remote repository, Then local dashboard content is updated with the latest changes

---

User Story 4 - Environment Deployment (Priority: P2)

A dashboard developer needs to deploy their dashboard changes to different target environments (e.g., staging, production) after committing changes. They want to select a target environment and trigger the deployment process.

Why this priority: This enables the complete development-to-production workflow, allowing teams to promote dashboard changes through different environments.

Independent Test: Can be fully tested by selecting a target environment and triggering deployment, delivering the ability to promote dashboard changes to different environments.

Acceptance Scenarios:

1. Given dashboard changes are committed, When a user selects a target environment for deployment, Then the system validates the deployment configuration
2. Given deployment is initiated, When the process completes, Then the user receives clear feedback on deployment success or failure
3. Given multiple environments are configured, When a user deploys to one environment, Then other environments remain unaffected

---

User Story 5 - Git History and Change Tracking (Priority: P3)

A dashboard developer needs to view the commit history and changes made to dashboards over time. They want to see who made changes, when they were made, and what specific changes were included in each commit.

Why this priority: This provides visibility into the development process and helps with debugging, auditing, and understanding the evolution of dashboards.

Independent Test: Can be fully tested by viewing commit history and examining specific commits, delivering transparency into dashboard development history.

Acceptance Scenarios:

1. Given multiple commits exist, When a user views the commit history, Then they see a chronological list of all commits with relevant details
2. Given a specific commit is selected, When the user views commit details, Then they see the changes included in that commit
3. Given commit history is available, When a user searches for specific changes, Then they can filter and find relevant commits

---

Edge Cases

• What happens when Git server is temporarily unavailable during synchronization?
• How does system handle merge conflicts when multiple developers modify the same dashboard?
• What happens when a user tries to deploy to an environment that doesn't exist or is misconfigured?
• How does system handle large dashboard files that exceed Git repository size limits?
• What happens when Git authentication tokens expire during operations?
• How does system handle network interruptions during long-running operations like large pushes?

Requirements (mandatory)

Clarifications

Session 2026-01-22

• Q: Что именно должно входить в состав данных дашборда в Git-репозитории? → A: Распакованный архив экспорта Superset (YAML файлы: метаданные, чарты, датасеты, базы данных).
• Q: Какова структура хранения дашбордов в Git-репозитории? → A: Один репозиторий соответствует одному дашборду.
• Q: Как должен происходить деплой на целевое окружение после коммита? → A: Импорт через API (Superset Import API).
• Q: Как система должна обрабатывать конфликты слияния (merge conflicts)? → A: UI для выбора версии (Keep Mine / Keep Theirs) на уровне файлов.
• Q: Как должен происходить выбор дашборда для работы с Git? → A: Выбор конкретного дашборда из списка в UI.
• Q: What triggers a deployment to a target environment? → A: Manual trigger by user from UI
• Q: How should the system handle authentication for the different providers (GitHub, GitLab, Gitea)? → A: Option [A] - Personal Access Token (PAT) for all providers

Functional Requirements

• FR-001: System MUST allow users to configure Git server connection settings including provider type (GitHub, GitLab, Gitea), server URL, authentication via Personal Access Token (PAT), and repository details
• FR-002: System MUST support GitLab, GitHub, and Gitea as supported Git server providers
• FR-003: System MUST validate Git server connection using the provided PAT for the selected provider before saving configuration
• FR-004: Users MUST be able to view all available branches from the configured Git repository
• FR-005: Users MUST be able to create new branches both locally and remotely with proper naming validation
• FR-006: Users MUST be able to switch between existing branches and have dashboard content update accordingly
• FR-007: System MUST allow users to commit dashboard changes with commit messages and optional file selection
• FR-008: System MUST support pushing local commits to remote repository branches
• FR-009: System MUST support pulling changes from remote repository to local working directory
• FR-010: System MUST handle merge conflicts with a built-in UI providing "Keep Mine", "Keep Theirs", and "Manual Edit" (via a text area editor for YAML content) resolution options
• FR-011: Users MUST be able to configure multiple target environments for dashboard deployment
• FR-012: System MUST allow users to manually trigger deployment to a selected target environment from the UI
• FR-013: System MUST validate deployment configuration before initiating deployment process
• FR-014: System MUST provide clear feedback on deployment success or failure with detailed logs
• FR-015: Users MUST be able to view commit history with details including author, timestamp, and commit message
• FR-016: System MUST display detailed changes included in each commit for audit purposes
• FR-017: System MUST handle PAT expiration gracefully with re-authentication prompts
• FR-018: System MUST provide offline mode functionality when Git server is unavailable
• FR-019: System MUST store and validate dashboard data as a standard unpacked Superset export (YAML files for dashboard metadata, charts, datasets, and database connections) within their respective directories.
• FR-020: Users MUST be able to search and filter commit history by date, author, or message content
• FR-021: System MUST support rollback functionality to previous dashboard versions via Git operations

Key Entities (include if feature involves data)

• GitServerConfig: Represents Git server connection configuration including server URL, Personal Access Token (PAT), repository path, and connection status
• Branch: Represents a Git branch with properties like name, commit hash, last updated timestamp, and remote tracking status
• Commit: Represents a Git commit with properties like commit hash, author, timestamp, commit message, and list of changed files
• Environment: Represents a deployment target environment with properties like name, URL, authentication details, and deployment status
• DashboardChange: Represents changes made to dashboard directories (YAML metadata + assets) including file paths, change type (add/modify/delete), and content differences

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can successfully configure a supported Git server connection (GitLab, GitHub, or Gitea) and validate it within 2 minutes
• SC-002: Dashboard branch switching operations complete within 5 seconds for repositories with up to 100 commits
• SC-003: Commit and push operations succeed in 95% of attempts under normal network conditions
• SC-004: Deployment to target environments completes successfully within 30 seconds for standard dashboard configurations
• SC-005: Users can view and navigate through commit history for dashboards with up to 1000 commits without performance degradation
• SC-006: Merge conflict resolution guidance is provided in 100% of conflict scenarios with clear resolution steps
• SC-007: Authentication token refresh process completes within 10 seconds when tokens expire
• SC-008: System maintains dashboard state consistency across branch switches in 99% of operations
• SC-009: Deployment rollback operations complete within 1 minute for standard dashboard configurations
• SC-010: Users can search and filter commit history with results displayed within 2 seconds for repositories with up to 500 commits