{"id":16489553,"url":"https://github.com/nanoy42/gitlab-webhook-telegram","last_synced_at":"2025-03-23T12:34:36.197Z","repository":{"id":46044362,"uuid":"163744986","full_name":"nanoy42/gitlab-webhook-telegram","owner":"nanoy42","description":null,"archived":false,"fork":false,"pushed_at":"2022-12-08T03:18:44.000Z","size":80,"stargazers_count":10,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2024-10-12T13:44:24.630Z","etag":null,"topics":["gitlab","telegram","telegram-bot","webhooks"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nanoy42.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-01T15:03:00.000Z","updated_at":"2023-07-31T19:04:50.000Z","dependencies_parsed_at":"2023-01-25T04:01:00.511Z","dependency_job_id":null,"html_url":"https://github.com/nanoy42/gitlab-webhook-telegram","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoy42%2Fgitlab-webhook-telegram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoy42%2Fgitlab-webhook-telegram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoy42%2Fgitlab-webhook-telegram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoy42%2Fgitlab-webhook-telegram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nanoy42","download_url":"https://codeload.github.com/nanoy42/gitlab-webhook-telegram/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221851170,"owners_count":16891733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gitlab","telegram","telegram-bot","webhooks"],"created_at":"2024-10-11T13:44:31.136Z","updated_at":"2024-10-28T15:52:20.352Z","avatar_url":"https://github.com/nanoy42.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gitlab-webhook-telegram\n\n## What can GWT do for you ?\n\nGwt is a simple python server triggered by gitlab webhooks which trigger messages on telegram via a bot.\n\nSome functionnalities : \n * bind multiple projects to multiple chats\n * display messages for every type of gitlab webhook\n * choose message length with verbosity per chat and per project\n * configure nearly all the bot by interaging with it on telegram (optional)\n * easliy turn the app into a service\n\n## Installation\n\n### 0) Prepare\n\nYou will need a server with python3 and pip.\n\n### 1) Get a telegram bot\n\nFirst things first, you need a telegram bot. To get one, you need to interact with @BotFather on telegram. Please refer to https://core.telegram.org/bots for the explicit procedure. You should et a token (like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`) and we will refer with `\u003ctoken\u003e` for the following.\n\n### 2) Clone the repository\n\nYou can clone the git repository with \n\n```\ngit clone https://github.com/nanoy42/gitlab-webhook-telegram.git\n```\n\nThen you need to install the requirements. The recommanded way is to use pipenv.\n\n#### Production\n\nYou can install dependencies with : \n\n```\npipenv install --ignore-pipfile\n```\n\n#### Dev\n\nYou can install dependencies and dev dependencies with the command :\n\n```\npipenv install --dev\n```\n\n#### I don't want to use pipenv\n\nIf you don't want to use pipenv, the list of requirements are in the requirements.txt file. Also in the dev-requirements.txt, you have the recommanded requirements for developpement.\n\n### 3) Configure the app\n\nThere are 3 files to edit in order to get the bot working.\n\nNote : If you choose to use `configure-by-telegram` option, only one file need to be edited\n\nFirst copy example configuration files where the app is installed \n\n```\ncp config.json.example config.json\ncp verified_chats.json.example verified_chats.json\ncp chats_projects.json.example chats_projects.json\n```\n\nNote : if you want to have the configuration files elsewhere (in `/etc/gwt/` for example), please refer to the FAQ.\n\n#### 3.1) config.json\n\nThis is the main configuration file.\n\nIt looks like \n```json\n{\n    \"configure-by-telegram\": true,\n    \"port\": 8080,\n    \"telegram-token\": \"\",\n    \"passphrase\": \"Here we go !\",\n    \"gitlab-projects\": [],\n    \"log-file\": \"./gwt.log\",\n    \"log-level\": \"warning\"\n}\n```\n| Parameter                 | Type                                      | Default value    | Description                                                                                                                    |\n|---------------------------|-------------------------------------------|------------------|--------------------------------------------------------------------------------------------------------------------------------|\n| `configure-by-telegram`   | boolean (`true` or `false`)               | `true`           | If `true`, it will possible to verify chats, add and remove projects, change verbosity of projects directly in telegram chats. |\n| `port`                    | integer (between 0 and 65535)             | 8080             | The device port on which the web server should run.                                                                            |\n| `telegram-token`          | string                                    | `\"\"`             | The value of the telegram bot token.                                                                                           |\n| `passphrase`              | string                                    | `\"Here we go !\"` | A passphrase to verify chats when `configure-by-telegram` is set to `true`.                                                    | \n| `gitlab-projects`         | array (see below)                         | `[]`             | An array of configured projects. See below.                                                                                    |\n| `log-file`                | string                                    | `\"./gwt.log\"`    | Absolute or relative path to the log file. Make sure the process has the right tro write there.                                |\n| `log-level`               | string                                    | `\"warning\"`      | The log level.                                                                                                                 |\n\nThe array of `gitlab-projects` should contain name and token for each project :\n\n| Parameter | Type   | Description                                                           |\n|-----------|--------|-----------------------------------------------------------------------|\n| `name`    | string | Pretty name of project                                                |\n| `token`   | string | Token of project. It sould be the same as on the gitlab webhook page. |\n\nThe log level should be picked among :\n* info\n* debug\n* warning\n* error\n* critical\n\nMore information on the log levels : https://docs.python.org/fr/3/howto/logging.html\n\nA working example :\n\n```json\n{\n    \"configure-by-telegram\": true,\n    \"port\": 8080,\n    \"telegram-token\": \"123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11\",\n    \"passphrase\": \"BCX2ipcGv5wCorPUWhTi9SXfWK6gz7\",\n    \"gitlab-projects\": [\n        {\n            \"name\": \"My awesome project\",\n            \"token\": \"this is a secret token\"\n        },\n        {\n            \"name\": \"Another project\",\n            \"token\": \"G4oJnAm9ljWksgfjGTnUcUguv6WvkF\"\n        }\n    ],\n    \"log-file\": \"/var/log/gwt/gwt.log\",\n    \"log-level\": \"info\"\n}\n```\n\nNote : The log-file parameter is ignored when the server is launched with the `python3 manage.py test` command and the logs are printed to the console.\n\n#### 3.2) verified_chats.json\n\nIf you use `configure-by-telegram`, the bot will propose you to verify the chat on the `/start` command (you will have to send the passphrase on the chat) and will write the verified_chats.json file. If you don't want to use `configure-by-telegram` or don't want to send the passphrase you should manually add the chat ip in the verified_chats.json file. \n\nThe file is composed by a array of integers, which represent telegram chats identifier.\n\nHow to get this identifier : the bot will display the chat id if the chat is not verified (wether `configure-by-telegram` is se tot `true` or `false`).\n\nYou can also use https://api.telegram.org/bot\u003cYourBOTToken\u003e/getUpdates.\n\nA \"working\" example :\n\n```json\n[1, -234, 10]\n```\n\n#### 3.3) chats_projects.json\n\nThis file allows to keep trak of relations betweens chats and projects.\n\nYou could see config.json has storing projects, verified_chats.json the chats and chats_projects.json the relations between the two.\n\nThe format of this file is the following : \n```json\n{\n    \"token\": {\n        \"chat_id\": verbosity,\n        \"chat_id2\": verbosity2\n    }\n}\n```\n\nMessages for the project associated to token will be sent to all chats in the dictionnary with the associated verbosity.\n\nThe tokens and the chat ids should be in `config.json` and `verified_chats.json` respectively.\n\nA working example :\n\n```json\n{\n    \"this is a secret token\": {\n        \"1\": 3\n    },\n    \"G4oJnAm9ljWksgfjGTnUcUguv6WvkF\": {\n        \"-234\": 1,\n        \"1\": 2\n    }\n}\n```\n\nA webhook from the \"My awesome project\" project will be sent to the chat with id 1 with a verbosity of 3.\n\nA webohhom from the \"Another project\" project will be sent to the chats with id -234 and 1 with verbosities 1 and 2 respectively.\n\nEven if the chat with id 10 is in the `verified_chats.json` file, no message will reach it.\n\n### 4) Test the app\n\nYou can start the server with the \n\n```\npython3 main.py test\n```\n\nYou can then test the bot by interaging with i on messenger and use the test button on the gitlab interface.\n\n### 5) Make it a service\n\nThe `main.py` script allows 5 commands : `start`, `restart`, `stop`, `test` and `help`.\n\nThe `help` command displays an help message.\n\nThe `test` command runs the server but ends with an intureption (ctrl-c) or the user`s session end. Also, logs are printed in console and not in file.\n\nThe `start`, `restart` and `stop` commands allows to use the a daemonized script. You can easily use those commands to make gwt a service to start when the server boots.\n\n## How to use the bot\n\nThe behavior of the bot depends on the value of `configure-by-telegram`.\n\n### configure-by-telegram is false\n\nIn this case, the bot will react to three commands : `/start`, `/help` and `/listProjects`.\n\nNote : the bot will trivially react to other commands with the following message : If you want to configure the bot with telegram, please set the 'configure-by-telegram' option to true in the settings.\n\n| Command         | Usage                                                                                                                                                                     |\n|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `/start`        | Begin point of the bot. In this case, it basically dislays the id of the current chat.                                                                                    |\n| `/help`         | Will display the list of available commands and the version of the bot.                                                                                                   |\n| `/listProjects` | Will display the configured projects for this chat and the verbosity of each, reprensented by an integer (from 0 to 3). The higher the integer, the verbosier the bot is. | \n\n### configure-by-telegram is true\n\nIn this case, the bot will react to three commands : `/start`, `/help`, `/listProjects`, `addProject`, `removeProject` and `changeVerbosity`.\n\n| Command            | Usage                                                                                                                                                                     |\n|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `/start`           | Begin point of the bot. In this case, it displays the chat id and propose to verify chat by sending the passphrase.                                                       |\n| `/help`            | Will display the list of available commands and the version of the bot.                                                                                                   |\n| `/listProjects`    | Will display the configured projects for this chat and the verbosity of each, reprensented by an integer (from 0 to 3). The higher the integer, the verbosier the bot is. |\n| `/addProject`      | Will display an interactive keyboard to choose a non-configured project to add to the current chat. The project will be added with the maximal verbosity (3).             |\n| `/removeProject`   | Will display an interactive keyboard to choose a configured project and delete it from the table.                                                                         |\n| `/changeVerbosity` | Will display an interactive keyboard to choose a configured project and change its verbosity.                                                                             |\n\n## Under the hood\n\nHow does the app works.\n\nWhen receiving a post request from Gitlab, it will retrieve the token and verify that the token is in the `config.json` file. If it is not, it will log an error and if it is it will retrieve the type of the hook in the following list :\n\n* PUSH\n* TAG\n* ISSUE\n* CONFIDENTIAL_ISSUE\n* NOTE\n* CONFIDENTIAL_NOTE\n* MR\n* JOB\n* WIKI\n* PIPELINE\n\nThen it will call the appropriate handler with the POST parameters. Each handler will then print message accordinglyot the chat verbosity and send it.\n\nThe bot also listen for messages and commands (messages with `/`) and react accordingly to write configuration files.\n\n\n## FAQ\n\n### Any python framework for the server ?\nNo it is written only using requests.\n\n### Can I use this chat for a group ? For a single user ?\n\nYes you can do it for both. \n\nFor a single user to have to search the bot name and start chating with it.\n\nFor a group, you have to invite him on the group.\n\n### I want to put the configuration files elsewhere\n\nIf you want to have the configuration files in another directory (say `/etc/gwt/`), it is possible to do so by setting the `GWT_DIR` environment variable (using `export` command for instance) . It sould be an abstract path to a readable-writable directory (the script writes ine the configuration files). You have to put the final / :\n\n```\nexport GWT_DIR=/etc/gwt/\n```\n\nNote : you can use a relative path here but this is strongly discouraged.\n\n### Verbosities ?\n\nThere are 4 levels of verbosity, described below :\n\n| Level | Description                                                                                                                        |\n|-------|------------------------------------------------------------------------------------------------------------------------------------|\n| 0     | Print all except issues descriptions, assignees, due dates, labels, commit messages and URLs and reduce commit messages to 1 line. |\n| 1     | Print all except issues descriptions, assignees, due dates and labels and reduce commit messages to 1 line.                        |\n| 2     | Print all but issues descriptions and reduce commit messages to 1 line.                                                            |\n| 3     | Print all.                                                                                                                         |\n\n\n### Can I configure the projects and turn `configure-by-telegram` afterwards ?\n\nYes. It is even recommended.\n\n### How do I block certain types of handlers ?\n\nYou cannot block on the app side, but you can select what webhooks are active in the gitlab pannel.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanoy42%2Fgitlab-webhook-telegram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnanoy42%2Fgitlab-webhook-telegram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanoy42%2Fgitlab-webhook-telegram/lists"}