---
url: /en/build/pipeline-visualization.md
---
## 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](./grammar.md#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](./configuration.md#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:

```yaml title="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"
```

```yaml title=".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](./grammar.md#include)

## 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](/images/build/pipeline-visualization/preview.en.png)

### 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](/images/build/pipeline-visualization/flow.en.png)

### 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](/images/build/pipeline-visualization/history-events-entry.en.png)

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](/images/build/pipeline-visualization/event-detail-push.en.png)

**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](/images/build/pipeline-visualization/event-detail-commit-add.en.png)

**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](./grammar.md) and [Configuration File](./configuration.md).