CNB Docs

English

简体中文

English

简体中文
简体中文

Appearance

NPC Events

Copy page

About 2246 wordsAbout 7 min

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

In addition, when triggering an api_trigger build via OpenAPI, you can pass npc.name=CodeBuddy so that the build follows NPC semantics for identity display, title, billing category, and token resource scoping. This is not a comment-triggered event; systemPrompt / userPrompt for npc:go still come from the pipeline options.

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.
  • When the comment count of an Issue or PR exceeds 100, the corresponding issue.comment / pull_request.comment and @npc events will no longer trigger any pipeline.
  • @ mentions inside the following formats will not trigger NPC events: blockquotes, code blocks, details blocks, ordered lists, unordered lists, tables, and some HTML tags.

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 help me answer this issue.

Custom NPCs

Users can define NPC roles in a repository.

Usage:

@cnb/feedback(Expert) help me answer this 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 Expert

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
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
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 depends on the trigger's role in the repository:
    • Developer / Master / Owner → maximum role Developer
    • Reporter / Guest → maximum role Reporter, and work mode is disabled (forced to false)
  • 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:

  1. Define role: In the NPC repository's .cnb/settings.yml file, configure the role name, avatar, prompt, etc.
  2. Custom behavior (optional): In the NPC repository's .cnb.yml, customize NPC event pipelines.
  3. Custom runtime environment (optional): Through the NPC repository's .cnb.yml and Dockerfile, 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: Expert
      slogan: Professional answers, efficient assistance
      prompt: |
        You refer to yourself as "Expert" and are committed to providing professional, accurate technical answers.
        Keep your responses concise and professional, citing reliable sources.
        Whether in casual conversation or explaining concepts, you maintain the above style.

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: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go

Image Note

The minimal example uses cnbcool/default-npc:latest as the runtime environment. If you have built and pushed a custom NPC image, you can reference it using:

image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest

Configuration Merging

When an NPC event is triggered, the system automatically merges the system default config and the NPC repository's .cnb.yml via include.

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: cnbcool/default-npc: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

NPC event pipeline config (defines what happens when the NPC is @-mentioned):

NPC repository's .cnb.yml (NPC events)
$:
  issue.comment@npc:
    - docker:
        image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
      stages:
        - name: npc go
          type: npc:go

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

Docker image build pipeline (builds and pushes the custom NPC image to the artifact registry):

NPC repository's .cnb.yml (image build)
main:
  push:
    - services:
        - docker
      stages:
        - name: build
          script: docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
        - name: push
          script: docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest

You can combine both sections in the same .cnb.yml file.

Configure by Role Name

If the NPC's repository defines multiple roles and you want to configure distinct NPC event pipelines for each, you can place events under the role name as a top-level key (at the same level as $). The event pipeline is only loaded when the @-mentioned role name matches a top-level key.

If no NPC event pipeline is explicitly configured in .cnb.yml, the system uses the built-in default configuration. In the example below, the Expert role runs the custom pipeline under Expert: when @-mentioned; other roles (without any matching top-level key) fall back to the system default behavior.

NPC repository's .cnb.yml
# Override event pipelines only for the Expert role
Expert:
  issue.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go
  pull_request.comment@npc:
    default:
      docker:
        image: cnbcool/default-npc:latest
      stages:
        - name: npc go
          type: npc:go

Merge relationship with $ configurations:

If the repository also contains a $ top-level key (i.e., a default configuration shared by all roles), the role name key is merged with the default configuration (system default + $ configurations) using the include semantics. Events under the role name override the same-named events under $; events not defined under that key still fall back to the system default behavior.

Naming Requirements

  • The top-level key must exactly match npc.roles[].name in .cnb/settings.yml (case-sensitive, character-exact match).
  • The top-level key must not include the @ prefix or the role name in parentheses; for example, do not use @cnb/feedback(Expert).
  • Different roles in the same repository can each have their own independent top-level key without interfering with each other.

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: web_trigger button to manually trigger NPC (enter $userPrompt on page)

.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. For how to configure manual trigger buttons, see Manual Pipeline Trigger.

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.

© 2026 cnb.cool