Earthly CI/CD集成指南:快速接入GitHub Actions、GitLab CI、Jenkins的完整方案

原创2026-09-21 14:11:171,622 阅读
文章标签:CI/CDDevOps构建工具

Earthly CI/CD集成指南:快速接入GitHub Actions、GitLab CI、Jenkins的完整方案

Earthly 是一个像 Dockerfile 和 Makefile 混血儿一样简单的构建框架,它以"快速、可重复构建"著称。把 Earthly 接入 CI/CD 比想象中简单得多:无论你的团队使用 GitHub Actions、GitLab CI 还是 Jenkins,只需完成安装依赖、安装 Earthly、配置三项基础设置,就能在几分钟内跑通第一条流水线。本文用尽量少的代码,带你一次配好三大主流 CI 系统,并附上远程 BuildKit 提速等进阶技巧。

Earthly CI/CD 集成前后对比图

上图展示了接入 Earthly 前后的变化:左侧 Before 区域里 Dockerfile、Makefile、Bash 各写一套,CI 与开发机行为不一致,故障难以复现;右侧 After 区域用一套 Earthly 统一了 CI 和开发机的构建逻辑。

为什么 CI/CD 集成 Earthly 特别简单

传统 CI 构建有三个老大难问题,而 Earthly 的 CI 集成方案正好对症下药:

传统 CI 痛点 Earthly 的解法
本地能跑、CI 挂了,难以复现 同一份 Earthfile 在开发机和 CI 上行为一致
Dockerfile、Makefile、Shell 脚本各维护一份 一个目标(target)统一定义构建步骤
缓存要手动上传/下载,构建慢 内置 BuildKit 缓存 + --save-inline-cache 自动优化

完整的官方思路见 docs/ci-integration/overview.md,核心就是三步:安装依赖 → 安装 Earthly → 配置。

三大 CI 通用的三步启动法

第一步:准备依赖

Earthly 只依赖两个组件:docker 和 git。绝大多数 CI 镜像(如 ubuntu-latest)已经自带。docker 用于管理 earthly-buildkitd 守护进程,git 用于拉取远程目标并提供构建元数据。

第二步:安装 Earthly

  • 直接安装(推荐):下载固定版本的二进制并执行 earthly bootstrap 完成初始化。建议把安装放进 runner 镜像配置而非每次构建时下载,既能提速又能保证版本稳定。
  • 官方镜像:如果无法本地安装,可直接用官方 earthly/earthly 镜像,它内置了 BuildKit 守护进程;更进阶的是 earthly/buildkitd 镜像,可用于多台 worker 共享一个远程构建守护进程。镜像使用细节见 docs/ci-integration/use-earthly-ci-image.md。

💡 官方强烈建议在 CI 中锁定 Earthly 版本,避免未来版本的行为变化悄悄破坏流水线。

第三步:配置与最佳实践命令

CI 环境下推荐一条"黄金命令":

earthly --ci --push +build
  • --ci 是 --save-inline-cache、--strict、--no-output 的快捷组合,是官方给出的 CI 最佳实践开关;
  • --push 用于执行 CI 中才需要的动作(如推送镜像),平时开发不会触发;
  • 私有仓库/镜像仓库的凭据,通过 --secret 选项注入或配合 docker login 完成,完整列表见 docs/earthly-config/earthly-config.md。

⚠️ 注意:earthly-buildkitd 需要以 --privileged 模式运行,请确保 CI 环境允许(rootless 配置目前不支持)。

GitHub Actions 接入教程

GitHub Actions 是最省心的场景:用官方 setup action 安装 Earthly,再登录镜像仓库、执行构建即可。一个典型的 .github/workflows/ci.yml 核心步骤如下(假设 Earthfile 中有 +build 目标):

env:
  DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
  DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
  FORCE_COLOR: 1
steps:
  - uses: earthly/actions-setup@v1
    with:
      version: v0.8.0
  - uses: actions/checkout@v4
  - name: Docker Login
    run: docker login --username "$DOCKERHUB_USERNAME" --password "$DOCKERHUB_TOKEN"
  - name: Run build
    run: earthly --ci --push +build

