Help Center/ CodeArts Pipeline/ User Guide/ Managing Pipeline Extensions/ Customizing Extensions on the GUI
Updated on 2024-10-15 GMT+08:00
View PDF
Share

Customizing Extensions on the GUI

Creating an Extension

  1. Access the CodeArts Pipeline homepage.
  2. On the CodeArts Pipeline homepage, choose Services > Extensions.
  3. Click .
  4. Set basic information. For details, see Table 1.

    Table 1 Extension information

    Parameter

    Description

    Icon

    Icon of the extension. Upload an image in PNG, JPEG, or JPG format, with a file size no more than 512 KB (recommended: 128 x 128 pixels). If no image is uploaded, the system generates an icon.

    Name

    The extension name displayed in the extension platform. Enter only spaces, letters, digits, underscores (_), hyphens (-), and periods (.) with a maximum of 50 characters.

    Unique Identifier

    ID of the extension. Once set, this parameter cannot be changed. Enter only letters, digits, underscores (_), and hyphens (-) with a maximum of 50 characters.

    Type

    Type of the extension, which can be Build, Check, Test, Deploy, or Normal. Once set, this parameter cannot be changed.

    Description

    Purposes and functions of the extension. The description can be edited. Enter no more than 1,000 characters.

  5. Click Next. On the Version Information page, set the version and description.

    • Version of the extension, in X.X.X format. Each digit ranges from 0 to 99.
    • Version information of the extension cannot be modified later.

  6. Click Next. The Input page is displayed. Configure widgets as needed.

    You can drag and drop widgets to generate visual forms, which can streamline pipeline contexts. Multiple preset widgets are available: Single-line Text Box, Digit, Single-selection Drop-down List, Multi-selection Drop-down List, Option Button, Switch, Multi-line Text Box, and so on.

    Figure 1 Orchestrating widgets

    Drag required widgets to the middle area. Click a widget to configure its parameters on right part of the page.

    Table 2 Widget parameters

    Category

    Parameter

    Description

    Widget

    Basic

    Unique Identifier

    Unique ID of the widget. The ID is used to obtain widget input. Enter only letters, digits, underscores (_), and hyphens (-) with a maximum of 200 characters.

    All

    Title

    Name of the widget. The name will be displayed on the pipeline job orchestration page. Enter no more than 140 characters.

    All

    Tips

    Tooltip of the widget. Enter no more than 1,000 characters.

    All

    Placeholder

    Message displayed in the text box. For example, input specifications.

    Single-line Text Box

    Accuracy

    Number of decimal places allowed in a widget value: 0 to 4.

    Digits

    Default Value

    Default value of the widget.

    Single-line Text Box, Digit, Switch, Multi-line Text Box, and Metrics

    Verification

    Mandatory

    Whether the widget content is mandatory. Error messages can be set.

    Single-line Text Box, Digit, Single-selection Drop-down List, Multi-selection Drop-down List, Option Button, and Multi-line Text Box

    RegEx Validation

    Verifies the widget content. You can set error messages.

    Single-line Text Box, Digit, Single-selection Drop-down List, Multi-selection Drop-down List, and Multi-line Text Box

    Word limit

    Max. widget characters.

    Multi-line Text Box

    Option

    Custom

    Options available for the widget. Click to add an option. Click to delete an option.

    • Option name: option displayed on the extension configuration page.
    • Value: value delivered when the extension is running.

    In addition to manual configuration, set options by:

    • APIs: Set options by configuring web APIs. Click on the right. On the displayed dialog box, you can configure parameters after enabling the function. For details, see Table 3.
    • Context: Configure data source to obtain the URL of the pipeline source or IDs of build jobs. Click next to Custom. The context dialog box is displayed. You can configure parameters after enabling the function.

    Single-selection Drop-down List, Multi-selection Drop-down List, and Option Button

    Advanced

    Display

    Whether the widget is visible. You can click on the right set display conditions.

    All

    Disable

    Whether the widget is disabled (not disabled by default). You can click on the right and configure the disable conditions.

    All
    Table 3 API parameters

    Parameter

    Description

    Enabled

    By enabling the function, you can set options by configuring APIs.

    Linked Attribute

    Associates the selected widgets with the API to transfer parameters. When a widget value is changed, the new value is used to call the API again.

    URL

    Only HTTPS protocol is supported.

    Returned Data Path

    The widget used must be list data. In the following response body example, the returned data path is result.parameters.

    {
    "result": {
        "total": 2,
        "parameters": [
            {
                "id": 3353753,
                "name": "parameters01"
            },
            {
                "id": 3353697,
                "name": "parameters02"
            }
        ]
    },
    "status": "success"
}

    Option Value

    Set this parameter to the value of the corresponding field in the returned data path. This parameter is delivered when the extension is running.

    Option Name

    Set this parameter to the value of the corresponding field in the returned data path. This parameter is displayed on the extension configuration page.

    Params

    Params parameters of the API request body.

    Header

    Header parameters of the API request body.

    Remote Search

    Enable this function to add a remote search field. For extension search, the entered value will be used as the value of the remote search field to call the API again.

    • Params parameter: The parameter type of the search field is the Params parameters of the API request body.
    • Body parameter: The parameter type of the search field is the Body parameters of the API request body.

  7. Click Next. On the displayed Orchestration page, you can add the ExecuteShellCommand extension.

    • ExecuteShellCommand: execute shell commands entered by users.

      Enter shell commands. Commands will be executed when a pipeline call the extension.

      The commands indicate the actual service logic implementation process of an extension. For more input and output configurations, see Customizing Shell Commands.

  8. Click Next. On the displayed page, click Add Configuration to configure output or metric information.

    • output: output data together with shell commands.
    • metric: output metric thresholds. The thresholds information can be referenced in an extension and finally applied to pipelines.

  9. After the configuration, click Release or Release Draft.

    • Draft release
      Click Release Draft to release a test version.
      • You can configure a draft extension in a pipeline for debugging. After debugging, the draft extension can be officially released, so that other members of the current tenant can use the extension.
      • All draft versions are marked with Draft.
      • Only one draft is allowed. If there is already a draft, no more versions can be created until you officially release or delete the draft.
    • Official release

      Click Release to release an official version. An official extension has a unique version number. All members of the current tenant can use this version in a pipeline.

