Jira-telegram-bot is a Spring Boot application which handing Jira webhook events and sends notifications via Telegram bot.
- 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
You can build application using following command:
./gradlew clean build
JDK >= 1.8
You can run unit tests using following command:
./grdlew test
You can run mutation tests using following command:
./grdlew pitest
You will be able to find pitest report in build/reports/pitest/ folder.
You can run integration tests using following command:
./grdlew testIntegration
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
-
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
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
/configsubdirectory of the current directory - the current directory
- 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)
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.
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.
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 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
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 .
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
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>
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
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent