NestJS + TypeScript backend for the DevOps operations platform. The current local MVP provides the enterprise project skeleton, Prisma data model, configuration validation, integration client boundaries, Gitea webhook handling, Jenkins queue/build synchronization, notification provider boundaries, audit logs, BPMN process definitions, and runnable seed-backed APIs.

Scope

Manage projects, deploy runs, BPMN step state, Jenkins/Gitea integration state, notification delivery, audit records, and agent invocations.
Keep all external credentials server-side.
Use Prisma as the default data access layer. Native SQL is allowed only inside Repository methods with a documented reason.

Local Setup

pnpm install
cp .env.example .env
pnpm prisma:generate
pnpm start:dev

The API listens on http://localhost:4300 by default and runs without a local MySQL database when USE_DATABASE_READS=false. In that mode /projects and /deploy-runs use seed-backed repository data while keeping the same service and controller contracts intended for Prisma-backed reads.

Useful Commands

pnpm lint
pnpm test
pnpm build
pnpm check
pnpm prisma:migrate:dev --name init

API

GET /health: dependency configuration and health summary.
GET /settings/integration-config: Jenkins/Gitea/notification/LLM/Database/Redis/Secret Encryption Key configuration status. The response only exposes environment variable names, never secret values.
GET /projects: configured project list.
GET /projects/:key: one project by key.
GET /deploy-runs: latest deploy runs.
POST /deploy-runs: create a deploy run. Missing Jenkins config uses a local dry-run path; configured Jenkins calls buildWithParameters and returns queued/running.
POST /deploy-runs/:id/sync-jenkins: synchronize Jenkins queue/build/log status and advance success or failure.
POST /deploy-runs/sync-jenkins: synchronize all queued/running runs that have Jenkins queue/build identifiers.
POST /deploy-runs/:id/cancel: cancel a deploy run.
POST /deploy-runs/:id/retry: create a retry deploy run.
POST /webhooks/gitea: accept Gitea push webhooks and trigger test deploy runs.
GET /process-definitions/release: BPMN release process definition.
GET /audit-logs: latest sanitized audit records.
GET /agent/invocations and POST /agent/invocations: DevOps-scoped agent invocation records and mock results.
GET /docs: Swagger UI.

Data Access Rules

Business modules access data through Repository classes, not direct Prisma calls in controllers.
Prisma owns connection pooling, transactions, migrations, and typed models.
Deploy run creation, status transition, step transition, and audit writes must use explicit Prisma transactions once DB writes are enabled.
Idempotency keys are mandatory for webhook callbacks, Jenkins queue/build tracking, and manual deploy retry paths.
Raw SQL must be parameterized, isolated in a Repository method, covered by tests, and justified in the method comment.

Secret Rules

Never commit real .env, Jenkins tokens, Gitea tokens, notification webhook URLs, LLM keys, private keys, or cookies.
Persisted secrets belong in the secrets table encrypted with a deployment-provided key or in the deployment secret manager.
Logs, audit records, integration errors, and LLM prompts must pass through redaction before storage or return.

Agent Boundary

The Agent module is not a generic chat entrypoint. It can only support DevOps workflows:

release risk summaries,
Jenkins failure diagnosis,
runbook Q&A against whitelisted sources,
release notes drafts,
incident review drafts.

Agent calls are read-only. They must not trigger deploys, mutate Jenkins/Gitea, or expose raw secrets. When LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL are configured, the backend proxies DevOps-scoped prompts to /chat/completions; otherwise it returns local mock results with the same API shape.

Notification Providers

DeployNotificationService supports the first provider boundary for:

NOTIFICATION_PROVIDER=wecom with WECOM_WEBHOOK_URL
NOTIFICATION_PROVIDER=feishu with FEISHU_WEBHOOK_URL
NOTIFICATION_PROVIDER=generic with NOTIFICATION_WEBHOOK_URL

Missing provider or webhook configuration returns a skipped notification result and does not block deploy status transitions.

Jenkins Auto Sync

Manual sync is always available through POST /deploy-runs/sync-jenkins. To enable a lightweight in-process poller before Redis/BullMQ is introduced:

JENKINS_AUTO_SYNC_ENABLED=true
JENKINS_AUTO_SYNC_INTERVAL_MS=30000

The poller only scans queued/running runs that already have a Jenkins queue id or build number.