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:

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

Usage

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

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

Configuration

Bot

Create telegram bot using the official guide

Environment variables

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.

Options

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	[]

Notification object

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

Template options

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

Sending messages to specific chats

{
    "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!

Custom inline template

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

{
    "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"
                    }
                }
            }
        ]
    ]
}

Custom template

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

<!--custom-success-template.html-->

<b>A new version of {{packageName}} has been released!</b>

Custom change log:

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

And specify the path to the template

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

MIT Licence