工作流
- 工作流
- 自定义工作流

工作流

本文主要介绍如何使用 Open API 来操作 Zadig 的工作流（包括工作流和自定义工作流）。

工作流

获取工作流任务状态

注意事项

目前仅支持 GitLab 的 commitId 查询
支持完整的 commitId 或者输入 commitId 前 8 位查询

请求

GET /api/directory/workflowTask?commitId=<commitId>

Query

参数名	类型	描述	默认值	是否必须
`commitId`	string	commitId	无	must

正常返回

[
    {
        "task_id": 49,
        "create_time": 1639466317,
        "start_time": 1639466318,
        "end_time": 1639466354,
        "status": "passed",
        "url": "http://my.zadig.com/v1/projects/detail/proxy/pipelines/multi/workflow-demo/49"
    }
]

返回说明

参数名	类型	描述
`task_id`	int64	任务 id
`url`	string	任务具体 url
`status`	string	任务状态
`create_time`	int64	Unix 时间戳格式的任务创建时间
`start_time`	int64	Unix 时间戳格式的任务开始时间
`end_time`	int64	Unix 时间戳格式的任务结束时间

任务状态包括：created(创建中)/running(运行中)/passed(通过)/failed(失败)/timeout(超时)/cancelled(取消)

错误码对应列表


{
    "resultCode":401,"errorMsg":"auth failed!",
    "resultCode":400,"errorMsg":"param is illegal!"
}

工作流任务重试

注意事项

需要有执行工作流的权限
支持对状态是 failed(失败)/timeout(超时)/cancelled(取消) 的工作流任务进行重试

请求

POST /api/directory/workflowTask/id/:id/pipelines/:pipelineName/restart

路径参数说明

参数名	类型	描述	默认值	是否必须
`id`	int	任务 id	无	是
`pipelineName`	string	工作流名称	无	是

正常返回

{"message":"success"}

异常返回

{
  "code": 6164,
  "description": "获取工作流任务失败",
  "extra": {},
  "message": "重试工作流任务失败",
  "type": "error"
}

取消工作流任务

注意事项

需要有执行工作流的权限；

请求

POST /api/directory/workflowTask/id/:id/pipelines/:pipelineName/cancel

路径参数说明

参数名	类型	描述	默认值	是否必须
`id`	int	任务 id	无	是
`pipelineName`	string	工作流名称	无	是

正常返回

{"message":"success"}

异常返回

{
  "code": 6163,
  "description": "mongo: no documents in result",
  "extra": {},
  "message": "取消工作流任务失败",
  "type": "error"
}

执行工作流

注意事项

需要有执行工作流的权限；
暂不支持更新环境变量；
暂不支持高级选项，如工作流空间缓存和 Docker 缓存。

请求

POST /api/directory/workflowTask/create

body 参数样例

{
    "workflow_name":"autoproject-workflow-dev",
    "env_name":"dev",    
    "release_images": [
        {                    
            "image": "ccr.ccs.tencentyun.com/trial/go-sample-site1:20211221120415-1-main",
            "service_name": "gss",
            "service_module": "go-sample-site1"
        },
        {                    
            "image": "ccr.ccs.tencentyun.com/trial/go-sample-site2:20211221120415-1-main",
            "service_name": "gss",
            "service_module": "go-sample-site2"
        }
    ],
    "targets":[
        {
            "name":"redis3",
            "service_type": "k8s",
            "build":{
                "repos":[
                    {
                        "repo_name":"voting-app",
                        "branch":"master",
                        "pr":0
                    },
                    {
                        "repo_name":"zadig-infra",
                        "branch":"master",
                        "pr":5
                    }
                ]
            }
        }
    ],
    "callback": {
        "callback_url": "https://callbackhost.com/callback",
        "callback_vars": {
            "k1": 1,
            "k2": "value2"
        }
    }
}

body 参数说明

参数名	类型	描述	默认值	是否必须
`workflow_name`	string	工作流名称	无	must
`env_name`	string	集成环境名称	无	must
`targets`	[]TargetArgs	构建参数	无	option
`release_images`	[]Image	分发镜像信息	无	option
`callback`	Callback	工作流执行完成回调信息	无	option

targets 和 release_images 必须有一个参数存在

TargetArgs 参数说明

参数名	类型	描述	默认值	是否必须
`name`	string	服务名称	无	must
`service_type`	string	服务部署方式，支持 k8s 或 helm	k8s	optional
`build`	BuildArgs	构建参数	无	must

