Files

T

2026-10-18 03:39:07 +08:00

7.0 KiB

Raw Blame History

title

title
GitHub Actions 镜像工作流

本文档描述了共享核心镜像和可重用下游应用镜像的当前工作流设置。

工作流角色

当前工作流布局是：

.github/workflows/core-build-develop.yml
.github/workflows/core-build-stable.yml
.github/workflows/core-build-test-images.yml
.github/workflows/core-publish-images.yml
.github/workflows/app-build-image.yml

core-build-develop.yml 和 core-build-stable.yml 是编排工作流。它们决定核心镜像流水线何时运行。

core-build-test-images.yml 是可重用工作流，它：

解析请求的发布行的镜像版本
将共享核心镜像构建到本地注册表
对这些镜像运行测试套件

core-publish-images.yml 是可重用工作流，它：

将测试过的镜像发布到 Docker Hub
将 base 和 build 发布到 GHCR

app-build-image.yml 是可重用工作流，下游仓库调用它来：

从调用者的应用仓库和 ref 创建 apps.json 文件
构建 images/layered/Containerfile
消费现有的 base 和 build 镜像
将请求的应用安装到最终镜像中
可选地将最终应用镜像推送到调用者的注册表

当前流程

当前结构是：

核心编排
  -> 核心构建和测试
  -> 核心发布

下游应用工作流
  -> 消费已发布的 base 和 build
  -> 安装应用
  -> 发布最终应用镜像

当前 Mermaid 概览：

flowchart TD
    subgraph Core["核心镜像流程"]
        A[core-build-develop.yml 或 core-build-stable.yml]
        B[core-build-test-images.yml]
        C[解析版本]
        D[构建本地测试镜像]
        E[运行 pytest]
        F[core-publish-images.yml]
        G[推送到 Docker Hub: erpnext, base, build]
        H[推送到 GHCR: base, build]

        A --> B
        B --> C
        C --> D
        D --> E
        E --> F
        F --> G
        F --> H
    end

    subgraph App["下游应用流程"]
        I[下游仓库工作流]
        J[app-build-image.yml]
        K[创建 apps.json]
        L[构建 images/layered/Containerfile]
        M[安装应用]
        N[推送最终应用镜像]

        I --> J
        J --> K
        K --> L
        L --> M
        M --> N
    end

    G --> J
    H --> J

更具体地说：

core-build-test-images.yml
  -> 解析 frappe 和 erpnext 标签
  -> 将镜像构建到本地 CI 注册表
  -> 运行测试

core-publish-images.yml
  -> 推送到 Docker Hub: erpnext, base, build
  -> 推送到 GHCR: base, build

app-build-image.yml
  -> 拉取:
     - <prefix>/base:<frappe_ref>
     - <prefix>/build:<frappe_ref>
  -> 从 app_repo + app_ref 安装应用
  -> 推送最终 image_name:image_tag

命名约定

GitHub Actions 要求工作流文件直接位于 .github/workflows 内。不支持工作流文件的子目录，因此结构应来自文件名和 name: 值。

推荐的文件命名约定：

<area>-<action>-<subject>.yml

当前示例：

core-build-bench.yml
core-build-develop.yml
core-build-stable.yml
core-build-test-images.yml
core-publish-images.yml
app-build-image.yml
docs-publish-site.yml

推荐的可见工作流名称：

Core / Build Bench
Core / Build Develop
Core / Build Stable
Core / Build and Test Images
Core / Publish Images
App / Build Image
Docs / Publish Site

样式规则

为了保持工作流可预测，每个类别使用一个约定而不是混合样式。

工作流文件名应使用 kebab-case：

core-build-test-images.yml
app-build-image.yml

工作流显示名称应使用短标题样式组：

Core / Build and Test Images
App / Build Image

工作流输入应使用 snake_case：

app_name:
frappe_ref:
image_name:

环境变量应使用大写 snake case：

FRAPPE_IMAGE_PREFIX
PYTHON_VERSION
NODE_VERSION

推荐的规则集是：

工作流文件名：kebab-case
工作流 name: 值：分组标题大小写
工作流输入：snake_case
作业 id 和步骤 id：实际可行的 snake_case
环境变量：UPPER_SNAKE_CASE

这意味着 - 更适合文件名，而 _ 仍然适合 YAML 键、输入和环境变量。

`app-build-image.yml` 中的重要输入

可重用的应用工作流主要由以下输入控制：

app_name 应用目录名称，例如 crm
app_repo 要安装的 Git 仓库，例如 frappe/crm
app_ref 要安装的分支或标签，例如 develop
frappe_ref 现有 base 和 build 镜像的标签，例如 version-16
frappe_image_prefix 共享 base 和 build 镜像的来源，例如 frappe 或 ghcr.io/frappe
image_name 最终目标镜像名称，例如 ghcr.io/acme/crm
image_tag 最终目标镜像标签，例如 develop
registry 最终推送的注册表，例如 ghcr.io 或 docker.io

关键区别是：

frappe_image_prefix = 共享 base/build 镜像的来源
image_name          = 最终应用镜像的目标

示例：调用者仓库发布到 GHCR

此示例假设：

共享基础镜像存在于 ghcr.io/frappe/base 和 ghcr.io/frappe/build
调用者仓库希望将其自己的应用镜像发布到 ghcr.io/acme/crm

name: App / Build CRM Image

on:
  workflow_dispatch:
  push:
    branches:
      - develop

permissions:
  contents: read
  packages: write

jobs:
  build-image:
    uses: frappe/frappe_docker/.github/workflows/app-build-image.yml@main
    with:
      app_name: crm
      app_repo: acme/crm
      app_ref: develop
      frappe_ref: version-16
      frappe_image_prefix: ghcr.io/frappe
      image_name: ghcr.io/acme/crm
      image_tag: develop
      registry: ghcr.io
      push: true
      platforms: linux/amd64

发生的事情：

1. 调用 app-build-image.yml
2. 从 acme/crm + develop 生成 apps.json
3. 工作流构建 images/layered/Containerfile
4. layered 使用:
   - ghcr.io/frappe/build:version-16
   - ghcr.io/frappe/base:version-16
5. 安装 CRM
6. 最终镜像推送到 ghcr.io/acme/crm:develop

对于 GHCR，调用者工作流应授予：

permissions: packages: write

然后可重用工作流使用工作流令牌登录。

示例：调用者仓库发布到 Docker Hub