Introduction

Cloud Native Build differentiates between UI interactions and automated interactions.

Automated interactions are collectively referred to as NPC (Non-Player Character) behaviors, with the actor displayed as NPC.

An NPC is an automated role in Cloud Native Build, essentially a virtual intelligent assistant, capable of executing comment replies, code collaboration, and other automated tasks.

Mentioning an NPC in an Issue or PR comment triggers the corresponding automated pipeline.

NPC Capabilities:

• Auto reply: Automatically reply to Issue or PR comments, e.g., answering questions or generating code review suggestions
• Work Mode: When enabled, NPCs can write code, push code, create branches, submit PRs, and help resolve Issues
• Custom behaviors: Support custom NPC roles and behaviors

NPC Events

The following NPC events are currently supported:

• issue.comment@npc: Triggered when mentioning an NPC in an Issue description or comment
• pull_request.comment@npc: Triggered when mentioning an NPC in a PR description, review, review comment, or comment

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 two types of NPCs:

• System NPCs: Built-in, currently including CodeBuddy
• Custom NPCs: Defined by users in their repositories

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

Typing @ in the editor opens the NPC selector, showing default NPCs, the current user's custom NPCs, and NPCs from followed repositories.

Work Mode

Check "Work for me" in the comment area to enable Work Mode (repository developer permission or above required).

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

For detailed permission information, 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 uses CNB_TOKEN to reply to comments, the comment author is displayed as the NPC role name.

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

1. The mentioned NPC role name and pipeline execution status are displayed below the current comment.
2. If the NPC replies, 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 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 is a Master or Owner.
• 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. Custom runtime environment (optional)	.cnb.yml + Dockerfile	NPC's repository	Build and specify the Docker image used to run the NPC

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. If no custom NPC event pipeline is configured, the system uses cnbcool/default-npc:latest as the NPC runtime environment by default.

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 can be used immediately after being defined.

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 specify a custom 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

Custom Runtime Environment

npc:go runs in the Docker container of the NPC event pipeline. You can customize the runtime environment in the following ways:

• Specify an existing image directly: specify the image in docker.image in .cnb.yml.
• Build a custom image from a Dockerfile: the Dockerfile is not read or run directly by NPC. It is only used to build an image. After building and pushing the image, reference it in docker.image in .cnb.yml.
• Default behavior when unspecified: the system uses cnbcool/default-npc:latest.

The full flow is: write a Dockerfile → build and push the image in a pipeline → reference the image via docker.image in .cnb.yml.

Dockerfile Example for a Custom Image

When building a custom image from a Dockerfile, install the Skills and CLI tools required by the NPC. 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, they can mention the NPC by entering the full NPC path after @. For the format, see 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.

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