完整示例见 docs/ci-integration/guides/gh-actions-integration.md。两个实用提示:

  • 设置 FORCE_COLOR: 1 保证日志中有可读的彩色输出;
  • 官方示例刻意不使用 actions/checkout 的 ref 参数,因为它会导致重跑旧 commit 时构建结果不一致。

Earthly CI 流水线运行成功界面

GitLab CI/CD 接入教程

GitLab CI 推荐直接基于 earthly/earthly 官方镜像,并搭配 Docker-in-Docker 服务。最小可用的 .gitlab-ci.yml 如下:

services:
  - docker:dind
variables:
  DOCKER_HOST: tcp://docker:2375
  FORCE_COLOR: 1
  EARTHLY_EXEC_CMD: "/bin/sh"
image: earthly/earthly:v0.8.13
before_script:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
earthly:
  stage: build
  script:
    - earthly --ci --push -P +build

几个关键点:

  • EARTHLY_EXEC_CMD=/bin/sh 让镜像的 entrypoint 只负责把 BuildKit 启动起来,再把 shell 交给 GitLab 的 before_script 流程,避免命令被 entrypoint 拦截;
  • 需要私有 registry 镜像加速时,用多行变量 EARTHLY_ADDITIONAL_BUILDKIT_CONFIG 写入 [registry."docker.io"] 的 mirrors 配置。

完整说明见 docs/ci-integration/guides/gitlab-integration.md。

Jenkins 接入教程

Jenkins 分两种部署形态:独立专用 runner(按上面三步走即可)和 Docker Cloud 弹性 runner(需要额外配置)。Docker Cloud 形态下要做的额外工作:

  1. 基于 earthly/earthly 镜像自建 runner 镜像,并打入 Jenkins agent;
  2. 在 runner 模板中勾选 "Expose Docker Host",把 DOCKER_HOST 指向可用的 Docker 守护进程;
  3. 设置 NO_COLOR=1,因为 Jenkins 会把环境误判为终端而输出大量 ANSI 转义码。

配一个 Pipeline 的实际操作如下:

Jenkins CI 集成中创建新项目的 Dashboard 界面

  • 选择 Pipeline 类型并命名(例如 test):

Jenkins 选择 Pipeline 类型创建 Earthly CI 任务

  • 在 Pipeline 区块中选择 "Pipeline script from SCM",SCM 选 Git,填好仓库地址与分支(如 */main):

Jenkins Pipeline 的 SCM 仓库配置界面

  • 保存后回到任务页面点击 Build Now,即可在构建历史中观看 Earthly 构建输出:

Jenkins 构建控制台中的 Earthly 构建过程输出

⚠️ 生产环境注意:Jenkins 示例中 DIND 默认不走 TLS,正式使用应配置 TLS(端口改用 2376)并把证书加入 Jenkins Credentials;若使用外部 earthly-buildkitd,建议采用 mTLS。详见 docs/ci-integration/guides/jenkins.md。

进阶:用远程 BuildKit 让 CI 构建起飞

本地构建的缓存"搬"到 CI 上很慢?Earthly 有个独门绝技——远程 BuildKit:部署一个 earthly/buildkitd 守护进程供所有 CI worker 共享,缓存秒级命中,构建速度相比传统"上传/下载缓存"方案提升明显。要点:

  • 开放 8371-8373 端口,/tmp/earthly 必须挂载为 Docker volume(否则缓存会拖垮磁盘和性能);
  • 客户端通过 buildkit_host 指向远程守护进程,生产环境务必开启 BUILDKIT_TLS_ENABLED 并配置 mTLS 证书。

完整配置见 docs/ci-integration/remote-buildkit.md。

另外,如果你的镜像拉取量大、经常撞 registry 限流,可以搭一个 pull-through cache(拉取穿透缓存)来减少网络流量,方案见 docs/ci-integration/pull-through-cache.md。需要跨平台构建时,先在 runner 上安装 binfmt_misc(qemu-user-static)即可。

常见问题速查

问题 解决办法
日志里全是颜色转义码 设置 NO_COLOR=1(或 FORCE_COLOR=1 强制开启)
启动 buildkitd 报权限错误 确认 CI 环境允许 --privileged 容器
重跑旧 commit 构建结果不一致 checkout 时不要固定 ref 参数
MTU 导致 CI 内网不通 用环境变量 CNI_MTU 显式指定

延伸阅读

登录后查看全文
earthly