CICD Gateway

Service: cicd-gateway · Port: 8087 · Database schema: cicd

cicd-gateway connects your CI systems to KubeOpera. It receives webhooks from GitHub and GitLab and direct reports from any CI tool, stores every pipeline run with its stages, and publishes CI/CD events so the rest of the platform can relate problems to the changes that caused them.

For the user's view, see Pipelines.

Domain model

Pipeline
  ├── id, tenant_id, name, repository, branch
  ├── provider: github | gitlab | generic
  └── trigger_events: [push, pull_request, manual, schedule]

PipelineRun
  ├── id, pipeline_id
  ├── status: queued | running | success | failed | cancelled
  ├── trigger_type, commit, branch, author, message
  ├── stages: []StageRun
  └── started_at, finished_at, duration_secs

StageRun
  └── id, name, status, started_at, finished_at,
      error_message, log_excerpt, exit_code, log_url

Two ways in

Webhooks

Provider	Endpoint	Verified with
GitHub	POST /webhook/github	X-Hub-Signature-256 — HMAC-SHA256 with the pipeline's webhook secret.
GitLab	POST /webhook/gitlab	X-Gitlab-Token — the pipeline's webhook token.

Each pipeline has its own webhook secret, generated when it's created. Webhooks are matched to pipelines by repository name, and GitHub push, workflow_run and check_suite events and GitLab Pipeline Hook events are recorded.

Reporting from your CI

Any CI system can report runs directly with the pipeline's reporting token:

curl -X PATCH https://kubeopera.example.com/api/cicd/api/v1/runs/{runId} \
  -H "X-Pipeline-Token: ${PIPELINE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "success",
    "finished_at": "2026-09-26T14:23:01Z",
    "stages": [
      { "name": "build",  "status": "success", "duration_secs": 45 },
      { "name": "test",   "status": "success", "duration_secs": 120 },
      { "name": "deploy", "status": "success", "duration_secs": 18 }
    ]
  }'

See Pipelines: connect your CI for complete examples.

Events

Published to the cicd.events exchange:

Routing key	When
cicd.{provider}.run_started	A run starts.
cicd.{provider}.run_completed	A run succeeds.
cicd.{provider}.run_failed	A run fails.
cicd.{provider}.deployed	A run that deploys to a cluster finishes.

The observability agent attaches deployment events to telemetry as change markers, and the incident manager links failed runs and recent deploys to incidents.

REST API

Method	Path	Description
GET · POST	/api/v1/pipelines	List or create pipelines.
GET · PATCH · DELETE	/api/v1/pipelines/{id}	Pipeline detail, update, delete.
POST	/api/v1/pipelines/{id}/rotate-secrets	Rotate the webhook secret and reporting token.
GET · POST	/api/v1/pipelines/{id}/runs	Run history; create a run (reporting token).
GET	/api/v1/pipelines/{id}/runs/find	Find a run by commit (?commit=).
PATCH	/api/v1/runs/{runId}	Update a run and its stages (reporting token).
GET	/api/v1/pipelines/summary	7-day summary: runs, success rate, failures, average duration.
POST	/webhook/github · /webhook/gitlab	Inbound webhooks.
GET	/healthz	Health check.

Users reach the pipeline routes through kubeopera-api, which scopes them to the caller's tenant.

Configuration

Variable	Default	Description
DATABASE_URL	—	PostgreSQL connection.
RABBITMQ_URL	—	RabbitMQ connection.
SECRET_ENCRYPTION_KEY	—	Encrypts per-pipeline webhook secrets at rest.
PUBLIC_URL	—	Public address shown in webhook URLs.
PORT	8087	HTTP port.