drone-slack Docker镜像文档

镜像概述与主要用途

drone-slack 是 Drone CI/CD 系统的官方 Slack 通知插件，用于将 CI/CD 流水线的构建事件（如构建开始、成功、失败等）实时通知发送至 Slack 频道。该镜像作为 Drone 生态的一部分，旨在通过集成 Slack 实现构建状态的可视化与团队协作，帮助开发、测试及运维团队快速响应流水线异常，提升协作效率。

核心功能与特性

• 构建状态通知：支持发送构建成功、失败、开始、取消等状态的通知至指定 Slack 频道。
• 自定义消息内容：允许通过模板或配置自定义通知消息的标题、正文、格式（支持 Slack 附件格式）。
• 事件触发控制：可配置触发通知的事件条件（如仅失败时通知、始终通知、仅特定分支通知等）。
• 构建元数据集成：自动包含构建相关信息，如分支名称、提交 SHA、构建链接、作者信息、提交消息等。
• Slack 原生支持：兼容 Slack Incoming Webhook，支持自定义通知用户名、头像，以及@提及指定用户/角色。

使用场景与适用范围

• 开发团队：实时获取代码提交后的构建状态，快速定位构建失败原因。
• 测试团队：跟踪自动化测试结果，及时发现测试用例失败。
• 运维团队：监控部署流水线状态，确保生产环境部署流程正常。
• 项目管理：通过构建通知掌握团队开发进度，协调资源分配。
• 自动化流程监控：作为 CI/CD 流水线的可视化节点，监控自动化流程健康状态。

详细使用方法与配置说明

前置条件

1. 已部署 Drone CI/CD 系统（Server 与 Runner）。
2. 已在 Slack 中创建 Incoming Webhook（需 Slack workspace 管理员权限，创建路径：Slack 应用 > 自定义集成 > Incoming Webhooks）。

1. 在 Drone Pipeline 中使用

drone-slack 作为 Drone 插件，需在项目的 .drone.yml 配置文件中定义为流水线步骤（step）。以下为基础配置示例：

kind: pipeline
type: docker
name: default

steps:
  - name: slack-notify
    image: plugins/slack
    settings:
      webhook: [***]  # Slack Incoming Webhook URL（必填）
      channel: #dev-team  # 目标 Slack 频道（必填，如 #ci-notifications）
      event: [success, failure]  # 触发通知的事件（可选，默认 [failure]）
      status: [success, failure]  # 构建状态（可选，与 event 配合使用）
      username: Drone CI  # Slack 通知显示的用户名（可选，默认 "Drone"）
      icon_url: [***]  # 通知头像 URL（可选）
      message: "构建 {{ build.status }}: {{ repo.name }}#{{ build.number }} ({{ commit.branch }})"  # 自定义消息（可选，支持变量替换）
      template: |  # 消息模板（可选，支持 Markdown 与 Slack 附件格式）
        [{{ repo.name }}] {{ build.status }} ({{ commit.branch }})  
        提交作者: {{ commit.author }}  
        提交信息: {{ commi***ssage }}  
        构建链接: {{ build.link }}

2. 环境变量配置

Drone 插件会将 .drone.yml 中 settings 下的配置项自动映射为环境变量（前缀 PLUGIN_）。若需手动运行容器（如本地测试），可通过 -e 参数传入环境变量：

3. 变量替换支持

消息模板（message 或 template）中可使用以下 Drone 内置变量（通过 Drone Runner 自动注入）：

部署示例

示例 1：Drone Pipeline 完整配置（.drone.yml）

kind: pipeline
type: docker
name: ci-pipeline

steps:
  - name: test
    image: golang:1.21
    commands:
      - go mod download
      - go test -v ./...

  - name: slack-notify
    image: plugins/slack
    settings:
      webhook:
        from_secret: slack_webhook  # 从 Drone Secret 中读取 Webhook（推荐，避免硬编码）
      channel: #ci-alerts
      event: [failure, success]
      username: Drone CI Bot
      icon_url: [***]
      template: |
        🚀 [{{ repo.name }}] {{ build.status | upper }} ({{ repo.branch }})  
        • 提交: {{ commit.sha }} ({{ commit.author }})  
        • 消息: {{ commi***ssage }}  
        • 详情: {{ build.link }}
    when:
      branch:
        - main  # 仅 main 分支触发通知

注意：webhook 建议通过 Drone Secret 管理（在 Drone 控制台为项目添加 slack_webhook 密钥），避免明文暴露。

示例 2：本地测试（docker run 命令）

模拟 Drone 环境变量，手动发送测试通知：

docker run --rm \
  -e PLUGIN_WEBHOOK=[***] \
  -e PLUGIN_CHANNEL=#test-notifications \
  -e PLUGIN_EVENT=always \
  -e PLUGIN_MESSAGE="测试通知：构建成功 🎉" \
  -e DRONE_BUILD_STATUS=success \
  -e DRONE_REPO_NAME=my-project \
  -e DRONE_BUILD_LINK=[***] \
  plugins/slack

运行后，目标 Slack 频道将收到一条测试通知。

常见问题

• 通知未发送：检查 webhook 是否有效（可通过 Slack 提供的测试按钮验证）、Drone Runner 是否有权限访问互联网（Slack Webhook 需外网访问）。
• 消息格式异常：Slack 附件格式需符合 Slack API 规范，避免使用不支持的 Markdown 语法。
• 事件触发不生效：确认 .drone.yml 中 when 条件与 event 配置是否冲突（如 when:branch: [dev] 与 event: [success] 需同时满足）。

参考链接

• Drone 官方文档
• Slack Incoming Webhooks 配置指南
• drone-slack GitHub 仓库（获取最新版本与更新日志）