在 GitHub Actions 中集成 Earthly:基于 earthly/actions-setup 的 CI 构建实战指南

原创2026-09-22 23:41:031,851 阅读
文章标签:CI/CDDevOps构建工具

在 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 等平台的对应接入文档。
登录后查看全文
earthly