Customizing Shell Commands

When registering an extension or creating an extension version, you can use shell commands to implement service logic. The commands usually involve interaction with all kinds of data during pipeline execution. This section describes how to implement extension logic through data input and output.

  • Data Input

    The obtained data consists of low-code GUI input, pipeline run parameters, and other information.

    • Low-code GUI input: Obtain the low-code user interface output by using environment variables, for example, echo ${Widget ID}.
    • Pipeline run parameters: Some pipeline run parameters will be delivered to environment variables as shown in the following table.
      Table 4 Pipeline environment variables

      Variable

      Description

      STEP_NAME

      Step name of the pipeline.

      STEP_ID

      Step ID of the pipeline.

      PLUGIN_VERSION

      Version of the extension.

      PIPELINE_ID

      Pipeline ID.

      PIPELINE_RUN_ID

      Pipeline execution ID.

      PLUGIN_NAME

      Extension name.

      PROJECT_ID

      Project ID.

      JOB_ID

      Job ID of the pipeline.
    • Other information: Obtain information by interacting with external data through Git, Wget, and Curl.
  • Data Output

    Once executed, the custom extension can read file information in a specified path and obtain the metric data output.

    1. On the configuration page, configure the thresholds output of the extension.
    2. During development, the ${STEP_ID}_result.json and ${STEP_ID}_metrics.json files are stored in a specified path so that metric values can be parsed.
      Table 5 Output files

      File

      Description

      ${RESULT_MSG_PATH}/${STEP_ID}_result.json

      The output is a text file in {"par1":123, "par2":456} format. After the pipeline is executed, the result will be displayed as the corresponding task result.

      NOTE:

      Only extensions of the check type can display the result.

      ${RESULT_MSG_PATH}/${STEP_ID}_metrics.json

      The output is a text file in {"par1":123, "par2":456} format. The Metrics widget should be configured. After the extension is executed, the threshold configured for the Metrics widget and the content of ${STEP_ID}_metrics.json are parsed for pipeline pass conditions. Notes:

      • During parsing, empty key values in the Metrics widget will be ignored.
      • If the key value configured for the Metrics widget cannot be found in the ${STEP_ID}_result.json file, the specified threshold value will be used.

      Example: par1 and par2 for pass conditions; par3 and par4 for task result display. The sample code is as follows:

      # Optionally, construct the extension output.
echo '{"par1":100,"par2":200}' > ${RESULT_MSG_PATH}/${STEP_ID}_result.json
echo '{"par3":300,"par4":400}' > ${RESULT_MSG_PATH}/${STEP_ID}_metrics.json
    3. After the extension run is complete, click the extension card to view the output.

      If policies are configured for the current extension and applied to the pipeline pass conditions, click the pass conditions to view the check status.