Authelia 开发工具 authelia-gen github issue-templates 命令详解：自动生成 GitHub Issue 模板
【免费下载链接】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-gen是 Authelia 仓库内置的代码与文档生成器，而authelia-gen github issue-templates是其下负责自动生成 GitHub Issue 模板文件的子命令。本文围绕该命令的完整 CLI 参考文档展开，先给出用法与全部参数说明，再结合 cmd_github.go 与 templates 中的源码实现，剖析模板渲染、标签注入与版本列表生成的底层逻辑，最后对照生成产物 .github/ISSUE_TEMPLATE 说明实际效果，帮助你理解 Authelia 如何以"代码生成"方式维护高质量的社区反馈渠道。
一、命令概览与作用
authelia-gen github issue-templates属于authelia-gen的github命令族，其职责在命令的 Short 描述中写得很明确：
Generate GitHub issue templates
即：生成 GitHub Issue 模板。它不是一个直接输出到终端文本的命令，而是把预置的 Go 文本模板渲染为仓库根目录下.github/ISSUE_TEMPLATE/中的 YAML 表单文件，供 GitHub 仓库的 Issue 创建流程使用。
从源码结构看，该命令的完整层级为：
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这一层级关系在 cmd_github.go 中通过三次cmd.AddCommand调用构建：newGitHubCmd()注册github命令，newGitHubIssueTemplatesCmd()注册issue-templates，后者再挂载bug-report与feature-request两个叶子子命令；同时仓库测试 cmd_root_test.go 断言github命令的子命令列表正是["issue-templates"]，验证了该命令结构。
二、命令用法
authelia-gen github issue-templates [flags]与许多只承担"命令分组"职责的中间命令一样，issue-templates自身的选项只有一个帮助选项，真正的功能逻辑在它的两个子命令中，但所有可用的全局/父级选项同样对本命令生效。
命令自身选项
| 选项 | 说明 |
|---|---|
-h, --help | 显示issue-templates命令的帮助信息 |
子命令
| 子命令 | 功能 |
|---|---|
authelia-gen github issue-templates bug-report | 生成 GitHub bug report issue 模板（默认输出 .github/ISSUE_TEMPLATE/bug-report.yml） |
authelia-gen github issue-templates feature-request | 生成 GitHub feature request issue 模板（默认输出 .github/ISSUE_TEMPLATE/feature-request.yml） |
三、从父命令继承的选项
作为authelia-gen的子命令，issue-templates会自动继承根命令newRootCmd()中注册的全部持久化选项（persistent flags），这些选项在文档中一一列出。它们按用途可分为四组：
1. 仓库与目录定位
| 选项 | 默认值 | 说明 |
|---|---|---|
-C, --cwd string | （空） | 为 git 命令设置工作目录（CWD），影响版本标签的获取 |
-d, --dir.root string | ./ | 仓库根目录 |
--dir.authentication string | internal/authentication | authentication 目录（相对仓库根） |
--dir.schema string | internal/configuration/schema | schema 目录（相对仓库根） |
--dir.web string | web | web 目录（相对仓库根） |
--dir.locales string | internal/server/locales | locales 目录（相对仓库根） |
2. 文档（docs）相关目录
| 选项 | 默认值 | 说明 |
|---|---|---|
--dir.docs string | docs | docs 目录 |
--dir.docs.adr string | reference/architecture-decision-log | ADR 数据目录 |
--dir.docs.cli-reference string | reference/cli | CLI 参考 markdown 存放目录 |
--dir.docs.content string | content | docs 内容目录 |
--dir.docs.data string | data | docs 数据目录 |
--dir.docs.static string | static | docs 静态文件目录 |
--dir.docs.static.json-schemas string | schemas | docs 静态 JSONSchema 文件目录 |
3. 文件路径
| 选项 | 默认值 | 说明 |
|---|---|---|
--file.bug-report string | .github/ISSUE_TEMPLATE/bug-report.yml | bug report issue 模板文件路径 |
--file.feature-request string | .github/ISSUE_TEMPLATE/feature-request.yml | feature request issue 模板文件路径 |
--file.commit-lint-config string | commitlint.config.mjs | commit lint JavaScript 配置文件（相对仓库根） |
--file.configuration-keys string | internal/configuration/schema/keys.go | 配置键文件路径 |
--file.docs-commit-msg-guidelines string | docs/content/contributing/guidelines/commit-message.md | 提交信息规范文档（相对仓库根） |
--file.docs.data.keys string | configkeys.json | docs 键数据文件路径 |
--file.docs.data.languages string | languages.json | docs 语言数据文件（相对 docs data 目录） |
--file.docs.data.misc string | misc.json | docs misc 数据文件（相对 docs data 目录） |
--file.docs.static.json-schemas.configuration string | configuration | 配置 JSONSchema 文件路径 |
--file.docs.static.json-schemas.exports.identifiers string | exports.identifiers | identifiers 导出 JSONSchema 路径 |
--file.docs.static.json-schemas.exports.totp string | exports.totp | TOTP 导出 JSONSchema 路径 |
--file.docs.static.json-schemas.exports.webauthn string | exports.webauthn | WebAuthn 导出 JSONSchema 路径 |
--file.docs.static.json-schemas.user-database string | user-database | 用户数据库 JSONSchema 路径 |
--file.scripts.gen string | cmd/authelia-scripts/cmd/gen.go | authelia-scripts gen 文件路径 |
--file.server.generated string | internal/server/gen.go | server 生成文件路径 |
--file.web.i18n string | src/i18n/index.ts | web 目录下 i18n TypeScript 配置文件 |
--file.web.package string | package.json | web 目录下 node 包配置文件 |
4. 生成行为开关与元数据
| 选项 | 默认值 | 说明 |
|---|---|---|
-X, --exclude strings | （空） | 设置被排除的生成器名称 |
--latest | false | 启用 latest 功能（影响 JSON Schema 等生成器） |
--next | false | 启用 next 功能（影响 JSON Schema 等生成器） |
--package.configuration.keys string | schema | 键文件的包名 |
--package.scripts.gen string | cmd | authelia-scripts gen 文件的包名 |
--version-count int | 5 | 输出模板中列出的最大 minor 版本数量 |
--versions strings | （空） | 指定生成器运行的版本，特殊值current与next互斥 |
说明：上表中的目录类默认值均为相对值，实际拼接根目录后构成完整路径。其中与 Issue 模板生成直接相关的核心选项是
--file.bug-report、--file.feature-request、--version-count、-C/--cwd与-d/--dir.root；其余选项多被authelia-gen的其他生成器（如 docs、JSON Schema、i18n）复用，属于全局共享的持久化参数。
四、源码级实现原理
1. 命令注册与执行入口
两个子命令的执行函数分别是cmdGitHubIssueTemplatesFeatureRunE与cmdGitHubIssueTemplatesBugReportRunE，均位于 cmd_github.go。二者的整体流程一致：
- 读取
--cwd、--dir.root、对应--file.*路径与--version-count等标志； - 调用
getGitTags(cwd)执行git tag --sort=-creatordate获取按创建时间倒序排列的版本标签； - 用
model.NewSemanticVersion解析标签构造语义版本对象； - 组装模板数据
tmplIssueTemplateData； - 执行 Go
text/template渲染并把结果写入目标文件。
模板文件通过//go:embed templates/*打包进二进制，相关注册见 templates.go：
tmplGitHubIssueTemplateBug = template.Must(newTMPL("github_issue_template_bug_report.yml")) tmplIssueTemplateFeature = template.Must(newTMPL("github_issue_template_feature.yml"))2. 模板数据结构
渲染所需数据由 types.go 中的结构体承载：
type tmplIssueTemplateData struct { Labels []string Versions []string Proxies []string }Labels：注入 Issue 模板 front matter 中的标签列表；Versions：注入"版本"下拉框的候选版本列表；Proxies：注入"反向代理"下拉框的候选代理列表（仅 bug-report 模板使用）。
3. 版本列表的两种计算策略
这是整个命令最有意思的部分：同一个--version-count标志，在两个子命令中含义截然不同。
feature-request 生成的是"未来版本"（cmd_github.go）：以最新 git tag 的Major.Minor为基准，依次生成Minor+1、Minor+2……共versions个未来版本号。例如最新稳定版为v4.39.x且--version-count=5时，会生成v4.40、v4.41、v4.42、v4.43、v4.44。这样做的意图是：提交功能请求的人可以声明该功能期望进入哪个未来版本。
bug-report 生成的是"最近支持版本"（cmd_github.go）：先以最新版本为基准，令Patch=0、Minor -= versions得到一个最低版本阈值minimum；随后遍历所有 git tag，跳过非稳定版本（version.IsStable()为假则忽略），只保留version.GreaterThanOrEqual(minimum)的稳定版本，并按创建时间倒序填入下拉框。因此--version-count=5意味着"列出最近 5 个 minor 版本线内的全部稳定补丁版本"。这一点在仓库产物中得到验证：当前 .github/ISSUE_TEMPLATE/bug-report.yml 中版本选项覆盖了v4.39.24至v4.34.x的数十个稳定版本，数量远大于 5，因为同一 minor 线内的所有 patch 版本都被保留。
4. 标签（Labels）的注入机制
两个模板的 labels 由代码直接拼装（cmd_github.go 与 cmd_github.go）：
- bug-report：
type/bug/unconfirmed+status/needs-triage+priority/4/normal - feature-request：
type/feature+status/needs-design+priority/4/normal
这些标签并非硬编码字符串，而是通过 types.go 中的枚举类型labelPriority、labelStatus、labelType及其String()方法格式化生成。格式化规则（labelFormatString）会把": "替换为/、空格替换为-并转小写，例如Bug: Unconfirmed→type/bug/unconfirmed、Needs Triage→status/needs-triage、priority 序号 4 + Normal→priority/4/normal。这意味着只要调整枚举定义并重新运行生成器，所有模板的标签即可一次性同步更新，这正是用代码生成维护 Issue 模板的核心价值。相关枚举的完整性由 types_test.go 覆盖。
5. 模板渲染细节
- bug-report 模板（github_issue_template_bug_report.yml.tmpl）产出一个包含 14 个表单块的完整 YAML：开头的 markdown 引导说明、Version / Deployment Method / Reverse Proxy 三个下拉框、Reverse Proxy Version 输入框、Description / Reproduction / Expectations / Configuration / Build Information / Logs 等文本域，以及 Generative AI 下拉框和 8 项 Pre-Submission Checklist 复选框。
- feature-request 模板（github_issue_template_feature.yml.tmpl）结构更轻量：markdown 引导、Description / Use Case / Details / Documentation 四个文本域、Generative AI 下拉框与 2 项 checklist 复选框。
- 反向代理候选列表在代码中以硬编码数组提供（cmd_github.go）：
Caddy、Traefik、Envoy、Istio、NGINX、SWAG、NGINX Proxy Manager、HAProxy——这与 Authelia 作为 Web 应用前置 SSO 门户、常部署于各类反向代理之后的典型场景相匹配。 - 两个模板的 checklist 都要求提交者确认遵循 Code of Conduct、已查阅相关 issue 与文档，其中 bug-report 额外要求提交者确认已阅读安全策略、提供完整配置文件或说明与配置无关、提供完整 debug/trace 日志或
build-info输出等，从流程上强制保证 Issue 信息质量。
五、实际生成产物
运行该命令后，仓库根目录下会生成（或覆盖）以下文件：
| 生成文件 | 对应子命令 | 说明 |
|---|---|---|
| .github/ISSUE_TEMPLATE/bug-report.yml | authelia-gen github issue-templates bug-report | Bug 报告表单 |
| .github/ISSUE_TEMPLATE/feature-request.yml | authelia-gen github issue-templates feature-request | 功能请求表单 |
| .github/ISSUE_TEMPLATE/config.yml | （静态文件） | Issue 流程辅助配置，如链接到讨论区 |
例如执行：
authelia-gen github issue-templates bug-report --version-count 5即以最近 5 个 minor 版本线内的全部稳定标签生成新版 bug 报告模板，产物 front matter 形如：
name: 'Bug Report' description: 'Report a bug' labels: - 'type/bug/unconfirmed' - 'status/needs-triage' - 'priority/4/normal'由于渲染结果直接覆盖.github/ISSUE_TEMPLATE/下的文件，该命令适合在每次发布新版本后由维护流程自动执行，从而让版本下拉框始终与仓库真实 git tag 保持同步，避免人工编辑 YAML 带来的遗漏与格式错误。
六、相关命令
- authelia-gen github —
github父命令，Generate GitHub files - authelia-gen github issue-templates bug-report — 生成 GitHub bug report issue 模板
- authelia-gen github issue-templates feature-request — 生成 GitHub feature request issue 模板
七、小结
authelia-gen github issue-templates展示了 Authelia 工程化维护社区流程的一贯思路：把模板、标签、版本清单全部沉淀为代码与模板文件，用git tag作为版本事实来源，用text/template渲染统一格式的 YAML 表单。理解它的参数体系与实现路径，不仅能在本地复现.github/ISSUE_TEMPLATE的生成过程，也能为自建项目的 Issue 模板自动化提供可借鉴的范本——核心入口在 cmd_github.go，模板定义在 templates 目录，生成结果可在 .github/ISSUE_TEMPLATE 中直接查看。
【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
