Authelia 代码生成器 authelia-gen：`github issue-templates bug-report` 命令全解析

Authelia 代码生成器 authelia-gengithub issue-templates bug-report命令全解析【免费下载链接】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 github issue-templates bug-report是 Authelia 仓库内置的代码生成器authelia-gen提供的一条子命令用于自动生成 GitHub 仓库的 Bug Report缺陷报告Issue 模板文件默认输出为.github/ISSUE_TEMPLATE/bug-report.yml。该命令并非写死一份静态模板而是实时读取仓库 Git 标签、计算受支持版本列表与默认代理列表再通过 Go 模板引擎渲染出一份结构完整、自带标签、包含严格提交前置检查清单的bug-report.yml。阅读本文后你将掌握该命令的完整用法、全部参数含义、底层实现逻辑与调用链并能在本地复现生成过程、按需定制输出。本文以 authelia-gen_github_issue-templates_bug-report.md 为骨架结合仓库中 cmd_github.go、cmd_root.go、types.go 及模板文件 github_issue_template_bug_report.yml.tmpl 等源码进行纵深扩充。命令概览与定位bug-report位于authelia-gen命令树的第三层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从源码看newGitHubCmd 注册github子命令newGitHubIssueTemplatesCmd 注册issue-templates而 newGitHubIssueTemplatesBugReportCmd 则注册本命令bug-report。三者均设置了DisableAutoGenTag: true表明这些命令是手工定义、而非 Cobra 自动生成帮助页的命令。基本调用形式与文档一致authelia-gen github issue-templates bug-report [flags]其唯一专属选项是标准的帮助参数-h, --help help for bug-report继承自父命令的全局参数bug-report本身没有业务参数但会继承authelia-gen根命令的全部持久化参数Persistent Flags定义于 cmd_root.go。这些参数在本命令中真正被使用的有三个--cwd、--dir.root、--version-count以及输出文件路径参数--file.bug-report。其余参数属于其他生成器如文档、代码、JSON Schema 生成器所需此处一并继承但通常不会影响 bug-report 的输出。影响 bug-report 输出的核心参数参数简写默认值作用-C, --cwd string-C空设置执行git命令的工作目录CWD用于读取 Git 标签-d, --dir.root string-d./仓库根目录输出文件的基准路径--file.bug-report string—.github/ISSUE_TEMPLATE/bug-report.ymlBug Report Issue 模板文件的输出路径相对于dir.root--version-count int—5生成版本下拉列表时回溯的最大 minor 版本数量其中--file.bug-report与常量fileGitHubIssueTemplateBR定义于 const.go对应注册代码见 cmd_root.go。其他继承参数供参考不影响本命令--dir.authentication string The authentication directory in relation to the root (default internal/authentication) --dir.docs string The directory with the docs (default docs) --dir.docs.adr string The directory with the ADR data (default reference/architecture-decision-log) --dir.docs.cli-reference string The directory to store the markdown in (default reference/cli) --dir.docs.content string The directory with the docs content (default content) --dir.docs.data string The directory with the docs data (default data) --dir.docs.static string The directory with the docs static files (default static) --dir.docs.static.json-schemas string The directory with the docs static JSONSchema files (default schemas) --dir.locales string The locales directory in relation to the root (default internal/server/locales) --dir.schema string The schema directory in relation to the root (default internal/configuration/schema) --dir.web string The repository web directory in relation to the root directory (default web) -X, --exclude strings Sets the names of excluded generators --file.commit-lint-config string The commit lint javascript configuration file in relation to the root (default commitlint.config.mjs) --file.configuration-keys string Sets the path of the keys file (default internal/configuration/schema/keys.go) --file.docs-commit-msg-guidelines string The commit message guidelines documentation file in relation to the root (default docs/content/contributing/guidelines/commit-message.md) --file.docs.data.keys string Sets the path of the docs keys file (default configkeys.json) --file.docs.data.languages string The languages docs data file in relation to the docs data folder (default languages.json) --file.docs.data.misc string The misc docs data file in relation to the docs data folder (default misc.json) --file.docs.static.json-schemas.configuration string Sets the path of the configuration JSONSchema (default configuration) --file.docs.static.json-schemas.exports.identifiers string Sets the path of the identifiers export JSONSchema (default exports.identifiers) --file.docs.static.json-schemas.exports.totp string Sets the path of the TOTP export JSONSchema (default exports.totp) --file.docs.static.json-schemas.exports.webauthn string Sets the path of the WebAuthn export JSONSchema (default exports.webauthn) --file.docs.static.json-schemas.user-database string Sets the path of the user database JSONSchema (default user-database) --file.feature-request string Sets the path of the feature request issue template file (default .github/ISSUE_TEMPLATE/feature-request.yml) --file.scripts.gen string Sets the path of the authelia-scripts gen file (default cmd/authelia-scripts/cmd/gen.go) --file.server.generated string Sets the path of the server generated file (default internal/server/gen.go) --file.web.i18n string The i18n typescript configuration file in relation to the web directory (default src/i18n/index.ts) --file.web.package string The node package configuration file in relation to the web directory (default package.json) --latest Enables latest functionality with several generators like the JSON Schema generator --next Enables next functionality with several generators like the JSON Schema generator --package.configuration.keys string Sets the package name of the keys file (default schema) --package.scripts.gen string Sets the package name of the authelia-scripts gen file (default cmd) --versions strings The versions to run the generator for, the special versions current and next are mutually exclusive命令执行流程与源码级原理1. 读取参数命令入口为 cmdGitHubIssueTemplatesBugReportRunE。它依次读取四个关键参数--cwdcmdFlagCwdgit 命令的工作目录--dir.rootcmdFlagRoot仓库根目录--file.bug-reportcmdFlagBugReport输出文件路径--version-countcmdFlagVersionCount版本回溯数量。2. 读取 Git 标签并筛选版本调用 getGitTags 执行git [-C cwd] tag --sort-creatordate即按创建时间倒序取得全部标签取第一个标签最新的 tag解析为语义化版本latest。随后计算最低边界版本minimum : latest.Copy() minimum.Patch 0 minimum.Minor - versions // versions 即 --version-count默认 5即把latest的 Patch 清零、Minor 减去version-count得到minimum。接着遍历全部标签仅保留满足以下条件的版本进入tagsRecent列表能成功解析为语义化版本version.IsStable()为真跳过预发布/不稳定版本version.GreaterThanOrEqual(minimum)处于最近 N 个 minor 版本范围内。这些版本会最终渲染进模板的Version下拉框中保证 Issue 中只能选择已发布的稳定版本而不会出现 latest 这类占位值。语义化版本解析与比较复用的是 internal/model 包中的model.SemanticVersion见 cmd_github.go 的使用方式。3. 组装模板数据并渲染构造模板数据 tmplIssueTemplateDatadata : tmplIssueTemplateData{ Labels: []string{labelTypeBugUnconfirmed.String(), labelStatusNeedsTriage.String(), labelPriorityNormal.String()}, Versions: tagsRecent, Proxies: []string{Caddy, Traefik, Envoy, Istio, NGINX, SWAG, NGINX Proxy Manager, HAProxy}, }三个字段含义如下Labels写入 YAML 头部的labels列表。根据 types.go 中的标签定义这三者最终格式为labelTypeBugUnconfirmed→type/bug/unconfirmedlabelStatusNeedsTriage→status/needs-triagelabelPriorityNormal→priority/3/normal即新提交的 Bug Report 会自动带上类型Bug未确认状态待分流优先级普通三枚标签便于维护者按状态机管理。Versions上一步筛选出的稳定版本列表渲染为 Version 下拉选项。Proxies默认反向代理列表涵盖 Caddy、Traefik、Envoy、Istio、NGINX、SWAG、NGINX Proxy Manager、HAProxy 八个常见部署代理。模板本身通过//go:embed templates/*嵌入二进制templates.go 中注册tmplGitHubIssueTemplateBug template.Must(newTMPL(github_issue_template_bug_report.yml))模板文件为 github_issue_template_bug_report.yml.tmpl使用 Go 标准库text/template渲染并注入了joinX等辅助函数见 templates.go。4. 写出文件输出路径由filepath.Join(dirRoot, file)拼接dirRoot来自--dir.rootfile来自--file.bug-report随后os.Create创建文件并把渲染结果写入。默认情况下即生成.github/ISSUE_TEMPLATE/bug-report.yml。生成的模板内容详解渲染后的bug-report.yml遵循 GitHub Issues 的 YAML 表单规范包含前置说明、表单字段、提交前检查清单三个部分。以下是关键字段的完整说明对照模板源码 github_issue_template_bug_report.yml.tmpl头部与标签--- name: Bug Report description: Report a bug labels: - type/bug/unconfirmed - status/needs-triage - priority/3/normal引导说明markdown 字段模板在开头嵌入了一段 markdown 引导要求提交者遵守 7 条前置要求安全漏洞不得通过此渠道上报应走安全策略尽量提供足够信息以便复现与快速修复先确认不存在重复 Issue只允许填写已发布的稳定版本未发布、未打 tag 或 beta 版本应通过 Discussion 上报仅报告 Authelia 应用本身的 Bug——第三方软件问题、文档错误、功能理解偏差等应改走 Discussion阅读 Troubleshooting 参考指南日志不得随意截断按 Logs 章节要求提供完整日志若需脱敏请遵循 Sanitization 章节若为重定向类问题建议附带 HTTP Archive FileHAR。表单字段字段 ID控件类型是否必填说明versiondropdown必填可复现 Bug 的 Authelia 版本多选选项由生成器实时计算deploymentdropdown必填部署方式Docker / Kubernetes / Bare-metal / Otherproxydropdown必填反向代理选项来自源码中硬编码的 Proxies 列表proxy-versioninput可选反向代理版本placeholder 为x.x.xdescriptiontextarea必填描述 Bugreproductiontextarea必填分步复现步骤要求具体、详细避免抽象描述expectationstextarea可选期望结果configurationtextarearender: yaml可选完整 Authelia 配置文件模板自动放入 YAML 代码块build-infotextarearender: shell必填必须提供authelia build-info命令的输出logstextarearender: shell必填从应用启动到问题发生为止的完整 debug/trace 日志logs-othertextarearender: shell可选受影响的代理/应用自身的 debug 日志documentationtextarea可选相关的规范或文档aidropdown必填是否使用生成式 AI 创建该 IssueYes/No受 Artificial Intelligence Policy 约束其中build-info与logs两个字段均强制必填是 Authelia 缺陷排查中定位问题版本、构建信息、运行时日志的关键依据对应命令行工具authelia build-info实现见 internal/commands/build_info.go。提交前检查清单模板末尾是一组 checkboxes全部为必勾选项同意遵守 Code of Conduct确认这是 Bug 报告而非支持请求已阅读安全策略确认非安全问题已包含完整配置文件或确认与配置无关已包含完整 debug/trace 日志或提供build-info输出已完整提供所有必填信息仅按 Troubleshooting Sanitization 指南做合理脱敏已检查相关代理/应用日志并尽可能附上已检索相关 Issue 并查阅文档。实际使用与验证复现生成在 Authelia 仓库根目录下执行go run ./cmd/authelia-gen github issue-templates bug-report即可生成或覆盖.github/ISSUE_TEMPLATE/bug-report.yml。若当前目录不是仓库根目录可通过-d指定go run ./cmd/authelia-gen github issue-templates bug-report -d /path/to/authelia若仓库的 git tag 与输出目录分离可用-C指定 git 命令的 CWDgo run ./cmd/authelia-gen github issue-templates bug-report -C /path/to/authelia -d /path/to/authelia调整版本回溯范围go run ./cmd/authelia-gen github issue-templates bug-report --version-count 3改变输出文件位置go run ./cmd/authelia-gen github issue-templates bug-report --file.bug-report .github/ISSUE_TEMPLATE/bug-report.yml验证要点检查生成的 YAML 中labels是否包含type/bug/unconfirmed、status/needs-triage、priority/3/normal检查version下拉框是否只包含最近 N 个 minor 的稳定版本标签按--sort-creatordate排序后筛选检查proxy下拉框是否包含源码 cmd_github.go 中列出的 8 个代理。与兄弟命令的关系authelia-gen github issue-templates父命令一次性执行其下全部子命令通过rootSubCommandsRunE递归执行authelia-gen github issue-templates feature-request兄弟命令生成功能需求模板实现于 cmdGitHubIssueTemplatesFeatureRunE。两者的差异在于feature-request 的标签为type/feature、status/needs-design、priority/3/normal版本列表为未来的 minor 版本latest.Minor i 1且不含代理列表。典型应用场景仓库维护者在发布新版本后重新运行该命令确保 Version 下拉框始终与最近支持的稳定版本同步CI 自动化将authelia-gen github issue-templates bug-report纳入发布流水线保证 Issue 模板与版本发布保持一致避免手工维护 YAML 出错二次开发如需调整默认代理列表、标签或字段可直接修改 cmd_github.go 中cmdGitHubIssueTemplatesBugReportRunE的数据组装逻辑或模板 github_issue_template_bug_report.yml.tmpl重新生成即可。小结authelia-gen github issue-templates bug-report是 Authelia 工程化工具链中以代码生成维护仓库元数据的典型代表它把版本支持范围默认代理列表标签规范提交流程约束集中收敛到源码与模板中通过一次命令调用即可产出一份与当前发布状态实时同步的缺陷报告模板。理解这条命令也就理解了 Authelia 如何用生成器体系authelia-gen保持文档、配置、CI 与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考