工作流

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

产品工作流

通过 commitId 获取工作流任务状态

注意事项

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

请求

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

Query

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

正常返回

[
    {
        "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!"
}

通过任务 ID 获取工作流任务状态

请求

GET /openapi/workflows/product/:workflowKey/task/:taskID?projectKey=<项目标识>

Query参数说明

参数名	类型	描述	是否必须	默认值
`projectKey`	string	项目标识	是	无

路径参数说明

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

返回说明

参数名	类型	描述
`project_key`	string	项目标识
`workflow_key`	string	工作流标识
`workflow_name`	string	工作流名称
`task_id`	int	工作流任务ID
`task_creator`	string	工作流任务执行者
`create_time`	int	工作流任务创建时间
`start_time`	int	工作流任务开始时间
`end_time`	int	工作流任务结束时间
`status`	string	任务状态包括：created(创建中)、running(运行中)、passed(通过)、failed(失败)、timeout(超时)、cancelled(取消)

正常返回

{
    "workflow_key": "patrick-yaml-01-ops-workflow",
    "workflow_name": "patrick-yaml-01-ops-workflow",
    "project_key": "patrick-yaml-01",
    "task_id": 7,
    "create_time": 1688622655,
    "task_creator": "admin",
    "start_time": 1688622658,
    "end_time": 1688622670,
    "status": "passed",
}

异常返回

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

获取工作流任务列表

请求

GET /openapi/workflows/product/:workflowKey/tasks?projectKey=<项目标识>&pageNum=<当前页>&pageSize=<单页显示条数>

query 参数说明

参数名	类型	描述	是否必须	默认值
`projectKey`	string	项目标识	是	无
`pageNum`	int	分页参数-当前页数	否	1
`pageSize`	int	分页参数-当前页展示条数	否	50

路径参数说明

参数名	类型	描述	是否必须	默认值
`workflowKey`	string	工作流标识	是	无

返回说明

参数名	类型	描述
`project_key`	string	项目标识
`workflow_key`	string	工作流标识
`task_id`	int	工作流任务ID
`task_creator`	string	工作流任务执行者
`create_time`	int	工作流任务创建时间
`start_time`	int	工作流任务开始时间
`end_time`	int	工作流任务结束时间
`status`	string	任务状态包括：created(创建中)、running(运行中)、passed(通过)、failed(失败)、timeout(超时)、cancelled(取消)

正常返回

[
    {
        "workflow_key": "cosmos-build-1",
        "project_key": "cosmos-1",
        "task_id": 21,
        "create_time": 1689669590,
        "task_creator": "admin",
        "start_time": 1689669593,
        "end_time": 1689669615,
        "status": "cancelled"
    },
]

获取工作流任务详情

请求

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: "
}

执行工作流

注意事项

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

请求

POST /openapi/workflows/product/task

body 参数样例

点击查看

{
  "workflow_key": "my-workflow",
  "project_key": "my-workflow",
  "input": {
    "target_env": "dev",
    "build": {
      "enabled": true,
      "service_list": [
        {
          "service_module": "svc1",
          "service_name": "my_service",
          "repo_info": [
            {
              "codehost_name": "my_codehost",
              "repo_namespace": "my_namespace",
              "repo_name": "my_repo",
              "branch": "main"
            }
          ],
          "inputs": [
            {
              "key": "mykey",
              "value": "myvalue"
            }
          ]
        }
      ]
    },
    "deploy": {
      "enabled": true,
      "source": "zadig",
      "service_list": [
        {
          "service_module": "li",
          "service_name": "li",
          "image": "xxxxx:aaaaaa"
        }
      ]
    }
  }
}

body 参数说明

参数名	类型	描述	默认值	是否必须
`workflow_key`	string	工作流标识	无	是
`project_key`	string	项目标识	无	是
`input`	WorkflowInput	执行工作流参数	无	是

input 参数说明

参数名	类型	描述	默认值	是否必须
`target_env`	string	目标环境名称	无	否
`build`	BuildArgs	构建参数	无	是
`deploy`	DeployArgs	部署参数	无	是

BuildArgs 参数说明

参数名	类型	描述	默认值	是否必须
`enabled`	bool	是否启用构建	无	是
`service_list`	[]BuildServiceInfo	构建服务所需信息	无	否

BuildServiceInfo 参数说明

参数名	类型	描述	默认值	是否必须
`service_module`	string	服务组件名称	无	是
`service_name`	string	服务名称	无	是
`repo_info`	[]RepositoryInfo	代码库信息	无	否
`inputs`	[]UserInput	构建变量	无	否

