从 GitHub Actions 迁移到腾讯云 CNB：语法对照与避坑清单

摘要：

从 GitHub Actions 迁移到腾讯云云原生构建（CNB），核心是把分散的 workflow 文件改写为根目录的 .cnb.yml，并完成触发规则、运行环境、任务依赖等语法的对应转换。本文逐项对照两者语法差异，并梳理迁移中的常见陷阱，帮助团队少走弯路。

一、迁移前先看清本质差异

GitHub Actions 和 CNB 都用 YAML 定义自动化构建、测试、部署流程，表面相似，底层结构却不同。迁移前如果只想着「把文件搬过去」，往往会在第一条流水线运行失败时卡住。真正的迁移是配置逻辑的重写，而不是文件的搬运。

两者在概念层级上存在对应关系：GitHub Actions 的一个 workflow 对应 CNB 的一条 Pipeline，workflow 里的 job 对应 CNB 的 Stage，job 里的 step 对应 CNB 的 Job。记住这组映射，后面的语法转换就有了抓手。

最关键的结构差异有两点。第一，文件组织方式不同。GitHub Actions 每个 workflow 是单独的 YAML 文件，放在 .github/workflows 目录下；CNB 把所有流水线配置集中在仓库根目录的 .cnb.yml 文件中，也可以通过 include 关键字导入其他配置文件拆分管理。第二，运行环境不同。GitHub Actions 的 Runner 是执行任务的虚拟机，需要预装或手动安装软件；CNB 的 Runner 是构建节点，任务运行在 Docker 容器中，只需指定镜像即可搭建环境，默认仅支持 Linux Docker 容器，企业版私有化部署可接入 macOS、Windows、Linux 等不同机器。

二、配置文件结构如何对应

先看一个 GitHub Actions 的 Node.js 构建示例。

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: & build
    - name: Node.js CI/CD
      stages:
        - name: build
          image: ubuntu:latest
          jobs:
            - name: Run tests
              script: npm test
  pull_request: * build

这里能看到几个直接对应：on.push 和 on.pull_request 变成了分支名 main 下的 push 和 pull_request 事件；steps 变成了 stages；run 变成了 script；uses: actions/checkout@v3 这一步在 CNB 中直接省略，因为 CNB 默认就会拉取仓库代码，无需显式声明。末尾的 & build 和 * build 是 YAML 锚点语法，用于配置复用，让 push 和 pull_request 共享同一套流水线定义。

需要注意的是，CNB 的层级是「触发分支 → 触发事件 → Pipeline → Stage → Job」，stages 必须放在 Pipeline 数组项内部，缩进层级写错是最常见的配置失效原因。

三、核心语法逐项对照

下面用一张表把高频语法差异列清楚，迁移时可直接对照。

依赖编排是迁移中改动较大的一块。GitHub Actions 用 needs 声明 job 之间的先后关系，CNB 则通过 jobs 的结构控制执行顺序：写成数组时串行执行，写成对象时并行执行；需要互斥或排队时，可以用 lock 给 Pipeline / Stage / Job 加锁来实现。

四、迁移成本主要来自三部分

迁移成本主要来自三部分：配置重写、环境变量与密钥改造、镜像环境重建。

配置重写是工作量最大的一项。所有 workflow 文件需要按新的层级结构改写为 .cnb.yml，触发规则、运行环境、步骤语法都要逐一转换。如果一个仓库里有多个 workflow 文件，可以借助 include 拆分，保持配置清晰。

环境变量与密钥需要重新组织。GitHub Actions 里用 secrets 管理的敏感信息，在 CNB 中改为通过 imports 引用外部密钥仓库文件。例如把 DEPLOYMENT_ENV 这类变量放进一个 env.yml，再在 .cnb.yml 里用 imports 引入。这里要特别注意，CNB 流水线中无效的写法包括 triggers、matrix、runs-on、uses、steps，以及 ${{ matrix.xxx }} 变量模板、actions/checkout 等插件引用、$GITHUB_TOKEN 等 GitHub 专属环境变量，这些都需要替换为 CNB 的等价实现。

镜像环境重建相对轻量。CNB 基于 Docker 生态，每个 Job 在指定镜像中运行，官方提供常用语言的预置镜像。原来依赖 actions/setup-node、actions/setup-java 这类 Action 安装运行时的步骤，可以直接换成对应语言的官方镜像，例如 node:21、node:20，省去运行时安装环节。

构建节点规格上，CNB 提供 amd64 架构（1～64 核 CPU）、arm64/v8 架构（1～16 核 CPU）和 GPU 节点（固定 16 核加 48GB 显存），所有节点最大构建时长为 18 小时。迁移时可按原 Runner 的资源规格就近选择。

五、一个完整的改写示例

把前面零散的片段拼成一条可运行的完整流水线，帮助理解整体结构。下面这条配置在 main 分支 push 时，用 Node.js 21 镜像完成安装、构建、测试。

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

如果需要区分不同分支，可以为每个分支单独配置，或用 YAML 锚点复用同一套 stages。需要多版本并行验证时，由于 CNB 不原生支持矩阵策略，可以为每个版本声明一条独立的 pipeline，各自指定不同版本的镜像，用锚点共享 stages 内容，达到类似矩阵构建的效果。

六、迁移中的常见陷阱

第一，不要依赖「一键迁移」工具直接搬运 .github 目录。这类工具通常只能完成 Git 对象的克隆与推送，无法把 workflow 的事件定义、运行环境、步骤时序转换成 CNB 的 Pipeline 语义，搬过去的配置往往运行即报错。

第二，注意层级缩进。stages 必须位于 Pipeline 数组项内部，与 imports、docker 等同级，缩进错误会导致流水线根本不触发。

第三，把 GitHub 专属的环境变量和上下文表达式替换干净。$GITHUB_STEP_SUMMARY、$GITHUB_TOKEN、github.ref 等在 CNB 中没有对应物，需要改用 CNB 的内置环境变量和条件字段。

第四，缓存策略要重新设计。跨节点共享缓存时使用 docker:cache 声明远端 Docker 镜像缓存，单节点本地缓存则用 docker.volumes，两者适用场景不同。

官方提供了完整的迁移指南，涵盖上述所有差异点和更多细节，迁移前值得通读一遍。

腾讯云 CNB 把代码托管、云原生构建、制品库和 AI 能力整合在同一平台，基于 Docker 生态和声明式的 .cnb.yml 配置，让迁移后的流水线更贴近云原生方式运行。如果你的团队正在评估从 GitHub Actions 迁出，不妨先在一个小仓库上跑通最小示例，再逐步推广；想动手验证，可以到腾讯云 CNB 用一个真实仓库跑通第一条迁移后的流水线。