在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

immich-app/immich

菜单

CI/CD 流水线

相关源文件

本文档描述了 Immich 项目的持续集成和持续部署 (CI/CD) 流水线。它详细介绍了构建、测试和部署系统不同组件的自动化工作流。有关构建系统本身的信息，请参阅构建系统。

概述

Immich 的 CI/CD 流水线使用 GitHub Actions 自动化应用程序不同组件的测试、构建和部署。该流水线确保代码库的更改在集成前经过充分测试，并确保在适当时候自动构建和发布可部署的工件。

CI/CD 管道架构

来源：.github/workflows/docker.yml .github/workflows/test.yml .github/workflows/cli.yml .github/workflows/build-mobile.yml .github/workflows/prepare-release.yml .github/workflows/docs-build.yml .github/workflows/docs-deploy.yml

工作流触发器

CI/CD 流水线由不同事件触发

触发器描述相关工作流
拉取请求当 PR 被打开或更新时test.yml, docker.yml, static_analysis.yml
推送到主分支当代码被推送到主分支时test.yml, docker.yml, build-mobile.yml
发布当发布新版本时docker.yml, cli.yml, sdk.yml
手动当工作流被手动触发时prepare-release.yml, build-mobile.yml

流水线使用路径过滤来确定哪些组件需要测试或构建，通过仅运行必要的工作流来优化资源。

来源：.github/workflows/test.yml13-54 .github/workflows/docker.yml19-43 .github/workflows/build-mobile.yml19-36 .github/workflows/cli.yml2-13

测试工作流

测试流水线包含多个阶段，以确保代码质量和功能

单元测试和集成测试

The test.yml 工作流对不同组件运行单元测试、集成测试和端到端测试

组件测试类型描述
服务器单元、集成、中型NestJS 服务器应用程序的测试
Web单元SvelteKit Web 应用程序的测试
移动端单元Flutter 移动应用程序的测试
CLI单元命令行界面的测试
机器学习单元Python 机器学习服务的测试
端到端端到端测试跨组件集成测试

每个组件的测试仅在相关文件发生更改时运行，这由路径过滤决定。

来源：.github/workflows/test.yml56-408

额外的质量检查

额外的工作流对代码库执行额外的检查

  1. 静态分析：使用 CodeQL 等工具检测安全漏洞和代码质量问题
  2. 格式验证：确保代码库中代码格式的一致性
  3. API 生成检查：验证 OpenAPI 客户端代码生成是否最新
  4. 数据库迁移检查：确保数据库迁移已正确定义
  5. Conventional Commits：验证 PR 标题是否遵循 Conventional Commit 格式

来源：.github/workflows/codeql-analysis.yml .github/workflows/static_analysis.yml .github/workflows/test.yml447-562 .github/workflows/pr-require-conventional-commit.yml

Docker 构建工作流

The docker.yml 工作流负责构建和发布服务器和机器学习组件的 Docker 镜像。

构建流程

来源：.github/workflows/docker.yml95-419

Docker 镜像标签策略

Docker 镜像根据触发事件进行不同的标记

事件标签格式示例注册表
推送到主分支mainghcr.io/immich-app/immich-server:main仅限 GHCR
拉取请求pr-{number}ghcr.io/immich-app/immich-server:pr-123仅限 GHCR
提交commit-{sha}ghcr.io/immich-app/immich-server:commit-abc123仅限 GHCR
发布{tag}, releaseghcr.io/immich-app/immich-server:v1.2.3GHCR 和 Docker Hub

对于机器学习服务，标签中会添加额外的特定变体后缀

变体标签后缀示例
CPU (默认)(无)ghcr.io/immich-app/immich-machine-learning:main
CUDA-cudaghcr.io/immich-app/immich-machine-learning:main-cuda
ROCm-rocmghcr.io/immich-app/immich-machine-learning:main-rocm
OpenVINO-openvinoghcr.io/immich-app/immich-machine-learning:main-openvino
ArmNN-armnnghcr.io/immich-app/immich-machine-learning:main-armnn
RKNN-rknnghcr.io/immich-app/immich-machine-learning:main-rknn

来源：.github/workflows/docker.yml269-292 .github/workflows/docker.yml447-469

CLI 构建和发布

CLI 组件有一个专门的工作流，用于构建和发布 CLI 包

来源：.github/workflows/cli.yml

CLI 发布为

  1. NPM 包 (@immich/cli)
  2. Docker 镜像 (ghcr.io/immich-app/immich-cli)

两者都只在发布事件时发布。

移动应用构建流程

移动应用构建工作流负责构建 Android 应用程序

来源：.github/workflows/build-mobile.yml

移动构建流水线创建

  1. 常规 Android APK 文件
  2. 针对不同架构（arm、arm64、x64）优化的拆分 APK

这些工件被上传到 GitHub Actions，并在发布过程中使用。

发布流程

发布流程由 prepare-release.yml 工作流处理，该工作流可以手动触发

来源：.github/workflows/prepare-release.yml misc/release/pump-version.sh

发布流程

  1. 更新各个组件的版本号
  2. 提交更改并创建版本标签
  3. 构建移动应用程序
  4. 创建包含必要文件的 GitHub 草稿版本
  5. 然后可以手动发布该版本，这将触发其他发布工作流

文档构建和部署

文档系统有其自己的 CI/CD 流水线

来源：.github/workflows/docs-build.yml .github/workflows/docs-deploy.yml

文档流水线根据触发器部署到不同的环境

  1. 拉取请求：部署到预览环境 (pr-{number}.docs.immich.app)
  2. 主分支：部署到主环境 (main.docs.immich.app)
  3. 发布：部署到发布环境 (docs.immich.app)

CI/CD 基础设施

CI/CD 流水线结合使用 GitHub 托管的运行器和自托管运行器

运行器用于备注
ubuntu-latest大多数作业GitHub 托管的 Linux 运行器
macos-14移动构建GitHub 托管的 macOS 运行器
mich端到端测试，专用构建用于硬件功能的自托管运行器
ubuntu-24.04-armARM 构建GitHub 托管的 ARM 运行器

一些作业（如 ML Docker 构建）使用专用运行器来访问 CUDA、ROCm 或其他加速技术等硬件功能。

来源：.github/workflows/docker.yml98-141 .github/workflows/test.yml281-282 .github/workflows/build-mobile.yml43

CI/CD 流水线优化

流水线使用多种技术来优化构建时间和资源使用

  1. 路径过滤：仅在相关文件更改时运行工作流
  2. Docker 层缓存：通过缓存层加快 Docker 构建
  3. 并发控制：当有新提交推送时取消进行中的工作流
  4. 条件作业执行：仅在必要时根据之前的作业结果运行作业
  5. 矩阵构建：并行运行多种配置

来源：.github/workflows/docker.yml11-13 .github/workflows/test.yml8-10 .github/workflows/docker.yml177-179