企业官网建设流程全解析

Authelia authelia-gen github 命令完全指南：自动化生成 GitHub 问题模板

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia

Authelia 项目使用自研的代码生成器authelia-gen维护仓库内大量需要与代码、文档、版本号保持同步的衍生文件。其中authelia-gen github子命令专门负责生成 GitHub 相关的仓库文件——最核心的是 Bug 报告与 Feature Request 两类 Issue 模板。本文以 authelia-gen_github.md 为骨架，结合 cmd_github.go 源码，讲解该命令的完整语法、全部参数、底层实现原理以及实际使用方式，帮助你理解 Authelia 如何把「版本号驱动的 Issue 模板」变成可重复执行的构建流程。

authelia-gen github 在工具链中的定位

authelia-gen是 Authelia 的生成器工具（generator tooling），其根命令注册了多个子命令，覆盖代码、文档、locale、提交规范、GitHub 文件等生成任务。从 cmd_root.go 可以看到，根命令通过cmd.AddCommand挂载了code、contributors、docs、github、locales、commit-lint、misc、release共 8 个子命令：

• authelia-gen github— 生成 GitHub 相关文件（本文主题）
• authelia-gen code— 生成代码
• authelia-gen docs— 生成文档
• authelia-gen release— 准备发布版本

github子命令本身是一个纯分组命令（grouping command），自身没有执行逻辑，其RunE直接复用rootSubCommandsRunE，真正的生成逻辑都在它下面的二级、三级子命令中。命令树结构如下：

authelia-gen └── github # Generate GitHub files └── issue-templates # Generate GitHub issue templates ├── bug-report # Generate GitHub bug report issue template └── feature-request # Generate GitHub feature request issue template

命令语法与基本用法

authelia-gen github [flags]

该命令在仓库根目录下直接执行即可，默认路径参数均指向仓库内的标准目录结构。查看帮助：

authelia-gen github --help

一个典型用法是仅生成 Bug 报告模板：

authelia-gen github issue-templates bug-report

或者仅生成 Feature Request 模板：

authelia-gen github issue-templates feature-request

生成结果默认写入.github/ISSUE_TEMPLATE/bug-report.yml与.github/ISSUE_TEMPLATE/feature-request.yml（路径可通过--file.bug-report、--file.feature-request覆盖）。

参数详解

authelia-gen github自身只有一个-h, --help参数；其余参数全部继承自父命令authelia-gen（在 cmd_root.go 中通过PersistentFlags注册，因此对包括github在内的所有子命令均生效）。

自身参数

继承自父命令的参数

在这些参数中，与github子命令直接相关的关键参数有三个：

• --file.bug-report：控制 Bug 报告模板的输出路径；
• --file.feature-request：控制 Feature Request 模板的输出路径；
• --version-count：控制模板版本下拉框中列出的版本数量；
• -C, --cwd：指定 git 命令执行目录，用于读取 git tags；
• -d, --dir.root：指定仓库根目录，用于拼接输出文件路径。

源码级实现解析

命令树注册

在 cmd_github.go 中，newGitHubCmd创建github命令并挂载issue-templates子命令；issue-templates又挂载bug-report与feature-request两个叶节点命令。这些命令均设置了DisableAutoGenTag: true，避免 Cobra 在帮助信息中自动附加生成标记。命令常量定义在 const.go（cmdUseGitHub = "github"、cmdUseGitHubIssueTemplates = "issue-templates"等）。

模板渲染机制

模板通过 Go 的embed.FS嵌入二进制，在 templates.go 中注册了两个与 GitHub 相关的模板：

tmplGitHubIssueTemplateBug = template.Must(newTMPL("github_issue_template_bug_report.yml")) tmplIssueTemplateFeature = template.Must(newTMPL("github_issue_template_feature.yml"))

模板数据模型定义在 types.go：

type tmplIssueTemplateData struct { Labels []string Versions []string Proxies []string }

模板源文件分别为：

• templates/github_issue_template_feature.yml.tmpl
• templates/github_issue_template_bug_report.yml.tmpl

Feature Request 生成逻辑

cmdGitHubIssueTemplatesFeatureRunE（cmd_github.go）的执行流程：

1. 读取--cwd、--dir.root、--file.feature-request、--version-count参数；
2. 调用getGitTags(cwd)获取仓库 git tags；
3. 取最新的 tag 解析为语义化版本，向后生成version-count个未来的 minor 版本号（形如vX.Y.0）；
4. 在root与file拼接的路径上创建文件；
5. 以{Labels, Versions}渲染 Feature 模板，其中 Labels 固定为：

type/feature status/needs-design priority/3/normal

从 types.go 可以推断，label 字符串由labelFormatString统一格式化：": "替换为/、空格替换为-并转小写。例如labelPriorityNormal输出priority/3/normal，labelStatusNeedsDesign输出status/needs-design，labelTypeFeature输出type/feature。

Bug Report 生成逻辑

cmdGitHubIssueTemplatesBugReportRunE（cmd_github.go）的流程略有不同：

