介绍
DevOps 是一个完整的面向 IT 运维的工作流，以 IT 自动化以及持续集成(CI)、持续部署(CD)为基础，来优化程式开发、测试、系统运维等所有环节，现在飞书项目基于字节跳动研发实践的研发全流程方案，支持研发编码到发布的主流程在平台内完成闭环，落实研发流程规范，提升协作效率及交付质量，沉淀研发过程数据。
- 开发阶段：代码开发分支基于规则自动建立，在飞书项目运行流水线
- 集成阶段：在飞书项目完成代码的集成工作，包括上线单的提交、code review、代码合并
- 发布阶段：在飞书项目里运行流水线完成发布
插件安装
管理员前往空间配置 → 插件管理 → 搜索 DevOps 完成插件的添加。
250px|700px|reset
插件配置
250px|700px|reset
仓库配置
目前仅支持 GitLab
新建仓库：点击插件配置-仓库配置-新建仓库
- 获取仓库地址：登录 GitLab 后，点击进入对应的仓库，复制 GitLab 仓库链接
- 获取命名空间：复制 GitLab 仓库链接中命名空间部分
- 获取应用 ID：在 GitLab 里新建应用（User owned applications、Group owned applications、Instance-wide applications 任选一种即可)，Group owned applications 的应用 ID 可参考以下录屏获取，其他 applicantions 可参考 GitLab 文档获取
- 填写仓库 Access Token：Token 分为「当前单个仓库的 token」和「全局 token」。若填写了「单个仓库的 token」，则优先使用「单个仓库的 token」，否则默认使用「全局 token」。
- 当前单个仓库的 token：通常填写 GitLab 管理员的 Personal access tokens
250px|700px|reset
- 全局 token：点击仓库配置-配置 token，通常使用 GitLab 的 Project access tokens 或 Group access tokens，可参考可参考 GitLab 文档获取
- 配置 webhook
- 在仓库配置-点击「webhook」，获取 webhook 链接
- 点击进入对应的 GitLab 仓库，点击侧边的 Setting → Webhooks 选项；
- 将复制的链接粘贴到 GitLab 的 Webhook 中的 URL 选项中，勾选「Merge request events」后点击下方的「Add webhook」完成 webhook 关联。
流水线配置
火山 DevOps流水线配置
- 新建流水线
- Accountld：即账号ID，在控制台页面，点击右上角个人信息-复制账号ID
- AccessKey：即Access Key ID，在控制台页面，点击右上角个人信息-API访问密钥-复制Access Key ID
- SecretKey：即Secret Access Key，在控制台页面，点击右上角个人信息-API访问密钥-复制Secret Access Key
- 回调配置
- 复制流水线 webhook
- 登录火山引擎，进入「持续交付」平台，点击概览-选择对应的工作区
- 进入工作区页面-点击基本信息-对应的流水线，点击编辑流水线
- 进入流水线编辑页面-点击通知提醒-打开「Webhook 通知」-Webhook 地址选择「通用模式」-粘贴 Webhook 地址
自定义流水线配置
配置侧
界面展示
- 认证令牌、认证值
认证令牌就是token，认证值就是token的具体值（用于认证信息）
- 流水线接口
- 自定义三个POST请求的https接口
- （用户）将接收到的header统一入参格式为
header key:value // 认证令牌：认证值（认证信息））
- 流水线列表
- 第三方插件将接收到的入参格式为：
body:
{
"page_no": 1, // 页码
"page_size": 10 // 每页的条数
}}
- 需要返回给devops插件的出参格式为：
{
"code": 0,
"msg": "success",
"data": {
"total": 25,
"list": [
{
"template_id": "pipeline_example_id_123", // 流水线模板id
"template_name": "example" // 流水线模板名称
}
]
}
}}
- 运行流水线
- 第三方插件将接收到的入参格式为：
body:
{
"template_id": "pipeline_example_id_123", // 流水线模板id
"template_name": "example", // 流水线模板名称
"work_item_id": 30124567, // 工作项id
"node_key": "doing", // 节点key
"operator": "kanghuaisong", // 操作人
"repository": [
{
"address":"https://gitlab.com/demo/test", // 仓库信息
"branch": "feature/123" // 分支
}
]
}}
- 需要返回给devops插件的出参格式为：
{
"code": 0,
"msg": "success",
"data": [
{
"template_id": "pipeline_example_id_123", // 流水线模板id
"template_name": "example", //流水线模板名称
"instance_id": "pipeline_runing_id_123", // 流水线运行实例id
"instance_name": "pipeline_running_name", // 流水线运行名称
"status": "Running", // 流水线运行状态, Pending, Running, Succeed, Failed
"created_at": "2024-06-03 12:01:01", // 流水线触发时间
}
]
}}
- 流水线详情
- 第三方插件将接收到的入参格式为：
body
{
"template_id": "pipeline_example_id_123",
"template_name": "example",
"instance_id": "pipeline_running_id"
}}
- 需要返回给devops插件的出参格式为：
{
"code": 0,
"msg": "success",
"data": {
"template_id": "pipeline_example_id_123", // 流水线模板id
"template_name": "example", //流水线模板名称
"instance_id": "pipeline_runing_id_123", // 流水线运行实例id
"instance_name": "pipeline_running_name", // 流水线运行名称
"status": "Succeed", // 流水线运行状态
"created_at": "2024-06-03 12:01:01", // 流水线触发时间
"updated_at": "2024-06-03 12:10:11", // 流水线更新时间
"ref": "http://pipeline.example.com/pipeline/instance/123" // 流水线运行实例链接
}
}}
- 发布配置
- 此处的选择模板列表数据源为：流水线接口 → 流水线列表接口
250px|700px|reset
使用侧
- 手动触发流水线的数据源为：流水线接口 → 流水线列表接口
250px|700px|reset
- 确定之后会执行：流水线接口 → 运行流水线接口
- 流水线信息列表：流水线接口 → 流水线详情接口（包含时间、状态等）
Jenkins 流水线配置
配置侧
新建 Jenkins 流水线
- 在 Devops 插件 -> 流水线配置 -> 新建流水线
250px|700px|reset
- 新建 Jenkins 流水线
- 流水线名称: 填写相应名称
- 集成产品: 选择 Jenkins
- Jenkins URL: 填写 Jenkins 地址
250px|700px|reset
- 复制回调地址
安装飞书项目 jenkins 插件
- 下载飞书项目 jenkins 插件
- Jenkins 安装插件
推荐jenkins版本: 2.414.3
Manage Jenkins -> Plugins
250px|700px|reset
Advanced Settings -> 选择文件(FeishuProjectPlugin.hpi) -> Deploy
250px|700px|reset
- 配置 飞书项目Jenkins插件
Manage Jenkins -> System
找到 Feishu Project Plugin -> Callback填入流水线Jenkins的回调地址 -> Save
250px|700px|reset
Jenkins 无法访问互联网场景
在Jenkins服务器没有互联网访问出口时, 可以通过反向代理的方式, 进行jenkins回调
250px|700px|reset
使用301 转发
server {
listen 8081; # 监听的端口号
return 301 https://project.feishu.cn/m-api/v1/builtin_app/devops/jenkins/callback;
}}
使用 proxy_pass 转发
server {
listen 8081; # 监听的端口号
location / {
proxy_pass https://project.feishu.cn/m-api/v1/builtin_app/devops/jenkins/callback;
}
}}
使用侧
配置 Jenkins Item
- 得到飞书工作项 jenkins标识
点击工作项(如需求) -> 工作项实例(test01) -> ... -> 复制jenkins标识(xxxxxx#story#xxxxxxx)
250px|700px|reset
- 配置jenkins的 Item
选择相关Item -> Configure
250px|700px|reset
General -> This project is parameterized -> String Parameter
配置String Parameter
Name: feishu_project_key (注: 此变量为固定值)
Default Value: 飞书项目jenkins标识(xxxxxx#story#xxxxxxx)
250px|700px|reset
配置Post-build Actions
250px|700px|reset
选择Feishu Project Deploy Notifier
250px|700px|reset
填加Feishu Project Deploy Notifier后, Save保存
编译 Item
Build with Parameters -> feishu_project_key(会带入默认值, 也可进行实际值的填写) -> Build
250px|700px|reset
输出日志
feishu model: 向后台提交的参数
feishu result: 返回结果信息
feishu error: 返回错误信息
查看关联结果
点击相关工作项(如需求) -> 工作项实例(test01) -> DevOps -> 流水线信息
自动关联分支功能
在未填写"飞书项目Jenkins标识"时, 插件可根据编译的仓库与分支信息和工作项实例中代码信息中关联分支的仓库与分支信息相匹配, 如果分支名称相同, 可对编译结果与工作项实例进行关联
- 点击相关工作项(需求) -> 工作项实例(test01) -> DevOps -> 代码信息-> 分支
250px|700px|reset
- Jenkins git 配置 1.仓库信息, 2.分支信息
Pipeline模式支持
飞书项目jenkins插件支持pipeline模式
声明式使用方式
在流水线脚本中post阶段, 条件为always, 加入feishuProjectPost函数
参数为
gitUrl: git仓库地址
branchName: 代码分支
pipeline {
agent any
parameters {
gitParameter(
branchFilter: 'origin/(.*)',
defaultValue: '*/main',
name: 'BRANCH',
type: 'PT_BRANCH',
useRepository: 'https://gitlab.com/xxxxxxx/gitlab-test'
)
}
stages {
stage('Hello') {
steps {
echo 'Hello World'
git branch: "${params.BRANCH}", credentialsId: 'xxxxxxx', url: 'https://gitlab.com/xxxxxx/gitlab-test'
// sh "printenv"
}
}
}
post {
always {
//此处加入插件函数
feishuProjectPost(
gitUrl: 'https://gitlab.com/xxxxxx/gitlab-test',
branchName: "${params.BRANCH}"
)
}
}
}}
脚本式使用方式
由于脚本式语法没有POST阶段, 无法得到执行结果, 需要根据脚本执行来赋值currentBuild.result
node {
def mvnHome
try {
stage('run') { // for display purposes
echo 'Hello World'
currentBuild.result = 'SUCCESS' // 赋值为非给定值都为FAILURE
/*
* 成功（SUCCESS）：任务成功执行并且没有错误。
* 失败（FAILURE）：任务执行过程中出现错误或失败。
* 中断（ABORTED）：任务在执行过程中被中断或取消。
* 不稳定（UNSTABLE）：任务执行完成，但可能存在一些警告或非关键错误。
* 未构建（NOT_BUILT）：任务尚未构建，通常是由于配置问题或其他原因导致任务未开始构建
*/
echo manager //报错演示
}
} catch (e) {
echo 'ERROR'
currentBuild.result = 'FAILURE'
} finally { //无论前面失败还是成功都会执行
stage('Results') {
feishuProjectPost(
gitUrl: 'https://gitlab.com/vc7841029/gitlab-test',
branchName: "${params.BRANCH}"
)
}
}
}}
发布配置
- 工作项：不支持配置，目前关联工作项仅支持「版本」工作项，如果空间没启用「版本」工作项，可以在空间配置-工作项管理-版本-启用
- 配置分支规则：
- 选择当版本状态存在属于xx状态时
- 选择在「仓库配置」中配置的仓库名称和源分支
- 配置发布分支名称，命名时支持配置变量：工作项id: {{work_item_id}}，节点id:{{node_state_key}}，触发时间{{trigger_time}} ，如release_{{work_item_id}}_{{node_state_key}}_{{trigger_time}}
- 配置流水线运行规则：选择当版本状态存在属于xx状态时，触发在「流水线配置」中配置的流水线
如版本流转到「灰度中」时，触发版本发布的流水线
- 新建上线单权限控制：即什么时候可以新建上线单
如版本封版后不允许新建上线单，可配置当前工作项状态存在属于「未启动」、「开发中」等封版前的状态
- 配置完成后，记得点击右上角「保存」按钮
250px|700px|reset
开发配置
新建开发配置
- 规则名称：命名开发配置规则
- 适用工作项：规则关联的工作项
- 配置分支规则
- 选择工作项对应的流程类型-节点名称
- 配置触发状态：当节点状态变为进行中或已完成
- 选择在「仓库配置」中配置的仓库名称和源分支
- 配置开发分支名称，命名时支持配置变量：工作项id: {{work_item_id}}，节点id:{{node_state_key}}，触发时间{{trigger_time}} ，如feat_{{work_item_id}}_{{node_state_key}}_{{trigger_time}}
通知配置
当编辑或者新增审核人时，机器人会向审核人发送通知
- 进入飞书开放平台-创建应用
- 复制App ID、App Secret
250px|700px|reset
- 在飞书项目-空间配置-插件管理-飞书项目 DevOps 插件-配置-通知配置，粘贴App ID、App Secret，点击保存
250px|700px|reset
上线单控件配置
在空间配置-工作项关联-版本-页面布局-配置「DevOps上线单信息」控件
250px|700px|reset
插件使用
步骤一：新建版本
如已有可用版本，这一步可跳过
- 在空间界面点击右上角的「新建」按钮；
- 选择「新建版本」选项（如新建页无新建版本入口，需查看空间配置中版本工作项是否启用并pin到导航栏）；
- 需要根据管理员配置的表单内容填写表单项信息，必填项必须填写，否则将无法创建版本；
- 填写完毕后，点击「创建」创建完成。
250px|700px|reset
步骤二：关联分支
- 完成开发后，选择需要关联的工作项（如需求、缺陷），点击详情页-devops标签页，关联仓库配置里的代码分支
- 如管理员已在开发配置里配置规则，流转到对应的节点会自动创建分支
步骤三：运行流水线
如未配置流水线或无需运行，可跳过此步骤
250px|700px|reset
步骤四：添加或新建上线单
- 点击对应工作项-「DevOps」标签页-代码信息-点击「添加到上线单」
- 选择上线版本、修改审核人后点击确定
步骤五：上线单（代码）审核
- 代码审核
版本封版前，对应的审核人，可在版本-「DevOps上线单信息」控件中进行代码审核
- 在版本-「DevOps上线单信息」控件-对应上线任务-点击详情，可查看代码 Diff、添加评论
- 点击「核准」-「OAuth 授权」，授权后完成审批
250px|700px|reset
- 代码合并
审核完成后，如有多个代码任务，可点「全部合并」
步骤六：版本封版
- 如果管理员在发布配置中配置新建上线单权限控制为：版本状态存在属于「未启动」、「开发中」等封版前的状态
- 当版本负责人将版本流转到「已封版」时，「新建上线单」按钮置灰，不允许再新增上线单
250px|700px|reset
步骤七：版本发布
如未配置流水线或无需运行，可跳过此步骤
- 版本封版后，可运行对应的流水线，发版上线
- 如管理员已在开发配置里配置规则，流转到对应的状态会自动运行流水线
250px|700px|reset
Jenkins 无法访问互联网场景的解决方法
在Jenkins服务器没有互联网访问出口时, 可以通过反向代理的方式, 进行jenkins回调
250px|700px|reset
使用301 转发
server {
listen 8081; # 监听的端口号
return 301 https://project.feishu.cn/m-api/v1/builtin_app/devops/jenkins/callback;
}}
使用 proxy_pass 转发
server {
listen 8081; # 监听的端口号
location / {
proxy_pass https://project.feishu.cn/m-api/v1/builtin_app/devops/jenkins/callback;
}
}}
