CICD Gateway

cicd-gateway is the CI/CD integration service. It receives webhooks from GitHub and GitLab, stores pipeline run history, and publishes events to the cicd.events RabbitMQ exchange.

Domain Model

Pipeline
  ├── id, cluster_id, name, repository, branch
  ├── provider: github | gitlab
  └── 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, pipeline_run_id, name, status, started_at, finished_at, log_url

Webhook Endpoints

GitHub

POST /webhook/github
Headers: X-Hub-Signature-256, X-GitHub-Event

Validates HMAC-SHA256 signature using GITHUB_WEBHOOK_SECRET. Handles workflow_run and check_suite event types.

GitLab

POST /webhook/gitlab
Headers: X-Gitlab-Token

Validates the token against GITLAB_WEBHOOK_TOKEN. Handles Pipeline Hook events.

REST API

Method	Path	Description
GET	/api/v1/pipelines	List pipeline definitions
POST	/api/v1/pipelines	Register a pipeline
GET	/api/v1/pipelines/{id}/runs	Run history with stage breakdown
GET	/api/v1/clusters/{clusterId}/runs/summary	Dashboard aggregation (success rate, avg duration)
PATCH	/api/v1/runs/{runId}	CI agent callback to update run status

CI Agent Callback

For CI systems that cannot use webhooks directly, use the status update endpoint to report run completion:

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

RabbitMQ Events

Published to the cicd.events topic exchange with routing keys:

• pipeline.run.started
• pipeline.run.completed
• pipeline.run.failed

Environment Variables

Variable	Description
DATABASE_URL	PostgreSQL connection
RABBITMQ_URL	RabbitMQ connection
GITHUB_WEBHOOK_SECRET	Secret for HMAC-SHA256 validation
GITLAB_WEBHOOK_TOKEN	Token for GitLab webhook validation
PORT	HTTP port (default: 8087)