Introduction

To clearly trace where actions come from, Cloud Native Build strictly distinguishes between UI interactions and automated interactions.

In Cloud Native Build, these automated interactions are collectively referred to as NPC (Non-Player Character) behaviors, and the actor identity is displayed uniformly as NPC.

What is an NPC: An NPC is an automated role identity in Cloud Native Build. You can think of it as a virtual intelligent assistant used to handle automated tasks such as comment replies and code collaboration.

What is an NPC event: Mentioning an NPC role in a specific scenario triggers the corresponding automated pipeline. For example, when you @ mention an NPC in an Issue or PR comment, the NPC automatically runs the preset task and provides a reply.

What NPCs can do:

• Auto reply: NPCs can automatically reply to Issue or PR comments, for example by answering questions or generating code review suggestions
• Work Mode: After Work Mode is enabled, NPCs can write code autonomously, push code, create branches, submit PRs, and help resolve Issues
• Custom behaviors: Users can define custom NPC roles and behaviors to support personalized automation scenarios

NPC Events

The following NPC events are currently supported:

• issue.comment@npc
• pull_request.comment@npc

Mentioning an NPC role in the following scenarios triggers the issue.comment@npc event:

• The description entered when creating an Issue
• Issue comments

Mentioning an NPC role in the following scenarios triggers the pull_request.comment@npc event:

• The description entered when creating a PR
• PR reviews
• PR comments
• PR review comments

Important

• Reopening a PR or Issue, or editing a description or comment, does not trigger the NPC event again.
• At most 10 NPC events can be triggered at one time.

NPC Types

Cloud Native Build provides the following two types of NPCs:

• System NPCs
• Custom NPCs

System NPCs

Cloud Native Build provides the following system NPC:

• CodeBuddy

Usage:

@CodeBuddy 帮我回答下这个 issue。

Custom NPCs

Users can define NPC roles in a repository.

Usage:

@cnb/feedback(猿芳) 帮我回答下这个 issue。

Where:

• The part after @ is the repository path where the NPC belongs, for example cnb/feedback
• The content inside the parentheses is the role name, for example 猿芳

NPC Selector

When mentioning a custom NPC in the editor, you need to enter the full repository path and role name. To make selection easier, typing @ opens the NPC selector.

The selector shows default NPCs, NPCs defined by the user, and NPCs defined in other followed repositories, so you can choose one directly.

Work Mode

You can enable Work Mode by checking 替我上班 in the comment area (repository developer permission or above is required).

In Work Mode, NPCs have elevated permissions. They can write code autonomously, push code, create branches, create merge requests, and help resolve Issues.

For detailed permission information in Work Mode, see CNB_TOKEN.

Illustration of selecting an NPC role and enabling Work Mode in the Markdown editor

How to Define NPCs

Define NPC Roles

You can define NPC roles in the repository's .cnb/settings.yml file.

Configuration example:

.cnb/settings.yml

npc:
  roles:
    - name: 猿芳
      prompt: |
        你用"猿芳"自称，叫用户"大人"，
        你的口头禅是『此事必有蹊跷！』，
        结束对话前礼貌地回复一行："此事背后一定有一个天大的秘密。"
        在最后一行你会输出一张表情包，
        无论是日常对话还是讲解知识，你都会保持以上风格，
        使用中文的『～』代替所有英文的『~』，
        用卑微的语气回答接下来的问题

For detailed configuration, see UI Customization Configuration File.

Define NPC Behaviors

When an NPC is mentioned, Cloud Native Build already provides default behavior, so the NPC role can be used immediately after it is defined.

If you want to customize NPC behaviors, you can configure NPC event pipelines in the .cnb.yml file on the default branch (such as main) of the repository where the NPC belongs.

Example of custom NPC pipeline configuration:

.cnb.yml

.npc: &npc
  - services:
      - docker
    stages:
      - name: run with npc
        image: cnbcool/default-npc-agent:latest

# NPC 事件可以匹配角色名下的事件配置
猿芳:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc

# 若未在角色名下定义 NPC 事件，则取 $ 下对应 NPC 事件配置
$:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc

Configuring SKILL

The default NPC behavior automatically loads SKILL.md and skills/SKILL.md from the repository where the NPC belongs.

Sharing NPCs

After defining a useful NPC, how can you make it available to others?

If the repository that owns the NPC is public, or the other user has code read access to that repository, they can directly mention the NPC in the editor by entering the full NPC path after @. For the format, see the usage example in Custom NPCs above.

When other users follow the repository that owns your NPC, the NPC you defined will also appear in the selector that opens after they type @. For details, see NPC Selector above.

NPC Event Execution

NPC event pipelines run on the default branch of the repository where the current Issue or PR belongs, rather than the repository where the NPC belongs. The trigger is the current operator.

When a custom NPC pipeline uses CNB_TOKEN to reply to comments on an Issue or PR, the comment author is displayed as the corresponding NPC role name.

Using commenting on an Issue as an example, after an NPC event is triggered:

1. The mentioned NPC role name and the pipeline execution status are displayed below the current comment.
2. If the NPC replies to the comment, the reply author is displayed as the NPC role name.

Result display after an NPC event is triggered

NPC events are treated as development scenarios, and therefore consume Workspaces usage.

Security Restrictions

For NPC events triggered in non-cross-repo PR scenarios, TOKEN-type environment variables in the pipeline can access only the current repository.

Environment Variables

When an NPC event pipeline runs, additional NPC-related environment variables are injected. For details, see Environment Variables.

Previous pageCustom Deployment Process

Next pageMigrating from GitHub Actions to CNB