BuildArgs 参数说明

参数名	类型	描述	默认值	是否必须
`repos`	[]Repository	关联代码库信息	无	must

Repository 参数说明

参数名	类型	描述	默认值	是否必须
`repo_name`	string	代码库名称	无	must
`branch`	string	分支	无	must
`pr`	int	pr ID	0	使用 pr 构建时必传

Image 参数说明

参数名	类型	描述	默认值	是否必须
`image`	string	镜像信息	无	must
`service_name`	string	服务名称	无	must
`service_module`	string	服务组件	无	must

Callback 参数说明

参数名	类型	描述	默认值	是否必须
`callback_url`	string	回调地址	无	must
`callback_vars`	map[string]Any	回调参数	无	optional

正常返回

{
  "project_name": "test-project",
  "workflow_name": "test-project-workflow-dev",
  "task_id": 74
}

异常返回

{
  "code": 6540,
  "description": "workflow [hello-world-workflow-dev] 在项目 [hellow-world] 中已经存在!",
  "extra": {},
  "message": "新建或更新wokflow失败",
  "type": "error"
}

获取工作流任务详情

请求

GET /api/directory/workflowTask/id/:id/pipelines/:pipelineName

路径参数说明

参数名	类型	描述	默认值	是否必须
`id`	int	任务 id	无	是
`pipelineName`	string	工作流名称	无	是

正常返回

{
    "workflow_name": "test-project-workflow-dev",
    "env_name": "dev",
    "targets": [
        {
            "name": "gss-1",
            "service_type": "helm",
            "build": {
                "repos": [
                    {
                        "repo_name": "hzx-test",
                        "branch": "main",
                        "pr": 0
                    }
                ]
            }
        },
        {
            "name": "gss-2",
            "service_type": "helm",
            "build": {
                "repos": [
                    {
                        "repo_name": "hzx-test",
                        "branch": "main",
                        "pr": 0
                    }
                ]
            }
        }
    ],
    "images": [
        {                    
                "image": "ccr.ccs.tencentyun.com/trial/go-sample-site:20211221120415-1-main",
                "service_name": "gss-1",
                "registry_repo" : "https://ccr.ccs.tencentyun.com/trial"                    
        },
        {                    
                "image": "ccr.ccs.tencentyun.com/trial/go-sample-site:20211221120415-1-main",
                "service_name": "gss-2",
                "registry_repo" : "https://ccr.ccs.tencentyun.com/trial"                    
        }
    ],
    "test_reports": [
        {
            "test_name": "test",
            "function_test_report": {
                "tests": 24,
                "successes": 24,
                "failures": 0,
                "skips": 0,
                "errors": 0,
                "detail_url": "/v1/projects/detail/test-project/pipelines/multi/testcase/test-project-workflow-dev/51/test/test-project-workflow-dev-51-test?is_workflow=1&service_name=test&test_type=function"
            }
        }
   ],
    "status": "timeout"
}

返回说明

参数名	类型	描述
`workflow_name`	string	工作流名称
`env_name`	string	环境名称
`status`	string	任务状态
`targets`	[]TargetArgs	构建参数
`images`	[]Image	构建生成的镜像信息
`test_reports`	[]TestReport	测试报告信息

Image 参数说明

参数名	类型	描述
`image`	string	镜像地址
`service_name`	string	服务名称
`registry_repo`	string	镜像仓库

TestReport 参数说明

参数名	类型	描述
`test_name`	string	测试名称
`function_test_report`	FunctionTestReport	测试报告概览

FunctionTestReport 参数说明

参数名	类型	描述
`tests`	int	测试用例数量
`successes`	int	成功数量
`failures`	int	失败数量
`skips`	int	跳过数量
`errors`	int	错误数量
`detail_url`	string	测试报告详情 URL

异常返回

{
    "code": 500,
    "description": "[400 BadRequest] {\"code\":6161,\"description\":\"\",\"extra\":{},\"message\":\"获取工作流任务失败\",\"type\":\"error\"}",
    "message": "Internal Error: "
}

自定义工作流

获取自定义工作流任务详情

GET /openapi/workflows/custom/task

参数名	类型	描述	默认值	是否必须
`task_id`	int	自定义工作流任务 id	无	是
`workflow_name`	string	自定义工作流名称	无	是

正常返回

