# CNB Docs

Cloud Native Build Docs

## Table of Contents

### Guide

- [Create Your First Repository](/en/guide/first-repo.md): A step-by-step guide to getting started on CNB by creating an organization and your first code repository to host enterprise assets and pipeline configurations.
- [Git Address and Authentication Instructions](/en/guide/git-access.md): Explains the Git repository address format on CNB, authentication methods (HTTPS and SSH), and how to configure credentials for cloning and pushing code.
- [Migration Tools](/en/guide/migration-tools.md): Introduces tools for migrating code repositories to CNB, including the CNB Code Import batch migration tool supporting GitHub, GitLab, Gitee, and other platforms, as well as Git Sync for repository synchronization.
- [Role Permissions](/en/guide/role-permissions.md): Documents the five member roles on CNB (Guest, Assistant, Developer, Administrator, Owner) and a detailed permission matrix showing what actions each role can perform on repositories and resources.
- [Access Token](/en/guide/access-token.md): Explains how to create and manage access tokens on the CNB platform for authenticating access to code repositories, artifact repositories, and the OpenAPI.
- [Deploy Key](/en/guide/deploy-key.md): Describes CNB deploy keys, which are read-only credentials for securely accessing repositories in CI/CD pipelines and scripts without exposing primary account credentials.

### Repositories

- [Product Introduction](/en/repo/intro.md): Overview of CNB Repositories, covering core features such as code management, branch protection, code review (Pull Requests), issue tracking, and version management for cloud-based collaborative development.
- [KeyStore](/en/repo/secret.md): Describes CNB's KeyStore repository type, a high-security storage solution for sensitive data (passwords, API keys, tokens) with strict access controls, audit logs, and watermarks; covers creation steps and core security features.
- [Metadata](/en/repo/annotations.md): Explains the repository metadata feature for storing key-value annotations on Tags and Commits, including how to view metadata via the web interface and manage it through the API.
- [ISSUE Template](/en/repo/issue-template.md): Describes how to configure Issue templates in CNB repositories using YAML or Markdown format, compatible with GitHub's issue form syntax, placed in the .cnb/ISSUE_TEMPLATE directory.
- [Labels](/en/repo/label.md): Explains how to import labels from a CNB public repository into your own repository as an incremental import, without overwriting existing labels.
- [UI Customization](/en/repo/settings.md): Overview of repository UI customization via the .cnb/settings.yml configuration file, covering workspace launch buttons, issue buttons, fork buttons, reaction images, tags, NPC AI roles, and copy-repo button settings.
- [Cloud-Native Development Button Customization](/en/repo/settings-workspace.md): Explains how to customize the cloud-native development launch button via .cnb/settings.yml, including name, description, hover image, CPU resource configuration, and enabling or disabling the button.
- [Issue Button Customization](/en/repo/settings-issue.md): Explains how to customize the Create Issue button appearance via .cnb/settings.yml, including adding a description and hover image to give the repository more personality.
- [Fork Button Customization](/en/repo/settings-fork.md): Explains how to customize the Fork button appearance via .cnb/settings.yml, including adding a description and hover image to attract contributors to fork open-source projects.
- [Copy Repo Button Customization](/en/repo/settings-copy-repo.md): Explains how to customize the appearance of the Copy Repo button via .cnb/settings.yml, including button descriptions and hover images, to make template repositories more appealing.
- [Reaction Custom Image](/en/repo/settings-reaction.md): Explains how to replace default reaction icons with custom images (such as a project mascot) via .cnb/settings.yml to match the repository's visual style.
- [Tag Auto-Generation Configuration](/en/repo/settings-tag.md): Explains how to configure automatic tag creation via .cnb/settings.yml, specifying which branch triggers tag auto-generation to standardize version tagging workflows.
- [NPC Configuration](/en/repo/settings-npc.md): Explains how to configure AI assistant (NPC) roles, knowledge bases, and interaction buttons for a repository via .cnb/settings.yml, enabling intelligent code review and Q&A collaboration.

### Artifact

