Matrix provides an "open network for secure, decentralised communication". With Matrix bridges, you can connect to Slack, IRC, Teams, Discord, you name it!
This blog post explains how to interconnect a Tekton pipeline with a Matrix room, for the purpose of notifying the room members of the pipeline status.
Matrix API
Matrix provides several APIs, Client-Server API is one of them.
In order to be able to send messages to a matrix room, the Tekton pipeline needs to send an access_token along with the request to the Matrix server.
Thus, a prerequisite to this task is to register a Matrix user for the bot with one of the Matrix servers.
Obtaining a Matrix access_token
Once the registration process is done, I obtained the access_token through a simple login API call:
curl -XPOST -d '{"type":"m.login.password", "user":"sherine.khoury", "password":"take_a_wild_guess"}' "https://matrix.org/_matrix/client/r0/login"
{"user_id":"@sherine.khoury:matrix.org","access_token":"syt_c2hlcmluZS5raG91cnk_NFpzzGCtxFAHEDVKhYTl_123456","home_server":"matrix.org","device_id":"CNYGHLSLQY","well_known":{"m.homeserver":{"base_url":"https://matrix-client.matrix.org/"}}}
With the access_token, I created a secret, with name matrix-access-token in the namespace hosting my pipeline, of type generic with a single key, token, containing the access_token I just obtained in the step above.
Example
kind: Secret
apiVersion: v1
metadata:
name: matrix-access-token
stringData:
token: {OAuth token for the bot app}
Obtaining the Matrix Room ID
The hardest for me was to create a room with Matrix. I'm pretty new to Matrix 😛, and it seems every server has different rules when it comes to the request body of POST /_matrix/client/v3/createRoom.
Similarly, every Matrix client calls the room differently: On FluffyChat, it's a Group, which can be created after creating a space. In Element, it's simply called a room!! Thankfully.
When you create a room in Element, the web UI provides the room ID back to you.
But you still need to set a Local address for the room in the Room Settings in order to be able to query the roomAlias by API. 🤷
The room alias usually is #ROOM_NAME:SERVER_NAME.
So for a room with name my-team on matrix.org, you can also obtain the RoomID by sending the following request to the client-server API:
curl -v https://matrix.org/_matrix/client/v3/directory/room/%23my-room:matrix.org
{"room_id":"!xWldUqOaDUkrHUZRIP:matrix.org","servers":["matrix.org"]}
Notice there is no need for authentication here. Notice also the %23 replacing the # character in the room alias.
Tekton Task
Largely inspired from the Slack task on TektonHub:
apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
name: send-to-matrix-room
labels:
app.kubernetes.io/version: "0.1"
annotations:
tekton.dev/pipelines.minVersion: "0.12.1"
tekton.dev/categories: Messaging
tekton.dev/tags: messaging
tekton.dev/platforms: "linux/amd64,linux/s390x,linux/ppc64le"
spec:
description: >-
These tasks post a simple message to a matrix room.
This task uses Matrix's Client-Server REST api to send the message.
params:
- name: matrix-access-token
type: string
description: secret name containing matrix access token (key is token)
- name: room
type: string
description: room id (in the format !<ROOM_ID>:<SERVER_NAME>)
- name: endpoint
type: string
description: Matrix server URL to which to send the message
- name: message
type: string
description: plain text message
steps:
- name: post
image: docker.io/curlimages/curl:7.70.0@sha256:031df77a11e5edded840bc761a845eab6e3c2edee22669fb8ad6d59484b6a1c4 #tag: 7.70.0
script: |
#!/bin/sh
/usr/bin/curl -X POST -H 'Content-type: application/json' --data '{"msgtype":"m.text", "body":"$(params.message)"}' https://$(params.endpoint)/_matrix/client/r0/rooms/$(params.room)/send/m.room.message?access_token=$TOKEN
env:
- name: TOKEN
valueFrom:
secretKeyRef:
name: $(params.matrix-access-token)
key: token
💡 It could be an idea to replace
roomandendpointby the room alias.
Instead of having a single step I could have used:
- Use
cut -d\: -f2, I could retrieve the endpoint- Curl the
/_matrix/client/v3/directory/roomto retrieve the RoomID- Send the message using the RoomID and Endpoint
💡 If this looks good, I could send a PR to the TektonHub.
Tekton example pipeline
Now that I've got a task, I can use that task in a pipeline, like so:
apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
name: pipeline-matrix-hello
namespace: okd-team
spec:
params:
- name: matrix-room
description: room id (in the format !<ROOM_ID>:<SERVER_NAME>)
type: string
- name: matrix-endpoint
description: room id (in the format !<ROOM_ID>:<SERVER_NAME>)
type: string
- name: repo-name
description: The repo name
type: string
- name: bundle-version
description: The bundle version
type: string
tasks:
- name: talk-to-matrix
params:
- name: matrix-access-token
value: matrix-access-token
- name: endpoint
value: $(params.matrix-endpoint)
- name: room
value: $(params.matrix-room)
- name: message
value: Going to run operator pipeline on repo $(params.repo-name) to build $(params.bundle-version)
taskRef:
kind: Task
name: send-to-matrix-room
Finally, start the pipeline using
tkn pipeline start pipeline-matrix-hello --param repo-name=node-observability-operator --param bundle-version=v1.1.1 --param matrix-endpoint=matrix.org --param matrix-room=\!yKXXPqFwfCOTipZMxp:matrix.org
The logs of the pipelinerun show:
tkn pipelinerun logs pipeline-matrix-hello-run-hscx9 -f -n okd-team
[talk-to-matrix : post] % Total % Received % Xferd Average Speed Time Time Time Current
[talk-to-matrix : post] Dload Upload Total Spent Left Speed
100 172 0 59 100 113 114 219 --:--:-- --:--:-- --:--:-- 334
[talk-to-matrix : post] {"event_id":"$EYhJ9A5DlMlBx8xD4ORF9q-8r1KmLTsvODvCgwu5xkU"}