{
    "task_id": 24,                              # 自定义工作流任务序号 ID
    "workflow_name": "build-images",            # 自定义工作流名称
    "params": [                                 # 自定义工作流变量
        {
            "name": "USERNAME",
            "description": "",
            "type": "string",
            "value": "zadig",
            "default": "",
            "is_credential": false
        }
    ],
    "status": "running",                        # 自定义工作流任务状态
    "task_creator": "admin",                    # 自定义工作流任务触发者
    "create_time": 1664161285,                  # 工作流任务创建时间，Unix 时间戳格式
    "start_time": 1664161286,                   # 工作流任务开始执行时间，Unix 时间戳格式
    "end_time": 1664172997,                     # 工作流任务执行结束时间，Unix 时间戳格式
    "stages": [                                 # 工作流任务包含的所有阶段详情
        {
            "name": "构建",                      # 阶段名称
            "status": "passed",                 # 阶段状态
            "start_time": 1664161286,           # 阶段执行开始时间，Unix 时间戳格式
            "end_time": 1664172974,             # 阶段执行结束时间，Unix 时间戳格式
            "jobs": [                           # 阶段中包含的所有任务详情
                {
                    "name": "a-myapp-1-build-myapps",
                    "type": "zadig-build",      # 内置构建任务
                    "status": "passed",         # 任务状态
                    "start_time": 1664172967,   # 任务执行开始时间，Unix 时间戳格式
                    "end_time": 1664172974,     # 任务执行结束时间，Unix 时间戳格式
                    "spec": {                   # 构建任务执行详细信息（包括代码信息、镜像信息、服务信息、服务组件信息、构建变量信息）
                        "repos": [              # 代码信息
                            {
                                "source": "gitee",
                                "repo_owner": "kr-test-dev",
                                "repo_namespace": "kr-test-dev",
                                "repo_name": "zadig",
                                "remote_name": "origin",
                                "branch": "main",
                                "commit_id": "a13120997b95d8b63f2b5b29c700f89d38a5de54",
                                "commit_message": "update pkg/microservice/warpdrive/config/const.go.\n\nSigned-off-by: grandy <10196377+grandy@user.noreply.gitee.com>",
                                "address": "https://gitee.com",
                                "author_name": "grandy"
                            }
                        ],
                        "image": "koderover.tencentcloudcr.com/koderover-demo/myapp-1:20220926141606-26-main", # 镜像信息
                        "service_name": "a",            # 服务名称
                        "service_module": "myapp-1",    # 服务组件名称
                        "envs": [                       # 构建变量信息
                            {
                                "key": "username",
                                "value": "admin",
                                "type": "string",
                                "is_credential": false
                            },
                            {
                                "key": "password",
                                "value": "zadig",
                                "type": "string",
                                "is_credential": true
                            },
                            {
                                "key": "version",
                                "value": "1",
                                "type": "string",
                                "is_credential": false
                            }
                        ]
                    }
                }
            ]
        },
        {
            "name": "部署",
            "status": "passed",
            "start_time": 1664172974,
            "end_time": 1664172990,
            "approval": {                               # 审核信息
                "enabled": true,                        # 需要审核
                "approve_users": [                      # 审核人列表
                    {
                        "user_name": "admin",
                        "reject_or_approve": "approve",
                        "comment": "LGTM",
                        "operation_time": 1664172985
                    }
                ],
                "timeout": 120,                         # 审核超时时间，单位：分钟
                "needed_approvers": 1,                  # 需要满足的审核通过人数
                "description": "需审核通过方可部署",       # 审核描述
                "reject_or_approve": "approve"          # approve：通过；reject：拒绝
            },
            "jobs": [
                {
                    "name": "a-myapp-1-deploy-myapps",
                    "type": "zadig-deploy",             # 内置部署任务
                    "status": "passed",
                    "start_time": 1664172986,
                    "end_time": 1664172990,
                    "spec": {                           # 部署任务的详细信息
                        "env": "dev",
                        "skip_check_run_status": false, # 是否关闭服务状态检测
                        "service_and_images": [         # 部署的服务、服务组件、镜像信息
                            {
                                "service_name": "a",
                                "service_module": "myapp-1",
                                "image": "koderover.tencentcloudcr.com/koderover-demo/myapp-1:20220926141606-26-main"
                            }
                        ]
                    }
                }
            ]
        },
        {
            "name": "通用任务",
            "status": "passed",
            "start_time": 1664172990,
            "end_time": 1664172993,
            "jobs": [
                {
                    "name": "echo-hello",
                    "type": "freestyle",                # 通用任务
                    "status": "passed",
                    "start_time": 1664172990,
                    "end_time": 1664172993,
                    "spec": {                           # 通用任务执行详细信息
                        "repos": [
                            {
                                "source": "gitee",
                                "repo_owner": "kr-test-dev",
                                "repo_namespace": "kr-test-dev",
                                "repo_name": "demo-test",
                                "remote_name": "origin",
                                "branch": "master",
                                "commit_id": "2000aba9195bfce73b0a676e48c0ebfe2f59a4a9",
                                "commit_message": "update org-debug.txt.\n\nSigned-off-by: grandy <10196377+grandy@user.noreply.gitee.com>",
                                "address": "https://gitee.com",
                                "author_name": "grandy"
                            }
                        ],
                        "image": "",
                        "service_name": "",
                        "service_module": "",
                        "envs": [
                            {
                                "key": "myName",
                                "value": "zadig",
                                "type": "string",
                                "is_credential": false
                            }
                        ]
                    }
                }
            ]
        },
        {
            "name": "自定义任务",
            "status": "passed",
            "start_time": 1664172993,
            "end_time": 1664172997,
            "jobs": [
                {
                    "name": "say-hi",
                    "type": "plugin",                   # 自定义任务
                    "status": "passed",
                    "start_time": 1664172993,
                    "end_time": 1664172997,
                    "error": "",
                    "spec": {
                        "name": "输出 Hello 问候信息",
                        "is_offical": false,
                        "description": "问候指定用户",
                        "repo_url": "",
                        "version": "v0.0.1",
                        "image": "koderover.tencentcloudcr.com/koderover-public/greeting-bot:20220923-amd64",
                        "args": [],
                        "cmds": [],
                        "envs": [
                            {
                                "name": "WHO_AM_I",
                                "value": "Zadig"
                            },
                            {
                                "name": "WEATHER_STATUS",
                                "value": "sunny"
                            }
                        ],
                        "inputs": [
                            {
                                "name": "who_am_i",
                                "description": "who am i",
                                "type": "string",
                                "value": "Zadig",
                                "default": "Zadig",
                                "is_credential": false
                            },
                            {
                                "name": "weather_status",
                                "description": "what's the weather like today",
                                "type": "choice",
                                "value": "sunny",
                                "choice_option": [
                                    "sunny",
                                    "cloudy",
                                    "rainy"
                                ],
                                "default": "sunny",
                                "is_credential": false
                            }
                        ],
                        "outputs": []
                    }
                }
            ]
        }
    ],
    "project_name": "simple-service-demo",              # 项目名称
}