- [Introduction to Artifact Registry](/en/artifact/intro.md): Overview of the CNB Artifact Registry covering supported artifact types (Docker, Helm, Maven, npm, PyPI, etc.), how to manage registries, permission control, storage billing, and artifact migration.
- [Docker Artifact Registry](/en/artifact/docker.md): Guide for logging in, pushing, and pulling Docker container images from the CNB Docker Artifact Registry, including artifact path naming rules and CI pipeline usage.
- [Helm Artifact Registry](/en/artifact/helm.md): Guide for logging in, pushing, and pulling OCI-format Helm charts from the CNB Helm Artifact Registry, including artifact path naming rules and CI pipeline usage.
- [Docker Model Registry](/en/artifact/docker-model.md): Guide for logging in, pushing, and pulling AI model artifacts from the CNB Docker Model Registry, including artifact path naming rules and CI pipeline usage.
- [Maven Artifact Registry](/en/artifact/maven.md): Guide for configuring credentials and using the CNB Maven artifact registry to push and pull Java/JVM packages with Maven or Gradle, covering local development and CI pipeline workflows.
- [npm Artifact Registry](/en/artifact/npm.md): Guide for configuring credentials and using the CNB npm artifact registry to publish and install Node.js packages, covering local development and CI pipeline workflows.
- [ohpm Artifact Registry](/en/artifact/ohpm.md): Guide for configuring credentials and using the CNB ohpm artifact registry to push and pull HarmonyOS packages, covering local development and CI pipeline workflows.
- [Nuget Artifact Registry](/en/artifact/nuget.md): Guide for configuring credentials and using the CNB NuGet artifact registry to push and pull .NET packages, covering local development with dotnet CLI or nuget.exe and CI pipeline workflows.
- [Composer Artifact Registry](/en/artifact/composer.md): Guide for configuring push and pull credentials and using the CNB Composer artifact registry to manage PHP packages, covering local development and CI pipeline scenarios.
- [PyPI Artifact Registry](/en/artifact/pypi.md): Guide for configuring credentials and using the CNB PyPI artifact registry to upload and install Python packages, covering local development and CI pipeline workflows.
- [Cargo Artifact Registry](/en/artifact/cargo.md): Guide for configuring credentials and using the CNB Cargo artifact registry to push and pull Rust packages, covering both local CLI and CI pipeline workflows.
- [Conan Artifact Repository](/en/artifact/conan.md): Guide for using the CNB Conan artifact repository to store and distribute C/C++ packages, covering remote configuration, authentication, and pushing/pulling packages via local CLI and CI pipelines.

### AI Assistant

- [AI Assistant Introduction](/en/ai/intro.md): Introduces the AI features available on the CNB platform, including TencentCloud CodeBuddy integration, Chat assistant, RAG Knowledge Base, Issue Analysis, and Change Analysis.
- [Knowledge Base](/en/ai/knowledge-base.md): Explains how to build an enterprise or personal RAG (Retrieval-Augmented Generation) knowledge base using a code repository, by uploading documents and configuring a pipeline to automatically process and index content for Q&A and Open API scenarios.
- [MCP Server](/en/ai/mcp-server.md): Describes how to connect to the CNB MCP Server using the MCP protocol, covering both Streamable (recommended) and SSE connection methods with authentication token configuration.
- [Code Wiki](/en/ai/codewiki.md): Explains how to configure the CodeWiki pipeline plugin to automatically generate a wiki from a code repository's content, creating a documentation center portal on the repository homepage.

### Workspaces