RepositoryInfo 参数说明

参数名	类型	描述	默认值	是否必须
`codehost_name`	string	代码源标识	无	是
`repo_namespace`	string	代码库所属命名空间（组织/个人）	无	是
`repo_name`	string	代码库名称	无	是
`branch`	string	分支	无	是
`pr`	int	pr ID	0	使用 pr 构建时必传

UserInput 参数说明

参数名	类型	描述	默认值	是否必须
`key`	string	自定义变量的键	无	是
`value`	string	自定义变量的值	无	是

DeployArgs 参数说明

参数名	类型	描述	默认值	是否必须
`enabled`	bool	是否启用构建	无	是
`source`	string	部署镜像来源	无	如果使用 Zadig 构建则固定为 “zadig”
`service_list`	[]DeployServiceInfo	部署服务所需信息	无	否

DeployServiceInfo 参数说明

参数名	类型	描述	默认值	是否必须
`service_module`	string	服务组件名称	无	是
`service_name`	string	服务名称	无	是
`image`	string	镜像信息	无	使用 Zadig 构建时不填，否则必填

正常返回

{
  "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"
}

取消工作流任务

注意事项

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

请求

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"
}

重试工作流任务

注意事项

需要有执行工作流的权限
支持对状态是 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"
}

删除工作流

请求

DELETE /openapi/workflows/product?workflowKey=<工作流标识>&projectKey=<项目标识>

query 参数说明

参数名	类型	描述	默认值	是否必须
`workflowKey`	string	工作流标识	无	是
`projectKey`	string	项目标识	无	是

正常返回

{
  "message": "success"
}

自定义工作流

获取工作流列表

请求

GET /openapi/workflows?projectKey=<项目标识>&viewName=<视图名称>

Query

参数名	类型	描述	是否必须	默认值
`projectKey`	string	项目标识	是	无
`viewName`	string	工作流视图名称	否	无

返回说明

参数名	类型	描述
`workflows`	[]workflow	工作流列表

workflow

参数名	类型	描述
`workflow_key`	string	工作流标识
`workflow_name`	string	工作流名称
`update_by`	string	更新者
`update_time`	int	更新时间
`type`	string	工作流类型，有以下两种类型：”product”: 产品工作流”; custom”: 自定义工作流

成功返回

点击查看

{
    "workflows": [
        {
            "workflow_key": "just-deploy",
            "workflow_name": "just-deploy",
            "update_by": "admin",
            "update_time": 1686217885,
            "type": "custom"
        },
        {
            "workflow_key": "xiaxianfuwu",
            "workflow_name": "下线服务",
            "update_by": "admin",
            "update_time": 1686193453,
            "type": "custom"
        }
    ]
}

获取工作流详情

请求

GET /openapi/workflows/custom/{workflowKey}/detail?projectKey=<项目标识>

Query

参数名	类型	描述	是否必须	默认值
`projectKey`	string	项目标识	是	无

路径参数说明

参数名	类型	描述	是否必须	默认值
`workflowKey`	string	工作流标识	是	无

成功返回

点击查看

