A bot that allows users to post issues on a Gitea instance without registering simply by acting as a medium.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

159 lines
6.0 KiB

2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
  1. # `issue_bot`
  2. A bot to handle bug reports through mail, for gitea's issue tracker.
  3. ## Problem
  4. Users have to register to your gitea instance to file bugs. This is a deterrent. A mailing list requires less effort, but lacks bridging with an issue tracker.
  5. ## Solution
  6. Users send new issues with an e-mail to the address of your bot. Your bot replies with a password that allows the author to reply with the same identity and to close the issue.
  7. The bot binary can also be run periodically to check for new replies in issues and send the updates to the issue authors, if they are subscribed to the issue. Subscription is true by default, and the subscription status can be changed with the password.
  8. ## Problems this solution brings
  9. Spam?
  10. ## Configuration
  11. The bot looks for a `config.toml` file in the same directory as the binary. The config needs the following values:
  12. ```text
  13. # the tag that prefixes email subjects eg "[issue-bot-issues] blah blah"
  14. tag = "issue-bot-issues"
  15. # the auth_token for the gitea's instance API
  16. auth_token= "7a36300555aaf84a0af9847e9747a0df72a82056"
  17. # the local part of your bot's receiving address.
  18. local_part= "issues"
  19. domain= "meli.delivery"
  20. base_url = "https://git.meli.delivery"
  21. repo = "meli/issue-bot"
  22. bot_name = "IssueBot"
  23. bot_username = "issue_bot"
  24. # the shell command that the bot pipes mail to
  25. # mailer = "cat" # just print the e-mail in stdout
  26. # mailer = "/usr/sbin/sendmail -t webmaster@meli.delivery" # send copies to an address
  27. mailer = "/usr/sbin/sendmail -t"
  28. ```
  29. Setup your mail server to deliver mail with destination `{local_part}+tags@{domain}` to this binary. Simply call the binary and write the email in UTF-8 in the binary's standard input.
  30. On postfix this can be done by creating a transport map and a pipe. A transport map is a file that tells postfix to send mails send to `{local_part}` to a specific program. The pipe will be this program.
  31. Open `master.cf` and paste this line at the bottom:
  32. ```text
  33. issue_bot unix - n n - - pipe
  34. user=issuebot directory=/path/to/binarydir/ argv=/path/to/binary
  35. ```
  36. an example:
  37. ```text
  38. issue_bot unix - n n - - pipe
  39. user=issuebot directory=/home/issuebot/ argv=/home/issuebot/issue-bot
  40. ```
  41. Then create your transport map:
  42. ```text
  43. {local_part}@{domain} issue_bot:
  44. ```
  45. Notice the colon at the end. This means that it refers to a transfer, not an address. Save the file somewhere (eg `/etc/postfix/issue_transport`) and make it readable by postfix. Issue `postmap /etcpostfix/issue_transport`. Finally add the entry `hash:/etc/postfix/issue_transport` in your `transport_maps` and `local_recipient_maps` keys in `main.cf`. `postfix reload` to load the configuration changes.
  46. You will also need the following setting to allow tags in your recipient addresses:
  47. ```text
  48. recipient_delimiter = +
  49. ```
  50. Setup a periodic check in your preferred task scheduler to run `issue_bot_bin cron` in order to fetch replies to issues. On systemd this can be done with timers.
  51. ### Troubleshooting
  52. If you your email stops working or postfix doesn't pass mail to the bot, make sure you're not using a non-default setup like virtual mailboxes. In that case you have to add the transport along with the transports of your setup, whatever that be.
  53. If the e-mail gets to the binary and nothing happens, make sure:
  54. - the binary is executable and readable by the pipe's user
  55. - the configuration file is in the same directory as the binary
  56. - that in `master.cf` there are no `flags=` in the transport entry. The mail must be piped unaltered.
  57. - your auth token works. You can check yourself by issuing requests to your API via cURL. There are examples here: https://docs.gitea.io/en-us/api-usage/
  58. If commands (using +reply, +close etc) don't work, make sure you have added `recipient_delimiter = +` in your `main.cf` file.
  59. The bot's state is saved in a sqlite3 database in the same directory as the binary. You can view its data by using the `sqlite3` cli tool:
  60. ```shell
  61. root# sqlite3 /home/issuebot/sqlite3.db
  62. SQLite version ****** ********** ********
  63. Enter ".help" for usage hints.
  64. sqlite> .tables
  65. issue
  66. sqlite> select * from issue;
  67. 1|Name <add@res.tld>|1F:|2019-09-29T12:20:21.658495173Z|0|1|issue title|"2019-09-29T15:20:21+03:00"
  68. 2|Name <add@res.tld>|{^D0u|2019-09-29T12:23:48.291970808Z|0|1|issue title#2|"2019-09-29T15:23:48+03:00"
  69. 3|Name <add@res.tld>|Gd)i]|2019-09-29T12:24:31.414792595Z|0|1|issue title again|"2019-09-29T15:26:53+03:00"
  70. 4|Name <add@res.tld>|$3fBוv|2019-09-29T12:28:21.187425505Z|1|1|many issues|"2019-09-29T15:28:21+03:00"
  71. ```
  72. ## Demo
  73. My email:
  74. ```e-mail
  75. Date: Fri, 20 Sep 2019 20:12:21 +0300
  76. From: me@domain.tld
  77. To: issues@git.tld
  78. Subject: Issue title
  79. Issue body text, with formatting.
  80. ```
  81. The reply I get:
  82. ```e-mail
  83. Date: Fri, 20 Sep 2019 20:12:21 +0300
  84. From: issues@git.tld
  85. To: me@domain.tld
  86. <--8<--->
  87. Subject: [issue-bot-issues] Issue `Issue title` successfully created
  88. Hello,
  89. You have successfully submitted an issue titled "Issue title". Your issue can be found at
  90. https://git.tld/epilys/test/issues/24
  91. You will receive replies from other users. To unsubscribe from the conversation, send an email to issues+5590e09e-b6da-419b-b8d9-e86852d8d6b1+unsubscribe@git.tld.
  92. To reply to other users or post new comments, send your text to issues+5590e09e-b6da-419b-b8d9-e86852d8d6b1+reply@git.tld.
  93. To close the issue, send an email to issues+5590e09e-b6da-419b-b8d9-e86852d8d6b1+close@git.tld.
  94. Please keep this email in order to be able to keep in touch with your issue.
  95. This is an automated email from IssueBot <issues+help@git.tld>
  96. ```
  97. A reply notice sent for subscribed issues:
  98. ```e-mail
  99. Date: Fri, 20 Sep 2019 21:06:56 +0300
  100. From: issues@git.tld
  101. To: me@domain.tld
  102. Subject: [issue-bot-issues] new replies in issue `Issue title`
  103. Hello,
  104. There have been new replies in issue `Issue title`. You are receiving this notice because you are subscribed to the discussion. To unsubscribe, send an email to issues+5590e09e-b6da-419b-b8d9-e86852d8d6b1+unsubscribe@git.tld
  105. me@domain.tld replies:
  106. This is my reply
  107. This is an automated email from IssueBot <issues+help@git.tld>
  108. ```