Use the ankra CLI in CI

Your CI already has the schedule, the secrets and the logs. What it lacks is an answer to “what will this change do to the live cluster?” or “why did that deploy fail?”. The Ankra CLI gives a CI job two commands for that: ankra chat asks Ankra’s AI a question with your clusters as context and prints the answer, and ankra cluster apply --wait applies a cluster definition and waits for the result. This page shows one working job for each of three uses.

Prerequisites

A CI system that can run a shell step. The examples use GitHub Actions; the commands are the same anywhere.
A service token stored as the CI secret ANKRA_API_TOKEN, with the narrowest role the job needs - see Keep CI jobs read-only.

The CLI installed in the job:

bash <(curl -sL https://github.com/ankraio/ankra-cli/releases/latest/download/install.sh)

ankra chat prints the answer on standard output and the conversation ID on standard error, so redirecting standard output captures only the answer. To parse the answer, the tools the AI ran and any change it proposed, add -o json - see Parse the answer as JSON.

Comment a review of a cluster change on the pull request

When a pull request changes a cluster definition, pass the diff to ankra chat and post the answer as a comment. Ankra’s AI compares the change with the live cluster.

# .github/workflows/ankra-review.yml
name: Ankra review
on:
  pull_request:
    paths:
      - "cluster.yaml"
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install Ankra CLI
        run: bash <(curl -sL https://github.com/ankraio/ankra-cli/releases/latest/download/install.sh)
      - name: Review the change against the live cluster
        env:
          ANKRA_API_TOKEN: ${{ secrets.ANKRA_API_TOKEN }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          change=$(git diff "$BASE_SHA" HEAD -- cluster.yaml | head -c 20000)
          ankra chat --cluster my-cluster --mode ask \
            "This pull request changes the definition of this cluster. Compare it with the live cluster, \
             summarise what will change, and flag any capacity or quota risk. The diff: $change" \
            > review.md
      - name: Comment on the pull request
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs')
            await github.rest.issues.createComment({
              ...context.repo,
              issue_number: context.issue.number,
              body: fs.readFileSync('review.md', 'utf8'),
            })

Replace cluster.yaml with the path of your cluster definition and my-cluster with the cluster’s name.

Explain a failed deploy in Slack

After a merge, apply the cluster definition and wait for Ankra to accept it. If the apply fails, ask why and post the answer to Slack, so the channel gets a cause instead of a red cross.

set -euo pipefail

if ankra cluster apply -f cluster.yaml --wait --timeout 15m; then
  echo "Configuration applied"
else
  summary=$(ankra chat --cluster my-cluster --mode ask \
    "The last apply to this cluster failed. Give the root cause and the exact fix.")
  curl -sS -X POST "$SLACK_WEBHOOK_URL" \
    -H 'Content-Type: application/json' \
    -d "$(jq -n --arg text ":rotating_light: Deploy failed on my-cluster: $summary" '{text: $text}')"
  exit 1
fi

ankra cluster apply --wait exits with code 5 when --timeout expires, so you can treat a slow apply differently from a hard failure. --wait covers the configuration write only: add-on deploys are dispatched afterwards, so check them with ankra cluster operations list before calling a rollout healthy. The CLI’s other exit codes let a job treat 3 (not found) as success for idempotent steps and re-authenticate on 6.

Post a scheduled health check

Run every 30 minutes, stay silent while everything is healthy, and post to Slack only when something is degraded.

# .github/workflows/ankra-health.yml
name: Ankra health check
on:
  schedule:
    - cron: "*/30 * * * *"
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - run: bash <(curl -sL https://github.com/ankraio/ankra-cli/releases/latest/download/install.sh)
      - name: Check every cluster
        env:
          ANKRA_API_TOKEN: ${{ secrets.ANKRA_API_TOKEN }}
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
        run: |
          report=$(ankra chat --mode ask \
            "Check every cluster. Reply with the single word OK if all are healthy, \
             otherwise a short summary of what is degraded and why.")
          if [ "$(echo "$report" | tr -d '[:space:]')" != "OK" ]; then
            curl -sS -X POST "$SLACK_WEBHOOK_URL" -H 'Content-Type: application/json' \
              -d "$(jq -n --arg t ":warning: $report" '{text: $t}')"
          fi

Without --cluster, ankra chat answers across the whole organisation.

Parse the answer as JSON

With -o json (or -o yaml), ankra chat "<question>" prints one document on standard output when the turn ends, instead of streaming the answer. Status lines and notices go to standard error, so standard output is only the document. The health check above, with a parsed result:

set -uo pipefail

ankra chat --mode ask -o json \
  "Check every cluster. Reply with the single word OK if all are healthy, otherwise a short summary of what is degraded and why." \
  > result.json
status=$?

if [ ! -s result.json ]; then
  # The platform refused to start the turn (for example a rejected token): no document, the exit code says why.
  echo "ankra chat did not start (exit $status)" >&2
  exit "$status"
fi

answer=$(jq -r '.answer' result.json)
error=$(jq -r '.error // empty' result.json)
failed_tools=$(jq -r '[.tool_calls[] | select(.success == false) | .tool_name] | join(", ")' result.json)

if [ -n "$error" ]; then
  echo "The turn failed: $error" >&2
  exit 1
fi
if [ "$(echo "$answer" | tr -d '[:space:]')" != "OK" ]; then
  curl -sS -X POST "$SLACK_WEBHOOK_URL" -H 'Content-Type: application/json' \
    -d "$(jq -n --arg t ":warning: $answer" '{text: $t}')"
fi
[ -z "$failed_tools" ] || echo "Tools that failed during the check: $failed_tools" >&2

Field	Meaning
`answer`	The AI’s answer as text.
`error`	Present when the turn failed, was cancelled or expired. The command then exits non-zero after printing the document.
`conversation_id`, `continuable`	Pass the ID to `--conversation` to ask a follow-up, when `continuable` is `true`.
`session_id`	The chat session the platform opened.
`mode`	The safety mode the turn ran in: `ask`, `agent` or `plan`.
`cluster_id`, `cluster_name`	The cluster the turn was scoped to. `cluster_id` is `null` for an organisation-wide question.
`tool_calls`	The tools the AI ran, in order: `tool_name`, `tool_call_id`, `success`, `status`, `execution_time_ms`, and `error`, `error_class` and `error_code` when one failed. `success` is `null` for a call that did not finish, and for a proposed change, whose `status` is `pending_confirmation`.
`pending_actions`	Changes the AI proposed that have not run: `action_id`, `tool_name`, `description`, `parameters`, `risk_level`, `reversible`, `created_at`, `expires_in_seconds`.

A turn that starts and then fails still prints the document, with error set, and exits non-zero. When the platform refuses to start the turn, nothing is printed on standard output and the command exits with that error’s exit code (6 for a rejected token, 3 for an unknown cluster). -o works for a one-shot question only, not for interactive chat.

GitLab CI and other runners

The commands are the same in any CI. In GitLab CI, run the review job on rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" and diff against $CI_MERGE_REQUEST_DIFF_BASE_SHA, and run the health check from a scheduled pipeline with rules: - if: $CI_PIPELINE_SOURCE == "schedule".

Keep CI jobs read-only

The review and health check jobs only read. Give them a service token with the viewer role, which includes ask-mode AI. Token --scopes only choose MCP access (mcp:read, mcp:write), so the role is what limits a CLI token.
Only the deploy job writes. Give it a separate service token with a role that can deploy Stacks, such as member.
Run ankra chat with --mode ask: ask mode investigates and may make safe creations, but does not change what is already running. Never pass --mode agent in CI; make changes through ankra cluster apply and your GitOps repository.

Ankra CLI - installing and configuring the CLI
ankra chat reference and ankra cluster apply reference - every flag
Service Tokens - organisation-owned tokens for CI

Get Started

Concepts

Create and Run Clusters

Ship Your App

Stacks and Add-ons

Observe and Troubleshoot

Ankra AI

Connect Tools

Source Control

Security and Access

Cost and Backups

Organisation and Account

Reference

Use the ankra CLI in CI

Prerequisites

Comment a review of a cluster change on the pull request

Explain a failed deploy in Slack

Post a scheduled health check

Parse the answer as JSON

GitLab CI and other runners

Keep CI jobs read-only

​Prerequisites

​Comment a review of a cluster change on the pull request

​Explain a failed deploy in Slack

​Post a scheduled health check

​Parse the answer as JSON

​GitLab CI and other runners

​Keep CI jobs read-only

​Related

Prerequisites

Comment a review of a cluster change on the pull request

Explain a failed deploy in Slack

Post a scheduled health check

Parse the answer as JSON

GitLab CI and other runners

Keep CI jobs read-only

Related