{
    "workflow_key": "build-deploy", // 工作流标识
    "workflow_name": "build-deploy", // 工作流名称
    "project_key": "lilian-test", // 项目标识
    "description": "", // 工作流描述
    "created_by": "admin", // 创建者
    "create_time": 1686192946, // 创建时间
    "updated_by": "", // 更新者
    "update_time": 1690180684, // 更新时间
    "params": [ // 工作流参数列表
        {
            "name": "code",
            "description": "",
            "type": "repo",
            "value": "",
            "repo": {
                "source": "gitee",
                "repo_owner": "liyue326",
                "repo_namespace": "liyue326",
                "repo_name": "picture",
                "remote_name": "origin",
                "branch": "master",
                "hidden": false,
                "is_primary": false,
                "codehost_id": 4,
                "oauth_token": "",
                "address": "",
                "source_from": "",
                "param_name": "",
                "job_name": "",
                "service_name": "",
                "service_module": "",
                "repo_index": 0,
                "submission_id": ""
            },
            "default": "",
            "is_credential": false
        },
        {
            "name": "name",
            "description": "",
            "type": "string",
            "value": "build",
            "repo": null,
            "default": "",
            "is_credential": false
        }
    ],
    "stages": [ // 工作流阶段列表
        {
            "name": "build", // 阶段名称
            "parallel": true, // 是否并发运行
            "approval": { // 审批信息
                "enabled": false,
                "type": "native",
                "description": "",
                "native_approval": {
                    "Timeout": 5,
                    "approve_users": [],
                    "NeededApprovers": 0
                },
                "dingtalk_approval": {
                    "Timeout": 5
                }
            },
            "jobs": [ // 工作流job列表
                {
                    "name": "build", // job名称
                    "type": "zadig-build", // job类型
                    "skipped": false, // 是否执行
                    "spec": { // job详细信息
                        "docker_registry_id": "630c7ad700430c131062e245",
                        "service_and_builds": [
                            {
                                "build_name": "openapi-build",
                                "image": "",
                                "image_name": "service1",
                                "key_vals": [],
                                "repos": [],
                                "service_module": "service1",
                                "service_name": "service1",
                                "share_storage_info": null
                            }
                        ]
                    },
                    "run_policy": "",
                    "service_modules": []
                }
            ]
        },
        {
            "name": "deploy",
            "parallel": true,
            "approval": {
                "enabled": false,
                "type": "native",
                "description": "",
                "native_approval": {
                    "Timeout": 5,
                    "approve_users": [],
                    "NeededApprovers": 0
                },
                "dingtalk_approval": {
                    "Timeout": 5
                }
            },
            "jobs": [
                {
                    "name": "deploy",
                    "type": "zadig-deploy",
                    "skipped": false,
                    "spec": {
                        "deploy_contents": [
                            "image",
                            "vars"
                        ],
                        "deploy_type": "",
                        "env": "dev",
                        "job_name": "build",
                        "origin_job_name": "",
                        "production": false,
                        "service_and_images": [],
                        "services": [
                            {
                                "key_vals": [],
                                "latest_key_vals": [],
                                "latest_variable_kvs": [],
                                "service_name": "service2",
                                "updatable": false,
                                "update_config": false,
                                "variable_configs": [],
                                "variable_kvs": [],
                                "variable_yaml": ""
                            },
                            {
                                "key_vals": [],
                                "latest_key_vals": [],
                                "latest_variable_kvs": [],
                                "service_name": "service1",
                                "updatable": true,
                                "update_config": false,
                                "variable_configs": [
                                    {
                                        "use_global_variable": false,
                                        "variable_key": "cpuLimit"
                                    },
                                    {
                                        "use_global_variable": false,
                                        "variable_key": "memoryLimit"
                                    },
                                    {
                                        "use_global_variable": false,
                                        "variable_key": "port"
                                    }
                                ],
                                "variable_kvs": [],
                                "variable_yaml": ""
                            }
                        ],
                        "skip_check_run_status": false,
                        "source": "fromjob"
                    },
                    "run_policy": "",
                    "service_modules": []
                },
                {
                    "name": "default",
                    "type": "plugin",
                    "skipped": false,
                    "spec": {
                        "plugin": {
                            "args": [
                                "echo $(inputs.CONTENT)"
                            ],
                            "category": "",
                            "cmds": [
                                "/bin/sh",
                                "-c"
                            ],
                            "description": "hello world",
                            "envs": [
                                {
                                    "name": "CONTENT",
                                    "value": "$(inputs.CONTENT)"
                                }
                            ],
                            "image": "alpine/curl:3.14",
                            "inputs": [
                                {
                                    "default": "hello world",
                                    "description": "content to print",
                                    "is_credential": false,
                                    "name": "CONTENT",
                                    "repo": null,
                                    "type": "string",
                                    "value": "hello world"
                                }
                            ],
                            "is_offical": false,
                            "name": "hello-world",
                            "outputs": [],
                            "repo_url": "",
                            "version": "v0.0.1"
                        },
                        "properties": {
                            "build_os": "",
                            "cache": {
                                "medium_type": "",
                                "nfs_properties": {
                                    "provision_type": "",
                                    "pvc": "",
                                    "storage_class": "",
                                    "storage_size_in_gib": 0,
                                    "subpath": ""
                                },
                                "object_properties": {
                                    "id": ""
                                }
                            },
                            "cache_dir_type": "",
                            "cache_enable": false,
                            "cache_user_dir": "",
                            "cluster_id": "",
                            "custom_envs": [],
                            "envs": [],
                            "image_from": "",
                            "image_id": "",
                            "log_file_name": "",
                            "namespace": "",
                            "params": [],
                            "registries": [],
                            "res_req": "low",
                            "res_req_spec": {
                                "cpu_limit": 1000,
                                "gpu_limit": "",
                                "memory_limit": 512
                            },
                            "retry": 0,
                            "share_storage_details": [],
                            "timeout": 60
                        }
                    },
                    "run_policy": "",
                    "service_modules": []
                }
            ]
        }
    ],
    "notify_ctls": [ // 通知配置信息列表
        {
            "enabled": true,
            "webhook_type": "wechat",
            "weChat_webHook": "xxx",
            "notify_type": [
                "created",
                "failed"
            ]
        }
    ],
    "share_storages": [], // 共享卷信息
    "concurrency_limit": 1 // 并发执行数量
}

