nikola
73 lines
2.2 KiB
Markdown
73 lines
2.2 KiB
Markdown
# CI Observer Architecture
|
|
|
|
## What It Is
|
|
CI Observer is a read-only dashboard that polls GitHub Actions run data and renders a live CI status wall.
|
|
|
|
## Core Technologies
|
|
- Backend: Python 3.11 + FastAPI
|
|
- HTTP client: `httpx`
|
|
- Storage: SQLite (`/app/data/ci_observer.db`)
|
|
- Frontend: server-rendered static HTML/CSS/JS (no SPA framework)
|
|
- Runtime: Docker + Docker Compose
|
|
- Source control: GitHub
|
|
|
|
## High-Level Flow
|
|
```mermaid
|
|
flowchart LR
|
|
GH[GitHub Actions API] -->|poll runs| APP[FastAPI Poller]
|
|
APP -->|upsert| DB[(SQLite)]
|
|
UI[Browser] -->|GET /api/runs /api/filters /api/config| APP
|
|
APP -->|query| DB
|
|
APP -->|JSON + static assets| UI
|
|
```
|
|
|
|
## Runtime Components
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Runner_VM
|
|
C[Docker Container: ci-observer-dashboard-prod]
|
|
D[(Volume ./data -> /app/data)]
|
|
S[Static UI: index.html + app.js + styles.css]
|
|
A[FastAPI app/main.py]
|
|
C --> A
|
|
C --> S
|
|
C --> D
|
|
end
|
|
|
|
Browser -->|HTTP :8089| C
|
|
A -->|HTTPS calls| GitHubAPI[api.github.com]
|
|
```
|
|
|
|
## Data Model (Main Fields)
|
|
Stored run fields include:
|
|
- `repo`, `workflow`, `run_id`, `status`, `conclusion`
|
|
- `head_branch`, `head_sha`, `actor`
|
|
- `started_at`, `updated_at`, `duration_seconds`
|
|
- `html_url`
|
|
- `raw_json` (full run payload for future extensions)
|
|
|
|
## App Principles
|
|
- Read-only by design: no write-back to GitHub or pipeline control.
|
|
- Operational simplicity: one container, one DB file, one compose file per instance.
|
|
- Clear rollout model: feature branch on test port, then merge to `main`, then production deploy.
|
|
- Low blast radius: test instances isolated by folder, port, and SQLite volume path.
|
|
|
|
## Config Contract
|
|
Environment variables:
|
|
- `GITHUB_TOKEN`
|
|
- `GH_REPOS` (comma-separated)
|
|
- `GH_WORKFLOWS` (comma-separated workflow file names)
|
|
- `REFRESH_SECONDS`
|
|
- `DASHBOARD_TITLE`
|
|
|
|
Important:
|
|
- Current polling logic requires both `GH_REPOS` and `GH_WORKFLOWS`.
|
|
- If `GH_WORKFLOWS` is empty, polling does not start.
|
|
|
|
## Deployment Model Used
|
|
1. Build/test on temporary instance in `/webapps/ci-observer-dashboard-<feature>` on test port.
|
|
2. Validate UI/behavior.
|
|
3. Merge approved branch to `main`.
|
|
4. Production update from `/webapps/ci-observer-dashboard-prod` on `8089`.
|
|
|