ss-tools/specs/011-git-integration-dashboard/data-model.md

Data Model: Git Integration Plugin

Feature: Git Integration for Dashboard Development Date: 2026-01-22 Last Updated: 2026-07-01

Model Alignment Note

Target branch model is dev -> preprod -> prod. References to main are legacy examples only. Existing repositories with main or master must remain readable, but new repositories and UI defaults should use prod.

Entities

1. GitServerConfig

Configuration for connecting a dashboard to a Git repository.

Field	Type	Description
id	UUID	Unique identifier
dashboard_uuid	UUID	The Superset Dashboard UUID this config applies to
provider	Enum	GITHUB, GITLAB, GITEA, GENERIC
server_url	String	Base URL of the git server (e.g., https://gitlab.com)
repo_url	String	Full HTTPS clone URL
username	String	Username for auth
pat_token	String	Personal Access Token (stored securely)
created_at	DateTime	Creation timestamp
updated_at	DateTime	Last update timestamp

2. Environment

Target environments for deployment.

Field	Type	Description
id	UUID	Unique identifier
name	String	Display name (e.g., "Production", "Staging")
superset_url	String	Base URL of the target Superset instance
auth_token	String	Authentication token/credentials for the target API
is_active	Boolean	Whether this environment is enabled

3. Branch (DTO)

Data Transfer Object representing a Git branch.

Field	Type	Description
name	String	Branch name (e.g., prod, dev, feature/fix-chart)
branch_type	Enum	ENVIRONMENT, FEATURE, HOTFIX, LEGACY, REMOTE_REF, OTHER
is_current	Boolean	True if currently checked out
is_remote	Boolean	True if it exists on remote
last_commit_hash	String	SHA of the tip commit
last_commit_msg	String	Message of the tip commit

Branch classification rules:

• dev, preprod, prod -> ENVIRONMENT
• feature/* -> FEATURE
• hotfix/* -> HOTFIX
• main, master -> LEGACY
• origin/* and other remote tracking refs -> REMOTE_REF

4. Commit (DTO)

Data Transfer Object representing a Git commit.

Field	Type	Description
hash	String	Full SHA hash
short_hash	String	First 7 chars of hash
author_name	String	Author name
author_email	String	Author email
date	DateTime	Commit timestamp
message	String	Commit message
files_changed	List[String]	List of modified files

5. DashboardChange (DTO)

Represents a local change (diff) between Superset state and Git state.

Field	Type	Description
file_path	String	Relative path in repo
change_type	Enum	ADDED, MODIFIED, DELETED, RENAMED
artifact_type	Enum	DASHBOARD_METADATA, CHART, DATASET, DATABASE, FILTER, ASSET, OTHER
artifact_name	String	Best-effort Superset object name extracted from YAML metadata
diff_content	String	Unified diff string

Relationships

• One-to-One: Dashboard (Superset concept) <-> GitServerConfig.
• Many-to-Many: Dashboard <-> Environment (Technically environments are global or scoped, but for MVP they can be global settings available to all dashboards).

Validation Rules

• repo_url: Must be a valid HTTPS URL ending in .git.
• pat_token: Must not be empty.
• branch.name: Must follow git branch naming conventions.
• New feature/hotfix branch names should match ^[a-zA-Z0-9._\/-]+$, must not contain .., and must not start with /.
• New repositories should use prod as production branch. main and master are legacy-compatible names, not preferred defaults.