Introduction

To clearly distinguish where actions originate, Cloud Native Build differentiates 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.

An NPC is an automated role in Cloud Native Build, essentially a virtual intelligent assistant for handling automated tasks such as comment replies and code collaboration.

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 replies.

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 collaborate on code, 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.
• @ mentions inside the following formats will not trigger NPC events: blockquotes, code blocks, ordered lists, unordered lists, and tables.

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

NPC Event Execution

NPC event pipelines run in the repository where the current Issue or PR belongs (not the NPC's repository). The trigger is the current user.

• issue.comment@npc: Runs on the repository's default branch.
• pull_request.comment@npc: Runs on the PR's target branch. For cross-repo fork PRs, if triggered by the PR author, clones code from the source repository's source branch.

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

• CNB_TOKEN in NPC event pipelines is limited to the current repository. For pull_request.comment@npc events in cross-repo fork PRs, if triggered by the PR author, CNB_TOKEN is limited to public repositories only.
• The maximum role of CNB_TOKEN in NPC event pipelines is Developer. Even if the trigger user is a repository Master or Owner, the CNB_TOKEN in the NPC pipeline will not exceed Developer permissions.
• If an NPC pipeline references secret repository files via imports, settingsFrom, optionsFrom, or similar methods, the NPC will not be shareable (it will not appear in the NPC leaderboard).

Environment Variables

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

How to Define NPCs

Defining a custom NPC involves the following:

Step	File	Location	Description
1. Define role	.cnb/settings.yml	NPC's repository	Role name, avatar, prompt, etc.
2. Custom behavior (optional)	.cnb.yml	NPC's repository	Custom NPC event pipelines
3. Define runtime environment (optional)	Dockerfile	NPC's repository	Install NPC runtime tools

Quick Start

Only step 1 (defining the role) is required to use an NPC. Steps 2 and 3 are only needed when you want to customize behavior.

Define NPC Roles

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

Configuration example:

.cnb/settings.yml

npc:
  roles:
    - name: 猿芳
      slogan: 此事必有蹊跷！
      prompt: |
        你用"猿芳"自称，叫用户"大人"，
        你的口头禅是『此事必有蹊跷！』，
        结束对话前礼貌地回复一行："此事背后一定有一个天大的秘密。"
        无论是日常对话还是讲解知识，你都会保持以上风格

For detailed configuration, see UI Customization Configuration File.

Custom 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, configure NPC event pipelines in the NPC repository's .cnb.yml file under $ (or under the role name).

Minimal Example

Customize only the issue.comment@npc event pipeline:

NPC repository's .cnb.yml

$:
  issue.comment@npc:
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

Configuration Merging

When an NPC event is triggered, the system automatically merges two configurations via the include syntax:

1. System default NPC configuration (built-in fallback)
2. The NPC repository's .cnb.yml (if it exists)

The merge follows standard include semantics: event configurations defined in the NPC repository override the defaults, while undefined events retain the default behavior.

Using the minimal example above, the effective merged configuration is:

$:
  issue.comment@npc: # ← from NPC repository (overrides default)
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

  pull_request.comment@npc: # ← from system default (NPC repo didn't define this)
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go

Note

Merging is performed per event independently. If the NPC's repository only configures issue.comment@npc but not pull_request.comment@npc, Issue comments will run the custom pipeline while PR comments will still use the system default behavior.

To fully customize all NPC events, make sure to configure both issue.comment@npc and pull_request.comment@npc.

Full Example

Customize both events and build a runtime image:

NPC repository's .cnb.yml

.npc: &npc
  - docker:
      # Image containing CLI tools and Skills required by the NPC
      image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
    stages:
      - name: npc go
        type: npc:go

# NPC events can match event configurations under the role name
猿芳:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc

# If not defined under role name, falls back to $ configuration
$:
  issue.comment@npc: *npc
  pull_request.comment@npc: *npc

# Build and push Docker image
main:
  push:
    - services:
        - docker
      stages:
        - name: Docker build
          script: docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
        - name: Docker push
          script: docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest

Define Runtime Environment

Install the Skills and CLI tools required by the NPC in the Dockerfile. The following example installs cnb-skill and cnb-cli.

Dockerfile

FROM node:22-bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates git git-lfs curl jq ripgrep \
    && rm -rf /var/lib/apt/lists/* \
    && git lfs install \
    && npm install -g @cnbcool/cnb-cli skills \
    && npx skills add https://cnb.cool/cnb/skills/cnb-skill.git -g -y

Skills are automatically loaded from the following directories: ~/.agents/skills, ~/.codebuddy/skills and their project-level counterparts: .agents/skills, .codebuddy/skills.

Project-level Skills take priority over user-level Skills. A project-level Skill with the same name will override its user-level counterpart.

Sharing NPCs

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

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

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

More Use Cases

NPC's core capabilities (AI-driven automated tasks; can collaborate on code when granted write permissions) are not limited to NPC events triggered by @ mentions. You can use NPC capabilities in any event's pipeline via the npc:go built-in task, enabling broader automation coverage.

Example 1: NPC automatically reviews code and comments on pull_request events

.cnb.yml

$:
  pull_request:
    - docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            role: Code Reviewer
            systemPrompt: You are a professional code reviewer. Please review the code changes and suggest improvements.
            userPrompt: Review the code changes in this PR and suggest improvements

Example 2: Manually trigger NPC via a web_trigger button

.cnb.yml

$:
  web_trigger:
    - docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
          options:
            role: Assistant
            systemPrompt: You are an assistant responsible for executing user-specified tasks and returning results.
            userPrompt: $userPrompt

Code Write Permissions

In NPC events, code write permissions are granted by enabling Work Mode. In other events, whether the NPC can collaborate on code depends on the pipeline's CNB_TOKEN permissions.

When triggering web_trigger, you can enter the userPrompt environment variable on the page as the NPC task description.

NPC roles can be defined in the current repository's .cnb/settings.yml, see Define NPC Roles. For more npc:go parameters and usage, see Built-in Task npc:go.

External System Integration

External systems can trigger pipelines via API to use NPC capabilities, suitable for integrating CNB NPC into third-party platforms.

For details, see External System Integration with NPC.

Previous pageCustom Deployment Process

Next pageMigrating from GitHub Actions to CNB