Jira Telegram Bot

Jira-telegram-bot is a Spring Boot application which handing Jira webhook events and sends notifications via Telegram bot.

Key features

• processing Jira webhook issue events
• notification templating (using Apache FreeMarker template engine)
• support several databases (PostgreSQL (v 9+), MySQL (v 5.7+), H2)
• Jira OAuth
• monitoring using Prometheus
• holding secrets with HashiCorp Vault
• sending notifications by tags
• REST API

Build

Build from source

You can build application using following command:

./gradlew clean build

Requirements:

JDK >= 1.8

Unit tests

You can run unit tests using following command:

./grdlew test

Mutation tests

You can run mutation tests using following command:

./grdlew pitest

You will be able to find pitest report in build/reports/pitest/ folder.

Integration tests

You can run integration tests using following command:

./grdlew testIntegration

Running jira-telegram-bot

After the build you will get fully executable jar archive

You can run application using following commands:

java -jar jira-telegram-bot.jar

or

./jira-telegram-bot.jar

Building and running app with Docker and docker-compose

• For building the application and creation Docker image run

   docker-compose build
  

• Customise configs with you preferred editor

  place configs in ./config directory

• Add to docker-compose.yaml your preferred database service

• Run the docker image

   docker-compose up -d
  

Configuration

You can see all the necessary configuration properties in the file example/application.properties

According to Spring Docs you can override default application properties by put custom application.properties file in one of the following locations:

• a /config subdirectory of the current directory
• the current directory

Custom properties

jira.bot.notification.sendToMe

whether the user should receive their self-created events

jira.bot.notification.jiraUrl

jira instance url for building browse link in notification message

telegram.bot.token

telegram bot secret token

telegram.bot.name

telegram bot name

telegram.bot.adminId

id of telegram bot admin

telegram.bot.proxyHost

http proxy host

telegram.bot.proxyPort

http proxy port

telegram.bot.connectionTimeout

timeout in milliseconds until a connection is established

telegram.bot.connectionRequestTimeout

timeout in milliseconds used when requesting a connection

telegram.bot.socketTimeout

the socket timeout in milliseconds, which is the timeout for waiting for data or, put differently, a maximum period inactivity between two consecutive data packets)

Jira Webhooks

To receive jira webhooks you may to configure your jira instance. See jira docs

WARNING!

Jira-telegram-bot supports only issue events at the moment

By default jira-telegram-bot process only following issue events:

• issue_created
• issue_updated
• issue_generic
• issue_commented
• issue_assigned

If you want to process any other issue event or change default template you can modify corresponding row in jira-telegram-bot database table called templates.

Templating

Jira-telegram-bot using Apache FreeMarker template engine. All templates by default stored in jira-telegram-bot database table called templates. Each template must be a message in properly telegram markdown style.

In example/templates folder you can find default jira event templates.

Jira user registration

To register jira user to receive webhook events you should add corresponding row into jira-telegram-bot database table called chats.

You should specify jira_id (jira user login) and telegram_id (telegram chat id) unique fields.

To find out your telegram chat id you should write simple command "/me" to telegram bot.

Telegram bot commands

Telegram bot supports following text commands:

• /me - prints telegram chat id
• /jira_login - prints attached jira login to this telegram chat id
• /help - prints help message

Admin commands:

• /users_list - prints list of users
• /add_user jiraLogin telegramId - add new user to bot
• /remove_user jiraLogin - remove user from bot

Jira oauth commands:

• /auth - starts jira authorization
• /my_issues - shows list of unresolved issues assigned to user

Jira OAuth

Please read Jira OAuth to understand how to configure Jira before using Jira OAuth in jira-telegram-bot.

You must provide next properties to use Jira OAuth in jira-telegram-bot :

jira.oauth.baseUrl

your jira instance url

jira.oauth.authorizationUrl

jira authorization url, {jira.oauth.baseUrl}/plugins/servlet/oauth/authorize

jira.oauth.accessTokenUrl

jira access token url, {jira.oauth.baseUrl}/plugins/servlet/oauth/access-token

jira.oauth.requestTokenUrl

jira request token url, {jira.oauth.baseUrl}/plugins/servlet/oauth/request-token

jira.oauth.consumerKey

consumer key

jira.oauth.publicKey

client RSA public key

jira.oauth.privateKey

client RSA private key

/auth telegram command will be allowed after all properties configured properly .

Notify issues watchers

To notify issues watchers about events jira-telegram-bot must get watchers list via Jira REST API.

You must provide next properties to use Jira REST API in jira-telegram-bot :

jira.watchers.username

your jira user login

jira.watchers.password

your jira user password

jira.bot.notification.jiraUrl

jira url for calling REST API

INTEGRATIONS

Monitoring using Prometheus

You can access prometheus metrics by url:

{host:port}/actuator/prometheus

Jira bot comes with next custom counter metrics:

jira_bot_event_counter

number of incoming events

jira_bot_event_error_counter

number of incoming events with an error

Holding secrets with HashiCorp Vault

Integration with Vault was made using spring-cloud-vault.

By default jira-telegram-bot integration with Vault disabled.

To enable integration with Vault pass following arguments to jira-telegram-bot run command:

java -jar jira-telegram-bot.jar --spring.cloud.vault.enabled=true --spring.cloud.vault.uri=<your vault uri> 
--spring.cloud.vault.token=<your vault token> --spring.cloud.vault.kv.application-name=<vault application name>

Sending notifications by tags

You can add any tag to table tags.

Any tag can be linked to any user via chats_tags table.

Issue commented with message hello @devs will be recieved to all users with tag devs.

There are only one tag exist by default - @everyone. Using @everyone you can send notification to all users.

REST API

jira-telegram-bot bot provides simple REST API under /api mapping.

Supported requests:

• POST /api/send/all - sends message to all users.

Body:

   {
   "message" : "any supported telegram markdown message"
   }

Contributing

Feel free to contribute. New feature proposals and bug fixes should be submitted as GitHub pull requests. Fork the repository on GitHub, prepare your change on your forked copy, and submit a pull request.

IMPORTANT!

Before contributing please read about Conventional Commits / Conventional Commits RU