Automating

• 1: Automate Jikkou with GitHub Actions
• 2: Detect Configuration Drift

1 - Automate Jikkou with GitHub Actions

Setup Jikkou

The streamthoughts/setup-jikkou action is a JavaScript action that sets up Jikkou in your GitHub Actions workflow by:

• Downloading a specific version of Jikkou CLI and adding it to the PATH.
• Configuring JIKKOU CLI with a custom configuration file.

After you’ve used the action, subsequent steps in the same job can run arbitrary Jikkou commands using the GitHub Actions run syntax. This allows most Jikkou commands to work exactly like they do on your local command line.

Usage

steps:
  - uses: streamthoughts/setup-jikkou@v1

A specific version of Jikkou CLI can be installed:

steps:
  - uses: streamthoughts/setup-jikkou@v0.1.0
    with:
      jikkou_version: 0.37.0

A custom configuration file can be specified:

steps:
  - uses: streamthoughts/setup-jikkou@v0.1.0
    with:
      jikkou_config: ./config/jikkouconfig.json

Inputs

This Action additionally supports the following inputs :

See also

• Detect configuration drift: a scheduled workflow that alerts when your clusters no longer match Git.

2 - Detect Configuration Drift

Configuration drift happens to every Kafka platform: someone bumps retention.ms during an incident with a vendor UI, a topic gets created by hand, an ACL is “temporarily” widened. Because Jikkou is stateless and always compares your Git-versioned definitions against the actual cluster state, detecting drift is a single command:

jikkou diff --files ./resources --fail-on-changes

Exit codes

With --fail-on-changes, jikkou diff uses distinct exit codes so CI can react precisely:

A one-line summary is printed to stderr (for example, 3 changes detected: 1 CREATE, 2 UPDATE), while stdout carries the full machine-readable diff (YAML by default, -o JSON available).

Scheduled drift check with GitHub Actions

The workflow below runs every hour using the streamthoughts/setup-jikkou action, uploads the diff as an artifact, and opens an issue when drift is detected:

name: Kafka Drift Detection

on:
  schedule:
    - cron: '0 * * * *'   # every hour
  workflow_dispatch: {}

jobs:
  drift:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - uses: actions/checkout@v4

      - uses: streamthoughts/setup-jikkou@v1
        with:
          jikkou_config: ${{ github.workspace }}/.jikkou/config

      - name: Check for drift
        id: diff
        run: |
          set +e
          jikkou diff --files ./resources --fail-on-changes -o YAML > drift.yaml
          echo "exit_code=$?" >> "$GITHUB_OUTPUT"          

      - name: Upload diff
        if: steps.diff.outputs.exit_code == '3'
        uses: actions/upload-artifact@v4
        with:
          name: drift-report
          path: drift.yaml

      - name: Open an issue on drift
        if: steps.diff.outputs.exit_code == '3'
        run: |
          gh issue create \
            --title "Kafka configuration drift detected ($(date -u +%F))" \
            --body "jikkou diff found pending changes. Download the drift-report artifact from run ${{ github.run_id }}."          
        env:
          GH_TOKEN: ${{ github.token }}

      - name: Fail on error
        if: steps.diff.outputs.exit_code == '1' || steps.diff.outputs.exit_code == '2'
        run: exit 1

Instead of opening an issue, the same gate (exit_code == '3') can post to Slack, page an on-call rotation, or even trigger a jikkou apply job to revert the drift automatically.

Running without cluster credentials

CI runners do not need direct access to your Kafka clusters. Run the Jikkou API server inside your platform, and point the CLI at it with proxy mode:

jikkou {
  proxy {
    enabled = true
    url = "https://jikkou.my-platform.internal"
    security {
      access-token = ${?JIKKOU_API_TOKEN}
    }
  }
}

With this configuration, the workflow above only needs an API token: cluster credentials stay on the server side.

Related

• jikkou diff command reference
• Automate Jikkou with GitHub Actions
• Jikkou vs Terraform: why stateless reconciliation catches drift that state files miss