钉钉机器人接入GitLab CI/CD,大多数人第一次动手时,卡住的不是发请求,而是接缝处的细节:签名怎么算、状态变量什么时候才有值、消息发出去为什么群里收不到。下面按排查顺序整理一遍,先把风险说清楚。
先别急着配流水线,把机器人创建和安全设置定下来
在配置流水线之前,需要先在钉钉群中添加一个自定义机器人。进入群设置,选择智能群助手,点击添加机器人,再选择自定义。这里有两个关键选项:安全设置推荐使用加签方式,它会生成一个密钥;也可以选择自定义关键词,例如设置“流水线”作为触发词,但这种方式容易误报。创建完成后会得到一个Webhook地址,形如https://oapi.dingtalk.com/robot/send?access_token=xxxx。如果使用加签,调用时需要在请求参数中额外携带timestamp和sign,具体算法是把密钥拼在时间戳后面做HMAC-SHA256,再把结果做Base64编码。建议将Webhook地址和密钥存入GitLab CI/CD的变量中,不要明文写进仓库。
创建机器人时,最影响后续调试的是安全设置。关键词方式虽然可以绕过签名计算,但如果你在消息正文里没写全关键词,或者关键词被拆分,请求会被钉钉拒绝。加签方式没有这种限制,只是每次调用前需要先算签名,而且timestamp与服务器时间差超过一定范围也会失败。选定方式后,把Webhook和密钥存到GitLab项目的Settings -> CI/CD -> Variables里,命名时区分好,比如DINGTALK_WEBHOOK和DINGTALK_SECRET,后面所有job都从环境变量读取。
发送逻辑单独抽成脚本,别堆在yaml里
通知发送本身是“有副作用”的步骤,不太适合直接写进编译job。因为只要编译job里多几行curl,后续改动消息格式时就得重新触发流水线,而且本地也无法单独验证。更常见的做法是放一个notify.sh,放在项目仓库的scripts目录下,接收三个参数:Webhook地址、消息内容、加签密钥(如果启用)。脚本内部用curl发起POST请求,请求头Content-Type设为application/json,请求体里至少包含msgtype和text两个字段。如果启用了加签,还要先计算签名,把timestamp和sign拼到请求URL上。这个脚本的作用是把流水线的状态、分支、提交人等信息格式化成一条JSON消息,再传给钉钉机器人。脚本本身不负责触发条件,只负责发送,这样的好处是可以单独测试。
脚本里的消息体最好用markdown类型,而不是纯text。因为markdown可以呈现标题、粗体、链接,群内可读性好很多。钉钉的markdown对图片外链有域名白名单限制,普通链接不受影响。
通知job放在流水线最后,用when: always保证失败也能发
在.gitlab-ci.yml中,可以通过after_script或一个小job来发送通知。例如,定义一个名为notify的stage,放在流水线最后,并且设置when: always,这样无论前序job成功还是失败都会执行。由于通知逻辑通常不依赖编译环境,可以直接使用镜像ruby:2.7或alpine,避免占用构建资源。在job的script里,先加载项目根目录的notify.sh,再传入环境变量。GitLab自动预置了CI_JOB_STATUS、CI_PROJECT_NAME、CI_COMMIT_REF_NAME等变量,可以直接用来构造消息。要注意的是,notify脚本最好放到一个公用位置,如果复制到每个项目,后续改接口格式时需要同步修改所有仓库。
需要理解一个容易混淆的点:独立通知job里的CI_JOB_STATUS,指向的是这个通知job本身的状态,而不是整个流水线的状态。由于通知job几乎总是成功,所以不能用它来判断“构建是否通过”。建议在通知job里使用CI_PIPELINE_STATUS(如果GitLab版本支持),或者把关键job的结果通过 artifacts 或变量汇总后再传入消息。如果你使用after_script,那读取的是当前job的状态,适合在单个job内部发通知,但无法覆盖整个流水线。两种方式可以结合,但不要混用同一个变量。
消息按状态区分,但不要把整个日志塞进去
为了让通知更可读,消息内容最好根据状态区分。可以在脚本中读取预先传入的状态变量,是success还是failed。成功时消息可以写“构建通过”,失败时写“构建失败,请检查日志”。消息正文建议用Markdown格式,钉钉机器人支持markdown类型的消息,在msgtype里指定markdown,然后text字段里写Markdown内容。注意钉钉的markdown对图片外链有域名白名单限制,普通链接可以正常点击。另外,消息内容不要包含整个日志,日志量太大容易被截断或触发风控,建议只给出流水线URL和简短错误概括。URL可以通过CI_PIPELINE_URL变量获取,拼上“查看流水线详情”的文字。
如果觉得每个项目写一套模板太散,可以把模板也放到公共脚本里,使用环境变量传入项目名、分支和提交人。模板里统一写“项目:xxx,分支:xxx,状态:xxx,链接:xxx”,这样团队看消息时能快速定位。
本地先用curl试通,再挂到流水线上
第一次接入时,最容易踩的坑是签名计算错误,导致返回errcode为310000,提示签名不匹配。可以先在本地用curl构造一个最小请求,不带任何业务信息,只发一条“测试消息”,把Webhook地址和签名正确传入,确认能收到后再套进流水线。另一个常见问题是CI_JOB_STATUS的使用时机:它只在job执行结束后才可用,在script开头为空,所以需要放在after_script里读取。如果发现请求成功但群内无消息,检查机器人是否被移除,或者群是否解散。还需要注意消息发送频率,流水线频繁触发时,短时间内发送大量相同内容容易触发钉钉限流,建议在脚本中加入简单的去重逻辑,比如比较最近一次的消息内容,相同则不重复发送。
本地测试时,最简单的命令长这样(注意把TOKEN和SECRET替换成自己的):
timestamp=$(date +%s%3N)
sign=$(printf "%s" "$timestamp$SECRET" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)
curl -X POST "https://oapi.dingtalk.com/robot/send?access_token=$TOKEN×tamp=$timestamp&sign=$sign" \
-H "Content-Type: application/json" \
-d '{"msgtype":"markdown","markdown":{"title":"测试","text":"### 测试消息\n来自本地curl"}}'如果返回的JSON中errcode为0,说明链路通了。再把同样的逻辑套进notify.sh,让脚本处理变量和JSON转义,避免在yaml里写一长串curl。
上线后看这几个信号,判断接入是否正常
通知job合入主分支后,手动触发一次成功构建和一次故意失败构建。观察三个信号:钉钉群是否在流水线结束后几秒内收到消息;消息里的分支、commit链接是否正确;失败构建是否也收到了消息。如果失败时没有消息,优先检查when: always是否写在了通知job上,以及该job是否被rules条件跳过。
如果一切正常,可以再跑几次并注意限流。短期内推送大量相同内容时,钉钉会在一段时间内拒绝新的请求。在脚本里加一个简单的去重,记录最近一次消息内容,如果相同就直接退出,这个逻辑通常放在发送前,比发送后再判断更省资源。注意去重逻辑不要误伤真正需要重复提醒的场景,比如每次构建失败都要提醒,那可以去重但不丢弃超过一定间隔的消息。
如果后续要更换Webhook地址或密钥,记得先改GitLab变量,再触发一次测试。旧地址被删除后,之前的调用会得到无效的access_token或机器人已停用提示,所以切换时要确保所有相关job都能读到新变量,避免出现一部分job还在用旧值。