150 lines
5.8 KiB
Markdown
150 lines
5.8 KiB
Markdown
# drone-matrixchat-notify
|
|
|
|
[](https://github.com/SpotlightKid/drone-matrixchat-notify/blob/master/LICENSE)
|
|
[](https://github.com/SpotlightKid/drone-matrixchat-notify/tags)
|
|
[](https://hub.docker.com/r/spotlightkid/drone-matrixchat-notify)
|
|
[](https://github.com/SpotlightKid/drone-matrixchat-notify)
|
|
[](https://gitlab.com/SpotlightKid/drone-matrixchat-notify)
|
|
[](https://github.com/SpotlightKid/drone-matrixchat-notify/issues)
|
|
|
|
A [drone.io] [plugin] to send notifications to Matrix chat rooms from CI
|
|
pipeline steps. Supports *Jinja* message templates and *Markdown* rendering.
|
|
|
|
Example pipeline configuration:
|
|
|
|
```yaml
|
|
kind: pipeline
|
|
type: docker
|
|
name: default
|
|
|
|
steps:
|
|
- name: build
|
|
image: alpine
|
|
commands:
|
|
- ./build
|
|
|
|
- name: notify
|
|
image: spotlightkid/drone-matrixchat-notify
|
|
settings:
|
|
homeserver: 'https://matrix.org'
|
|
roomid: '!xxxxxx@matrix.org'
|
|
userid: '@drone-bot@matrix.org'
|
|
password:
|
|
from_secret: drone-bot-pw
|
|
markdown: 'yes'
|
|
template: |
|
|
`${DRONE_REPO}` build #${DRONE_BUILD_NUMBER} status: **${DRONE_BUILD_STATUS}**
|
|
|
|
${DRONE_PULL_REQUEST_TITLE}](${DRONE_COMMIT_LINK})
|
|
```
|
|
|
|
## Configuration settings
|
|
|
|
### Required
|
|
|
|
* `roomid` *(required)*
|
|
|
|
ID of matrix chat room to send messages to (ID, not alias).
|
|
|
|
* `userid` *(required)*
|
|
|
|
Matrix user ID on homeserver to send message as (ID, not username).
|
|
|
|
* `password` *(required)*
|
|
|
|
Password to use for authenticating the user set with `userid`. Either a
|
|
password or an access token is required.
|
|
|
|
* `accesstoken` *(required)*
|
|
|
|
Access token to use for authentication instead of `password`. Either an
|
|
access token or a password is required.
|
|
|
|
### Optional
|
|
|
|
* `allowed_attrs` *(default:* [`DEFAULT_ALLOWED_ATTRS`]*)*
|
|
|
|
List or string with comma-separated list of HTML attribute names or
|
|
dict mapping tag names to lists of attributes names.
|
|
|
|
See the bleach documentation on [allowed attributes] for more information.
|
|
|
|
* `allowed_tags` *(default:* [`DEFAULT_ALLOWED_TAGS`]*)*
|
|
|
|
List or set or string with comma-separated list of HTML tag names. HTML
|
|
tags not included will be stripped from the HTML output generated by
|
|
rendering a Markdown message template.
|
|
|
|
Note that the default list does not include any tags, which allow to load
|
|
external resources when the generated HTML is displayed, notably `img`
|
|
is not included.
|
|
|
|
* `deviceid`
|
|
|
|
Device ID to send with access token.
|
|
|
|
* `devicename`
|
|
|
|
Device name to send with access token.
|
|
|
|
* `homeserver` *(default:* `https://matrix.org`*)*
|
|
|
|
The Matrix homeserver URL.
|
|
|
|
* `jinja`
|
|
|
|
If set to `yes`, `y`, `true`, `t`, `on` or `1`, the message template is
|
|
rendered with the [Jinja] templating engine (instead of performing simple
|
|
placeholder substitution). The template context is controlled by the
|
|
`pass_environment` setting, same as with non-Jinja templates, but
|
|
placeholders use a different syntax (example: `{{DRONE_REPO}}`), so the
|
|
`template` setting should be changed to be a valid Jinja template string
|
|
when this is enabled.
|
|
|
|
Using this feature requires the `jinja2` Python module to be available
|
|
(it is installed by default in the plugin's docker image).
|
|
|
|
* `markdown`
|
|
|
|
If set to `yes`, `y`, `true`, `t`, `on` or `1`, the message resulting from
|
|
template substtution is considered to be in Markdown format and will be
|
|
rendered to HTML and sent as a formatted message with the format set to
|
|
`org.matrix.custom.html`.
|
|
|
|
Using this feature requires the `markdown` and `bleach` Python modules to
|
|
be available (they are installed by default in the plugin's docker image).
|
|
|
|
* `markdown_extensions` *(default:* `admonition, extra, sane_lists, smarty`)
|
|
|
|
Comma-separated list of enabled Markdown extensions. See this
|
|
[list of extensions] for valid extension names. Including an invalid
|
|
extension name in this list will disable Markdown rendering.
|
|
|
|
* `pass_environment` *(default:* `DRONE_*`*)*
|
|
|
|
Comma-separated white-list of environment variable names or name patterns.
|
|
Patterns are shell-glob style patterns and case-sensitive.
|
|
|
|
Only environment variables matching any of the given names or patterns will
|
|
be available as valid placeholders in the message template.
|
|
|
|
* `template` *(default:* `${DRONE_BUILD_STATUS}`*)*
|
|
|
|
The message template. Valid placeholders (example: `${DRONE_REPO}`) will be
|
|
substituted with the values of the matching environment variables (subject
|
|
to filtering according to the `pass_environment` setting).
|
|
|
|
See this [reference] for environment variables available in drone.io CI
|
|
pipelines.
|
|
|
|
|
|
|
|
[`DEFAULT_ALLOWED_ATTRS`]: https://github.com/SpotlightKid/drone-matrixchat-notify/blob/master/matrixchat-notify.py#L28
|
|
[`DEFAULT_ALLOWED_TAGS`]: https://github.com/SpotlightKid/drone-matrixchat-notify/blob/master/matrixchat-notify.py#L35
|
|
[allowed attributes]: https://bleach.readthedocs.io/en/latest/clean.html#allowed-attributes-attributes
|
|
[drone.io]: https://drone.io/
|
|
[jinja]: https://jinja.palletsprojects.com/
|
|
[list of extensions]: https://python-markdown.github.io/extensions/
|
|
[plugin]: https://docs.drone.io/plugins/overview/
|
|
[reference]: https://docs.drone.io/pipeline/environment/reference/
|