开放集成

遵循统一权限控制规则,提供Git仓库URL、用户账号、集成凭据和集成API等开放接口,快速集成IDE、Git客户端、Jenkins等CI/CD工具,实现持续集成和持续部署,打造立体工具链,助力DevOps。

开始了解

集成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
             }
        }
    }
                        
                    

6. iSoftBook Jenkins集成结果

项目主页-“集成”选项卡-“集成消息”栏,实时跟踪Jenkins持续集成执行状态,跳转到Jenkins查看构建日志。并查看项目的持续集成历史。

社区版开放集成

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配置和触发机制。