- [Introduction to Workspaces](/en/workspaces/intro.md): Introduces CNB Workspaces, a cloud-native remote development solution supporting WebIDE, VSCode, and Cursor clients, featuring declarative environment configuration, quick startup, and on-demand resource allocation.
- [Default Development Environment](/en/workspaces/default-dev-env.md): Introduces the default cloud-native development environment image (`cnbcool/default-dev-env`) and explains how to configure automatic command execution on environment startup using the `CNB_WELCOME_CMD` environment variable.
- [Custom Development Environment](/en/workspaces/custom-dev-env.md): Describes how to customize the Workspaces development environment by specifying a Docker image in `.cnb.yml` or by writing a custom `.ide/Dockerfile` to define the environment from scratch.
- [Business Port Preview](/en/workspaces/business-preview.md): Explains how to preview services running in the Workspaces environment by accessing business ports through WebIDE or VSCode/Cursor client, including port mapping and port forwarding methods.
- [Workspaces Recycling Mechanism](/en/workspaces/workspace-recycling.md): Explains the automatic recycling mechanism for Workspaces development environments, including inactivity-based recycling after 10 minutes, maximum 18-hour active duration, and forced overnight recycling between 4-6 AM.
- [Code Backup and File Roaming](/en/workspaces/file-keeper.md): Describes the code backup and file roaming strategies used by Workspaces to prevent loss of uncommitted code and configuration files when development environments are automatically destroyed, including backup-on-destruction and restore-on-rebuild mechanisms.
- [Recommended Workspaces Usage](/en/workspaces/working-principle.md): Describes the recommended workflow for using Workspaces, including creating development branches, writing code, submitting merge requests, handling code reviews, and managing multiple features in parallel.
- [Differences from Cloud Native Build](/en/workspaces/workspace-vs-build.md): Clarifies the relationship and differences between Workspaces and Cloud Native Build pipelines, explaining that Workspaces is essentially a Cloud Native Build pipeline with `service.vscode` declared, and highlighting key differences in purpose, default image, node assignment, and billing.
- [Frequently Asked Questions](/en/workspaces/question.md): Answers common questions about Workspaces, including how to install a specific version of code-server and troubleshoot WebIDE issues caused by code-server version bugs.
- [Customize Environment Creation Pipeline](/en/workspaces/custom-dev-pipeline.md): Explains how to write a custom `.cnb.yml` pipeline for Workspaces environment creation, including setting a custom Docker image, configuring resource specifications (CPU/memory), and other pipeline options.
- [Customize Workspaces Launch Button](/en/workspaces/custom-dev-button.md): Explains how to customize the Workspaces launch button by adding a `.cnb/settings.yml` configuration file to the repository.
- [Single/Double Container Mode​](/en/workspaces/double-container.md): Explains the difference between single-container mode (development environment and code-server in one container) and double-container mode (in separate containers) for Workspaces, and describes when each mode is used.
- [Usage Tips](/en/workspaces/usage-tips.md): Provides practical tips for using Workspaces, including how to avoid clipboard and font permission pop-ups in WebIDE, resolve shortcut conflicts, and configure browser settings for a smoother development experience.
- [Preview Mode Only](/en/workspaces/only-preview.md): Describes the Cloud Development Preview Mode, a derivative of Workspaces that skips WebIDE and directly opens a preview page for faster previewing, including configuration via `.cnb.yml` and its limitations.
- [VSCode/Cursor Client](/en/workspaces/vscode-likes.md): Explains how to configure Workspaces development environments to support remote connection via VSCode, Cursor, and CodeBuddy clients, including installing openssh-server in the Dockerfile and resolving window overlap issues.
- [JetBrains Client](/en/workspaces/jetbrains.md): Explains how to connect to CNB Workspaces development environments using JetBrains Gateway, including prerequisites, supported IDEs (IntelliJ IDEA, GoLand, PyCharm, etc.), and environment image requirements.
- [Workspaces SSH Key Fingerprint Verification](/en/workspaces/fingerprint.md): Explains how to verify the SSH key fingerprint for CNB Workspaces remote connections, including how to check and update the `.ssh/known_hosts` file to ensure connection security.

### Cloud Native Build

