如何搭建 Gitea Actions 自动化流水线

如何搭建 Gitea Actions 自动化流水线

【免费下载链接】giteaGit with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD项目地址: https://gitcode.com/GitHub_Trending/gi/gitea

周三晚上十点，热修上线，你手动跑测试、打 tag、把包传到服务器——中间漏掉一条迁移命令，生产库直接报错。这类事故很少是因为某一步多难，而是步骤太多、全靠人记忆。把测试、构建、发布交给 Gitea Actions 这条自动化流水线，持续集成就从口号变成了仓库里的一个 YAML 文件，每次 push 后它自己把该干的活干完。

Gitea Actions 运行列表页截图

🚀 触发与编排：一次 push 之后发生什么

这一节解决"什么时候跑、按什么顺序跑"的问题。

Workflow 文件放在仓库的.gitea/workflows目录下，.yml或.yaml结尾。触发器写在on字段里，常用的一共有这些：

常用触发器对照

下面这段 YAML 只要 15 行，就能让每次 push 到main自动跑完 Node.js 的测试，测试通过后才进入打包阶段——这是一个典型的 Gitea 自动化测试部署起点：

on: push: branches: [ main ] jobs: unit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm ci && npm test package: needs: unit runs-on: ubuntu-latest steps: - run: echo "unit 通过后才会执行"

needs是编排的核心：package声明needs: unit，只有unit成功后它才会启动，unit失败则整个后续链跳过。反过来，没有needs的 Job 之间是并行执行的，于是可以这样拆一条 Gitea 构建流水线实战里常见的验证链：

三条验证 Job 同时开跑，全部通过才进build，整体耗时约等于最慢的那条，而不是四条之和。

Gitea Actions 执行界面：Job 状态

🔒 Runner 与 Secrets：环境隔离和密钥不落地

这一节解决"在哪台机器上跑、敏感信息怎么传"的问题。

Job 由 Runner（执行 Job 的守护进程）真正运行。接入步骤很短：

1. 管理员在后台「服务 → Actions」勾选启用 Actions
2. 仓库「设置 → 功能」里打开 Actions
3. 在 Actions 页点「管理 Runner → 创建 Runner」，拿到注册 token
4. 在目标机器按提示注册并启动 Runner 进程

Gitea CI/CD 配置里有两种常见的运行方式：

• 直接跑在 Runner 主机上：runs-on: ubuntu-latest
• 跑在容器里：runs-on: docker://node:20，每个 Job 一个一次性容器，装了什么依赖、缺了什么依赖都可控，天然避免"在我机器上能跑"

容器化还有一个好处：镜像版本就是环境版本，回滚时把runs-on的 tag 换回去即可。

密钥不落地：Secrets 注入

部署口令、仓库注册表 token 这类东西，永远不要写进 YAML。把它们存到仓库「设置 → Secrets」，运行时再注入：

- name: 发布 env: DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }} VERSION: ${{ github.sha }} run: ./deploy.sh --key "$DEPLOY_KEY" --ver "$VERSION"

${{ secrets.X }}只在 Runner 执行时展开成环境变量，不进代码库、不进日志。另外每个 Job 会自动拿到一个GITEA_TOKEN，用于checkout等步骤，它的权限会被仓库/组织级别的策略硬限制——这块的设计细节可以看 Actions 令牌权限说明。

Runner 注册后的状态页

🐳 集成：质量门禁与镜像构建

这一节解决"流水线怎么接第三方工具"的问题。

接外部工具就两条路：run里直接调命令行工具（golangci-lint、ruff、pnpm audit 都行），或者uses一个现成的 Action。质量门禁建议放在 PR 触发的 Job 里，覆盖率没达标就让 CI 红掉，比事后补扫省事。

镜像构建是另一个高频场景，把构建和推送串成一个 Job，版本直接用 commit 短 hash，保证可追溯：

jobs: image: runs-on: docker://node:20 env: USERNAME: ${{ secrets.REGISTRY_USER }} TOKEN: ${{ secrets.REGISTRY_TOKEN }} steps: - uses: actions/checkout@v4 - run: docker build -t myapp:${{ github.sha }} . - run: | docker login -u "$USERNAME" -p "$TOKEN" docker push myapp:${{ github.sha }}

发 release 时，把 tag 也打一份镜像（比如myapp:${{ github.ref_name }}），回滚就是拉旧 tag 重新部署，不用再从 git 里翻历史。

容器镜像构建 Job 的日志

⚡ 提速与排障：缓存、矩阵和日志

这一节解决"流水线跑得慢、失败又难查"的问题。

缓存让第二次跑快一半

依赖下载通常占单 Job 的大头，用actions/cache按锁文件指纹缓存，依赖没变就直接命中：

- uses: actions/cache@v4 with: path: ~/.npm key: npm-${{ hashFiles('package-lock.json') }} restore-keys: npm-

用 matrix 跑多环境

同一套测试要在多个 Node 版本、多个系统上跑时，不要复制多份 Job，用strategy.matrix展开：

jobs: test: strategy: fail-fast: false matrix: node: [ 18, 20 ] os: [ ubuntu-latest, windows-latest ] runs-on: ${{ matrix.os }} steps: - uses: actions/setup-node@v4 with: node-version: ${{ matrix.node }} - run: npm test

fail-fast: false表示某格失败不取消其他格，方便一次看全所有兼容性问题。

失败先看这三处

1. 不触发：文件是否在.gitea/workflows、on里的分支是否匹配、仓库是否启用 Actions
2. 触发但 Job 不启动：runs-on的标签没有对应在线 Runner
3. 启动但步骤失败：打开 run 详情看对应 step 的日志，定位到具体命令的退出码

Job 日志详情页

✅ 什么时候该上，什么时候不必

给个判断标准，避免为了 CI 而 CI：

如果你已经在用 Gitea 托管代码，Actions 是最顺手的补全件：YAML 就在仓库里，配置随代码 review，环境与流水线一起版本化。先从"push 自动跑测试"这一个最小 Job 开始，等它稳定，再把构建、发布一格一格加上去——比一次性搭大流水线更容易落地，也更少返工。

【免费下载链接】giteaGit with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD项目地址: https://gitcode.com/GitHub_Trending/gi/gitea