busya
64564da988
Backend: - fix 17 missing 'await' in git route handlers causing silent no-ops (branches, diff, history, commit, push, pull, merge, promote, sync) - fix async coroutine passed to run_blocking in git_plugin.py Frontend: - add collapsible 'How it works' onboarding (GitHelpPanel) - add status legend with color-coded repository statuses - i18n: add 50+ missing keys, replace hardcoded strings - add Refresh button in modal header - add PROD deploy confirmation dialog (replaces browser prompt()) - add CommitHistory to workspace tab with timeline nodes - add post-commit success banner with next-step guidance - increase success toast duration to 8s - group local/remote branches in selector (optgroup) - format last_modified dates timezone-aware - change PROD badge from red to neutral indigo - extract shared resolveGitStatusToken to git-utils.ts - fix 'slug' label regression - remove dead init_repo_button key UI/UX audit fixes: - add descriptions to Create/Init buttons in init panel - add actionable CTA to server mismatch warning - improve checkbox text phrasing
114 lines
3.6 KiB
Markdown
114 lines
3.6 KiB
Markdown
# API Contracts: Git Integration Plugin
|
|
|
|
**Feature**: Git Integration for Dashboard Development
|
|
**Date**: 2026-01-22
|
|
**Last Updated**: 2026-07-01
|
|
|
|
## Contract Alignment Note
|
|
|
|
This document describes the target API contract. The current codebase uses decomposed routes under `/api/git/repositories/{dashboard_ref}/...`. Older examples that referenced `main` have been updated to `prod`; `main/master` are legacy-compatible refs only.
|
|
|
|
## Base Path
|
|
`/api/git`
|
|
|
|
## Endpoints
|
|
|
|
### 1. Configuration
|
|
|
|
#### `GET /config/{dashboard_uuid}`
|
|
Retrieve Git configuration for a specific dashboard.
|
|
- **Response**: `GitServerConfig` (excluding full token)
|
|
|
|
#### `POST /config`
|
|
Save or update Git configuration.
|
|
- **Request**: `GitServerConfig`
|
|
- **Response**: `GitServerConfig`
|
|
|
|
### 2. Repository Operations
|
|
|
|
#### `POST /init/{dashboard_uuid}`
|
|
Initialize/Clone the repository for the dashboard.
|
|
- **Request**: Empty (uses stored config)
|
|
- **Response**: `{ "status": "success", "message": "Repository cloned" }`
|
|
|
|
#### `GET /status/{dashboard_uuid}`
|
|
Get current status (changes between Superset export and local git HEAD).
|
|
- **Response**:
|
|
```json
|
|
{
|
|
"branch": "prod",
|
|
"changes": [
|
|
{
|
|
"file_path": "charts/sales.yaml",
|
|
"change_type": "MODIFIED",
|
|
"artifact_type": "CHART",
|
|
"artifact_name": "Sales"
|
|
}
|
|
],
|
|
"is_clean": false
|
|
}
|
|
```
|
|
|
|
#### `POST /sync/{dashboard_uuid}`
|
|
Fetch latest dashboard export from Superset and unpack into the git working directory (overwriting local files to match Superset state).
|
|
- **Response**: `{ "status": "success", "changes_detected": true }`
|
|
|
|
### 3. Branch Management
|
|
|
|
#### `GET /branches/{dashboard_uuid}`
|
|
List all local and remote branches.
|
|
- **Response**: `List[Branch]`, grouped or classifiable by branch type: `ENVIRONMENT`, `FEATURE`, `HOTFIX`, `LEGACY`, `REMOTE_REF`, `OTHER`.
|
|
|
|
#### `POST /branches/{dashboard_uuid}`
|
|
Create a new branch.
|
|
- **Request**: `{ "name": "feature/new-chart", "source_branch": "dev" }`
|
|
- **Response**: `Branch`
|
|
|
|
#### `POST /checkout/{dashboard_uuid}`
|
|
Switch to a different branch. **Warning**: This updates the Superset Dashboard content to match the branch state!
|
|
- **Request**: `{ "branch_name": "dev" }`
|
|
- **Response**: `{ "status": "success", "message": "Switched to dev and updated dashboard" }`
|
|
|
|
### 4. Commit & Push
|
|
|
|
#### `POST /commit/{dashboard_uuid}`
|
|
Commit staged changes.
|
|
- **Request**: `{ "message": "Updated sales chart", "files": ["charts/sales.yaml"] }`
|
|
- **Response**: `Commit`
|
|
|
|
#### `POST /push/{dashboard_uuid}`
|
|
Push commits to remote.
|
|
- **Response**: `{ "status": "success" }`
|
|
|
|
#### `POST /pull/{dashboard_uuid}`
|
|
Pull changes from remote.
|
|
- **Response**: `{ "status": "success", "updates": [...] }`
|
|
|
|
### 5. History
|
|
|
|
#### `GET /history/{dashboard_uuid}`
|
|
Get commit log.
|
|
- **Query Params**: `limit=20`, `branch=prod`
|
|
- **Response**: `List[Commit]`
|
|
|
|
### 6. Deployment
|
|
|
|
#### `GET /environments`
|
|
List configured target environments.
|
|
- **Response**: `List[Environment]`
|
|
|
|
#### `POST /deploy/{dashboard_uuid}`
|
|
Deploy current branch state to a target environment.
|
|
- **Request**: `{ "environment_id": "uuid", "commit_hash": "optional-hash" }`
|
|
- **Response**: `{ "status": "success", "job_id": "..." }`
|
|
|
|
### 7. Promotion
|
|
|
|
#### `POST /repositories/{dashboard_ref}/promote`
|
|
Promote changes between environment branches.
|
|
- **Request**: `{ "from_branch": "dev", "to_branch": "preprod", "mode": "mr" }`
|
|
- **Request**: `{ "from_branch": "preprod", "to_branch": "prod", "mode": "mr" }`
|
|
- **Response**: `{ "mode": "mr", "status": "opened", "url": "..." }`
|
|
|
|
Direct promote is allowed only with an explicit reason and should be audited.
|