- [Introduction to Cloud Native Build](/en/build/intro.md): Overview of Cloud Native Build, a Docker-based CI/CD system with declarative syntax for defining build environments, caches, and plugins alongside source code.
- [Quick Start](/en/build/quick-start.md): Step-by-step tutorial to create and run your first Cloud Native Build pipeline, including creating a repository, writing a .cnb.yml configuration file, and setting up a practical PR quality-gate pipeline.
- [Trigger Rules](/en/build/trigger-rule.md): Explains how Cloud Native Build determines which pipelines to run in response to events, covering all supported trigger types (git operations, manual, API, scheduled, issue, NPC events) and branch/event matching rules.
- [Configuration File](/en/build/configuration.md): Introduces the .cnb.yml configuration file used by Cloud Native Build, explaining its role, format requirements, and providing a basic example for defining build pipelines triggered by repository events.
- [Grammar Manual](/en/build/grammar.md): Comprehensive reference for the .cnb.yml pipeline syntax, covering the hierarchical Pipeline/Stage/Job structure and all configuration options including triggers, environment, caching, plugins, and advanced features.
- [Build Environment](/en/build/build-env.md): Explains how to configure the Docker-based build environment for Cloud Native Build pipelines, covering how to use existing images or build images dynamically from a Dockerfile.
- [Building Nodes](/en/build/build-node.md): Lists available build node clusters for Cloud Native Build pipelines in the SAAS distribution, including amd64, arm64/v8, and GPU (amd64:gpu, L40) architectures with configurable CPU ranges, maximum task durations, and example pipeline configuration.
- [Environment Variables](/en/build/env.md): Covers how to declare, import, export, and use environment variables in Cloud Native Build pipelines, including pipeline-level and job-level variable scoping.
- [Built-in Environment Variables](/en/build/build-in-env.md): Reference for all built-in read-only environment variables automatically injected by Cloud Native Build into pipeline jobs, including CI metadata, branch, commit, and PR-related variables.
- [Timeout Strategy](/en/build/timeout.md): Describes the timeout limits for Cloud Native Build pipelines and jobs, including default no-output timeout, maximum execution durations, and how to configure custom timeout values.
- [Permission Description](/en/build/permission.md): Describes the role-based permission requirements for triggering and viewing Cloud Native Build pipelines, including rules for public and private repositories.
- [Built-in Plugin](/en/build/internal-steps.md): Reference for all built-in plugins provided by Cloud Native Build, including docker cache, pipeline control (apply/trigger/await), git automation (reviewer/auto-merge/release), testing coverage reporting, and artifact management.
- [Plugins Market](/en/plugins.md): Browsable marketplace for discovering and using CNB pipeline plugins.
- [Plugin Development](/en/build/create-plugin.md): Step-by-step guide for developing a Cloud Native Build plugin as a Docker image, covering parameter design, input handling, image building, and publishing to the plugin registry.
- [Contribute Plugins](/en/build/contribute-plugin.md): Explains how to contribute a general-purpose plugin to the CNB Plugin Market for sharing with the community.
- [Simplifying Configuration Files](/en/build/simplify-configuration.md): Explains how to use advanced YAML features (anchors, aliases, merge operators) and CNB's include/imports directives to reduce duplication and simplify complex .cnb.yml pipeline configuration files.
- [File References](/en/build/file-reference.md): Explains the four types of file references supported in CNB pipeline configurations (pipeline templates, environment variable imports, built-in task parameters, plugin task parameters), including permission controls to prevent information leakage.
- [Pipeline Visualization](/en/build/pipeline-visualization.md): Guides developers through writing, previewing, and visually verifying pipeline configurations using the write-preview-flow-event-tracking workflow to achieve "what you see is what you get" for CI/CD pipelines.
- [Pipeline Caching](/en/build/pipeline-cache.md): Explains how Cloud Native Build caches dependencies and build artifacts on runner nodes to reduce build time, covering runner node caching, file caching, and cross-node caching strategies.
- [Scheduled Tasks](/en/build/crontab.md): Explains how to configure cron-based scheduled tasks in Cloud Native Build pipelines, allowing pipelines to run automatically at specified times for scenarios like nightly builds and periodic testing.
- [Skip Pipeline Execution](/en/build/skip-pipeline.md): Describes methods to prevent pipeline execution, including using commit message keywords ([ci skip], [skip ci]), git push options, and event-level ignore configurations in .cnb.yml.
- [Login Debugging](/en/build/login-debug.md): Explains how to use the Login Debugging feature to SSH into a pipeline's Docker container for troubleshooting CI build failures that don't reproduce locally.
- [Manually Trigger Pipeline](/en/build/web-trigger.md): Explains how to configure custom buttons in CNB to manually trigger pipelines from the web UI, including the .cnb/web_trigger.yml configuration format and support for passing environment variables via the interface.
- [Custom Deployment Process](/en/build/deploy.md): Describes how to configure custom deployment environments, approval workflows, and deployment pipelines in Cloud Native Build to achieve automated deployment with role-based permissions.
- [NPC Events](/en/build/npc.md): Explains NPC (Non-Player Character) automated roles in Cloud Native Build, including how mentioning an NPC in issues or PR comments triggers automated pipelines for tasks like auto-reply, code writing, and PR management.
- [Migrating from GitHub Actions to CNB](/en/build/migrate-to-cnb/migrate-from-github-actions.md): A migration guide highlighting the syntax and conceptual differences between GitHub Actions and CNB pipelines, helping users transition their workflows to the CNB platform.
- [Build and Push Docker Image to Artifact](/en/build/showcache/docker-build-and-push-to-cnb-artifact.md): Demonstrates how to build a Docker image within a CNB pipeline and push it to CNB Docker Artifact Registry using built-in pipeline credentials.
- [AI Review](/en/build/showcase/ai-review.md): Explains two methods for automatically performing AI code reviews on Pull Requests in CNB pipelines—using the AI Review plugin for automatic triggering or NPC events for on-demand reviews.
- [Issue Notification to Enterprise WeChat Group](/en/build/showcase/issue-notice-group.md): Provides pipeline configuration examples for sending automated Enterprise WeChat group notifications when Issue events (create, reopen, close, comment) occur in a CNB repository.
- [On-Demand Build for Monorepo](/en/build/showcase/monorepo.md): Shows how to configure CNB pipelines to trigger builds only for modified directories in a Monorepo, using the ifModify field and CNB_PIPELINE_KEY environment variable to avoid unnecessary full builds.
- [Pull Request Notification to Enterprise WeChat Group](/en/build/showcase/pr-notice-group.md): Provides a pipeline configuration example for sending automated Enterprise WeChat group notifications when Pull Request events (open, review, merge) occur in a CNB repository.

