Skip to content

Slack Reporter

Overview

The Slack Reporter posts validation results to a Slack channel via an Incoming Webhook. It uses Slack's Block Kit format to produce a structured, readable message with a status header, severity summary, and individual finding details.

Up to 10 findings are shown in the message. When there are more than 10, a context block notes how many additional findings were omitted.

How it works

The Slack reporter composes two modules:

  • SlackFormatModule - renders findings as a Slack Block Kit JSON payload
  • SlackOutputModule - POSTs the payload to the configured Incoming Webhook URL

Configuration

YAML

reporters:
  slack:
    webhook: "${SLACK_WEBHOOK_URL}"

With Channel Override

reporters:
  slack:
    webhook: "${SLACK_WEBHOOK_URL}"
    channel: "#mr-validation"

JSON

{
  "reporters": {
    "slack": {
      "webhook": "${SLACK_WEBHOOK_URL}",
      "channel": "#mr-validation"
    }
  }
}

Options

Option Type Required Default Description
webhook string Yes - Slack Incoming Webhook URL (must start with https://hooks.slack.com/; a loopback URL is also accepted under allow-localhost)
channel string No Webhook default Target Slack channel (e.g. #builds). Overrides the webhook's default channel
token string No - Bot token (xoxb-…). Switches to bot mode (below); webhook is then not needed
when string No changed Which runs deliver: always, changed (the verdict or the set of findings differs from the last platform summary comment; a run without a platform counts as changed), failed, never

Bot Token Mode

With a webhook every run posts a new message. With a bot token the reporter posts once per MR and updates that message on later runs, so the channel keeps one message per MR that always shows the latest verdict:

reporters:
  slack:
    token: "${SLACK_BOT_TOKEN}"
    channel: C0123456789
    when: changed
  • The first run calls chat.postMessage with message metadata naming the MR; a later run for the same MR finds that message in conversations.history (the newest 200 messages) and calls chat.update.
  • A run without an MR (a local run) always posts a new message.
  • The bot needs the chat:write and channels:history scopes (groups:history for a private channel) and must be a member of the channel. channel is required and should be a channel ID.
  • when decides whether the run delivers at all, as in webhook mode.
  • The token goes only into the Authorization header and never into a log. A failed lookup logs a warning and posts a new message; a failed post or update follows onError.

Setting Up a Slack Webhook

  1. Go to https://api.slack.com/apps and create a new app (or use an existing one)
  2. Navigate to Incoming Webhooks and activate them
  3. Click Add New Webhook to Workspace
  4. Select the channel and authorize
  5. Copy the webhook URL (starts with https://hooks.slack.com/services/...)
  6. Store the URL as a CI/CD secret and reference it via ${SLACK_WEBHOOK_URL}

Message Format

The reporter sends a Block Kit message with the following structure:

Header block: Karandash Validation: ✅ PASSED or Karandash Validation: ❌ FAILED

Summary section: - When all pass: All validation checks passed! 🎉 - When findings exist: *Errors:* 2 | *Warnings:* 1 | *Info:* 0

Finding sections (up to 10):

❌ *title-format*
MR title does not match required pattern: ^(feat|fix): .+
How to fix: Use a conventional commit prefix

The labelled Where:, How to fix: and Format: lines follow the message when the finding carries them.

Overflow context (when >10 findings):

... and 5 more findings

Footer context: Generated by karandash at {unix timestamp}

Examples

Notify on Failure Only

Use a CI/CD conditional to run Karandash and send Slack notifications only when validation fails:

# .karandash/config.yaml
reporters:
  console: true
  slack:
    webhook: "${SLACK_WEBHOOK_URL}"
    channel: "#ci-alerts"

GitLab CI with Slack

# .gitlab-ci.yml
karandash:
  stage: test
  rules:
    - if: $CI_MERGE_REQUEST_IID
  script:
    - karandash validate
  variables:
    GITLAB_TOKEN: $CI_JOB_TOKEN
    SLACK_WEBHOOK_URL: $SLACK_WEBHOOK

Notes

  • The webhook URL is validated to start with https://hooks.slack.com/. An IllegalArgumentException is thrown for invalid URLs.
  • When the run sets allow-localhost: true (or --allow-localhost), a loopback http:// or https:// URL (localhost, 127.0.0.0/8, ::1) is accepted too - for a local relay or an offline test double. Private and other non-Slack hosts are still rejected; without allow-localhost only https://hooks.slack.com/ is accepted.
  • If the HTTP POST to Slack fails, a warning is logged but the validation exit code is not affected.
  • The channel option overrides the webhook's default channel. If omitted, messages go to the channel configured when the webhook was created.
  • The reporter uses the shared ProviderHttpClientFactory HTTP client with a 30-second timeout.
  • Email - Send results via SMTP email
  • Webhook - HTTP POST to any endpoint
  • Markdown - Post results as an MR comment