Skip to content

Latest commit

 

History

History
231 lines (182 loc) · 12.5 KB

README.md

File metadata and controls

231 lines (182 loc) · 12.5 KB
Raw

semantic-release-telegram-bot

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

npm CircleCI branch license

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