集成Git客户端
iSoftBook支持与Git Bash、Sourcetree、IntelliJ IDEA的VCS等Git客户端集成,访问iSoftBook项目的代码仓库。
- 应用用户个人账号进行认证访问。
- 基于平台统一权限控制规则,实行代码仓库访问授权。
- 区分push和pull权限,保护master分支。
- 集成Git客户端详细规则和示例请见:代码仓库管理
CI/CD集成接口
iSoftBook平台提供专属的CI/CD集成接口,与Jenkins等CI/CD服务器快捷、双向、安全集成。
iSoftBook CI/CD集成特点:
- 配置项目的专属集成账号,仅能执行本项目代码库的clone和pull操作,不能执行push操作,保障集成过程中平台数据安全。
- 专属集成账号遵循项目集的权限访问控制规则,无需单独授权,可以访问项目集中的代码仓库,支持规模化、多模块CI/CD集成。
- 支持配置一个或多个Webhook,代码库push操作触发CI/CD服务器实时执行。
- 提供集成状态通知API,通知CI/CD执行状态和信息。
iSoftBook CI/CD集成过程:
- 用户向iSoftBook项目push操作,iSoftBook平台调用Webhook,触发CI/CD服务器执行集成任务。
- iSoftBook平台于项目集成任务表中,添加一条状态为“Pending”的待集成任务。
- CI/CD服务器集成任务执行过程中,调用iSoftBook平台提供的Web API,更新iSoftBook平台项目集成任务表中任务的状态。
- 用户查看集成任务的执行状态与情况,查看整个项目持续集成历史。
iSoftBook CI/CD Webhook接口:
- iSoftBook运用HTTP POST请求,触发Webhook。
- 该HTTP POST设置Content-Type Header:"application/json;charset=UTF-8"。
- 基于配置,该HTTP POST设置Authorization Header,提供Basic安全基础认证。
- 基于配置,该HTTP POST设置Token Header。
- 该HTTP POST发送如下JSON格式的Body:{"ref":"refs/heads/develop","committer":"zhangsan"},向CI/CD服务器提供推送的分支和代码提交人。
iSoftBook CI/CD Web API接口:
- iSoftBook平台提供CINotify Web API,供CI/CD服务器调用,通知iSoftBook平台CI/CD执行的状态和结果信息。
- CINotify支持POST和GET方法调用。
- CINotify接受的Content-Type:"application/x-www-form-urlencoded;charset=utf-8"。
- CINotify三个请求参数:commitId,CI/CD签出提交的SHA-1;status,CI/CD的执行状态;resultText,CI/CD的执行结果。
- resultText值的长度不超过4096。
- status的有效取值:Pending,等待运行;Running:正在运行;Success:成功运行;Failure,运行失败;Aborted,运行终止;Unstable:运行存在缺陷;Unknown,未知状态。该取值与Jenkins构建状态取值相一致。状态取值与大小写无关。
CI/CD集成配置
项目主页中,点击“集成”选项卡,进入CI/CD集成配置页面,具体配置如下图。
持续集成配置执行必要的数据验证,包括iSoftBook集成账号必填、其User ID项目内唯一、API Token长度至少8位、Webhook URL的格式正确性等。
CI/CD服务器访问iSoftBook,执行代码仓库clone或checkout、或者调用CINotify Web API,都必须提供该集成账号作为凭据。
iSoftBook访问CI/CD服务器,请求Webhook,触发集成任务,需要提供CI/CD服务器配置的账号、或者Token,作为触发凭据。具体遵循CI/CD服务器的访问控制规则。
Webhook配置后,点击测试按钮,向CI/CD服务器执行一次触发测试,测试Webhook URL、Webhook账号与Token配置是否正确有效。常见测试结果与意义:
Webhook配置测试常见显示结果与含义:
- OK:测试成功,成功触发一次集成构建。
- Unauthorized:Webhook账号和密码错误,不能通过CI/CD服务器认证。
- Not Found:Token配置不正确,CI/CD服务器上不能找到与该Token匹配的集成项目。
- java.net.UnknownHostException:Webhook URL主机地址错误。
集成Jenkins
Jenkins一款卓越的CI/CD自动化工具。基于iSoftBook的集成接口和配置,提供iSoftBook集成Jenkins的一个实例方案,创建一个Jenkins Pipeline项目,实现多分支参数化构建。
iSoftBook集成Jenkins,虽支持Freestyle、Maven等项目类型,但建议采用社区推荐和主流发展的Jenkins Pipeline项目。Pipeline项目的脚本和环境变量直接提供了iSoftBook的Web API CINotify调用需要的参数。而在Freestyle、Maven等项目类型中,需要调用Jenkins的API,获取相应的参数值,增加了配置管理的复杂度。
本实例的Jenkins版本V2.346,安装Generic Webhook Trigger、Jenkins Pipeline、HTTP Request、 Credentials插件。
集成配置核心要点:
- 配置iSoftBook与Jenkins双向访问凭据,保障集成安全可靠。
- iSoftBook利用Generic Webhook Trigger插件,配置和触发该插件,启动构建任务。
- Jenkins利用Jenkins Pipeline插件,从iSoftBook平台签出代码,执行构建。
- 构建执行过程中,Jenkins运用HTTP Request插件,调用iSoftBook的CINotify Web API,返回构建任务执行状态与结果。
1. iSoftBook集成Jenkins的配置
给出iSoftBook集成Jenkins的整体配置。该配置表单创建“iSoftBook集成账号”,Jenkins以此创建访问iSoftBook的凭据。同时,填写Jenkins的Webhook URL和触发凭据,iSoftBook据此触发构建。
2. Jenkins创建iSoftBook凭据
根据iSoftBook集成配置的“iSoftBook集成账号”,在Jenkins系统Dashboard-凭据-系统-全局凭据中,创建iSoftBook的访问凭据。Jenkins在checkout和httpRequest操作中,提供该凭据,实现Jenkins访问iSoftBook的认证。
3. Jenkins创建Webhook触发器凭据
iSoftBook向Jenkins的Generic Webhook Trigger发送触发请求时,需提供认证凭据。Generic Webhook Trigger支持两种类型的凭据:User ID And API Token、Secret Text,两个凭据仅需提供一个即可。Jenkins创建其中一个,并相应设置在iSoftBook持续集成配置的“Webhook集成账号”或“Webhook Token”,实现iSoftBook访问Jenkins的认证。
User ID And API Token凭据创建与配置
Secret Text凭据创建与配置
Jenkins的Generic Webhook Trigger支持明文的Token参数作为凭据,但为了增加安全性,建议采用Secret Text凭据进行配置。
4. Jenkins Generic Webhook Trigger配置
Jenkins创建Pipeline项目,Build Triggers选择Generic Webhook Trigger,并解析和设置iSoftBook触发传递的参数,配置Token。
5. Jenkins Pipeline Script
给出Pipeline Script的示例。注意要点:
- checkout操作引用“branch”参数实现参数化构建,引用凭据'isoftbookUserForjenkins'。
- gitScm存储checkout操作结果,gitScm.GIT_COMMIT的值是签出提交的SHA-1,作为CINotify回调参数。
- 环境变量currentBuild.currentResult,表示构建状态,作为CINotify回调参数。
- 环境变量env.BUILD_URL,表示本次构建的URL,作为CINotify回调参数,返回到iSoftBook。支持从iSoftBook点击查看构建日志。
- httpRequest引用凭据'isoftbookUserForjenkins'。其requestBody遵循iSoftBook的CI/CD集成接口,其值是Groovy双引号(“)定义的GStrings插值字符串,以对其中的表达式求值。。
建议:运用Jenkins Shared Libraries封装httpRequest的调用。
pipeline{
agent any
stages{
stage("checkout"){
steps{
script {
gitScm = checkout poll: false, scm: [$class: 'GitSCM',
branches: [[name: "${branch}"]], extensions: [],
userRemoteConfigs: [[credentialsId: 'isoftbookUserForjenkins',
url: 'http://demo.intellbook.com/GitHub/15']]]
}
}
}
stage("package"){
steps{
bat 'mvn clean package'
}
}
}
post{
always{
httpRequest authentication: 'isoftbookUserForjenkins',
customHeaders: [[maskValue: false, name: 'Content-Type',value: 'application/x-www-form-urlencoded;charset=utf-8']],
httpMode: 'POST',
requestBody: "commitId=${gitScm.GIT_COMMIT}&status=${currentBuild.currentResult}&resultText=<a target='_blank' href='${env.BUILD_URL}'>点击查看构建日志",
responseHandle: 'NONE',
url: ' http://demo.intellbook.com/API/CINotify?projectId=15',
wrapAsMultipart: false
}
}
}
社区版开放集成
iSoftBook社区版提供简单、快速的开放集成机制。
- iSoftBook社区版同企业版、旗舰版一样,提供Git仓库URL、用户账号作为开放接口,实施平台统一的认证和权限控制,与Git Bash、Sourcetree、IntelliJ IDEA的VCS等Git客户端集成。
- iSoftBook社区版运用Git仓库URL、用户账号开放接口,通过"poll scm"、"build periodically"等触发器,实现与Jenkins等CI/CD服务器集成。
- iSoftBook社区版与Jenkins等服务器集成不需要额外配置,简单便捷,能够满足通常使用。
- iSoftBook社区版项目主页不提供“持续集成”配置,不提供集成凭据和集成API开放接口。
- iSoftBook社区版不提供Webhook配置和触发机制。