CNB 文档

简体中文

English

简体中文

English

外观

从 GitHub Actions 迁移到 CNB

复制页面

2192 字约 7 分钟

简介

GitHub Actions 和 CNB 都支持通过 YAML 配置文件定义自动化的构建、测试、发布和 部署工作流，两者有一些相似之处：

  • 工作流配置文件以 YAML 编写并存储在代码仓库中 （CNB 中工作流称为流水线 Pipeline）
  • 工作流包含一项或多项任务（CNB 中任务对应阶段 Stage）
  • 任务包含一个或多个步骤或单个命令 （CNB 中步骤对应任务 Job，每个任务可执行一系列命令或插件）

本指南将重点说明两者差异，以便您将 GitHub Actions 迁移到 CNB。

工作流配置

  • GitHub Actions：每个工作流配置为单独的 YAML 文件，存放在 .github/workflows 目录
  • CNB：所有工作流配置存储在仓库根目录的 .cnb.yml 文件中 （也可通过 include 关键字导入其他配置文件）

以下是两者语法的主要差异：

GitHub Actions 格式

name: Node.js CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: npm test

CNB 格式

.cnb.yml
main:
  push:
    - name: Node.js CI/CD
      stages:
        - name: build
          image: ubuntu:latest
          jobs:
            - name: Run tests
              script: npm test

  pull_request:
    - name: Node.js CI/CD
      stages:
        - name: build
          image: ubuntu:latest
          jobs:
            - name: Run tests
              script: npm test

如需在 push 和 pull_request 中复用相同配置，可参考 YAML 高级语法 使用锚点功能。

构建触发规则

GitHub Actions 通过 on 字段定义触发规则， CNB 通过 触发分支 和 触发事件 来定义。详见 构建触发规则。

GitHub Actions 格式

name: Node.js CI/CD

on:
  push:
    branches: [main]

jobs:
  build:
    steps:
      - name: echo
        run: echo "do some job"

CNB 格式

.cnb.yml
main: # 触发分支
  push: # 触发事件,对应一个构建,可以包含多条 Pipeline。既可以是数组,也可以是对象。
    - stages: # 流水线1
        - name: echo
          script: echo "do some job"

Runners

  • GitHub Actions 中 Runner 指执行任务的虚拟机（如 macOS、Windows、Linux）
  • CNB 中 Runner 指构建节点（默认运行 Docker 容器的节点），目前仅支持 Linux Docker 容器。企业版（私有化部署）可接入 macOS、Windows、Linux 等不同机器，详见 构建节点

GitHub Actions 使用 runs-on 指定 Runner， CNB 使用 runner 字段指定构建节点的架构和资源配置。

GitHub Actions 格式

linux_job:
  runs-on: ubuntu-latest
  steps:
    - run: echo "Hello, $USER!"

CNB 格式

.cnb.yml
main:
  push:
    - runner:
        tags: cnb:arch:amd64
        cpus: 16
      docker:
        image: ubuntu:latest
      stages:
        - name: echo
          script: echo "Hello, $USER!"

构建环境

  • GitHub Actions：工作流运行在虚拟机中，所需软件需预装或手动安装
  • CNB：工作流运行在 Docker 容器中，只需指定镜像或 Dockerfile 即可搭建构建环境。详见 构建环境

GitHub Actions 格式

linux_job:
  runs-on: ubuntu-latest
  steps:
    - name: Use Node.js 21
      uses: actions/setup-node@v4
      with:
        node-version: 21
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

CNB 格式

.cnb.yml
main:
  push:
    - docker:
        image: node:21
      stages:
        - name: npm ci
          script: npm ci
        - name: build
          script: npm run build --if-present
        - name: npm test
          script: npm test

仓库代码准备

  • GitHub Actions：使用 actions/checkout 拉取仓库代码
  • CNB：默认拉取仓库代码，无需显式声明。详见 流水线语法-仓库配置

GitHub Actions 格式

linux_job:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - run: ls -al .

CNB 格式

.cnb.yml
main:
  push:
    - stages:
        - name: ls
          script: ls -al .