### Developers

- [Badges](/en/develops/badge.md): Explains how to use CNB badges to display build metrics with color-coded status indicators, including badge access paths, types, and embedding them in README files.
- [OpenAPI](/en/develops/openapi.md): Describes how to access and call the CNB OpenAPI, including the API service address, authentication via access tokens, and example requests.
- [SKILLS](/en/develops/skills.md): Introduces CNB Skills, an OpenAPI-based toolkit that enables full AI interaction capabilities with the Cloud Native Build platform.

### oauth 授权

- [How to Use OAuth Authorization](/en/oauth/user.md): Explains how end users can authorize third-party tools to access their CNB account via OAuth, including the authorization steps, benefits of OAuth, and how to manage or revoke authorizations.
- [Create OAuth Application](/en/oauth/developer.md): Guides third-party developers through the CNB OAuth 2.0 integration process, covering application registration, user authorization flows, temporary ticket issuance, and API access control.

### Others

- [Script Jobs vs Plugin Jobs](/en/build/script-vs-plugin.md): Compares the two main CNB pipeline job types—Script Jobs and Plugin Jobs—covering their differences in execution method, parameter passing, flexibility, and reusability to help you choose the right approach.
- [CNB Events](/en/develops/openapi-event.md): Documents the CNB repository event types and their payloads, including CreateEvent, ForkEvent, PullRequestEvent, and other events recorded in hourly shards.
- [Cloud Native Build Enterprise Edition](/en/enterprise.md): Describes the CNB Enterprise Edition for deployment in Tencent Cloud VPCs, featuring intranet access, compliance support, and private infrastructure architecture.
- [FAQ](/en/faq.md): Answers frequently asked questions about CNB pipelines, build environments, artifact repositories, and common troubleshooting scenarios.
- [Logo](/en/logo.md): Provides downloadable CNB brand logo assets in multiple formats (PNG, SVG) and sizes for use in projects and publications.
- [Mission  Introduction](/en/missions/intro.md): Introduces CNB Missions, a collaborative task management tool that provides visual Kanban boards for centrally managing Issues and PRs across multiple organizations and repositories.
- [Pricing](/en/pricing.md): Describes the pay-as-you-go billing model for Cloud Native Build Community Edition (SAAS), covering free quotas and overage rates for repository storage, object storage, Events-CPU/GPU, Workspaces-CPU/GPU, and AI Credits, plus special privileges for non-profit organizations.
- [About Us](/en/saas/about.md): Contact information and version details for the Cloud Native Build SAAS distribution, including support email, phone, address, and WeChat official account.
- [云原生构建隐私保护声明](/en/saas/privacy.md): The privacy protection policy for Cloud Native Build (SAAS distribution), detailing how personal information is collected, used, stored, and protected by Tencent Cloud, and explaining user rights over their data.
- [Cloud Native Build Service Level Agreement](/en/saas/sla.md): The Service Level Agreement for Cloud Native Build (SAAS distribution), defining 99.8% service availability standards, compensation procedures for downtime, and exempt conditions.
- [TAPD](/en/saas/tapd.md): Guide for configuring CNB and TAPD integration in the SAAS distribution, including setup steps for administrators and a user guide for associating code commits, branches, and merge requests with TAPD work items.
- [Cloud Native Build Service Agreement](/en/saas/terms.md): The Cloud Native Build Service Agreement for the SAAS distribution, covering account management, service terms, billing, user obligations, data handling, intellectual property, and dispute resolution.
- [Platform Sponsorship](/en/sponsor.md): Explains how to use the CNB sponsorship feature to financially support projects or users, including how to upload a WeChat sponsorship QR code and how sponsorship funds are transferred.