semantic-release-telegram
semantic-release plugin. Provides notifications to Telegram chats.
🇺🇦 Help Ukraine
I woke up on my 26th birthday at 5 am from the blows of russian missiles. They attacked the city of Kyiv, where I live, as well as the cities in which my family and friends live. Now my country is a war zone.
We fight for democratic values, freedom, for our future! Once again Ukrainians have to stand against evil, terror, against genocide. The outcome of this war will determine what path human history is taking from now on.
Table of Contents
Requirements
To use library you need to have node and npm installed in your machine:
- node
>=10
- npm
>=6
Package is continuously tested on darwin, linux and win32 platforms. All active and maintenance LTS node releases are supported.
Installation
To install the library run the following command
npm i --save semantic-release-telegram
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", {
"chats": [ 123456789, -987654321 ]
} ]
]
}
This is a minimal usage sample with a default configuration. Next messages will be sent:
Configuration
if needed, the configuration can be extended:
{
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
["semantic-release-telegram", {
"name": "funny-app",
"chats": [ 123456789 ],
"templates": {
"fail" : "An error occured while trying to publish the new version of <b>{name}</b>.\n<pre><code class='language-javascript'>{error}</code></pre>",
"success" : "A new version of <a href='{repository_url}'>{name}</a> has been released. Current version is <b>{version}</b>"
}
}]
]
}
Config attribute description:
Option | Required | Type | Description | Default |
---|---|---|---|---|
name |
no | string |
Application name. | name from package.json |
chats |
yes | array |
List of chats for sending. The bot should have access to each chat. | |
templates.success |
no | string |
HTML template, send in case of success. | SUCCESS.html |
templates.fail |
no | string |
HTML template, send in case of fail. | FAIL.html |
assets |
no | array |
List of files to upload. See Assets | [] |
telegra.ph |
no | object |
Publish and attach Telegraph story | null |
Template variables:
key | Templates | Description | Example |
---|---|---|---|
repository_url |
success, fail | The git repository URL. By default repository property in package.json or git origin url | https://github.com/pustovitDmytro/semantic-release-telegram |
name |
success, fail | application name | funny-app |
version |
success | new version | 1.0.0 |
release_notes |
success | generated notes | |
release_type |
success | minor | |
commit |
success | commit hash | 13b16914f2893fa09e9a39f1dcda78af1fff0dbd |
branch |
success, fail | master | |
error |
fail | thrown error | SemanticReleaseError: Cannot push to the Git repository |
Authentication
To use this package, you need to register a new telegram bot. Then pass the next environment variables:
TELEGRAM_BOT_ID=123456
TELEGRAM_BOT_TOKEN=ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Assets
Can be glob or relative file path. name
specifies file label in telegram. In the case of glob pattern, all files are uploaded in a single archive, name
is required.
Example:
"assets" : [
{ "path": "README.md" },
{ "glob": [ ".docs/*" ], "name": "Documentation.zip" }
]
Assets will be attached to release message as separate files.
Telegraph
Upload bulky markdowns, as telegra.ph stories. Use next api for this:
"telegra.ph" : {
"title" : "{name} v.{version}",
"message" : "<a href='{telegraph_url}'>Release Notes</a>",
"content" : "{release_notes}"
}
title
and content
represent story content.
message
is a telegram message, sent to telegram chats (It is reasonable to include {telegraph_url}
here). Success template is extended with new variables {telegraph_url}
and {telegraph_title}
when telegra.ph
is used.
Contribute
Make the changes to the code and tests. Then commit to your branch. Be sure to follow the commit message conventions. Read Contributing Guidelines for details.