DevOps Platform API

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.