ticgithub

使用GitHub仓库作为工单系统的工具。

我们有一个共享的收件箱，流量不多（不足以证明花费$​$​$​$购买电子邮件工单解决方案的合理性），但所有进入该收件箱的电子邮件都必须及时响应。

我们的需求基本上是

• 将电子邮件分配给个人的能力，并通知该人他们已被分配。
• 一眼就能看到哪些电子邮件尚未分配。
• 一些自动化确保我们被提醒任何未分配的电子邮件。
• 一些自动化确保一旦工单被分配，就及时关闭。

这里提出的解决方案是使用GitHub问题作为工单管理系统。这允许在GitHub上正常分配和通知。使用GitHub Actions工作流程来检查电子邮件，并将任何新的电子邮件作为问题发布，如果问题尚未关闭/分配，则提醒团队。

设置

配料

• 一个收件箱，您在这里接收支持电子邮件。目前必须是GMail。
• 一个机器人，由GitHub用户帐户和（可选）SMTP帐户组成。
• 一个存储支持工单的仓库。

收件箱设置

一些当前的工作流程使用了一些GMail特定的IMAP扩展（特别是标签），因此只有GMail完全受支持。

要使用您现有的GMail账户，您需要提供一个应用密码，这目前需要启用两步验证。您还需要在账户中启用IMAP。具体来说

1. 启用IMAP，针对与您的收件箱关联的GMail账户。
2. 开启两步验证，针对该Google账户。
3. 添加应用密码。使用自定义名称；名称的值不重要（例如，您可以使用"ticgithub"或"Support Repository"或任何您想要的东西）。记录此密码；您稍后需要将其添加为GitHub密钥。
4. 在您的账户中创建标签来表示分配。我建议在assigned标签下创建嵌套标签，例如，assigned/dwhswenson。

机器人设置

该机器人由可选的SMTP账户和GitHub用户账户组成。机器人的SMTP账户用于向团队发送电子邮件（例如，在帖子中回复以提供相关GitHub问题的链接）。在大多数情况下，让机器人拥有自己的电子邮件地址，并使用该地址注册机器人的GitHub账户似乎是合理的。

您需要

1. 为机器人创建一个电子邮件账户。如果您使用GMail，您将不得不按照“收件箱设置”下描述的步骤设置应用密码。
2. 为机器人创建一个GitHub账户。

创建存储库后（见下文），您还需要使用

存储库设置

这是一个标准的GitHub存储库。当前方法假设所有问题都是应由机器人管理的支持票据（带有提醒等），因此在这个阶段建议将此存储库与核心开发存储库分开。该存储库可以是私有的，尽管使用ticgithub工作流程将减少您每月分配的GitHub Actions分钟数。

要设置存储库

1. 创建存储库。

2. 授予您的机器人对存储库的写权限。

3. 创建机器人的个人访问令牌（PAT），并授予对存储库的访问权限。这需要在机器人的GitHub账户内完成。

4. 添加密钥到GitHub存储库。密钥的名称可以自定义，并将作为配置文件的输入，但您需要为以下每个项目存储一个密钥：

   • 您的收件箱的应用密码
   • 您的机器人的SMTP账户密码（如果使用sendmail功能）
   • 机器人具有对存储库写访问权限的个人访问令牌

配置

ticgithub通过存储在问题存储库根目录下的.ticgithub.yml文件中的YAML文件进行配置。此文件由两个主要的设置组组成：config，它定义了收件箱、机器人和您的团队，以及workflows，它为通过python -m ticgithub.build命令安装的工作流程提供具体的说明。

收件箱配置

收件箱是您希望将其转换为GitHub问题的邮箱。它有以下条目

• type：目前，必须是gmail
• user：用户名，例如，inboxaddress@gmail.com
• secret：包含应用密码的GitHub密钥名称
• host：对于Gmail，imap.gmail.com

机器人配置

机器人执行向存储库写入和向共享收件箱发送电子邮件以链接到新存储库问题的操作。因此，您必须定义机器人的GitHub用户和sendmail用户。如果您不使用sendmail功能（reply-inbox: active: false）您仍然必须定义sendmail信息，但它不必是有效的。例如，您可以使用user: foo和secret: not_registered_in_github。

• token_name：包含机器人PAT的GitHub密钥名称（可能仅限于单个仓库）
• repo：机器人应管理的仓库的完整名称（owner/repository）。
• sendmail：sendmail用户信息，包含以下内容
  • user：sendmail用户名，例如，botaddress@gmail.com
  • secret：包含sendmail密码的GitHub密钥名称
  • host：sendmail主机名，例如，smtp.gmail.com

团队配置

config下的team参数是一个团队成员列表。每个团队成员应具有以下键

• github：GitHub用户名，例如，dwhswenson
• email：足以唯一识别用户的电子邮件地址的一部分（不必是完整电子邮件），例如，david.swenson
• label：在Gmail收件箱中创建的标签，以指示该用户已被分配，例如，assigned/dwhswenson

工作流程配置

每个工作流程都是.ticgithub.yml中的workflows内的一个键。键的名称必须与工作流程的名称匹配。

• active：布尔值，确定工作流程是否激活。如果工作流程在配置中列出且未显式列出active，则假定active == true。
• dry：布尔值，确定是否进行干运行。默认值为false

电子邮件到问题

这是一个将您的收件箱转换为GitHub问题的流程。这是一个计划工作流程，但也可以使用workflow_dispatch事件手动运行。

其参数如下

