自定义步骤介绍¶

不同企业在流水线的定义中，由于存在各种各样的场景，所以对所需要的流水线步骤也不尽相同，工作台提供了自定义步骤的能力，方便企业来快速编写开发符合实际场景自定义步骤。

开发自定义步骤¶

自定义步骤的开发通过纯 YAML 的声明模式来定义，前往了解自定义步骤开发指南。

另外 DCE 5.0 应用工作台提供了一些内置的自定义步骤来供用户使用。

创建自定义步骤¶

前往 应用工作台 -> 工作台管理 -> 流水线设置 -> 自定义步骤
在 自定义步骤列表 可以看到系统内置、平台定义两种来源的步骤，其中系统内置是由平台提供的自定义步骤
点击界面的 创建自定义步骤 按钮，进入到创建界面
按照自定义步骤开发指南开发好的声明文件填写至编辑器后，点击创建。

开启与禁用自定义步骤¶

自定义步骤提供了步骤的状态：启用、未启用，在实际开发过程中，对于一些还不具备生产可用的步骤，建议标记为禁用状态。对于已经调试完成的，管理员可以标记为开启状态，一旦开启后，所有工作空间下的成员均可使用该步骤。

使用自定义步骤¶

配置 Jenkins¶

自定义插件功能依赖于 Jenkins 的共享库功能，因此首先需要在 Jenkins 中配置共享库。

修改 Jenkins 的 casc 配置项使之开启：

点击左上角的 ≡ 打开导航栏，选择 容器管理 -> 集群列表 ，找到需要安装 Jenkins 的集群，点击该集群的名称。
找到 配置与密钥 -> 配置项 ，命名空间选择 amamba-system ，搜索 global-jenkins-casc-config ，在操作列点击 编辑 YAML 。
在 data -> jenkins.yaml -> unclassified 字段下添加如下内容：
```
unclassified:
  globalLibraries: # (1)!
    libraries:
      - name: amamba-shared-lib
        defaultVersion: main
        implicit: true # (2)!
        retriever:
          modernSCM:
            libraryPath: ./
            scm:
              git:
                remote: https://github.com/amamba-io/amamba-shared-lib.git # (3)!
```
1. 共享库配置
2. 表示该共享库会被默认引入到所有流水线中，在 Jenkinsfile 中就 不再需要 使用 @Library 注解引入。如果开启了此参数将会对所有的流水线生效，会略微延长流水线的执行时间。如果不需要则设置为 false，后续如果某个流水线需要使用到自定义插件功能，则需要在 Jenkinsfile 中使用 @Library('amamba-shared-lib@main') _ 引入。
3. 表示工作台维护的共享库地址，是实现自定义插件的代码仓库地址。仓库地址是公开的。 在网络受限的环境下，您可以将其 clone 到内网的 git 服务器上，然后将地址改为内网地址。

使用自定义插件¶

选择一条流水线，进入详情，点击 编辑流水线
点击 添加步骤 ，即可看到自定义步骤，选择后填写相关参数即可

注意，自定义步骤有以下限制：

必须要在一个包含 Docker 或者 Podman 的容器中运行，因此您需要选择 使用容器
因为本质上是在容器中执行脚本，某些脚本可能需要一些特殊的权限。当自定义步骤无法实现时，推荐使用 执行 Shell 步骤，自行编写脚本。

自定义插件使用时会被渲染成如下的 Jenkinsfile 片段：

container("base") {
    amambaCustomStep(
        pluginID: 'printEnv',      // 插件名称
        version: 'v1.0.0',         // 插件版本
        docker: [
            image: 'alpine',       // 插件使用的镜像
            shell: '/bin/bash',    // 解释器
            script: 'env',         // 在镜像中执行的脚本
        ],
        args: [
            key1: 'val',           // 插件中定义的参数
            key2: [
                'key3': 'val3'
            ],
            key4: ["val4", "val5"]
        ],
    )
}

args 中的所有参数都会以环境变量的形式传递到插件中，因此您可以在 script中通过 $key1 的形式获取到参数的值。如果参数的类型是 kv，参数的 key 会以 _ 连接后传递到插件中，如 key2_key3=val3。如果参数定义的是数组类型，则传递到插件中的值是 ["val4", "val5"]，您需要按照不同的语言自行解析。

因此，即使您不采用 DAG 的形式编排，依旧可以按照上述标准在 Jenkinsfile 中使用自定义插件。只是需要注意，参数的值类型为 string 时请使用单引号，避免无法替换环境变量的问题。

环境变量和凭证¶

在 Jenkinsfile 中定义的环境变量和凭证，都可以在插件中读取到，比如：

withCredential([usernamePassword(credentialsId: 'my-credential', usernameVariable: 'USERNAME', passwordVariable: 'PASSWORD')]) {
    amambaCustomStep(
        pluginID: 'printEnv',
        version: 'v1.0.0',
        docker: [
            image: 'alpine',
            shell: '/bin/bash', // 可以在插件的 script 中读取到 USERNAME 和 PASSWORD 变量
            script: 'env',
        ],
        args: [],
    )
}

如何拉取私有镜像¶

如果您在定义插件时使用的是私有镜像，则需要通过以下方式使用自定义步骤：

在工作台中创建一个用户名密码类型的凭证，用于存储私有镜像的用户名和密码。
在使用自定义步骤之前，添加一个 使用凭证 的步骤，用户名变量填写 PLUGIN_REGISTRY_USER，密码变量填写 PLUGIN_REGISTRY_PASSWORD。

渲染出的 Jenkinsfile 片段如下：

withCredential([usernamePassword(credentialsId: 'my-credential', usernameVariable: 'PLUGIN_REGISTRY_USER', passwordVariable: 'PLUGIN_REGISTRY_PASSWORD')]) {
    amambaCustomStep(
        ...
    )
}

后续即可使用私有的镜像作为插件的基础镜像。