Skip to content

Commit a61a717

Browse files
sherine-ksherine-k
committed
Add task notify-matrix
This PR adds a new task, `notify-matrix` which sends messages to a [Matrix](https://matrix.org/) room on its corresponding endpoint.
1 parent df36b38 commit a61a717

File tree

5 files changed

+127
-0
lines changed

5 files changed

+127
-0
lines changed

‎task/notify-matrix/0.1/README.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# `notify-matrix`
2+
3+
The `notify-marix` `Task` sends messages to a [Matrix](https://matrix.org/) room on its corresponding endpoint.
4+
5+
## Parameters
6+
7+
This `Task` has the following required inputs:
8+
9+
1. **`matrix-secret`**: the name of a secret, containing a valid matrix access token (see below)
10+
2. **`room`**: the matrix roomID where the notification will be sent, in the format `#ROOM_NAME:SERVER_NAME`
11+
3. **`endpoint`**: URI of the matrix server to connect and send the message from
12+
4. **`message`**: the message to be sent
13+
14+
## Setting up the `matrix-secret`
15+
16+
In order for the task to be able to send a message to the selected matrix room, make sure you create a secret, of type generic. It should contain a key `token`, containing the access token to the matrix endpoint.
17+
18+
Ex:
19+
```yaml
20+
kind: Secret
21+
apiVersion: v1
22+
metadata:
23+
name: matrix-access-token
24+
stringData:
25+
token: {OAuth token for the user/bot with access to the room}
26+
```
27+
28+
### Obtaining a Matrix `access_token`
29+
30+
First, create a Matrix user with one of the Matrix servers.
31+
32+
Once the registration process is done, start by setting the 3 following variables:
33+
* `MATRIX_USER`: username you just registered with
34+
* `PASSWORD`: corresponding password
35+
* `MATRIX_ENDPOINT`: Matrix server on which you registered the user
36+
37+
Then, you can get the `access_token` through a simple login API call:
38+
```bash=
39+
curl -XPOST -d "{\"type\":\"m.login.password\", \"user\":\"$MATRIX_USER\", \"password\":\"$PASSWORD\"}" "https://$MATRIX_ENDPOINT/_matrix/client/r0/login"
40+
{"user_id":"@my.user:matrix.endpoint","access_token":"syt_c2hlcmluZS5raG91cnk_NFpzzGCtxFAHEDVKhYTl_123456","home_server":"matrix.endpoint","device_id":"CNYGHLSLQY","well_known":{"m.homeserver":{"base_url":"https://matrix-client.matrix.org/"}}}
41+
```
42+
43+
With the `access_token` in the output, you can create the secret of type generic with a single key, `token`, containing the `access_token` you just obtained above.
44+
45+
## Platforms
46+
47+
The Task can be run on `linux/amd64`, `linux/s390x`, `linux/386`, and `linux/ppc64le` platforms.
48+
49+
## Usage
50+
51+
[This TaskRun](./samples/notify-matrix-run.yaml) demonstrate usage of the notify-matrix Task.
52+

‎task/notify-matrix/0.1/notify-matrix.yaml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
apiVersion: tekton.dev/v1beta1
2+
kind: Task
3+
metadata:
4+
name: notify-matrix
5+
labels:
6+
app.kubernetes.io/version: "0.1"
7+
annotations:
8+
tekton.dev/pipelines.minVersion: "0.12.1"
9+
tekton.dev/categories: Messaging
10+
tekton.dev/tags: messaging
11+
tekton.dev/platforms: "linux/386,linux/amd64,linux/s390x,linux/ppc64le"
12+
tekton.dev/displayName: "Notify Matrix Room"
13+
spec:
14+
description: >-
15+
These tasks post a simple message to a matrix room.
16+
This task uses Matrix's Client-Server REST api to send the message.
17+
params:
18+
- name: matrix-secret
19+
type: string
20+
description: secret name containing matrix access token (key is token)
21+
- name: room
22+
type: string
23+
description: room id (in the format !<ROOM_ID>:<SERVER_NAME>)
24+
- name: endpoint
25+
type: string
26+
description: Matrix server URL to which to send the message
27+
- name: message
28+
type: string
29+
description: plain text message
30+
steps:
31+
- name: post
32+
image: docker.io/curlimages/curl:7.70.0@sha256:031df77a11e5edded840bc761a845eab6e3c2edee22669fb8ad6d59484b6a1c4 #tag: 7.70.0
33+
script: |
34+
#!/usr/bin/env bash
35+
if [[ -z "$(params.room)" || -z "$(params.endpoint)" ]]; then
36+
echo "No Matrix parameters found - no notification sent"
37+
else
38+
/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"
39+
fi
40+
env:
41+
- name: TOKEN
42+
valueFrom:
43+
secretKeyRef:
44+
name: $(params.matrix-secret)
45+
key: token

‎task/notify-matrix/0.1/samples/matrix-access-token.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
kind: Secret
2+
apiVersion: v1
3+
metadata:
4+
name: matrix-access-token
5+
stringData:
6+
token: {OAuth token for the bot app}

‎task/notify-matrix/0.1/samples/notify-matrix-run.yaml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
apiVersion: tekton.dev/v1beta1
2+
kind: TaskRun
3+
metadata:
4+
name: notify-matrix-run
5+
spec:
6+
params:
7+
- name: matrix-secret
8+
value: matrix-access-token
9+
- name: room
10+
value: "!yKXXPqFwfCOTipZMxp:matrix.org"
11+
- name: endpoint
12+
value: matrix.org
13+
- name: message
14+
value: hello
15+
resources: {}
16+
serviceAccountName: default
17+
taskRef:
18+
kind: Task
19+
name: notify-matrix
20+
timeout: 1h0m0s

‎task/notify-matrix/OWNERS‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
approvers:
2+
- sherine-k
3+
reviewers:
4+
- sherine-k

0 commit comments

Comments
 (0)