drone-matrixchat-notify/README.md

# drone-matrixchat-notify

[![MIT License](https://img.shields.io/github/license/SpotlightKid/drone-matrixchat-notify?label=License)](https://github.com/SpotlightKid/drone-matrixchat-notify/blob/master/LICENSE)
[![GitHub tag (with filter)](https://img.shields.io/github/v/tag/SpotlightKid/drone-matrixchat-notify?filter=v*.*.*&logo=github&label=Latest%20version)](https://github.com/SpotlightKid/drone-matrixchat-notify/tags)
[![Docker image version](https://img.shields.io/docker/v/spotlightkid/drone-matrixchat-notify?logo=docker&label=Docker+image)](https://hub.docker.com/r/spotlightkid/drone-matrixchat-notify)
[![GitHub stars](https://img.shields.io/github/stars/SpotlightKid/drone-matrixchat-notify?logo=github&label=GitHub)](https://github.com/SpotlightKid/drone-matrixchat-notify)
[![GitLab stars](https://img.shields.io/gitlab/stars/SpotlightKid%2Fdrone-matrixchat-notify?logo=gitlab&label=GitLab)](https://gitlab.com/SpotlightKid/drone-matrixchat-notify)
[![GitHub issues](https://img.shields.io/github/issues/SpotlightKid/drone-matrixchat-notify?logo=github&label=Issues)](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/