diff --git a/task/notify-matrix/0.1/README.md b/task/notify-matrix/0.1/README.md new file mode 100644 index 0000000000..8c2209ffa6 --- /dev/null +++ b/task/notify-matrix/0.1/README.md @@ -0,0 +1,52 @@ +# `notify-matrix` + +The `notify-marix` `Task` sends messages to a [Matrix](https://matrix.org/) room on its corresponding endpoint. + +## Parameters + +This `Task` has the following required inputs: + +1. **`matrix-secret`**: the name of a secret, containing a valid matrix access token (see below) +2. **`room`**: the matrix roomID where the notification will be sent, in the format `#ROOM_NAME:SERVER_NAME` +3. **`endpoint`**: URI of the matrix server to connect and send the message from +4. **`message`**: the message to be sent + +## Setting up the `matrix-secret` + +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. + +Ex: +```yaml +kind: Secret +apiVersion: v1 +metadata: + name: matrix-access-token +stringData: + token: {OAuth token for the user/bot with access to the room} +``` + +### Obtaining a Matrix `access_token` + +First, create a Matrix user with one of the Matrix servers. + +Once the registration process is done, start by setting the 3 following variables: +* `MATRIX_USER`: username you just registered with +* `PASSWORD`: corresponding password +* `MATRIX_ENDPOINT`: Matrix server on which you registered the user + +Then, you can get the `access_token` through a simple login API call: +```bash= +curl -XPOST -d "{\"type\":\"m.login.password\", \"user\":\"$MATRIX_USER\", \"password\":\"$PASSWORD\"}" "https://$MATRIX_ENDPOINT/_matrix/client/r0/login" +{"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/"}}} +``` + +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. + +## Platforms + +The Task can be run on `linux/amd64`, `linux/s390x`, `linux/386`, and `linux/ppc64le` platforms. + +## Usage + +[This TaskRun](./samples/notify-matrix-run.yaml) demonstrate usage of the notify-matrix Task. + diff --git a/task/notify-matrix/0.1/notify-matrix.yaml b/task/notify-matrix/0.1/notify-matrix.yaml new file mode 100644 index 0000000000..dc750e4d30 --- /dev/null +++ b/task/notify-matrix/0.1/notify-matrix.yaml @@ -0,0 +1,45 @@ +apiVersion: tekton.dev/v1beta1 +kind: Task +metadata: + name: notify-matrix + 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/386,linux/amd64,linux/s390x,linux/ppc64le" + tekton.dev/displayName: "Notify Matrix Room" +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-secret + type: string + description: secret name containing matrix access token (key is token) + - name: room + type: string + description: room id (in the format !:) + - 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: | + #!/usr/bin/env bash + if [[ -z "$(params.room)" || -z "$(params.endpoint)" ]]; then + echo "No Matrix parameters found - no notification sent" + else + /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" + fi + env: + - name: TOKEN + valueFrom: + secretKeyRef: + name: $(params.matrix-secret) + key: token \ No newline at end of file diff --git a/task/notify-matrix/0.1/samples/matrix-access-token.yaml b/task/notify-matrix/0.1/samples/matrix-access-token.yaml new file mode 100644 index 0000000000..92392d0d37 --- /dev/null +++ b/task/notify-matrix/0.1/samples/matrix-access-token.yaml @@ -0,0 +1,6 @@ +kind: Secret +apiVersion: v1 +metadata: + name: matrix-access-token +stringData: + token: {OAuth token for the bot app} \ No newline at end of file diff --git a/task/notify-matrix/0.1/samples/notify-matrix-run.yaml b/task/notify-matrix/0.1/samples/notify-matrix-run.yaml new file mode 100644 index 0000000000..9231fe74f9 --- /dev/null +++ b/task/notify-matrix/0.1/samples/notify-matrix-run.yaml @@ -0,0 +1,20 @@ +apiVersion: tekton.dev/v1beta1 +kind: TaskRun +metadata: + name: notify-matrix-run +spec: + params: + - name: matrix-secret + value: matrix-access-token + - name: room + value: "!yKXXPqFwfCOTipZMxp:matrix.org" + - name: endpoint + value: matrix.org + - name: message + value: hello + resources: {} + serviceAccountName: default + taskRef: + kind: Task + name: notify-matrix + timeout: 1h0m0s \ No newline at end of file diff --git a/task/notify-matrix/OWNERS b/task/notify-matrix/OWNERS new file mode 100644 index 0000000000..ea88253caf --- /dev/null +++ b/task/notify-matrix/OWNERS @@ -0,0 +1,4 @@ +approvers: +- sherine-k +reviewers: +- sherine-k \ No newline at end of file