获取自定义工作流任务列表

请求

GET /openapi/workflows/custom/:workflowKey/tasks?projectKey=<项目标识>

query 参数说明

参数名	类型	描述	是否必须	默认值
`projectKey`	string	项目标识	是	无
`pageNum`	int	分页-当前页数	否	1
`pageSize`	int	分页-单页展示条目	否	50

路径参数说明

参数名	类型	描述	是否必须	默认值
`workflowKey`	string	工作流标识	是	无

返回说明

参数名	类型	描述
`total`	int	工作流任务总数
`workflow_tasks`	[]workflow_task	工作流任务列表

workflow_task

参数名	类型	描述
`workflow_key`	string	工作流标识
`workflow_name`	string	工作流名称
`project_key`	string	项目标识
`task_id`	int	工作流任务ID
`task_creator`	string	工作流任务执行者
`create_time`	int	工作流任务创建时间
`start_time`	int	工作流任务开始时间
`end_time`	int	工作流任务结束时间
`status`	string	任务状态包括：created(创建中)、running(运行中)、passed(通过)、failed(失败)、timeout(超时)、cancelled(取消)

正常返回

{
    "total": 15,
    "workflow_tasks": [
        {
            "workflow_key": "build-deploy",
            "workflow_name": "build-deploy",
            "project_key": "lilian-test",
            "task_id": 15,
            "create_time": 1688543613,
            "task_creator": "webhook",
            "start_time": 1688543615,
            "end_time": 1688543636,
            "status": "passed"
        }
    ]
}

异常返回

{
    "code": 400,
    "description": "workflow name is required",
    "extra": {},
    "message": "Bad Request",
    "type": "error"
}

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

GET /openapi/workflows/custom/task?taskId=<工作流任务ID>&workflowKey=<工作流标识>

Query

参数名	类型	描述	默认值	是否必须
`taskId`	int	工作流任务 ID	无	是
`workflowKey`	string	工作流标识	无	是

正常返回

点击查看

{
    "task_id": 24,                              # 自定义工作流任务序号 ID
    "workflow_key": "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": "ZadigX"
                            },
                            {
                                "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_否": [
                                    "sunny",
                                    "cloudy",
                                    "rainy"
                                ],
                                "default": "sunny",
                                "is_credential": false
                            }
                        ],
                        "outputs": []
                    }
                }
            ]
        }
    ],
    "project_key": "simple-service-demo",              # 项目标识
}

异常返回

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

执行自定义工作流

注意事项

暂不支持通过 OpenAPI 触发自定义任务
暂不支持通过 OpenAPI 指定工作流全局变量

请求

POST /openapi/workflows/custom/task

body 参数样例

点击查看