条件触发

  • GitHub Actions：使用 if 字段设置步骤执行条件
  • CNB：使用 if、ifModify、ifNewBranch 等字段设置步骤执行条件。 详见 流水线语法-if

GitHub Actions 格式

jobs:
  deploy_prod:
    if: contains( github.ref, 'master')
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploy to production server"

CNB 格式

.cnb.yml
$:
  push:
    - if: echo "$CNB_BRANCH" | grep -q 'master'
      stages:
        - name: Deploy to production server
          script: echo "Deploy to production server"

任务依赖

  • GitHub Actions：使用 needs 字段定义依赖关系
  • CNB：使用 cnb:await 和 cnb:resolve 内置任务定义依赖关系并传递变量。 详见 await-resolve 内置任务

GitHub Actions 格式

jobs:
  build_a:
    runs-on: ubuntu-latest
    steps:
      - run: echo "This job will be run first."

  build_b:
    runs-on: ubuntu-latest
    steps:
      - run: echo "This job will be run first, in parallel with build_a"

  test_ab:
    runs-on: ubuntu-latest
    needs: [build_a, build_b]
    steps:
      - run: echo "This job will run after build_a and build_b have finished"

  deploy_ab:
    runs-on: ubuntu-latest
    needs: [test_ab]
    steps:
      - run: echo "This job will run after test_ab is complete"

CNB 格式

通过 cnb:resolve 在上游流水线结束时登记 key，再用 cnb:await 按 key 等待其完成， 即可表达与 needs 等价的依赖关系。每个流水线下的 stages 默认顺序执行。

并行构建并登记 key：

.cnb.yml
main:
  push:
    # 两条流水线并行执行，结束时各自登记 key
    - name: build_a
      stages:
        - name: build_a
          script: echo "This job will be run first."
        - name: resolve
          type: cnb:resolve
          options:
            key: build_a
    - name: build_b
      stages:
        - name: build_b
          script: echo "This job will be run in parallel with build_a"
        - name: resolve
          type: cnb:resolve
          options:
            key: build_b

等待 build_a 与 build_b 都完成后，再执行测试：

.cnb.yml
main:
  push:
    - name: test_ab
      stages:
        - name: await build_a & build_b
          type: cnb:await
          options:
            key: [build_a, build_b]
        - name: run tests
          script: echo "This job runs after build_a and build_b"
        - name: resolve
          type: cnb:resolve
          options:
            key: test_ab

等待 test_ab 完成后，再执行部署：

.cnb.yml
main:
  push:
    - name: deploy_ab
      stages:
        - name: await test_ab
          type: cnb:await
          options:
            key: test_ab
        - name: deploy
          script: echo "This job runs after test_ab completes"

cnb:await 支持通过数组 key: [build_a, build_b] 同时等待多个上游 Pipeline，无需分拆为多个 await stage。

变量和密钥

  • GitHub Actions：使用 env 字段指定变量，使用 secrets 引用密钥
  • CNB：使用 env 字段指定变量，使用 imports 引用外部仓库或密钥 仓库文件作为环境变量。详见 引用变量 和 密钥仓库

GitHub Actions 格式

jobs:
  deploy_prod:
    runs-on: ubuntu-latest
    env:
      DEPLOYMENT_ENV: production
    steps:
      - run: echo "This job will deploy to the $DEPLOYMENT_ENV server"

CNB 格式

#env.yml
DEPLOYMENT_ENV: "production"
.cnb.yml
main:
  push:
    - imports:
        - cnb.cool/<your-repo-slug>/-/blob/main/xxx/env.yml
      stages:
        - name: Deploy to the $DEPLOYMENT_ENV server
          script: echo "This job will deploy to the $DEPLOYMENT_ENV server"

矩阵策略

  • GitHub Actions：支持矩阵策略，在单个作业定义中基于变量组合自动创建多个作业运行
  • CNB：不原生支持矩阵策略，但可使用 YAML 锚点功能模拟。 详见 YAML 高级语法

