drone-matrixchat-notify/README.md

drone-matrixchat-notify

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:

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
    template: '${DRONE_REPO} ${DRONE_COMMIT_SHA} ${DRONE_BUILD_STATUS}'

Configuration settings

• 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.

• accesstoken

  Access token to use for authentication instead of password. Either an access token or a password is required.

• 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.

• password

  Password to use for authenticating the user set with userid. Either a password or an access token is required.

• roomid (required)

  ID of matrix chat room to send messages to (ID, not alias).

• 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.

• userid (required)

  ID of user on homeserver to send message as (ID, not username).