1. 读取同样的四类参数；
2. 获取 git tags 后，取最新 tag 作为基准，将minor减去version-count、patch归零，得到「最低受支持版本」；
3. 遍历所有 tags，只保留满足以下条件的版本：
   • 非空字符串；
   • 是稳定版本（!version.IsStable()的跳过）；
   • 版本号>=最低受支持版本；
4. 在目标路径创建文件，以{Labels, Versions, Proxies}渲染 Bug 模板，其中 Labels 固定为：

type/bug-unconfirmed status/needs-triage priority/3/normal

Proxies 固定为 Authelia 官方支持与常见部署场景的 9 种反向代理：

Caddy, Traefik, Envoy, Istio, NGINX, SWAG, NGINX Proxy Manager, HAProxy

git tags 读取

getGitTags（cmd_github.go）通过exec.Command执行：

git [-C <cwd>] tag --sort=-creatordate

按创建时间倒序输出全部 tag，再以换行符切分为切片。这就是为什么该命令要求在一个 git 仓库内运行——版本号是模板内容的直接数据源。

生成的 Issue 模板结构

Bug Report 模板

bug-report.yml 模板 生成的表单字段（对应 GitHub Issue Form YAML 语法）：

• Version（下拉框，多选，必填）：由--version-count与 git tags 共同决定，仅列出仓库中「仍受支持」的稳定版本；
• Deployment Method（下拉框，必填）：Docker / Kubernetes / Bare-metal / Other；
• Reverse Proxy（下拉框，必填）：渲染 Proxies 列表（Caddy、Traefik、Envoy、Istio、NGINX、SWAG、NGINX Proxy Manager、HAProxy）；
• Reverse Proxy Version（输入框，可选，占位符x.x.x）；
• Description（多行文本，必填）；
• Reproduction（多行文本，必填）：要求逐步、具体地描述复现过程；
• Expectations（多行文本，可选）；
• Configuration (Authelia)（多行文本，YAML 渲染，可选）：要求提供完整配置文件；
• Build Information（多行文本，shell 渲染，必填）：要求粘贴authelia build-info命令输出；
• Logs (Authelia)（多行文本，shell 渲染，必填）：要求提供从启动到问题发生的完整 debug/trace 日志；
• Logs (Proxy / Application)（多行文本，shell 渲染，可选）；
• Documentation（多行文本，可选）；
• Generative AI（下拉框，必填）：是否使用了生成式 AI；
• Pre-Submission Checklist（复选框，全部必选）：包含遵守行为准则、确认非安全漏洞、提供完整配置或日志、按规范脱敏等 9 项确认。

模板开头的 markdown 说明区还会引导用户：安全漏洞应走安全政策渠道而非 Issue；只接受已发布的稳定版本；第三方软件 Bug 与文档错误应通过 Discussion 提交等。

Feature Request 模板

feature-request.yml 模板 生成的表单字段：

• Description（多行文本，必填）：描述功能；
• Use Case（多行文本，必填）：提供使用场景；
• Details（多行文本，可选）：详细描述功能；
• Documentation（多行文本，可选）：相关规范或文档；
• Generative AI（下拉框，必填）：是否使用了生成式 AI；
• Pre-Submission Checklist（复选框，全部必选）：遵守行为准则、已检查相关 Issue 与文档。

注意 Feature 模板的数据结构（Labels、Versions）中，Versions是「未来版本」——用于让用户勾选希望在哪一个未来版本中看到该功能落地。

为什么用生成器维护 Issue 模板

从实现可以看出，Authelia 把 Issue 模板当作「需要与仓库状态同步的构建产物」来管理，而不是手工维护的静态文件。这样做的收益体现在：

• 版本列表永不漂移：Bug 报告中的版本下拉框由git tag --sort=-creatordate实时推导，发布新版本后重新运行生成器即可自动更新，无需人工编辑 YAML；
• 支持范围策略集中化：--version-count（默认 5）统一控制「仍受支持」的 minor 版本范围，策略变更只需改一处参数；
• label 与流程强一致：模板中的type/*、status/*、priority/*label 由同一套类型系统（types.go）生成，避免手写 label 拼写不一致导致的问题分类失效；
• 多仓库路径可移植：所有路径参数均可覆盖，-d指定根目录、-C指定 git 目录，可在 CI 或本地对任意 checkout 运行。

实际操作示例

在仓库根目录生成全部 GitHub 文件（等价于分别运行两个子命令）：

authelia-gen github

自定义输出路径并控制版本数量：

authelia-gen github issue-templates bug-report \ --dir.root . \ --file.bug-report .github/ISSUE_TEMPLATE/bug-report.yml \ --version-count 3

在非当前目录的仓库上运行（指定 git 工作目录与仓库根目录）：

authelia-gen github issue-templates feature-request \ -C /path/to/repo \ -d /path/to/repo

相关参考

• 命令总览：authelia-gen
• issue-templates 子命令：authelia-gen github issue-templates
• 核心实现：cmd_github.go、cmd_root.go、types.go
• 模板源文件：github_issue_template_bug_report.yml.tmpl、github_issue_template_feature.yml.tmpl
• 生成产物（实际应用的模板）：.github/ISSUE_TEMPLATE/bug-report.yml与.github/ISSUE_TEMPLATE/feature-request.yml

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia