根据 Apache 软件基金会 (ASF) 的一个或多个贡献者许可协议授权。请参阅 NOTICE 文件以获取关于版权的附加信息。ASF 根据 Apache License, Version 2.0 (许可证) 将此文件许可给您；除非遵守许可证，否则您不得使用此文件。您可以在 http://www.apache.org/licenses/LICENSE-2.0 获取许可证的副本。

除非适用法律要求或书面同意，否则根据许可证分发的软件按“原样”分发，无任何明示或暗示的保证或条件。请参阅许可证以了解具体的权限和限制。

name: ci-cd description: 指导理解和使用 Apache Beam 的 CI/CD 系统，使用 GitHub Actions。在调试 CI 失败、理解测试工作流或修改 CI 配置时使用。

Apache Beam 中的 CI/CD

概述

Apache Beam 使用 GitHub Actions 进行 CI/CD。工作流位于 .github/workflows/。

工作流类型

预提交工作流

在 PR 和合并时运行
在合并前验证代码更改
命名：beam_PreCommit_*.yml

后提交工作流

在合并后和按计划运行
更全面的测试
命名：beam_PostCommit_*.yml

计划工作流

每晚在 master 分支上运行
检查外部依赖影响
用 nightly-master 标记 master

关键工作流

预提交

工作流	描述
`beam_PreCommit_Java.yml`	Java 构建和测试
`beam_PreCommit_Python.yml`	Python 测试
`beam_PreCommit_Go.yml`	Go 测试
`beam_PreCommit_RAT.yml`	许可证头检查
`beam_PreCommit_Spotless.yml`	代码格式化

后提交 - Java

工作流	描述
`beam_PostCommit_Java.yml`	完整的 Java 测试套件
`beam_PostCommit_Java_ValidatesRunner_*.yml`	运行器验证测试
`beam_PostCommit_Java_Examples_*.yml`	示例管道测试

后提交 - Python

工作流	描述
`beam_PostCommit_Python.yml`	完整的 Python 测试套件
`beam_PostCommit_Python_ValidatesRunner_*.yml`	运行器验证
`beam_PostCommit_Python_Examples_*.yml`	示例

负载和性能测试

工作流	描述
`beam_LoadTests_*.yml`	负载测试
`beam_PerformanceTests_*.yml`	I/O 性能

触发测试

自动

PR 触发预提交测试
合并触发后提交测试

触发特定工作流

使用触发文件来运行特定工作流。

工作流调度

大多数工作流支持通过 GitHub UI 手动触发。

理解测试结果

查找日志

转到 PR → Checks 标签
点击失败的工作流
展开失败的作业
查看步骤日志

常见失败模式

不稳定测试

与更改无关的随机失败
解决方案：使用触发文件重新运行特定工作流。

超时

如果合理，增加工作流中的超时时间
或优化测试

资源耗尽

GCP 配额问题
检查项目设置

GCP 凭证

需要 GCP 访问的工作流使用这些秘密：

GCP_PROJECT_ID - 项目 ID (例如，apache-beam-testing)
GCP_REGION - 区域 (例如，us-central1)
GCP_TESTING_BUCKET - 临时存储桶
GCP_PYTHON_WHEELS_BUCKET - Python 轮子存储桶
GCP_SA_EMAIL - 服务账户邮箱
GCP_SA_KEY - Base64 编码的服务账户密钥

所需的 IAM 角色：

Storage Admin
Dataflow Admin
Artifact Registry Writer
BigQuery Data Editor
Service Account User

自托管与 GitHub 托管的运行器

自托管 (大多数工作流)

预配置依赖项
GCP 凭证预配置
命名：beam_*.yml

GitHub 托管

用于跨平台测试 (Linux, macOS, Windows)
可能需要显式凭证设置

工作流结构

name: 工作流名称
on:
  push:
    branches: [master]
  pull_request:
    branches: [master]
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

jobs:
  build:
    runs-on: [self-hosted, ...]
    steps:
      - uses: actions/checkout@v4
      - name: 运行 Gradle
        run: ./gradlew :task:name

本地调试

运行与 CI 相同的命令

检查工作流文件的 run 命令：

./gradlew :sdks:java:core:test
./gradlew :sdks:python:test

常见问题

清理 gradle 缓存：rm -rf ~/.gradle .gradle
移除构建目录：rm -rf build
检查 Java 版本与 CI 匹配

快照构建

位置

Java SDK: https://repository.apache.org/content/groups/snapshots/org/apache/beam/
SDK 容器: https://gcr.io/apache-beam-testing/beam-sdk
可移植运行器: https://gcr.io/apache-beam-testing/beam_portability
Python SDK: gs://beam-python-nightly-snapshots

发布工作流

工作流	目的
`cut_release_branch.yml`	创建发布分支
`build_release_candidate.yml`	构建 RC
`finalize_release.yml`	最终化发布
`publish_github_release_notes.yml`	发布笔记