{
    "project_key": "helm", // 项目标识
    "workflow_key": "test-openapi", // 工作流标识
    "inputs": [
        {
            "job_name": "build-myapps",
            "job_type": "zadig-build",
            "parameters": {
                "registry": "https://koderover.******.com/test",
                "service_list": [
                    {                                 
                        "service_module": "aslan",
                        "service_name": "zadig",
                        "repo_info": [{
                            "codehost_name": "koderover",
                            "repo_namespace": "koderover",
                            "repo_name": "zadig",
                            "branch": "main"
                        }]
                        inputs: [{
                            "key": "username",
                            "value": "admin"
                        },
                        {
                            "key": "password",
                            "value": "ZadigX"
                        }]
                    }
                ]
            }
        },
        {
            "job_name": "deploy-myapps",
            "job_type": "zadig-deploy",
            "parameters": {
                "env_name": "dev",
                "service_list": [
                {
                    "service_name": "zadig",
                    "service_module": "aslan",
                    "image_name": "koderover.******.com/test/aslan:main"
                },
                {
                    "service_name": "zadig",
                    "service_module": "zadig-portal",
                    "image_name": "koderover.******.com/test/zadig-portal:main"
                }
            ]
        }
        {
            "job_name": "jira-issue-update",
            "job_type": "freestyle",
            "parameters": {
                "kv": [
                    {
                        "key": "IssueID",
                        "value": "ZAD-10126"
                    },
                    {
                        "key": "FromStatus",
                        "value": "Testing"
                    },
                    {
                        "key": "TargetStatus",
                        "value": "ToBeReleased"
                    }
                ]
            }
        },
        {
            "job_name": "deploy-my-app",
            "job_type": "custom-deploy",
            "parameters": {
                "target_list": [
                    {
                        "workload_type": "Deployment",
                        "workload_name": "service2",
                        "container_name": "service2",
                        "image_name": "koderover.***.com/test/service2:0505"
                    }
                ]
            }
        }
    ]
}

body 参数说明

参数名	类型	描述	默认值	是否必须
`project_key`	string	项目标识	无	是
`workflow_key`	string	自定义工作流标识	无	是
`inputs`	[]Input	执行工作流的具体参数	无	是

Input 参数说明

下面将分开介绍内置构建任务、部署任务、Kubernetes 部署任务、通用任务的触发参数。

构建任务

{
    "job_name": "build-myapps",                           # 构建任务名称
    "job_type": "zadig-build",                            # 构建任务类型，指定为 zadig-build
    "parameters": {
        "registry": "https://koderover.******.com/test",  # 镜像仓库信息
        "service_list": [                                 # 要构建的服务信息
            {                                 
                "service_module": "aslan",                # 服务组件名称
                "service_name": "zadig",                  # 服务名称
                "repo_info": [{                           # 构建该服务组件的代码库信息
                    "codehost_name": "koderover",         # 代码源标识
                    "repo_namespace": "koderover",        # 代码库组织名/用户名
                    "repo_name": "zadig",                 # 代码库名称
                    "branch": "main"                      # 代码库分支
                }]
                inputs: [{                                # 构建变量信息，若设置为固定值或全局变量，则无需指定
                    "key": "username",
                    "value": "admin"
                },
                {
                    "key": "password",
                    "value": "ZadigX"
                }]
            },
            {
                "service_module": "zadig-portal",
                "service_name": "zadig",
                "repo_info": [{
                    "codehost_name": "koderover",
                    "repo_namespace": "koderover",
                    "repo_name": "zadig-portal",
                    "branch": "main"
                }]
            }
        ]
    }
}

部署任务

{
    "job_name": "deploy-myapps",                              # 部署任务名称
    "job_type": "zadig-deploy",                               # 部署任务类型，指定为 zadig-deploy
    "parameters": {                                           # 部署参数
        "env_name": "dev",                                    # 待部署环境信息，若设置为固定值或全局变量，则无需配置该字段
        "service_list": [                                     # 待部署服务信息，若设置为其他任务输出，则无需配置该字段
        {
            "service_name": "zadig",                          # 待部署服务名称
            "service_module": "aslan",                        # 待部署服务组件名称
            "image_name": "koderover.***.com/test/aslan:main" # 待部署服务组件的镜像
        },
        {
            "service_name": "zadig",
            "service_module": "zadig-portal",
            "image_name": "koderover.***.com/test/zadig-portal:main"
        }
    ]
}

Kubernetes 部署任务

{
    "job_name": "deploy-my-app",                                     # Kubernetes 部署任务名称
    "job_type": "custom-deploy",                                     # Kubernetes 部署任务类型，指定为 custom-deploy
    "parameters": {
        "target_list": [                                             # 待部署容器信息，若设置为固定值，则无需指定
            {
                "workload_type": "Deployment",                       # 待部署容器应用的类型，支持 Deployment 以及 StatefulSet
                "workload_name": "service2",                         # 待部署容器应用的名称
                "container_name": "service2",                        # 待部署容器应用的 container 名称
                "image_name": "koderover.***.com/test/service2:0505" # 待部署容器的镜像信息
            }
        ]
    }
}

通用任务

{
    "job_name": "jira-issue-update",            # 通用任务名称
    "job_type": "freestyle",                    # 通用任务类型，指定为 freestyle
    "parameters": {                             # 通用任务中的参数和值，若设置为固定值或全局变量，则无需指定
        "kv": [
            {
                "key": "IssueID",
                "value": "ZAD-10126"
            },
            {
                "key": "FromStatus",
                "value": "Testing"
            },
            {
                "key": "TargetStatus",
                "value": "ToBeReleased"
            }
        ],
        "repo_info": [                          # 通用任务中的代码库信息
            {
                "codehost_name": "koderover",   # 代码源标识
                "repo_namespace": "koderover",  # 代码库组织名/用户名
                "repo_name": "zadig",           # 代码库名称
                "branch": "task-mgr"            # 代码库分支
            }
        ]
    }
}

测试任务

{
    "job_name": "test-myapps",                            # 测试任务名称
    "job_type": "zadig-test",                             # 构建任务类型，指定为 zadig-test
    "parameters": {
        "testing_list": [                                 # 要测试的任务信息
            {                                 
                "testing_name": "unit-test",              # 测试任务名称
                "repo_info": [{                           # 测试任务的代码库信息
                    "codehost_name": "koderover",         # 代码源标识
                    "repo_namespace": "koderover",        # 代码库组织名/用户名
                    "repo_name": "zadig",                 # 代码库名称
                    "branch": "main"                      # 代码库分支
                }]
                inputs: [{                                # 测试变量信息，若设置为固定值或全局变量，则无需指定
                    "key": "username",
                    "value": "admin"
                },
                {
                    "key": "password",
                    "value": "ZadigX"
                }]
            },
            {
                "testing_name": "integration-test",
                "repo_info": [{
                    "codehost_name": "koderover",
                    "repo_namespace": "koderover",
                    "repo_name": "zadig-portal",
                    "branch": "main"
                }]
            }
        ]
    }
}

代码扫描任务

{
    "job_name": "scan-myapps",                            # 代码扫描任务名称
    "job_type": "zadig-scanning",                         # 构建任务类型，指定为 zadig-scanning
    "parameters": {
        "scanning_list": [                                # 代码扫描的任务信息
            {                                 
                "scanning_name": "scan",                  # 代码扫描任务名称
                "repo_info": [{                           # 代码扫描任务的代码库信息
                    "codehost_name": "koderover",         # 代码源标识
                    "repo_namespace": "koderover",        # 代码库组织名/用户名
                    "repo_name": "zadig",                 # 代码库名称
                    "branch": "main"                      # 代码库分支
                }]
            },
            {
                "scanning_name": "scan-1",
                "repo_info": [{
                    "codehost_name": "koderover",
                    "repo_namespace": "koderover",
                    "repo_name": "zadig-portal",
                    "branch": "main"
                }]
            }
        ]
    }
}

正常返回

{
    "project_name": "simple-service-demo", # 项目标识
    "workflow_name": "openapi-test",       # 自定义工作流名称
    "task_id": 20                          # 自定义工作流任务执行的序号 ID
}

取消自定义工作流任务

请求

DELETE /openapi/workflows/custom/task?task_id=<task_id>&workflowKey=<工作流标识>

Query

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

正常返回

{
    "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/:workflowKey/task/:taskID?projectKey=<项目标识>

query 参数说明

参数名	类型	描述	是否必须	默认值
`projectKey`	string	项目标识	是	无

路径参数说明

参数名	类型	描述	是否必须	默认值
`workflowKey`	string	工作流标识	是	无
`taskID`	int	工作流任务ID	是	无

正常返回

{
  "message": "success"
}

异常返回

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

审批自定义工作流

提示

适用于 Zadig 审批。

请求

POST /openapi/workflows/custom/task/approve

body 参数说明

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

body 参数示例

{
    "task_id": 2,
    "workflow_key": "infra-dev-workflow",
    "stage_name": "deploy",
    "approve": true,
    "comment": "LGTM"
}

正常返回

{
    "message": "success"
}

异常返回

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

创建自定义工作流

请求

POST /api/aslan/workflow/v4

body 参数说明

提示

该接口的参数相对复杂，自己组装比较费力。推荐先在页面中创建自定义工作流 -> 在配置页面点击 YAML -> 复制 YAML 内容后借助在线转换工具 (opens new window)来快速获得参数。

参数名	类型	描述	默认值	是否必须
`name`	string	自定义工作流标识	无	是
`display_name`	string	自定义工作流名称	无	是
`project`	string	项目标识	无	是
`description`	string	自定义工作流描述信息	无	否
`concurrency_limit`	int	工作流任务并发数，-1 表示无限制，0 表示不可执行	0	是
`stages`	[]Stage	阶段配置	无	否

Stage 参数说明

参数名	描述	类型	必填
`name`	阶段名称	string	是
`parallel`	是否开启并发执行	bool	是
`approval`	人工审批配置	[]Approval	否
`jobs`	任务配置	[]interface{}	是

Approval 参数说明

参数名	描述	类型	必填
`enabled`	是否开启人工审批	bool	是
`type`	审批方式，可选值如下： `native`（即：Zadig 审批） `lark`（即：飞书审批）	string	`enabled` = true 时必填
`native_approval`	Zadig 审批配置	[]NativeApproval	`type` = `native` 时必填
`lark_approval`	飞书审批配置	[]LarkApproval	`type` = `lark` 时必填

NativeApproval 参数说明

参数名	描述	类型	必填
`approve_users`	审批人清单	[]ApproveUser	是
`timeout`	超时时间，单位分钟	int	是
`needed_approvers`	需要审批的人数	int	是

ApproveUser 参数说明

参数名	描述	类型	必填
`user_name`	审批人的账号名称	string	是
`user_id`	审批人的账号 ID	string	是

LarkApproval 参数说明

参数名	描述	类型	必填
`approve_users`	审批人清单	[]LarkApproveUser	是
`timeout`	超时时间，单位分钟	int	是

LarkApproveUser 参数说明

参数名	描述	类型	必填
`id`	审批人的账号 ID	string	是
`name`	审批人的账号名称	string	是

body 参数示例

以下 body 示例中包含 构建 -> 部署 -> 测试 -> 自定义任务四个阶段：

点击查看

{
    "name": "workflow-demo",
    "display_name": "workflow-demo",
    "project": "demo",
    "description": "workflow-demo description",
    "concurrency_limit": 5,
    "stages": [
        {
            "name": "构建",
            "parallel": true,
            "jobs": [
                {
                    "name": "build",
                    "type": "zadig-build",
                    "run_policy": "",
                    "spec": {
                        "docker_registry_id": "62c**********",
                        "service_and_builds": [
                            {
                                "service_name": "service1",
                                "service_module": "service1",
                                "image_name": "nginx",
                                "value": "service1/service1",
                                "build_name": "build-demo"
                            }
                        ]
                    }
                }
            ]
        },
        {
            "name": "部署",
            "parallel": true,
            "approval": {
                "enabled": true,
                "type": "native",
                "native_approval": {
                    "approve_users": [
                        {
                            "user_name": "admin",
                            "user_id": "9792310b-**********"
                        },
                        {
                            "user_name": "sre-admin",
                            "user_id": "9837370s-**********"
                        }
                    ],
                    "timeout": 5,
                    "needed_approvers": 1
                }
            },
            "jobs": [
                {
                    "name": "deploy",
                    "type": "zadig-deploy",
                    "spec": {
                        "env": "dev",
                        "production": false,
                        "deploy_contents": [
                            "image"
                        ],
                        "skip_check_run_status": false,
                        "source": "fromjob",
                        "job_name": "build",
                        "service_and_images": [
                            {
                                "service_name": "service1",
                                "service_module": "service1",
                                "value": "service1/service1"
                            }
                        ]
                    }
                }
            ]
        },
        {
            "name": "测试",
            "parallel": true,
            "jobs": [
                {
                    "name": "test",
                    "type": "zadig-test",
                    "spec": {
                        "test_type": "service_test",
                        "source": "fromjob",
                        "job_name": "build",
                        "service_and_tests": [
                            {
                                "service_name": "service1",
                                "service_module": "service1",
                                "name": "smoke-test",
                                "project_name": "voting-app"
                            }
                        ]
                    }
                }
            ]
        },
        {
            "name": "分发",
            "parallel": true,
            "jobs": [
                {
                    "name": "common",
                    "type": "freestyle",
                    "run_policy": "",
                    "spec": {
                        "properties": {
                            "timeout": 60,
                            "res_req": "low",
                            "res_req_spec": {
                                "cpu_limit": 1000,
                                "memory_limit": 512
                            },
                            "cluster_id": "",
                            "build_os": "focal",
                            "image_id": "630xxxxxxxxxxxx",
                            "image_from": "koderover",
                            "envs": [
                                {
                                    "key": "key1",
                                    "value": "val1",
                                    "type": "string",
                                    "is_credential": false
                                }
                            ],
                            "cache_enable": true,
                            "cache_dir_type": "workspace",
                            "cache_user_dir": ""
                        },
                        "steps": [
                            {
                                "name": "tools",
                                "type": "tools",
                                "spec": {
                                    "installs": [
                                        {
                                            "name": "go",
                                            "version": "1.19.3",
                                            "id": "go1.19.3"
                                        }
                                    ]
                                }
                            },
                            {
                                "name": "git",
                                "type": "git",
                                "spec": {
                                    "repos": [
                                        {
                                            "codehost_id": 23,
                                            "repo_owner": "owner1",
                                            "repo_name": "hello",
                                            "source": "GitHub",
                                            "branch": "main",
                                            "checkout_path": "",
                                            "remote_name": "origin",
                                            "submodules": false,
                                            "hidden": false,
                                            "repo_namespace": "owner1"
                                        }
                                    ]
                                }
                            },
                            {
                                "name": "shell",
                                "type": "shell",
                                "spec": {
                                    "script": "#!/bin/bash\nset -e\necho hello"
                                }
                            }
                        ]
                    }
                }
            ]
        },
        {
            "name": "镜像分发",
            "parallel": true,
            "jobs": [
                {
                    "name": "image-release",
                    "type": "zadig-distribute-image",
                    "run_policy": "",
                    "isCreate": true,
                    "spec": {
                        "source": "fromjob",
                        "job_name": "build",
                        "source_registry_id": "",
                        "target_registry_id": "630xxxxxxxxxxxx",
                        "targets": [
                        {
                            "service_name": "n-1",
                            "service_module": "nginx-latest",
                            "image_name": "nginx",
                            "value": "n-1/nginx-latest"
                        }
                        ],
                        "timeout": 10,
                        "cluster_id": "",
                        "params": []
                    }
                }
            ]
        }
    ]
}

删除自定义工作流

请求

DELETE /openapi/workflows/custom?workflowKey=<工作流标识>&projectKey=<项目标识>

query 参数说明

参数名	类型	描述	默认值	是否必须
`workflowKey`	string	工作流标识	无	是
`projectKey`	string	项目标识	无	是

正常返回

{
  "message": "success"
}

工作流视图

获取工作流视图列表

请求

GET /openapi/workflows/view?projectKey=<项目标识>

query 参数说明

参数名	类型	描述	是否必须	默认值
`projectKey`	string	项目标识	是	无

返回说明

参数名	说明	类型
`name`	视图名称	string
`project_key`	项目标识	string
`update_time`	更新时间	int
`update_by`	更新者	string
`workflows`	工作流列表	[]workflow

workflow

参数名	说明	类型
`workflow_key`	工作流标识	string
`workflow_type`	工作流类型，有以下两种类型： `product`：产品工作流 `custom`：自定义工作流	string

正常返回

点击查看

[
    {
        "name": "test-view",
        "project_key": "lilian-test",
        "workflows": [
            {
                "workflow_key": "xiaxianfuwu",
                "workflow_type": "custom",
            }
        ],
        "update_time": 1689329334,
        "update_by": "admin"
    }
]

创建工作流视图

请求

POST /openapi/workflows/view

body 参数说明

参数名	说明	类型	必填
`project_key`	项目标识	string	是
`name`	工作流视图名称	string	是
`workflow_list`	工作流列表	[]Workflow	是

Workflow 参数说明

参数名	说明	类型	必填
`workflow_key`	工作流标识	string	是
`workflow_type`	工作流类型，有以下两种类型： `product`：产品工作流 `custom`：自定义工作流	string	是

body 参数示例

点击查看

{
    "project_key": "demo",
    "name": "view-demo",
    "workflow_list": [
        {
            "workflow_key": "dev",
            "workflow_type": "custom"
        },
        {
            "workflow_key": "nacos-config-update",
            "workflow_type": "custom"
        }
    ]
}

正常返回

{
  "message": "success"
}

编辑工作流视图

请求

PUT /openapi/workflows/view/:viewName?projectKey=<项目标识>

query 参数说明

参数名	类型	描述	是否必须	默认值
`projectKey`	string	项目标识	是	无

路径参数说明

参数名	类型	描述	是否必须	默认值
`viewName`	string	视图名称	是	无

body 参数说明

参数名	说明	类型	必填	默认值
`workflow_list`	工作流列表	[]Workflow	是	无

workflow

参数名	说明	类型	必填	默认值
`workflow_key`	工作流标识	string	是	无
`workflow_type`	工作流类型，有以下两种类型： `product`：产品工作流 `custom`：自定义工作流	string	是	无
`enabled`	`true`：将工作流加入视图 `false`：将工作流从视图中删除	bool	是	无

body参数示例

点击查看

{
    "workflow_list":[
        {
            "workflow_key":"build-deploy",
            "workflow_type":"custom",
            "enabled":true
        }
    ]
}

正常返回

{
  "message": "success"
}

删除工作流视图

请求

DELETE /openapi/workflows/view/:viewName?projectKey=<项目标识>

query 参数说明

参数名	类型	描述	是否必须	默认值
`projectKey`	string	项目标识	是	无

路径参数说明

参数名	类型	描述	是否必须	默认值
`viewName`	string	视图名称	是	无

正常返回

{
    "message": "success"
}

异常返回

{
    "code": 6894,
    "description": "find workflow view error: mongo: no documents in result",
    "extra": {},
    "message": "删除视图失败",
    "type": "error"
}