在 GitHub Actions 中集成 Earthly:基于 earthly/actions-setup 的 CI 构建实战指南
在 GitHub Actions 中集成 Earthly:基于 earthly/actions-setup 的 CI 构建实战指南
本指南以 Earthly 官方仓库中的 GitHub Actions 集成文档为主体,讲解如何在 GitHub Actions 工作流中运行 Earthly 构建:包括使用 earthly/actions-setup Action 的标准方案、直接下载 Earthly 二进制的备选方案,以及 --ci、--push、FORCE_COLOR 等关键标志的底层原理与最佳实践。读完本文,你将能够把任意带有 +build 目标的 Earthfile 接入 GitHub Actions,实现可重复、可推送产物、支持缓存复用的持续集成流水线。
前提条件:一个可构建的 Earthfile
GitHub Actions 集成示例假设你的仓库根目录已经存在一个 Earthfile,并且其中定义了一个 +build 目标。例如一个最小化的 Earthfile 可以长这样:
# Earthfile
VERSION 0.8
build:
FROM alpine:3.18
RUN echo "hello from earthly" > /out.txt
SAVE ARTIFACT /out.txt AS LOCAL build-output.txt
工作流最终通过 earthly --ci --push +build 触发该目标。如果仓库中还没有 Earthfile,可以先参考 Earthfile 语法文档 或 CI 集成总览 中的示例来创建。
另外需要说明的是,Earthly 的两个软件依赖是 docker 和 git(GitHub Actions 的 ubuntu-latest 镜像已内置),earthly 本身不会为你安装它们,详见 CI 集成总览 的依赖章节。
方案一:使用 earthly/actions-setup Action
官方推荐的接入方式是在工作流中引入 earthly/actions-setup 这个 Action,由它负责安装并引导 Earthly。完整的工作流文件如下(保存为 .github/workflows/ci.yml):
# .github/workflows/ci.yml
name: Earthly +build
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
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
对其中每个环节的解读如下:
- 触发条件:工作流在
main分支的push与pull_request事件时运行,保证每次合并前和合并后都能验证构建结果。 earthly/actions-setup@v1:通过with.version指定要安装的 Earthly 版本(示例中为v0.8.0)。该 Action 内部完成下载、安装以及必要的bootstrap引导(即启动并配置earthly-buildkitd守护进程所需的镜像与配置)。actions/checkout@v4:检出仓库代码。注意它被放在 actions-setup 之后执行,顺序本身并不关键,但两个步骤都必须存在。- Docker Login:当 Earthfile 中的
SAVE IMAGE --push或RUN --push需要推送到 Docker Hub 时,需要先登录。这里的用户名与令牌来自 GitHub Actions Secrets 中的DOCKERHUB_USERNAME和DOCKERHUB_TOKEN。私有仓库或私有镜像源的认证配置可参考 认证指南。 FORCE_COLOR: 1:强制 Earthly 输出 ANSI 彩色日志。在 CI 中 Earthly 有时会误判终端是否存在,FORCE_COLOR=1可强制开启颜色,便于阅读构建日志;反向场景可用NO_COLOR=1强制关闭。Run build:核心构建命令,见下文对--ci与--push的深入解析。
方案二:手动下载 Earthly 二进制
如果你不希望依赖第三方 Action,也可以省略 earthly/actions-setup 步骤,改为在工作流中直接用一行命令下载并安装 Earthly:
# .github/workflows/ci.yml
name: Earthly +build
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
env:
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
FORCE_COLOR: 1
steps:
- uses: actions/checkout@v4
- name: Docker Login
run: docker login --username "$DOCKERHUB_USERNAME" --password "$DOCKERHUB_TOKEN"
- name: Download latest earthly
run: "sudo /bin/sh -c 'wget https://github.com/earthly/earthly/releases/download/v0.8.13/earthly-linux-amd64 -O /usr/local/bin/earthly && chmod +x /usr/local/bin/earthly'"
- name: Run build
run: earthly --ci --push +build
这种方式的本质与 CI 集成总览 中推荐的“直接安装”一致:将 earthly-linux-amd64 下载到 /usr/local/bin/earthly 并赋予可执行权限。需要注意:
- 版本固定:官方文档建议将 Earthly 固定到具体版本(如
v0.8.13),而不是使用“latest”,以避免未来版本变更命令行为导致 CI 不稳定。在专用构建机上,应将安装固化到主机配置中,而不是放在每次构建里重复下载,这样既能加速构建,也能提升稳定性。 - 记得 bootstrap:直接下载安装后,正式构建前应运行
earthly bootstrap完成配置引导(actions-setup 方案会自动处理这一点)。bootstrap 会预拉取earthly-buildkitd相关镜像并生成配置。 - 两个示例的
docker login与FORCE_COLOR配置保持一致,说明这两种接入方式在构建语义上没有区别,只是安装路径不同。
关键构建标志解析:--ci 与 --push
工作流中的核心命令是 earthly --ci --push +build,理解这两个标志是正确使用 GitHub Actions 集成的关键。
--ci:面向 CI 的推荐模式
根据 Earthly 命令参考,在目标(target)模式下,--ci 是以下两个标志的组合别名:
--no-output --strict
--no-output:禁止输出任何镜像或工件。CI 环境中构建产物通常不需要落盘到 runner,因此关闭本地输出可以避免无意义的 I/O。--strict:禁止使用会导致构建不可重复的特性。这保证了 CI 构建的确定性。
从源码也可以印证这一行为:在 cmd/earthly/app/run.go 中,CLI 启动时会处理并过滤 --ci 相关参数;在 cmd/earthly/subcmd/build_cmd.go 中还有一处约束:--ci 标志不能与 --interactive(交互式调试)标志同时使用,因为交互式调试与 CI 的自动化定位相矛盾。此外 --ci 下若确实需要输出产物,可以使用 --output 标志显式放行(见 cmd/earthly/flag/global.go 中对应的 Usage 说明)。
--push:启用推送阶段
默认情况下 Earthly 构建分为 Init、Build、Push(可选,默认关闭)、Local output(可选,默认开启)四个阶段。--push 用于显式开启推送阶段:
- 执行 Earthfile 中
RUN --push标记的命令(如发布 release、部署脚本); - 推送 Earthfile 中
SAVE IMAGE --push标记的镜像到远程 registry; - 只有在构建成功后才执行推送,构建失败不会产生任何推送动作。
在 CI 场景中,把“推送镜像/执行发布操作”与日常开发构建区分开是刻意设计的:本地开发默认不推送,CI 中通过显式传入 --push 才执行这些副作用操作。更多细节可参考 Earthfile 中 SAVE IMAGE 与 RUN --push 的文档。
关于 actions/checkout ref 参数的重要警告
官方文档专门用醒目提示强调了一个容易踩坑的点:示例中刻意没有使用 actions/checkout@v4 的 ref 参数。
原因在于:如果工作流显式指定了 ref(例如固定到某个分支或提交),当用户在 GitHub 上选择“重新运行”一个已经不在分支头部的旧提交时,checkout 仍会检出那个旧提交,导致构建基于过期代码执行,产生不一致的构建结果。不指定 ref、依赖 GitHub Actions 默认检出行为,可以保证每次运行构建的都是当前分支最新代码,从而维持 CI 结果的可重复性与可解释性。
进阶:使用 Satellite 作为 GitHub Actions Runner
官方文档建议优先考虑使用 Satellites 作为 GitHub Actions runners,因为它不需要占用 GitHub Actions 的托管 worker。
该方案的核心思路是:Earthly Satellite 内置了 GitHub Actions runner,可以直接从 GitHub Actions 拉取任务,并且 runner 预装了 Earthly CLI、自动配置为使用卫星的 BuildKit 实例,因此 GitHub Actions 作业与传统的卫星构建共享同一个持久缓存,跨构建的缓存命中率更高。
接入后,你的作业只需通过 runs-on 标签把任务定向到卫星:
earthly-job:
runs-on: [earthly-satellite#<satellite-name>]
env:
FORCE_COLOR: 1
EARTHLY_TOKEN: "${{ secrets.EARTHLY_TOKEN }}"
steps:
- uses: actions/checkout@v2
- name: Earthly build
run: earthly -ci +build
注意此功能在文档中标记为 experimental(实验性),不建议直接用于生产环境,且需要提前在 Earthly 组织内通过 earthly gha add 注册 GitHub 集成、创建带相应 scope 的 GitHub token、并在创建卫星时启用 enable-gha-runner 特性标志。详细步骤请阅读 Satellites as GitHub Actions runners。
进一步阅读
- CI 集成总览:Docker/git 依赖安装、
earthly bootstrap、CNI_MTU等 CI 环境变量、跨平台构建(binfmt_misc)、pull-through cache 等完整主题。 - Earthly 命令参考:
--ci、--push、--secret、--output等全部命令行选项。 - Earthfile 参考:
SAVE IMAGE --push、RUN --push、ARG等 Earthfile 指令详解。 - 其他 CI 系统集成指南:Circle CI、GitLab CI/CD、Jenkins、AWS CodeBuild、Google Cloud Build、Woodpecker CI、Kubernetes 等平台的对应接入文档。