知识库

主题

Gitee Go CI/CD ​

大白话解释： Gitee Go 就是"国内版 GitHub Actions"。如果你的代码托管在 Gitee（码云）上，用 Gitee Go 可以实现和 GitHub Actions 一样的自动化功能：推送代码后自动构建、测试、部署。

Gitee Go vs GitHub Actions 怎么选？

  • Gitee Go：代码在 Gitee 上、服务器在国内、不想翻墙
  • GitHub Actions：代码在 GitHub 上、需要丰富的社区 Action、国际化项目

Gitee Go 的优势：

  • 国内访问快：不用翻墙，服务器在国内
  • 语法兼容：大部分 GitHub Actions 语法可以直接用
  • 适合国内项目：国内团队、国内服务器

Gitee Go 是 Gitee（码云）内置的 CI/CD 平台，语法与 GitHub Actions 类似。适合国内开发者使用，无需翻墙，访问速度快。

💡 Gitee Go 兼容大部分 GitHub Actions 语法，可直接使用 actions/checkout、actions/setup-node 等社区 Action。

与 GitHub Actions 对比 ​

特性Gitee GoGitHub Actions
平台Gitee（国内）GitHub（国外）
访问速度快需翻墙
免费额度1000 分钟/月（社区版）2000 分钟/月（私有仓库）
语法类似原版
生态较小丰富
Runner公有/自托管公有/自托管

与 GitHub Actions 语法差异 ​

Gitee Go 兼容大部分 GitHub Actions 语法，但存在以下差异。

