GitLab 官方 CI/CD 组件开发指南

本文档介绍了如何开发由 GitLab 维护的 CI/CD 组件，包括官方公开组件和内部使用的组件。

所有官方 GitLab 组件项目的位置都在 gitlab.com/components 组中。 该组包含所有设计为通用、服务于所有 GitLab 用户并由 GitLab 维护的组件。 例如：SAST、Secret Detection 和 Code Quality 组件。 组件项目最初可以在不同的组下创建（例如 gitlab-org）， 但在第一个版本发布到目录之前，需要将其移动到 components 组中。gitlab.com/components 组下的所有项目必须公开

仅用于 GitLab 内部使用的组件，例如特定于 gitlab-org/gitlab 项目的组件， 应该在 gitlab-org 组下实现。

预期要发布到 CI/CD 目录 的组件项目 应该先进行内部测试（dogfooded），以确保我们能够掌控项目质量并拥有第一手的使用经验。

定义所有权

官方 GitLab 组件受到社区信任，需要高质量和及时的维护。 组件必须保持更新，监控安全漏洞，并修复错误。

每个组件项目必须拥有一套所有者和维护者，他们同时也是领域专家。 专家可以来自 GitLab 的任何部门，从工程部到支持部、客户成功部和开发者关系部。

如果组件与 GitLab 功能相关（例如 Secret Detection），则拥有该功能类别或与其最相关的团队应该维护该项目。 在这种情况下，功能类别的工程经理被指定为项目所有者。

拥有项目 owner 角色的成员是负责处理开放问题和合并请求的 DRIs，以确保它们得到及时处理。

组件项目最初可以由单独的团队或个人创建，但在第一个版本发布到目录之前， 必须将其移交给一组所有者。

项目仓库中的 README.md 文件必须标明项目的主要所有者，以便在需要时可以被更广泛的社区联系。

开发流程

1. 在 gitlab.com/components 下创建项目， 或请求组所有者之一为您创建一个空项目。
2. 遵循 创建组件的标准指南。
3. 添加简洁的项目描述，清晰描述组件项目提供的能力。
4. 确保遵循 编写组件 的一般指导， 以及 官方组件 的指导。
5. 添加一个包含 MIT 许可证的 LICENSE.md 文件（示例）。
6. 项目必须有一个 .gitlab-ci.yml 文件，该文件：
   • 验证项目中的所有组件是否正确 (示例)。
   • 包含一个 release 作业，用于将新发布的标签发布到目录 (示例)。
7. 对于官方组件项目，将 官方头像图像 上传到组件项目。

官方组件的最佳实践

• 确保 README.md 至少包含以下部分（例如，参见 Code quality 组件）：
  • 概述：组件项目提供的能力。
  • 组件：每个组件的子部分，包含：
    • 用法：带输入和不带输入的示例（当输入为可选时）。
    • 输入：显示输入名称、类型、默认值（如果有）和描述的表格。
    • 变量（当适用时）：变量名称、支持的值和描述。
  • 贡献：说明以及如何联系维护者。 通常贡献过程应遵循 官方指南。
• 命名 inputs 时，如果需要，使用下划线 _ 作为复合名称，使用连字符 - 作为分隔符。例如：service_x-project_name。
• 如果您希望允许用户配置 rules，请使用 inputs。参见此处的示例。 为了在未定义 rules 时保留默认行为，您应该为输入使用 default: [{when: on_success}]， 直到 此问题 得到解决。

官方组件的审查和贡献流程

项目中的组件可能在 GitLab 代码库中有相关的 CI/CD 模板。 在这种情况下，我们需要交叉链接组件项目和 CI/CD 模板：

• 在 CI/CD 模板中添加评论，说明相关组件项目的位置。
• 在组件项目的 README.md 中添加一个部分，说明现有 CI/CD 模板的位置。

当对这些组件应用更改时，检查我们是否也可以在 CI/CD 模板中集成这些更改。 由于 CI/CD 模板中版本控制的严格性，这可能无法实现。

联系任何 维护者 进行审查， 以确保组件以一致的风格编写并遵循最佳实践。

GitLab 官方组件的默认维护者

gitlab.com/components 组下的每个组件项目都应该有特定的 DRIs 和维护者， 但是 @gitlab-org/maintainers/ci-components 维护者组负责总体管理 components 组。

该维护者组的职责：

• 管理任何开发和辅助资源，例如工具包组件和项目模板，以提供最佳的开发体验。
• 管理任何缺少明确 DRI 或正在开发过程中的组件项目，并努力寻找合适的长期所有者。
• 指导和指导单个组件项目的维护者，包括代码审查和故障排除时。
• 确保最佳实践得到应用并随着时间的推移不断改进。

成为维护者的要求：

• 深入了解 CI/CD YAML 语法 和功能。
• 了解 CI 组件的工作原理，并展示开发它们的相关经验。
• 对如何 编写组件 有扎实的理解。

如何加入 gitlab-components 通用维护者组：

• 查看 成为 gitlab-components 维护者的流程。