异常返回

# 指定的工作流任务不存在
{
    "code": 500,
    "description": "mongo: no documents in result",
    "message": "Internal Error: "
}

执行自定义工作流

coming soon…

取消自定义工作流任务

请求

DELETE /openapi/workflows/custom/task

Query

参数名	类型	描述	默认值	是否必须
`task_id`	int	自定义工作流任务 ID	无	must
`workflow_name`	string	自定义工作流名称	无	must

正常返回

{
    "message": "success"
}

异常返回

# 指定的工作流任务已成功运行完毕
{
    "code": 6163,
    "description": "task: build-images:20 is passed, cannot cancel",
    "extra": {},
    "message": "取消工作流任务失败",
    "type": "error"
}
# 指定的工作流或者任务不存在
{
    "code": 6163,
    "description": "mongo: no documents in result",
    "extra": {},
    "message": "取消工作流任务失败",
    "type": "error"
}

自定义工作流人工审核

请求

POST /openapi/workflows/custom/task/approve

Query

参数名	类型	描述	默认值	是否必须
`task_id`	int	自定义工作流任务 ID	无	must
`workflow_name`	string	自定义工作流名称	无	must
`stage_name`	string	自定义工作流待审核的阶段名称	无	must
`approve`	bool	是否审核通过	false	option
`comment`	string	审核信息	无	option

正常返回

{
    "message": "success"
}

异常返回

# 指定参数的阶段不需要审核
{
    "code": 6169,
    "description": "workflow build-images ID 23 stage deploy-myapps do not need approve",
    "extra": {},
    "message": "批准工作流任务失败",
    "type": "error"
}