项目Gitee GoGitHub Actions
流水线文件路径.gitee/pipelines/*.yml.github/workflows/*.yml
上下文变量gitee.ref、gitee.shagithub.ref、github.sha
触发事件push、pull_request、tag更丰富（schedule、workflow_dispatch 等）
Secrets 语法${{ secrets.KEY }}相同
服务容器不支持 services 字段支持
可重用 Workflow不支持 workflow_call支持
矩阵策略部分支持完整支持
并发组不支持 concurrency支持
权限声明不支持 permissions支持
环境变量文件不支持 env-file支持

Gitee 魔法变量 ​

yaml
steps:
  - name: Show info
    run: |
      echo "分支: ${{ gitee.ref }}"
      echo "提交: ${{ gitee.sha }}"
      echo "提交者: ${{ gitee.actor }}"
      echo "仓库: ${{ gitee.repository }}"
      echo "事件: ${{ gitee.event_name }}"
      echo "PR编号: ${{ gitee.event.number }}"
变量说明
gitee.ref触发引用（分支或 tag）
gitee.sha当前提交 SHA
gitee.actor触发操作的用户名
gitee.repository仓库全名（owner/repo）
gitee.event_name触发事件类型
gitee.event.numberPR 编号（仅 PR 事件）
gitee.event.head_commit.message最新提交信息

⚠️ 在 Gitee Go 中应使用 gitee.* 而非 github.*。两者部分兼容但不完全等价。

基本结构 ​

yaml
# .gitee/pipelines/deploy.yml

name: Deploy          # 流水线名称

on:                   # 触发条件
  push:
    branches: [main]

jobs:                 # 任务列表
  build-and-deploy:   # 任务名称
    runs-on: ubuntu-latest  # 运行环境

    steps:            # 步骤列表
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: yarn install

      - name: Build
        run: yarn build

      - name: Deploy
        run: echo "Deploying..."

前端项目完整示例 ​

Vue/React 项目部署 ​

yaml
name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: yarn install --frozen-lockfile

      - name: Build
        run: yarn build
        env:
          VITE_API_URL: ${{ secrets.VITE_API_URL }}

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist

      - name: Deploy to server
        uses: easingthemes/ssh-deploy@v5
        with:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
          REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
          REMOTE_USER: ${{ secrets.REMOTE_USER }}
          SOURCE: dist/
          TARGET: /var/www/html

部署到 Gitee Pages ​

yaml
name: Deploy to Gitee Pages

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install and Build
        run: |
          yarn install
          yarn build

      - name: Deploy to Gitee Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITEE_TOKEN }}
          publish_dir: ./dist
          publish_branch: gh-pages

常用触发事件 ​

⚠️ Gitee Go 社区版仅支持 push、pull_request、tag 三种触发事件，不支持 schedule（定时）和 workflow_dispatch（手动触发）。企业版支持定时触发，需在流水线配置中开启。 以下示例展示的是 GitHub Actions 的完整语法，供对比参考。实际 Gitee Go 流水线文件中请勿使用不支持的事件。

yaml
on:
  # push 到指定分支（Gitee Go ✅）
  push:
    branches: [main, develop]
    tags:
      - 'v*'              # tag 推送（发布版本）

  # Pull Request（Gitee Go ✅）
  pull_request:
    branches: [main]

  # 定时任务（Gitee Go ❌ 不支持，仅 GitHub Actions 可用）
  schedule:
    - cron: '0 0 * * *'

  # 手动触发（Gitee Go ❌ 不支持，仅 GitHub Actions 可用）
  workflow_dispatch:
    inputs:
      environment:
        description: '部署环境'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      version:
        type: string
        description: '版本号'
        required: false
        default: 'latest'

Secrets 管理 ​

设置 Secrets ​

  1. 进入仓库 → 管理 → 私密变量
  2. 添加键值对（如 VITE_API_URL、SSH_PRIVATE_KEY）

使用 Secrets ​

yaml
steps:
  - name: Build
    run: yarn build
    env:
      VITE_API_URL: ${{ secrets.VITE_API_URL }}
      VITE_APP_TITLE: ${{ secrets.VITE_APP_TITLE }}

自托管 Runner ​

为什么需要自托管 ​

  • 公有 Runner 速度慢
  • 需要访问内网资源
  • 需要特定环境

配置步骤 ​

  1. 进入仓库 → 管理 → CI/CD → Runner
  2. 下载 Runner 程序
  3. 按提示配置
bash
# 下载
wget https://gitee.com/gitee-go/runner/releases/download/v1.0.0/runner-linux-amd64

# 赋权
chmod +x runner-linux-amd64

# 配置
./runner-linux-amd64 configure --url https://gitee.com/your-org/your-repo --token YOUR_TOKEN

# 启动
./runner-linux-amd64 run

使用自托管 Runner ​

yaml
jobs:
  build:
    runs-on: self-hosted  # 使用自托管 Runner
    steps:
      - uses: actions/checkout@v4
      - run: yarn install
      - run: yarn build

构建环境可选列表 ​

Gitee Go 提供多种预置构建环境。

环境标签预装工具
Ubuntu 20.04ubuntu-20.04Git、Docker、Node.js 16/18/20、Python 3、Java 11/17
Ubuntu 22.04ubuntu-latest / ubuntu-22.04Git、Docker、Node.js 18/20/22、Python 3、Java 17/21
CentOS 7centos-7Git、Docker
yaml
jobs:
  build:
    runs-on: ubuntu-latest          # 使用最新 Ubuntu 环境
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: yarn install
      - run: yarn build

💡 具体可用环境以 Gitee 官方文档为准。企业版支持自定义镜像。

Webhook 配置 ​

Gitee Go 通过 Webhook 监听仓库事件来触发流水线。

配置方式 ​

  1. 进入仓库 → 管理 → WebHooks
  2. 添加 Webhook，填写 URL（Gitee Go 自动管理，通常无需手动配置）
  3. 选择触发事件：Push、Tag Push、Pull Request、Issue 等
  4. 填写 Secret（可选，用于验证请求来源）

手动触发（通过 API） ​

⚠️ Gitee Go 不支持 workflow_dispatch（手动触发），如需手动触发部署，请通过 Gitee API 调用流水线。

bash
# 通过 Gitee API 触发指定流水线
# {owner} = 仓库拥有者，{repo} = 仓库名，{pipeline_id} = 流水线 ID
curl -X POST "https://gitee.com/api/v5/repos/{owner}/{repo}/pipelines/{pipeline_id}/run" \
  -H "Content-Type: application/json" \                    # 请求体格式为 JSON
  -d '{
    "access_token": "YOUR_ACCESS_TOKEN",                  # 个人访问令牌（在 Gitee 私人令牌中生成）
    "ref": "main"                                          # 要触发的分支
  }'

# 也可以在 Gitee 控制台手动点击「运行流水线」按钮触发

多环境部署 ​

⚠️ Gitee Go 不支持 environment 字段（环境声明）。以下示例使用 shell 条件判断实现多环境部署。

yaml
# .gitee/pipelines/deploy.yml — 多环境部署流水线
name: Deploy

on:                                # 触发条件
  push:
    branches: [main, develop]      # push 到 main 或 develop 时触发

jobs:
  deploy:
    runs-on: ubuntu-latest         # 运行环境
    steps:
      - uses: actions/checkout@v4  # 拉取代码

      - name: Setup Node.js
        uses: actions/setup-node@v4  # 安装 Node.js
        with:
          node-version: 20           # 指定 Node.js 版本

      - name: Install
        run: yarn install            # 安装依赖

      - name: Build
        run: yarn build              # 构建项目
        env:
          # 根据分支名选择不同的 API 地址
          VITE_API_URL: ${{ gitee.ref == 'refs/heads/main' && secrets.PROD_API_URL || secrets.STAGING_API_URL }}

      - name: Deploy
        run: |
          # 根据分支名判断部署到哪个环境
          if [ "${{ gitee.ref }}" = "refs/heads/main" ]; then
            echo "Deploy to production"
            # 生产环境部署命令（如 SSH 到生产服务器）
          else
            echo "Deploy to staging"
            # 测试环境部署命令（如 SSH 到测试服务器）
          fi

常见问题 ​

流水线不触发 ​

bash
# 检查 YAML 语法
# 确认分支名正确
# 确认仓库已开启 CI/CD 功能

构建失败 ​

yaml
# 添加调试信息
- name: Debug
  run: |
    node -v
    npm -v
    yarn -v
    pwd
    ls -la

依赖安装慢 ​

yaml
# 使用淘宝镜像
- name: Install
  run: yarn install --registry https://registry.npmmirror.com

权限问题 ​

yaml
# 确保 Secrets 已正确配置
# 检查 Runner 权限
# 检查部署目标服务器权限

Gitee 与 GitHub 代码同步 ​

双向同步配置 ​

yaml
# .github/workflows/sync-to-gitee.yml
name: Sync to Gitee

on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Sync to Gitee
        uses: wearerequired/git-mirror-action@master
        env:
          SSH_PRIVATE_KEY: ${{ secrets.GITEE_SSH_PRIVATE_KEY }}
        with:
          source-repo: [email protected]:your-org/your-repo.git
          destination-repo: [email protected]:your-org/your-repo.git

Gitee Pages 部署详细步骤 ​

开启 Gitee Pages ​

步骤操作
1进入仓库 → 服务 → Gitee Pages
2选择部署分支（如 gh-pages）
3选择部署目录（根目录 / 或子目录 /docs）
4点击「启动」

注意事项 ​

项目说明
仓库要求公开仓库免费使用，私有仓库需付费
分支推荐使用独立分支 gh-pages 存放构建产物
更新每次推送后需手动点击「更新」重新部署
HTTPS在 Pages 设置中勾选「强制 HTTPS」
自定义域名支持绑定自定义域名，需配置 CNAME
访问地址https://gitee.io/{username}/{repo}

自定义域名配置 ​

步骤操作
1在仓库根目录创建 CNAME 文件，写入域名
2DNS 添加 CNAME 记录指向 {username}.gitee.io
3Gitee Pages 设置中填入自定义域名
4等待 DNS 生效后开启 HTTPS

流水线自动部署到 Gitee Pages ​

yaml
name: Deploy to Gitee Pages

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install and Build
        run: |
          yarn install
          yarn build

      - name: Deploy to Gitee Pages
        uses: yanglbme/gitee-pages-action@main
        with:
          gitee-username: ${{ secrets.GITEE_USERNAME }}
          gitee-password: ${{ secrets.GITEE_PASSWORD }}
          gitee-repo: ${{ gitee.repository }}
          branch: gh-pages
          directory: dist

制品管理 ​

上传制品 ​

yaml
steps:
  - name: Build
    run: yarn build

  - name: Upload artifact
    uses: actions/upload-artifact@v4
    with:
      name: dist
      path: dist/
      retention-days: 7
      compression-level: 6

下载制品 ​

yaml
steps:
  - name: Download artifact
    uses: actions/download-artifact@v4
    with:
      name: dist
      path: dist/

制品配置参数 ​

参数类型默认值说明
namestringartifact制品名称
pathstring必填上传/下载路径
retention-daysnumber90保留天数
compression-levelnumber6压缩级别 0-9

多制品管理 ​

yaml
jobs:
  build-web:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: yarn install && yarn build:web
      - uses: actions/upload-artifact@v4
        with:
          name: web-dist
          path: dist/web

  build-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: yarn install && yarn build:api
      - uses: actions/upload-artifact@v4
        with:
          name: api-dist
          path: dist/api

  deploy:
    needs: [build-web, build-api]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          path: all-artifacts
      - run: ls all-artifacts/

缓存配置 ​

使用 setup-node 内置缓存 ​

yaml
steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-node@v4
    with:
      node-version: 20
      cache: yarn         # 自动缓存 yarn 依赖

手动缓存 ​

yaml
steps:
  - name: Cache node_modules
    uses: actions/cache@v4
    with:
      path: node_modules
      key: ${{ runner.os }}-yarn-${{ hashFiles('yarn.lock') }}
      restore-keys: |
        ${{ runner.os }}-yarn-

缓存配置参数 ​

参数说明
path缓存目录路径
key缓存 key，变更则缓存失效
restore-keys缓存未命中时的回退 key

缓存最佳实践 ​

策略说明
使用 lock 文件 hashhashFiles('yarn.lock') 作为 key
分系统缓存key 中加入 ${{ runner.os }}
避免缓存过大只缓存 node_modules，不缓存 dist
设置回退 keyrestore-keys 提高命中率

缓存构建产物 ​

yaml
steps:
  - name: Cache build output
    uses: actions/cache@v4
    with:
      path: dist
      key: build-${{ runner.os }}-${{ hashFiles('src/**') }}
      restore-keys: |
        build-${{ runner.os }}-

通知配置 ​

钉钉通知 ​

yaml
steps:
  - name: DingTalk notification
    if: always()
    uses: zcong1993/setup-ding@v3
    with:
      ding-token: ${{ secrets.DINGTALK_TOKEN }}
      secret: ${{ secrets.DINGTALK_SECRET }}

  - name: Send message
    if: always()
    run: |
      ding -m "text" -c "构建结果: ${{ job.status }}\n分支: ${{ gitee.ref }}\n提交: ${{ gitee.event.head_commit.message }}"

企业微信通知 ​

yaml
steps:
  - name: WeChat Work notification
    if: failure()
    uses: wei/[email protected]
    with:
      args: >
        -X POST "${{ secrets.WECHAT_WEBHOOK }}"
        -H "Content-Type: application/json"
        -d '{"msgtype":"text","text":{"content":"构建失败\n仓库: ${{ gitee.repository }}\n分支: ${{ gitee.ref }}"}}'

邮件通知 ​

yaml
steps:
  - name: Send email
    if: failure()
    uses: dawidd6/action-send-mail@v3
    with:
      server_address: smtp.example.com
      server_port: 465
      username: ${{ secrets.MAIL_USERNAME }}
      password: ${{ secrets.MAIL_PASSWORD }}
      subject: "构建失败: ${{ gitee.repository }}"
      body: |
        构建失败通知
        仓库: ${{ gitee.repository }}
        分支: ${{ gitee.ref }}
        提交者: ${{ gitee.actor }}
      to: [email protected]
      from: [email protected]

条件通知策略 ​

yaml
steps:
  - name: Notify on failure
    if: failure()
    run: echo "发送失败通知"

  - name: Notify on success
    if: success() && gitee.ref == 'refs/heads/main'
    run: echo "主分支部署成功通知"

  - name: Always notify
    if: always()
    run: echo "无论结果都通知"

流水线模板 ​

使用 Gitee 市场模板 ​

  1. 进入仓库 → CI/CD → 新建流水线
  2. 选择「从模板创建」
  3. 浏览 Gitee 市场中的模板

常用模板类型 ​

模板说明适用场景
Node.js 前端构建安装依赖 → 构建 → 部署Vue/React/Angular 项目
Java Maven 构建编译 → 测试 → 打包Spring Boot 项目
Docker 镜像构建构建 → 推送镜像容器化部署
静态站点部署构建 → Pages 部署文档/博客
多语言构建矩阵策略多版本测试库/框架项目

自定义模板 ​

yaml
# .gitee/pipeline-templates/node-deploy.yml
name: Node.js 部署模板

inputs:
  node-version:
    default: '20'
  build-command:
    default: 'yarn build'
  deploy-branch:
    default: 'main'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: yarn

      - run: yarn install --frozen-lockfile
      - run: ${{ inputs.build-command }}

      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

使用自定义模板 ​

yaml
name: My Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    uses: ./.gitee/pipeline-templates/node-deploy.yml
    with:
      node-version: '20'
      build-command: 'yarn build:prod'

Gitee API 部署 ​

通过 Gitee API 可以在外部系统中触发流水线或直接操作仓库。

通过 API 触发流水线 ​

bash
# 触发指定流水线
curl -X POST "https://gitee.com/api/v5/repos/{owner}/{repo}/pipelines/{pipeline_id}/run" \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "YOUR_ACCESS_TOKEN",
    "ref": "main",
    "inputs": {
      "environment": "production"
    }
  }'

通过 API 创建部署 ​

bash
# 创建部署状态
curl -X POST "https://gitee.com/api/v5/repos/{owner}/{repo}/deployments" \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "YOUR_ACCESS_TOKEN",
    "ref": "main",
    "environment": "production",
    "description": "Production deployment"
  }'

API 部署到服务器 ​

⚠️ Gitee Go 不支持 workflow_dispatch 和 inputs。如需通过 API 传参触发部署，建议在流水线中使用 Gitee API + Secrets 来实现。

yaml
# .gitee/pipelines/api-deploy.yml — 通过 Gitee API 触发的部署流水线
name: API Deploy

on:
  push:
    branches: [main]               # 推送到 main 时自动触发

jobs:
  deploy:
    runs-on: ubuntu-latest         # 运行环境
    steps:
      - uses: actions/checkout@v4  # 拉取代码

      - uses: actions/setup-node@v4  # 安装 Node.js
        with:
          node-version: 20           # 指定版本

      - run: yarn install && yarn build  # 安装依赖并构建

      - name: Deploy via SSH
        uses: easingthemes/ssh-deploy@v5  # 通过 SSH 部署到服务器
        with:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}   # SSH 私钥（在仓库私密变量中配置）
          REMOTE_HOST: ${{ secrets.REMOTE_HOST }}           # 目标服务器地址
          REMOTE_USER: ${{ secrets.REMOTE_USER }}           # 登录用户名
          SOURCE: dist/                                     # 本地构建产物目录
          TARGET: /var/www/html                             # 服务器目标目录

💡 API Token 在 Gitee 个人设置 → 私人令牌 中生成。建议使用 Secrets 存储 Token。

参考 ​

个人学习笔记，部分内容借助 AI 辅助整理，仅供查阅参考，请以官方文档为准