GitHub Actions 格式

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [15.x, 16.x]
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - name: Install node modules
        run: npm install
      - name: Run a one-line script
        run: npm run build
      - name: Run a multi-line script
        run: npm run test

CNB 格式

.cnb.yml
main:
  push:
    - docker:
        image: node:14 # 替换为 node:16 可切换版本
      stages:
        - name: Install node modules
          script: npm install
        - name: Build
          script: npm run build
        - name: Test
          script: npm run test

CNB 不原生支持矩阵策略，需为每个版本添加独立 Pipeline。 如需避免重复，可参考 YAML 高级语法 使用锚点或 include。

缓存

  • GitHub Actions：使用缓存策略暂存构建中间产物，供后续构建使用
  • CNB：可通过 pipeline.runner.volumes 声明节点本地缓存， 或使用 docker:cache 内置任务声明远端 Docker 镜像缓存。 详见 流水线缓存

GitHub Actions 格式

jobs:
  deploy_prod:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Cache node modules
        uses: actions/cache@v2
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-
      - name: Build project
        run: npm ci && npm run build

CNB 格式

.cnb.yml
main:
  push:
    - docker:
        image: node:14
        volumes:
          - /root/.npm
      stages:
        - name: Build project
          script: npm ci && npm run build

使用 docker:cache 内置任务声明远端 Docker 镜像缓存：

.cnb.yml
main:
  push:
    - docker:
        image: node:14
      stages:
        - name: build cache image
          type: docker:cache
          options:
            dockerfile: cache.dockerfile
            by:
              - package.json
              - package-lock.json
            versionBy:
              - package-lock.json
          exports:
            name: DOCKER_CACHE_IMAGE_NAME
        - name: use cache
          image: $DOCKER_CACHE_IMAGE_NAME
          commands:
            - cp -r "$NODE_PATH" ./node_modules
        - name: Build project
          script: npm ci && npm run build

其中 cache.dockerfile 是一个用于构建缓存镜像的 Dockerfile，示例：

FROM node:14
WORKDIR /space
COPY . .
RUN npm ci
ENV NODE_PATH=/space/node_modules

制品

  • GitHub Actions：使用 actions/upload-artifact 上传制品
  • CNB：使用 cnbcool/attachments:latest 插件保存制品，详见 附件插件

GitHub Actions 格式

jobs:
  deploy_prod:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Upload a Build Artifact
        uses: actions/upload-artifact@v2
        with:
          name: my-artifact
          path: /path/to/artifact

CNB 格式

.cnb.yml
main:
  push:
    - docker:
        image: ubuntu:latest
      stages:
        - name: Upload a Build Artifact
          image: cnbcool/attachments:latest
          settings:
            attachments:
              - /path/to/artifact

数据库及服务容器

  • GitHub Actions：使用 services 字段编排数据库及服务容器
  • CNB：通过声明 docker 服务，直接在任务中执行 docker 或 docker compose 命令编排。 详见 Docker 服务

GitHub Actions 格式

jobs:
  container-job:
    runs-on: ubuntu-latest
    container: node:20-bookworm-slim

    services:
      postgres:
        image: postgres
        env:
          POSTGRES_PASSWORD: postgres

    steps:
      - name: Check out repository code
        uses: actions/checkout@v4

      # Performs a clean installation of all dependencies
      # in the `package.json` file
      - name: Install dependencies
        run: npm ci

      - name: Connect to PostgreSQL
        # Runs a script that creates a PostgreSQL client,
        # populates the client with data, and retrieves data
        run: node client.js
        env:
          # The hostname used to communicate with the
          # PostgreSQL service container
          POSTGRES_HOST: postgres
          # The default PostgreSQL port
          POSTGRES_PORT: 5432

CNB 格式

.cnb.yml
main:
  push:
    - docker:
        image: ubuntu:latest
      services:
        - docker
      stages:
        - name: Start database and service
          script: docker-compose up -d
        - name: Connect to PostgreSQL
          script: node client.js
          env:
            POSTGRES_HOST: 127.0.0.1
            POSTGRES_PORT: 5432
© 2026 cnb.cool