> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# hubci/notify

Send notifications from a CircleCI Pipeline to a Mattermost channel.

Bash is required on the executor image. This orb supports Linux and macOS
based images on both the amd64 and arm64 architectures.


## Commands

### failed-mattermost

Notify a Mattermost channel or user (DM) that a CircleCI has failed. This 
command should be the final command/step in a job in order to work correctly.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `channel` | string |  | Mattermost webhooks have a default channel. Use this to send the text to
a channel other than the default. Use the channel’s name and not the
display name, e.g. use town-square, not Town Square. Use an "@" followed
by a username to send to a Direct Message.
 |
| `text` | string | The CircleCI job **${CIRCLE_JOB}** has failed. You can view it here: ${CIRCLE_BUILD_URL}
 | Markdown-formatted message to send to Mattermost to indicate a failed job.
Set this parameter if you don't want to use the default message.
 |
| `webhook` | env_var_name | MM_WEBHOOK | The name of the environment variable to use to read in the webhook. The
default value should be fine for most people.
 |

### notify-mattermost

Send a message to a Mattermost channel or user (DM).


| Parameter | Type | Default | Description |
|---|---|---|---|
| `channel` | string |  | Mattermost webhooks have a default channel. Use this to send the text to
a channel other than the default. Use the channel’s name and not the
display name, e.g. use town-square, not Town Square. Use an "@" followed
by a username to send to a Direct Message.
 |
| `text` | string |  | Markdown-formatted message to send to Mattermost. To trigger
notifications, use @<username>, @channel, and @here like you would in
other Mattermost messages.
 |
| `webhook` | env_var_name | MM_WEBHOOK | The name of the environment variable to use to read in the webhook. The
default value should be fine for most people.
 |
| `when` | enum | on_success | Add the when attribute to a job step to override its default behaviour
and selectively run or skip steps depending on the status of the job.
If you want to notify Mattermost only on fail, you can change this param, 
but it'll be easier to use the 'failed-mattermost' command.
 |

## Examples

### notify

An extremely simple example of sending a notification.


```yaml
version: '2.1'
orbs:
  notify: hubci/notify@x.y
jobs:
  build:
    docker:
      - image: cimg/base:2024.01
    steps:
      - checkout
      - notify/notify-mattermost:
          text: Hi friends!
workflows:
  main-wf:
    jobs:
      - build
```