Earthly CI/CD集成指南:快速接入GitHub Actions、GitLab CI、Jenkins的完整方案
Earthly CI/CD集成指南:快速接入GitHub Actions、GitLab CI、Jenkins的完整方案
Earthly 是一个像 Dockerfile 和 Makefile 混血儿一样简单的构建框架,它以"快速、可重复构建"著称。把 Earthly 接入 CI/CD 比想象中简单得多:无论你的团队使用 GitHub Actions、GitLab CI 还是 Jenkins,只需完成安装依赖、安装 Earthly、配置三项基础设置,就能在几分钟内跑通第一条流水线。本文用尽量少的代码,带你一次配好三大主流 CI 系统,并附上远程 BuildKit 提速等进阶技巧。
上图展示了接入 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 时构建结果不一致。
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 形态下要做的额外工作:
- 基于
earthly/earthly镜像自建 runner 镜像,并打入 Jenkins agent; - 在 runner 模板中勾选 "Expose Docker Host",把
DOCKER_HOST指向可用的 Docker 守护进程; - 设置
NO_COLOR=1,因为 Jenkins 会把环境误判为终端而输出大量 ANSI 转义码。
配一个 Pipeline 的实际操作如下:
- 选择 Pipeline 类型并命名(例如
test):
- 在 Pipeline 区块中选择 "Pipeline script from SCM",SCM 选 Git,填好仓库地址与分支(如
*/main):
- 保存后回到任务页面点击 Build Now,即可在构建历史中观看 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 显式指定 |
延伸阅读
- CI 集成总览:docs/ci-integration/overview.md
- 构建自定义 CI 镜像:docs/ci-integration/use-earthly-ci-image.md
- Earthfile 语法:docs/earthfile/earthfile.md
- Earthly 配置参考:docs/earthly-config/earthly-config.md





