Overview

Based on the Pipeline as Code philosophy, pipeline configuration files need to be written manually. When the configuration is complex, especially when using include to introduce templates, developers often face these questions: Is the syntax correct? Does the final pipeline content meet expectations? Will the pipeline be triggered as expected?

This article uses the code Push event as an example to help you achieve "what you see is what you get" for pipeline configuration through four steps: Write -> Preview -> Flow -> Event Tracking, ensuring efficient management and reliable operation of pipelines.

Writing

Before writing the pipeline configuration file, it is recommended to configure the syntax checking and auto-completion feature of your code editor to quickly discover syntax errors and provide code snippet suggestions.

Configuration Example

The following is an example of referencing a pipeline template file:

template.yml

main:
  push:
    - stages:
        - name: pipeline 1 stage 1
          script: echo "pipeline 1 stage 1"
        - name: pipeline 1 stage 2
          script: echo "pipeline 1 stage 2"

.cnb.yml

include:
  # This references a file in the current branch of the current repository, or you can reference files from other repositories
  - template.yml
main:
  push:
    - stages:
        - name: pipeline 2 stage 1
          script: echo "pipeline 2 stage 1"
        - name: pipeline 2 stage 2
          script: echo "pipeline 2 stage 2"

Usage Tips

• Use include to reuse pipeline templates, reduce duplicate configuration, and improve maintenance efficiency
• Supports referencing web addresses of template files from other repositories
• For detailed include syntax, please refer to include configuration

Preview

After writing, commit and push the configuration file to the remote repository, then view the .cnb.yml file on the repository homepage and switch to the Preview tab.

Preview Effect

You can see that the content of template.yml has been successfully merged into .cnb.yml:

preview

Features

• Configuration Validation: Confirm whether the final configuration meets expectations
• Merge Display: Show the merge result of templates introduced by include with the main configuration
• Troubleshooting: Avoid pipeline runtime failures caused by template reference errors or configuration conflicts
• Syntax Checking: Automatically detect syntax errors and discover issues before running

Flow

Click the Flow tab on the .cnb.yml file page to visually view the pipeline configurations triggered by the push event under the current branch.

Visual View

flow

View Description

The Flow view displays the pipeline structure in flowchart form, including:

• Branch Identification: Displays the target branch that triggered the pipeline
• Trigger Event: Displays the currently viewed event type (such as push)
• Pipeline Grouping: Each line under the event represents an independent pipeline
• Stage Display: Various stages within the pipeline are arranged in execution order

Functional Value

• Visual Display: Intuitively display pipeline structure and execution order
• Trigger Validation: Verify whether the pipeline is triggered as expected
• Configuration Check: Troubleshoot configuration issues, such as missing steps
• Dependency Relationship: Clearly display parallel or serial relationships between tasks

Event Tracking

After a Git event is triggered, view the pipeline trigger status through Events > History Events.

Event List

history-events

The list shows the two CI events triggered this time: push and commit.add.

CI Event Information Description:

• Event Type: Displays CI event types such as push, commit.add, pull_request, etc.
• Trigger Status: Triggered events are displayed as clickable
• Untriggered Description: Untriggered events cannot be clicked; hover to view the reason

push Event

Click the push event to jump to the build detail page to view the pipeline execution status and logs.

event-detail-push

Detail Page Features:

• Status Display: Real-time execution status of the pipeline, including success, failure, or in progress
• Log Viewing: View detailed log information to help locate issues or verify execution results
• Step Tracking: View the execution status and duration of each stage
• Environment Information: Display build environment, image, resource usage, etc.
• Retry Function: Support full or selective re-execution of pipelines and tasks

commit.add Event

Hover to view the reason why the event was not triggered.

event-detail-commit-add

Untriggered Reasons:

• No .cnb.yml under the branch, or .cnb.yml syntax error
• Event trigger conditions not met, such as event mismatch

Best Practices

To ensure efficient pipeline management, it is recommended to follow these best practices:

1. Modular Configuration

Abstract common pipeline steps into templates and reuse them through include to reduce duplicate configuration and improve maintainability.

2. Regular Checks

Use preview and Flow to verify correctness after modifying the configuration:

• Preview: Confirm include merge results
• Flow: Verify pipeline structure and task flow

3. Event Monitoring

Monitor pipeline triggering and execution through event tracking in real time:

• View History Events to confirm trigger status
• Hover over untriggered events to view reasons
• Track execution progress through the build detail page

4. Log Analysis

Analyze the cause based on logs when the build fails:

• View detailed logs of failed stages
• Check environment variables, dependencies, and script execution
• Adjust configuration and resubmit based on error information

5. Incremental Verification

Use incremental verification for complex configuration changes:

• Verify configuration in a test branch
• Use preview and Flow to confirm expected effects
• Merge to the main branch after testing passes

Notes

• Permission Check: The preview function only checks the access permissions of include files and does not verify allow_* attributes. After the event is triggered, the system will check allow_* attributes to confirm access permissions.
• Event Scope: History Events only displays code-related repository events such as push, tag_push, pull_request, etc., and does not display non-code related events such as tag_deploy, web_deploy, API Events, Scheduled Tasks, etc.
• Rebuild: Pipelines triggered by rebuild will not be displayed in History Events.

---

Through the above steps and best practices, you can easily achieve pipeline configuration writing, preview, flow viewing, and event tracking, ensuring that the pipeline runs as expected and improving development efficiency and system reliability.

For more details on pipeline configuration syntax, please refer to Grammar Manual and Configuration File.