GitOps Integration

Keystone Core integrates with a GitOps workflow at the operational seam: it receives deployment webhooks from your VCS / CD system, runs verification workflows to confirm a deployment is healthy, and can trigger a rollback when it isn’t.

This guide enables the webhook receiver, sends it an event, and runs a verification workflow.

Prerequisites

• A running kscore-server.
• curl.

1. Enable the webhook receiver

The receiver opens its own port and re-emits validated webhooks onto the event bus. It’s opt-in — add a gitops block and restart:

gitops:
  webhook:
    enabled: true
    addr: ":8081"
    path: "/webhooks"
    sources:
      github:
        method: hmac   # none | hmac | bearer
        secret: ${KSCORE_GITOPS_WEBHOOK_SOURCES_GITHUB_SECRET}

method selects how the source is authenticated: hmac (GitHub’s X-Hub-Signature-256), bearer (a token), or none (for local testing only). GitHub, GitLab, and Argo CD source shapes are supported.

2. Send an event

Point your VCS’s webhook at http://<host>:8081/webhooks, or simulate one locally. GitHub deployment events carry an X-GitHub-Event header:

curl -X POST http://localhost:8081/webhooks \
  -H "X-GitHub-Event: deployment_status" \
  -H "Content-Type: application/json" \
  -d '{"deployment_status":{"state":"success"},"repository":{"full_name":"acme/app"}}'

The receiver validates the source, normalizes the payload, and re-emits it onto the event bus. Watch it arrive:

kscore-events watch

3. Run a verification workflow

A verification workflow is a YAML file of checks — most commonly HTTP probes against the thing you just deployed. Save post-deploy.yaml:

name: post-deploy-checks
on_failure: abort   # abort | continue
steps:
  - name: server-health
    type: http
    timeout: 5s
    retries: 2
    config:
      url: http://localhost:8080/health
      expect_status: 200
  - name: api-ready
    type: http
    config:
      url: http://localhost:8080/readyz
      expect_status: 200
      expect_body_contains: ready

Run it:

kscore-gitops verify post-deploy.yaml

workflow=post-deploy-checks verdict=PASS duration=12ms steps=2
  [PASS] server-health (http) ...
  [PASS] api-ready (http) ...

on_failure: abort stops (and marks the rest skipped) on the first failure; continue runs every step. --parallel and --timeout override the file. A non-zero exit means the deployment failed verification — wire that into your pipeline to gate a promotion.

4. Roll back

When verification fails, trigger a rollback of the last applied change:

kscore-gitops rollback

Next steps

• Querying the Audit Log & Policies — webhook receipts and rollbacks are audited.
• HA Cluster Topology — run the control plane itself clustered.