You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Drew Short 005cfdda34 Fixed the curl version 2 years ago
bin Fix another method call 4 years ago
Dockerfile Fixed the curl version 2 years ago
LICENSE Initial commit 8 years ago Add configuration to format matrix messages as html 4 years ago
pipeline.yml Adding concourse pipeline 4 years ago
tag Updated the base image, pinned requirements, incremented tag 2 years ago Adding concourse pipeline 4 years ago

Matrix Notification Resource for Concourse CI

Send notification messages to Matrix using a string message or templated message.

This resource borrows heavily from the Slack notification resource. Usage and behavior around text and text_file parameters should be handled exactly the same as in that.


- name: matrix-notification-resource
  type: docker-image
    repository: freelock/matrix-notification-resource

Registering with Matrix

This resource needs an access token for a valid user account. It will not create the user account for you, or retrieve the token.

To get a token, first create a Matrix user account on your homeserver of choice. Then you can use Curl to get an access token for the account:

curl -XPOST -d '{"type":"m.login.password", "user":"example", "password":"wordpass"}' ""

    "access_token": "QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd",
    "home_server": "",
    "user_id": ""

... add the returned access_token to the resource.

Then, a user will need to invite the account to the appropriate room, and the account will need to accept the invitation.

Source Configuration

  • matrix_server_url: Required. Example:
  • token: Required. token to authenticate with Matrix server
  • room_id: Required. The room to send notifications to -- this account must already be a member of this room.
  • msgtype: Used to post a custom message type e.g. if you want to attach a json blob. If set to anything other than m.notice, the resource will attach a "build" json object containing the build metadata info. Defaults to m.notice, can be overridden by the put resource.
  • data_file: Optional. (string) Default file to post to the data key of a custom message type. The contents of this file is generally assumed to be a JSON-encoded string. Can be overridden in the job parameters.

Pull requests accepted for room_alias, user logins, auto-joins.

out: Sends message to Matrix room

Send message to specified Matrix Room, with the configured parameters


  • text: (string) Text to send to the Matrix room as the content.body.
  • text_file: (string) File containing text to send to the Matrix room as the content.body.
  • msgtype: Optional. Message type, m.notice, m.text (default: m.notice)
  • is_html: Optional. Indicate that the input is formatted as html
  • data_file: Optional. (string) Filename to post using a custom_event message type. If unset, defaults to the data_file on the resource. If it exists, the file must contain valid JSON.
  • trigger: Optional. (string) Arbitrary test to add to a "trigger" data item on custom message types.
  • always_notify: If true, send a notice even if text_file and data_file are empty. If false, and a text_file is specified but empty, a notification will not be sent.
  • prefix: If set, this will be added to the beginning of a message. Commonly used with $BUILD_PIPELINE_NAME to indicate which pipeline is sending this message.
  • link: If set to true, will wrap the text in a link to the build using the pattern $ATC_EXTERNAL_URL/pipelines/$BUILD_PIPELINE_NAME/jobs/$BUILD_JOB_NAME/builds/$BUILD_NAME



- name: matrix-notification
  type: matrix-notification-resource
    token: {{matrix_token}}
    room_id: {{matrix_room_id}}
    data_file: data


Not supported


Not supported


  - put: matrix-notification
      text_file: results/message.txt
      text: |
        The build had a result. Check it out at:
        or at:

        Result: $TEXT_FILE_CONTENT

Matrix has the ability to attach and store arbitrary JSON. This can be very useful to send arbitrary results that a bot might use for further action. Freelock uses this ability to pass extensive information about various deployment environment settings, while keeping the human-readable portion brief.

These extra data keys are not sent if using the default m.notice message type, but if you define a custom msgtype, this resource will automatically add a JSON object containing the build data -- Job name, pipeline name, build name (the sequence number within this pipeline), build id, and concourse ATC url. It will also attach the contents of a data file added to the data key, and a trigger key that is useful to easily pass info about a particular Matrix put -- e.g. 'success', 'fail', 'start', 'end', 'info' -- which your Matrix bot might find useful for handling the message.

  - put: matrix-notification
      data_file: matrix-notification/data
      trigger: fail
      message: Test failure.