• active：布尔值，确定工作流程是否激活。如果工作流程在配置中列出且未显式列出active，则假定active == true。
• dry：布尔值，确定是否进行干运行。默认值为false
• cron：此工作流程应运行时的crontab条目
• filters：要排除创建问题的电子邮件的过滤器列表，选项有
  • 机器人过滤器：过滤来自机器人sendmail地址的电子邮件
    • 名称：机器人
    • active：是否使用过滤器；默认值为true
  • 团队过滤器：是否过滤来自团队但不是直接发送到（即抄送、密送）收件箱的电子邮件
    • 名称：团队
    • active：是否使用过滤器；默认值为true
  • 省略发送者过滤器：过滤包含特定字符串的电子邮件
    • 名称：omit-senders
    • active：是否使用过滤器；默认值为true
    • senders：字符串列表；任何匹配此字符串的发送者都不会生成问题
  • recent：表示电子邮件应加载的时间间隔（向下取整到天）。参数与datetime.timedelta的参数匹配（即days、hours、minutes、seconds等）
  • reply-inbox：向收件箱发送回复的参数，以指示已为此电子邮件创建了GitHub问题
    • active：是否发送电子邮件；默认值为true
    • template：用于回复电子邮件的string.Template格式的文件。允许的键
      • $GITHUB_URL：问题的URL

未分配提醒

此工作流程会在一段时间后提醒未分配的问题。这是一个计划工作流程，但也可以使用workflow_dispatch事件手动运行。

其参数如下

• active：布尔值，确定工作流程是否激活。如果工作流程在配置中列出且未显式列出active，则假定active == true。
• dry：布尔值，确定是否进行干运行。默认值为false
• cron：此工作流程应运行时的crontab条目
• email-ticket-only：是否仅对看起来是由emails-to-issues任务创建的问题进行注释。
• delay：时间间隔，任何未分配且超过此时间的问题都将触发提醒评论。参数与datetime.timedelta的参数匹配（即days、hours、minutes、seconds等）
• template：用于回复电子邮件的string.Template格式的文件。允许的键：（尚未定义）
• notify：要提及在评论中的附加GitHub用户/团队名称（无需@）的列表

未关闭提醒

此工作流在一段时间后未关闭分配的问题时，会发布一条评论以提醒。这是一个计划的工作流，但也可以使用 workflow_dispatch 事件手动运行运行。

其参数如下

• active：布尔值，确定工作流程是否激活。如果工作流程在配置中列出且未显式列出active，则假定active == true。
• dry：布尔值，确定是否进行干运行。默认值为false
• cron：此工作流程应运行时的crontab条目
• email-ticket-only：是否仅对看起来是由emails-to-issues任务创建的问题进行注释。
• delay：时间差，任何在最后分配事件之前超过此时间仍然打开的问题都将触发提醒评论。参数与datetime.timedelta相同（即days、hours、minutes、seconds等）。
• template：用于回复电子邮件的string.Template格式的文件。允许的键：（尚未定义）
• notify：要提及在评论中的附加GitHub用户/团队名称（无需@）的列表

assignment-to-gmail

此工作流在问题被分配时立即触发。

其参数如下

• active：布尔值，确定工作流程是否激活。如果工作流程在配置中列出且未显式列出active，则假定active == true。
• dry：布尔值，确定是否进行干运行。默认值为false

构建时间与运行时间配置

一些参数在ticgithub.build过程中用于创建GHA工作流。这些参数是构建时间参数。其他参数在流程运行期间使用。这些是运行时参数。

如果更改构建时间参数，您将需要重新运行ticgithub.build过程。如果不清楚，重新运行ticgithub.build永远不会造成问题，并且可能会更新您的流程以适应新更改。

大多数参数是运行时参数。例外情况是

• 更改secret（在config中）的名称始终是构建时间参数。
• 对于计划的工作流，更改cron计划始终是构建时间参数。

"安装" / 使用

一旦您创建了您的.ticgithub.yml文件，您就可以使用ticgithub根据您的配置创建GHA工作流。在您的本地机器上，在您问题仓库的克隆中，将ticgithub安装到当前环境中。

python -m pip install ticgithub

从您问题仓库克隆的根目录中，运行以下命令：

python -m ticgithub.build

这将创建相关的工作流。确保它们被添加到git提交中，并推送到默认分支，这样您就有了一个正在运行的ticgithub！

本地运行任务

您也可以在本地运行任何内置任务。为此，例如使用：

python -m ticgithub.tasks.emails_to_issues

您需要设置GitHub Actions的秘密的环境变量。为此，在命令行上临时设置变量，只需在命令前设置变量即可

INBOX_PASSWORD="password" SENDMAIL_PASSWORD="password" BOT_TOKEN="token" python -m ticgithub.tasks.emails_to_issues

您可以通过传递--dry选择进行干燥运行。您可以通过--config或-c选择特定的配置文件（除./.ticgithub.yml之外）。

assignment-to-gmail任务需要额外的参数，例如问题编号：

python -m ticgithub.tasks.assignment_to_gmail --dry 99

自定义构建过程

可以根据构建配置YAML文件进一步自定义构建过程。默认构建配置在ticgithub/data/build_config.yml。这允许自定义build命令生成的文件。有两种自定义类别：自定义ticgithub本身，以及自定义builders标题下的单个工作流。

在ticgithub标题下

• install：运行以安装ticgithub的命令
• suffix：后缀（用于区分相同工作流的多个副本）
• force-dry：要求所有命令都使用--dry标志运行
• install-path：安装GitHub Actions工作流的路径

在builders标题下包含一个列表，其中每个条目都是一个工作流。对于每个工作流，应包括以下键

• config-name：配置中使用的流程名称
• run-command：为此流程运行的命令
• template：为此流程使用的模板文件；默认情况下，首先检查提供的值是否为存在的路径，如果不是，则在ticgithub/data/workflows/中检查
• build-params：为此工作流程从主配置文件中获取的构建时间参数。这些是键值对，其中配置文件中参数的名称作为键，模板文件中的替换变量（不带初始的$）作为值。