Skip to content

Commit ea6db3e

Browse files
cursoragentvenkateshsakamuri-lab
cursoragent
and
venkateshsakamuri-lab
committed
chore(release): add v1.0.0 GitHub release tooling and notes
Add tag-driven release workflow, local artifact builder (source archives, JAR, frontend tarball, MCP pack, CycloneDX SBOMs, checksums), changelog, and E2E verification record after full-stack redeploy smoke. Co-authored-by: Venkat SF <venkatesh.sakamuri@stayflexi.com>
1 parent 7833f31 commit ea6db3e

8 files changed

Lines changed: 485 additions & 0 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: release
2+
3+
# Cut a GitHub Release when a version tag is pushed.
4+
# Artifacts match scripts/release/build-artifacts.sh (source, JAR, frontend,
5+
# MCP pack, SBOMs, checksums, manifest).
6+
7+
on:
8+
push:
9+
tags:
10+
- 'v*.*.*'
11+
12+
permissions:
13+
contents: write
14+
15+
concurrency:
16+
group: release-${{ github.ref }}
17+
cancel-in-progress: false
18+
19+
jobs:
20+
build-and-publish:
21+
name: build artifacts + GitHub Release
22+
runs-on: ubuntu-latest
23+
timeout-minutes: 90
24+
steps:
25+
- uses: actions/checkout@v7
26+
with:
27+
fetch-depth: 0
28+
29+
- uses: actions/setup-java@v5.6.0
30+
with:
31+
distribution: temurin
32+
java-version: '25'
33+
cache: maven
34+
35+
- uses: actions/setup-node@v7
36+
with:
37+
node-version: '22'
38+
cache: npm
39+
40+
- name: Build release artifacts
41+
run: |
42+
chmod +x scripts/release/build-artifacts.sh
43+
./scripts/release/build-artifacts.sh "${GITHUB_REF_NAME}"
44+
45+
- name: Verify checksums
46+
run: |
47+
cd "release-artifacts/${GITHUB_REF_NAME}"
48+
sha256sum -c SHA256SUMS
49+
sha512sum -c SHA512SUMS
50+
51+
- name: Upload workflow artifacts
52+
uses: actions/upload-artifact@v4
53+
with:
54+
name: deepsql-${{ github.ref_name }}
55+
path: release-artifacts/${{ github.ref_name }}/
56+
if-no-files-found: error
57+
retention-days: 30
58+
59+
- name: Create GitHub Release
60+
env:
61+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
62+
run: |
63+
set -euo pipefail
64+
TAG="${GITHUB_REF_NAME}"
65+
NOTES="docs/releases/RELEASE_NOTES-${TAG}.md"
66+
if [[ ! -f "$NOTES" ]]; then
67+
NOTES="CHANGELOG.md"
68+
fi
69+
# Idempotent: if the release already exists (re-run), upload assets only.
70+
if gh release view "$TAG" >/dev/null 2>&1; then
71+
gh release upload "$TAG" "release-artifacts/${TAG}"/* --clobber
72+
else
73+
gh release create "$TAG" \
74+
--title "DeepSQL ${TAG}" \
75+
--notes-file "$NOTES" \
76+
--verify-tag \
77+
"release-artifacts/${TAG}"/*
78+
fi

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@
1515

1616
# production
1717
/build
18+
# Local / CI release bundles (JAR, source archives, SBOMs, checksums)
19+
/release-artifacts/
1820

1921
# misc
2022
.DS_Store

‎CHANGELOG.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Changelog
2+
3+
All notable changes to DeepSQL are documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
7+
for product tags (`vMAJOR.MINOR.PATCH`).
8+
9+
## [1.0.0] — 2026-08-13
10+
11+
First public OSS release.
12+
13+
### Added
14+
15+
- Self-hosted DeepSQL stack: Spring Boot backend, React UI, DeepSQL Agent, MCP/CLI (`@deepsql/mcp`).
16+
- Brain initialization with multi-schema discovery, coverage gates, and terminal `NEEDS_ATTENTION` handling.
17+
- Agent tab SSO bridge with per-user MCP tokens, token-file rotation, and fail-loud provisioning.
18+
- Dashboard artifact generation (HTML + sandboxed `deepsql.query` bridge).
19+
- BYO LLM via OpenAI-compatible providers (`LlmProviderRegistry` / `LlmConfigResolver`).
20+
- Official release tooling: `scripts/release/build-artifacts.sh` and tag-driven GitHub Release workflow.
21+
22+
### Security
23+
24+
- Session kill endpoints reject non-integer PIDs (SQL injection class closed).
25+
- Dangerous controllers enforce connection ACL; Hermes/agent provisioner bind loopback.
26+
- Compose Valkey password + Actuator limited to health for anonymous callers.
27+
- JWT / session auth fail-closed when secrets are missing.
28+
29+
### Known limitations
30+
31+
- Residual high-severity items tracked in `docs/oss-ux/OSS_SECURITY_REVIEW.md` (IDOR sweep, SET preamble allowlist, SSRF hardening, share-password defaults) are deferred past this cut.
32+
- Primary distribution path remains `docker compose up --build` (no pre-built container registry in this release).
33+
34+
[1.0.0]: https://github.com/DeepSQLAI/deepsql/releases/tag/v1.0.0

‎docs/oss-ux/E2E_RELEASE_VERIFICATION.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# E2E release verification — 2026-08-13
2+
3+
Stack: native Cloud VM (Postgres 16 + Redis + Spring Boot `:8080` + Vite `:3000` + Hermes `:8787` + provisioner `:8788`). `main` at `7833f31` (post security PR #49). Redeployed backend from packaged `dba-agent-backend-1.0.0.jar`.
4+
5+
## Results
6+
7+
| Check | Result | Notes |
8+
|-------|--------|-------|
9+
| `GET /api/actuator/health` | PASS | `200` |
10+
| Anonymous Prometheus | PASS | `401` (not exposed) |
11+
| Login `admin@localhost` | PASS | `auth_token` cookie |
12+
| Connections list | PASS | 3 connections incl. `demo_shop` |
13+
| Brain init status | PASS | `COMPLETED` / 100% |
14+
| `/onboarding` | PASS | `200`, title DeepSQL |
15+
| Agent session `mcpAuthOk` | PASS | `true` after provisioner restart |
16+
| Agent Q&A (`e2e-agent-check.py`) | PASS | `execute_sql` → `demo_shop` |
17+
| Dashboard generate | PASS | HTML + `deepsql.query` |
18+
| Kill malicious PID | PASS | `400` Invalid session id |
19+
| Logout | PASS | subsequent `/auth/me` → `401` |
20+
| MCP JS syntax | PASS | `node --check` clean |
21+
| Hermes bind | PASS | `127.0.0.1:8787` |
22+
23+
## Ops notes discovered during redeploy
24+
25+
1. **Provisioner must run current tree** — an Aug-12 `local-agent-provisioner.py` process lacked `DEEPSQL_TOKEN_FILE` writes; restarting from `scripts/local-agent-provisioner.py` fixed profile token files.
26+
2. **Hermes webui caches MCP env** — after rotating tokens / updating `~/.hermes/config.yaml`, restart `hermes-webui` or Agent tab MCP calls 401 with stale env (USER_ID=`deepsql-agent`, no `DEEPSQL_AUTH_TOKEN`). Dashboard generate stayed green because it uses the channel-token path.
27+
3. Syncing default `~/.hermes/config.yaml` `mcp_servers.deepsql.env` from the active `u-admin` profile after provision keeps native/dev Agent tab healthy.
28+
29+
## Release gate
30+
31+
Functional smoke + agent/dashboard E2E are green for the `v1.0.0` artifact cut. Remaining security Highs in `OSS_SECURITY_REVIEW.md` are documented, not blockers for this tagged OSS release.

‎docs/oss-ux/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,10 @@ These docs are the durable home for OSS go-live planning. **Do not rely on `/opt
77
| [`OSS_LAUNCH_USABILITY_CRITIQUE.md`](./OSS_LAUNCH_USABILITY_CRITIQUE.md) | E2E usability findings (Brain, Agent, onboarding) |
88
| [`E2E_FIX_PROPOSAL.md`](./E2E_FIX_PROPOSAL.md) | Product fix workstreams W1–W7 + PR order |
99
| [`OSS_SECURITY_REVIEW.md`](./OSS_SECURITY_REVIEW.md) | Security Criticals/Highs + S1–S10 track |
10+
| [`E2E_RELEASE_VERIFICATION.md`](./E2E_RELEASE_VERIFICATION.md) | Pre-`v1.0.0` stack redeploy + smoke matrix results |
11+
| [`RELEASE.md`](./RELEASE.md) | How to cut GitHub Releases (artifacts, tags, checksums) |
12+
| [`DAILY_RELEASE_AUTOMATION.md`](./DAILY_RELEASE_AUTOMATION.md) | Morning PR triage automation prompt |
13+
14+
Product release notes live under [`docs/releases/`](../releases/). Build locally with `./scripts/release/build-artifacts.sh v1.0.0` (output: `release-artifacts/v1.0.0/`).
1015

1116
Other Cloud Agents: read these paths from the repo (this branch or after merge to `main`).

‎docs/oss-ux/RELEASE.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# DeepSQL release process
2+
3+
How we cut an official GitHub release with builds, source archives, checksums, and SBOMs.
4+
5+
## Versioning
6+
7+
| Surface | Where | Current |
8+
|---------|-------|---------|
9+
| Product / Git tag | `vMAJOR.MINOR.PATCH` | `v1.0.0` |
10+
| Backend JAR | `backend/pom.xml` `<version>` | `1.0.0` |
11+
| Frontend package | root `package.json` | `0.1.0` (internal) |
12+
| MCP / CLI npm | `mcp/package.json` | `0.27.0` |
13+
14+
Tag the **product** version (`v1.0.0`). Keep backend `pom.xml` in lockstep with the tag for the JAR filename. MCP may continue its own semver when publishing `@deepsql/mcp` to npm.
15+
16+
## Pre-flight (release manager)
17+
18+
1. `main` is green on CI (`frontend`, `backend`, `mcp`, `compose-build`).
19+
2. Smoke matrix from `docs/oss-ux/E2E_FIX_PROPOSAL.md` W7 passes on a redeployed stack:
20+
- login / auth cookie
21+
- Brain init `COMPLETED`
22+
- Agent Q&A (`scripts/self-host/e2e-agent-check.py`) → `AGENT_OK` + `DASH_OK`
23+
- `/onboarding` renders
24+
- security smoke: anonymous Prometheus `401`, malicious kill pid `400`
25+
3. `CHANGELOG.md` and `docs/releases/RELEASE_NOTES-vX.Y.Z.md` updated.
26+
27+
## Local artifact build
28+
29+
```bash
30+
./scripts/release/build-artifacts.sh v1.0.0
31+
# → release-artifacts/v1.0.0/
32+
```
33+
34+
Skip expensive rebuilds when iterating:
35+
36+
```bash
37+
SKIP_BACKEND=1 SKIP_FRONTEND=1 ./scripts/release/build-artifacts.sh v1.0.0
38+
```
39+
40+
Verify checksums:
41+
42+
```bash
43+
cd release-artifacts/v1.0.0
44+
sha256sum -c SHA256SUMS
45+
```
46+
47+
## Publish on GitHub
48+
49+
Preferred path (CI):
50+
51+
```bash
52+
git checkout main && git pull
53+
git tag -a v1.0.0 -m "DeepSQL v1.0.0"
54+
git push origin v1.0.0
55+
```
56+
57+
Pushing the tag runs `.github/workflows/release.yml`, which:
58+
59+
1. Builds source archives, backend JAR, frontend tarball, MCP pack
60+
2. Generates CycloneDX SBOMs (best-effort)
61+
3. Writes `SHA256SUMS` / `SHA512SUMS` + `manifest.json`
62+
4. Creates a GitHub Release (non-draft) attaching every file under `release-artifacts/v1.0.0/`
63+
64+
Manual fallback (if Actions cannot publish):
65+
66+
```bash
67+
./scripts/release/build-artifacts.sh v1.0.0
68+
gh release create v1.0.0 \
69+
--title "DeepSQL v1.0.0" \
70+
--notes-file docs/releases/RELEASE_NOTES-v1.0.0.md \
71+
release-artifacts/v1.0.0/*
72+
```
73+
74+
## Artifact set (what “industry standard” means here)
75+
76+
| Artifact | Purpose |
77+
|----------|---------|
78+
| `*-source.tar.gz` / `.zip` | Bit-for-bit source corresponding to the tag (`git archive`) |
79+
| `dba-agent-backend-*.jar` | Runnable Spring Boot binary |
80+
| `deepsql-frontend-*.tar.gz` | Static SPA to serve behind nginx |
81+
| `deepsql-mcp-*.tgz` | CLI / MCP installable package |
82+
| `sbom-*.cdx.json` | CycloneDX software bill of materials |
83+
| `SHA256SUMS` / `SHA512SUMS` | Integrity verification |
84+
| `manifest.json` | Machine-readable inventory (commit, sizes, hashes) |
85+
| `RELEASE_NOTES.md` | Human-facing release notes |
86+
87+
Docker Compose remains the primary install path (`docker compose up --build`); the JAR + frontend tarball support air-gapped / non-Compose operators.
88+
89+
## Post-release
90+
91+
- Confirm the Release page lists every file and checksums verify.
92+
- Announce with the tag URL + one-line upgrade note.
93+
- Bump versions on `main` for the next cycle only after the tag is cut (avoid tagging a commit whose pom still says the previous version).

‎docs/releases/RELEASE_NOTES-v1.0.0.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# DeepSQL v1.0.0
2+
3+
**First public open-source release** — self-hosted database agent for PostgreSQL and MySQL.
4+
5+
## Highlights
6+
7+
- **Ask your database** — schema exploration, SQL generation, slow-query help, and index guidance through the web UI or MCP/CLI.
8+
- **Brain** — indexes your schemas (including non-`public` Postgres schemas) so the agent has real context.
9+
- **DeepSQL Agent** — per-user profiles, MCP tool access scoped to your login, dashboard HTML artifacts with a read-only query bridge.
10+
- **BYO model** — point at OpenAI, Azure OpenAI, or any OpenAI-compatible endpoint. No vendor lock-in on inference.
11+
- **Self-host first** — credentials stay in your vault DB; Compose builds from source.
12+
13+
## Install
14+
15+
```bash
16+
git clone https://github.com/DeepSQLAI/deepsql.git
17+
cd deepsql
18+
git checkout v1.0.0
19+
cp .env.example .env
20+
# set SECURITY_JWT_SECRET, ENCRYPTION_KEY, and DEEPSQL_CHAT_* in .env
21+
docker compose up --build -d
22+
```
23+
24+
Air-gapped / non-Compose: download the JAR + frontend tarball from this Release, verify `SHA256SUMS`, and follow `docs/oss-ux/RELEASE.md`.
25+
26+
## Artifacts in this release
27+
28+
| File | Contents |
29+
|------|----------|
30+
| `deepsql-1.0.0-source.tar.gz` / `.zip` | Source tree at this tag |
31+
| `dba-agent-backend-1.0.0.jar` | Spring Boot executable |
32+
| `deepsql-frontend-1.0.0.tar.gz` | Production static UI |
33+
| `deepsql-mcp-0.27.0.tgz` | CLI + MCP server package |
34+
| `sbom-*.cdx.json` | CycloneDX SBOMs |
35+
| `SHA256SUMS` / `SHA512SUMS` | Integrity hashes |
36+
| `manifest.json` | Machine-readable inventory |
37+
38+
Verify:
39+
40+
```bash
41+
sha256sum -c SHA256SUMS
42+
```
43+
44+
## Security notes
45+
46+
Critical/high items addressed before this cut are listed in `CHANGELOG.md` and `docs/oss-ux/OSS_SECURITY_REVIEW.md`. Please report new vulnerabilities per `SECURITY.md`.
47+
48+
## Verify before upgrading production
49+
50+
On a staging stack, run:
51+
52+
```bash
53+
python3 scripts/self-host/e2e-agent-check.py
54+
```
55+
56+
Expect `AGENT_OK True` and `DASH_OK True`.

0 commit comments

Comments
 (0)