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 payloadSlackOutputModule- 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.postMessagewith message metadata naming the MR; a later run for the same MR finds that message inconversations.history(the newest 200 messages) and callschat.update. - A run without an MR (a local run) always posts a new message.
- The bot needs the
chat:writeandchannels:historyscopes (groups:historyfor a private channel) and must be a member of the channel.channelis required and should be a channel ID. whendecides whether the run delivers at all, as in webhook mode.- The token goes only into the
Authorizationheader and never into a log. A failed lookup logs a warning and posts a new message; a failed post or update followsonError.
Setting Up a Slack Webhook
- Go to https://api.slack.com/apps and create a new app (or use an existing one)
- Navigate to Incoming Webhooks and activate them
- Click Add New Webhook to Workspace
- Select the channel and authorize
- Copy the webhook URL (starts with
https://hooks.slack.com/services/...) - 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/. AnIllegalArgumentExceptionis thrown for invalid URLs. - When the run sets
allow-localhost: true(or--allow-localhost), a loopbackhttp://orhttps://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; withoutallow-localhostonlyhttps://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
channeloption overrides the webhook's default channel. If omitted, messages go to the channel configured when the webhook was created. - The reporter uses the shared
ProviderHttpClientFactoryHTTP client with a 30-second timeout.