# Quickstart: Git Integration for Dashboards

**Last Updated**: 2026-07-01
**Audience**: BI developers and Superset analysts.

## Prerequisites
-   A running Superset instance.
-   A Git repository (GitLab, GitHub, etc.) created for your dashboard.
-   A Personal Access Token (PAT) with `repo` scope.

## Setup Guide

### 1. Configure Git Connection
1.  Navigate to **Git** in the operations menu.
2.  Open **Settings -> Git** if no Git server is configured.
3.  Enter your Git Provider details:
    -   **Repo URL**: `https://github.com/myorg/sales-dashboard.git`
    -   **Username**: `myuser`
    -   **PAT**: `ghp_xxxxxxxxxxxx`
4.  Test and save the connection.

### 2. Connect a Dashboard Repository
1.  Open **Git -> Управление Git**.
2.  Select a dashboard and click **Управление Git**.
3.  If the dashboard has no repository, choose one of two paths:
    -   **Create new repository**: create a remote repository on the selected Git server.
    -   **Connect existing repository**: bind a known remote URL to the dashboard.
4.  Confirm the setup summary before initialization:
    -   Git server
    -   Repository URL
    -   Default production branch: `prod`
    -   Environment branches: `dev`, `preprod`, `prod`
5.  After initialization, sync the current Superset dashboard into the repository.

## Branch Model

The primary dashboard lifecycle is:

```text
dev -> preprod -> prod
```

-   `dev`: active dashboard development.
-   `preprod`: validation before production.
-   `prod`: production-ready state.
-   Existing repositories with `main` or `master` remain supported as legacy refs, but new repositories should use `prod`.

Planned branch extensions:

-   `feature/*`: created from `dev`, merged back into `dev`.
-   `hotfix/*`: created from `prod`, merged into `prod` and `dev`.

## Development Workflow

#### Making Changes
1.  Edit your dashboard in Superset as usual.
2.  Open the dashboard in **Git Management**.
3.  Click **Sync from Superset**. This exports the current dashboard and unpacks it into the local Git repository.
4.  Review the change summary and raw YAML diff.

#### Saving a Version
1.  Enter a clear change description or generate one.
2.  Click **Save version** (`Commit`).
3.  Optionally send the commit to the remote server (`Push`).

#### Publishing Through Environments
1.  Work in `dev`.
2.  Promote `dev -> preprod` through a Merge Request when ready for validation.
3.  Promote `preprod -> prod` through a Merge Request after approval.
4.  Deploy to Superset production only from `prod`.

### Branching
1.  For parallel work, create a branch named like `feature/q4-updates` from `dev`.
2.  Keep environment branches (`dev`, `preprod`, `prod`) protected from accidental deletion.
3.  Treat `main`, `master`, and `origin/*` as legacy or advanced refs in the UI.

### Deploying
1.  Open **Publish to environment**.
2.  Select the target environment.
3.  For PROD, verify the confirmation summary: dashboard name, source branch, target environment, last commit, author, and changed files.
4.  Confirm deploy. The current repository state will be imported into the target Superset environment.

## Implementation Status (2026-07-01)

The target workflow is `dev -> preprod -> prod`. Phase 12A remediation replaced new-repository `main` defaults with `prod`, updated release UI labels, and keeps existing `main/master` repositories as legacy-compatible refs.