# workflow-components

**Repository Path**: mirrors_tencentyun/workflow-components

## Basic Information

- **Project Name**: workflow-components
- **Description**: tencent cloud workflow components
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-18
- **Last Updated**: 2025-08-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 腾讯云工作流组件打包指引

工作流组件(component) 是工作流的执行单元, 用于执行特定的 devops 操作。每个工作流组件本质上是一个docker 容器镜像, 理论上任何 docker 容器镜像都可以作为工作流组件使用。 Tencent Hub 工作流系统还提供了一套组件定义规范, 遵循此规范的组件在Tencent Hub 工作流系统能达到更好的使用效果。

---
### 工作流组件规范
遵循此规范的组件在Tencent Hub 工作流编排中可以在UI控制台选中，并解析该组件的输入/输出在UI控制台中，有更好的操作体验和更好的使用效果。   

存储于Tencent Hub 的工作流组件需要有一个名为 `TencentHubComponent` 的 [Image Label](https://docs.docker.com/engine/reference/builder/#label)来进行标识, 该label的内容是一个固定格式的json 字符串, 在编写时需要进行正确的转义。


#### TencentHubComponent 格式规范:


| 字段        | 类型   | 必要/可选 | 说明         |
|-------------|--------|-----------|--------------|
| desc        | string | 可选      | 组件描述信息 |
| input       | array  | 可选      | 组件输入列表 |
| output      | array  | 可选      | 组件输出列表 |

组件输入列表`input` 格式如下:

| 字段    | 类型   | 必要/可选 | 说明               |
|---------|--------|-----------|--------------------|
| name    | string | 必要      | 输入值名称         |
| desc    | string | 可选      | 输入值描述         |
| default | array  | 可选      | 输入值的默认展示值 |

组件输入列表`output` 格式如下:

| 字段    | 类型   | 必要/可选 | 说明               |
|---------|--------|-----------|------------------|
| name    | string | 必要      | 输出值名称         |
| desc    | string | 可选      | 输出值描述         |


#### 输入值、输出值 name 规范:

 输入值、输出值在工作流中将转换为环境变量进行流转, 因此输入值、输出值 名称应该符合环境变量的命名约定:
 
 * 由字母数字下划线构成
 * 字母建议使用全大写, 用下划线进行分割

---

### 工作流输入输出流转

工作流中的组件可以定义输入输出, 下游组件可以使用上游已结束组件的输出, 组件的输入通过环境变量读取, 组件的输入通过特定格式的stdout进行输出.

组件的输入包括2个来源:

1. 工作流的全局变量
2. 上游组件的输出

组件输出给下游的变量需要在stdout中以前缀`[JOB_OUT]`进行包裹, 用`=`连接输出值得key和value, 多个输出值通过换行进行分隔:

```
[JOB_OUT] ARTIFACT = ./vendor
[JOB_OUT] IMAGE_ID = c442b20ea805
```

#### 组件执行状态判断

组件最终的执行状态有:

* 执行成功
* 执行失败
* 执行超时

对于组件退出码大于0的情况, 工作流会标记组件执行失败.

对于组件退出码等于0的情况, 默认认为组件执行成功, 但是在某些业务场景下, 用户希望标记该执行为失败, 这种情况可以通过特殊的组件输出`JOB_RESULT = false`进行强制标记组件失败.


#### 腾讯云工作流系统环境变量

workflow 引擎在执行用户工作流时, 会根据场景生成一些预置的全局环境变量, 在整个flow的job中都可以按需读取使用:

| 环境变量名称              | 含义                             | 生成场景                  | 内容说明                                                       |
|---------------------------|----------------------------------|---------------------------|----------------------------------------------------------------|
| `_WORKFLOW_BUILD_TYPE`    | 构建类型, 表示工作流被触发的方式 | 默认生成                  | manually: 手动触发; webhook: webhook触发; api: API触发         |
| `_WORKFLOW_GIT_CLONE_URL` | git 克隆地址                     | 当工作流和已授权的git关联 | 包含Basic Auth信息的git 克隆地址                               |
| `_WORKFLOW_GIT_REF`       | git 引用                         | 同上                      | 可以是git tag, git branch 或者 git commit                      |
| `_WORKFLOW_GIT_TYPE`      | git 引用类型                     | 同上                      | 用于指示`_WORKFLOW_GIT_REF`的类型, 可选值: tag, branch, commit |


 
---
 
### 工作流组件示例

dockerfile示例如下：

```
FROM ubuntu
RUN apt-get -yqq update && apt-get -yqq install docker.io && apt-get -yqq install git
RUN mkdir -p /root/src
WORKDIR /root/src
COPY . /usr/bin/
CMD ["component-docker"]

LABEL TencentHubComponent='{\
  "description": "TencentHub container component, build docker image",\
  "input": [\
    {"name": "GIT_CLONE_URL", "desc": "required, git clone url"},\
    {"name": "GIT_REF", "desc": "optional, git target reference, it can be a git commit, git tag or git branch"},\
    {"name": "GIT_TPYE", "desc": "optional, type of `GIT_REF`, it can be branch, tag or commit"},\
    {"name": "IMAGE", "desc": "optional, the result docker image tag, like `hub.cloud.tencent.com/fox/nodejs`, it can with or without tag"},\
    {"name": "IMAGE_TAG_FORMAT", "desc": "optional, image tag format"},\
    {"name": "IMAGE_TAG", "desc": "optional, the result docker image tag, default is `latest`"},\
    {"name": "EXTRA_IMAGE_TAG", "desc": "optional, extra docker image tag"},\
    {"name": "BUILD_WORKDIR", "default": ".", "desc": "optional, the work dir to run docker build"},\
    {"name": "DOCKERFILE_PATH", "default": "Dockerfile", "desc": "optional, Dockerfile path`"},\
    {"name": "BUILD_ARGS", "desc": "optional, arguments pass to docker build as build-arg, it must be valid json string, like `{\"HTTP_PROXY\":\"http://10.20.30.2:1234\",\"TIMEOUT\":\"10\"}`"}\
  ],\
  "output": [\
    {"name": "IMAGE", "desc": "url of pushed image without tag"},\
    {"name": "IMAGE_ID", "desc": "ID of pushed image tag"},\
    {"name": "IMAGE_DIGEST", "desc": "Image digest of pushed image tag"}\
  ]\
}'
```

在docker环境中使用 `docker build -t [ImageName:tag] .` 编译出镜像组件，推送到镜像仓库中，即可以在工作流中使用该镜像组件。docker镜像基础知识请参考[指引](https://docs.docker.com/engine/reference/builder/#usage)。

---

### 推送镜像仓库指引
登录腾讯云docker registry
```
sudo docker login --username=yourname hub.tencentyun.com
```

登录registry的用户名是您TencentHub的用户名，密码是您开通TencentHub用户时设置的密码


将镜像推送到registry

```
sudo docker login --username=yourname hub.tencentyun.com
```

```
sudo docker tag [ImageId] hub.tencentyun.com/3321337994/my_awesome_component:[tag]
```

其中[ImageId]为您编译出的镜像id，[tag]请根据您的镜像版本信息进行自定义填写。
```
sudo docker push hub.tencentyun.com/yourname/my_awesome_component:[tag]
```

---