semantic-release-telegram-bot

semantic-release plugin to get release notifications
on telegram from a telegram bot


| Step | Description |
| --------- | ------------------------------------------------------ |
| success | Send a telegram message to notify of a new release. |
| fail | Send a telegram message to notify of a failed release. |

Install

Add the plugin to your npm-project:

``bash
$ npm install semantic-release-telegram-bot -D
`

Usage

The plugin can be configured in the
semantic-release configuration file:

`json
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
[
"semantic-release-telegram-bot",
{
"notifications": [
{
"chatIds": "123456",
"branch": "release/*.x.x"
}
]
}
]
]
}
`

Configuration

$3

Create telegram bot using the official guide

$3

The TELEGRAM_BOT_TOKEN variable can be defined in the environment where you will run semantic release. Copy and past
the token value to this variable.

$3

| Option | Description | Required | Default |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------- | :------------------------------------------- |
| packageName | Override or add package name instead of npm package name | no | SEMANTIC_RELEASE_PACKAGE or npm package name |
| notifyOnSuccess | Determines if a successful release should trigger a telegram message to be sent. If false this plugin does nothing on success. Can be overwritten by the same property in notifications | no | true |
| notifyOnFail | Determines if a failed release should trigger a telegram message to be sent. If false this plugin does nothing on fail. Can be overwritten by the same property in notifications | no | false |
| success | Provides a template for the telegram message on success when notifyOnSuccess is true. | no | DEFAULT SUCCESS MESSAGE |
| fail | Provides a template for the telegram message on fail when notifyOnFail is true. | no | DEFAULT FAIL MESSAGE |
| notifications | Provides a list of notification objects that can be flexibly configured | yes | [] |

$3

In the notification property, you can pass an object with the following values

| Option | Description | Required | Default |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------- | :---------------------- |
| notifyOnSuccess | Determines if a successful release should trigger a telegram message to be sent. If false this plugin does nothing on success. Can be overwritten by the same property in notifications | no | true |
| notifyOnFail | Determines if a failed release should trigger a telegram message to be sent. If false this plugin does nothing on fail. Can be overwritten by the same property in notifications | no | false |
| success | Provides a template for the telegram message on success when notifyOnSuccess is true. | no | DEFAULT SUCCESS MESSAGE |
| fail | Provides a template for the telegram message on fail when notifyOnFail is true. | no | DEFAULT FAIL MESSAGE |
| chatIds | One or more telegram chat IDs, you can also pass the name of the environment variable that contains the chat id | yes | undefined |
| branch | Describes a pattern for filtering a branch using a glob expression. | no | undefined |

$3

success and failure messages can be configured by passing an object with custom message, or a path to a template file.

#### Inline message

Here is a description of the object that can be passed to the success or fail property to describe the inline message

| Option | Description | Required | Default |
| :----------- | :-------------------------------------------------------------------- | :------- | :--------- |
| message | Notification message | yes | undefined |
| format | Message format, may have html or markdown values | no | 'markdown' |
| customData | An object with custom values that can be used for output in a message | no | undefined |

#### Message template

If you need more functionality, you can pass a path to the template file that will be rendered using nunjucks,
you will also have access to the context, and all a functionality that nunjucks provides.

Here is a description of the object with path that can be passed to the success or fail property

| Option | Description | Required | Default |
| :----------- | :-------------------------------------------------------------------- | :------- | :-------- |
| path | Path to a message template | yes | undefined |
| customData | An object with custom values that can be used for output in a message | no | undefined |

#### Context

A special context is available for each message, which provides access to the properties described by you in
customData property, as well as to the following values

| Option | Description |
| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| packageName | The name of the current package |
| branch | A branch object. You can find its description here |
| lastRelease | A lastRelease object. You can find its description here |
| nextRelease | A nextRelease object. You can find its description here |
| commits | A list of commits. You can find its description here |
| errors | A list of native Error objects, available only for fail messages |

Examples

$3

`json
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
[
"semantic-release-telegram-bot",
{
"success": {
"message": "Here is the new release!"
},
"notifications": [
{
"chatIds": "PrivateChatId",
"notifyOnFail": true,
"notifyOnSuccess": false,
"fail": {
"message": "Oops!"
}
},
{
"chatIds": "PrivateChatId",
"branch": "rc/*"
},
{
"chatIds": "PublicChatId",
"branch": "release/*"
}
]
}
]
]
}
`

In this example:

- Failure messages from all branches will be sent to PrivateChatId chat, also the messages changed to Oops!
- Success messages from rc branches will be sent to PrivateChatId chat
- Only a success message from release branches will be sent to PublicChatId chat
- All success messages changed to Here is the new release!

$3

Here is an example of the inline template, it uses template function from lodash
to render your message.

`json
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
[
"semantic-release-telegram-bot",
{
"success": {
"message": "Here is a new release of ${packageName} library and value ${myVariable} of my custom variable",
"customData": {
"myVariable": "myVariable"
}
}
}
]
]
}
`

$3

Be careful when describing your templates, you must support html or markdown telegram syntax.

Look at the nunjucks docs to see what functionality you can use

`md


A new version of {{packageName}} has been released!

Custom change log:

{% for commit in commits %}
• ({{ commit.subject }}): {{ commit.message }}
{% endfor %}
`

And specify the path to the template

`json
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
[
"semantic-release-telegram-bot",
{
"success": {
"path": "./path/to/custom-success-template.html"
}
}
]
]
}
``

MIT Licence