diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000000..bede08f11a --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,253 @@ +# Migrating from `earthly` to EarthBuild + +[`earthly`](https://github.com/earthly/earthly) was originally developed by [Earthly +Technologies](https://earthly.dev) as a corporately-sponsored open-source project. + +In 2025, earthly [announced a pivot to a different business +model](https://web.archive.org/web/20250420142821/https://earthly.dev/blog/shutting-down-earthfiles-cloud/), +no longer maintaining `earthly` to focus on entirely different products and directions. + +In response, the community has forked the project under the name `EarthBuild` to continue its development and maintenance. + +## What to Expect from EarthBuild + + + +EarthBuild is a community-driven project. This means development is no longer backed by a single corporation but by a collective of users and contributors. + +- **Stability**: The immediate goal of EarthBuild is to provide a secure, stable & reliable build tool for the community. +- **Open Governance**: The project aims for an open and transparent governance model. +- **Community Support**: Support is available through community channels. + +## Key Changes + +The most significant change is the removal of all features related to Earthly's commercial cloud offering. +EarthBuild focuses on being a great, self-hosted build tool. + +Features related to the cloud-hosted earthly commercial offering were removed in the [final release of earthly +`v0.8.16`](https://github.com/earthly/earthly/releases/tag/v0.8.16) and will never be present in EarthBuild +releases. + +We will maintain compatibility while logging warnings for other, more invasive, changes for releases of +EarthBuild on the `v0.8.x` minor version. + +We will publish a breaking change to these features in the first unique minor version for EarthBuild, `v0.9.x`. + +These changes include renaming of configuration variables from `EARTHLY_*` to `EARTHBUILD_*`, removal of Earthfile syntax related to cloud +hosting like `PROJECT` and naming of built-in arguments like `ARG EARTHLY_GIT_PROJECT_NAME` to `ARG EARTHBUILD_GIT_PROJECT_NAME`. + +### Binary Name Change + +The command-line tool has been renamed from `earthly` to `earth`. You will need to update your scripts, CI configurations, and any local aliases. + +```diff +- earthly +all ++ earth +all +``` + +In the `earthlybuild/actions-setup` github action, we've aliased `earthly` to `earth`, logging the deprecated +usage, to ease the switch. + +In version `v0.9.0` we will release a breaking change that removes the alias. + +As of that version, you must update your CI configuration to use `earth` instead of `earthly` to reference the +CLI binary. + +We recommend using this period of overlap to update your CI configuration in preparation of the release. + +### Installation + +To switch to EarthBuild, you will need to use the new installation scripts. + + + + +```bash +# Example of a potential new installation command +/bin/bash -c "$(curl -fsSL https://.../install.sh)" +``` + +- Mac - Brew +- Nix? +- WSL? + +You should remove the old `earthly` binary from your systems to avoid confusion. + +## Removed Features and Alternatives + +The following commands and flags, mostly related to Earthly Cloud, have been removed. + +### Removed Commands + +| Command(s) | Description | Alternative / Migration Path | +| ------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `account` | Managed Earthly accounts. | Not applicable. EarthBuild does not have a concept of user accounts. | +| `org`, `orgs` | Managed Earthly organizations. | Not applicable. | +| `project`, `projects` | Managed Earthly projects. | Not applicable. | +| `satellite`, `satellites` | Managed remote runners (Buildkitd instances). | You can run your own Buildkitd instances on any infrastructure and connect to them using `earth --buildkit-host `. See [remote buildkit documentation](docs/ci-integration/remote-buildkit.md). | +| `cloud`, `clouds` | Configured Cloud Installations for BYOC plans. | See `satellite` alternative. | +| `secret`, `secrets` | Managed cloud secrets. | Use standard environment variables, `--secret` flags with local files (`--secret-file-path`), or integrate with your own secret management solution (e.g., HashiCorp Vault, AWS Secrets Manager) within your Earthfiles. | +| `web` | Opened the Earthly Cloud web UI. | Not applicable. | +| `billing` | Viewed Earthly billing information. | Not applicable. | +| `gha` | Managed GitHub Actions integrations. | The core GitHub Actions integration remains. See the CI section below. This command was for a specific, now-removed, part of that integration. | +| `prune-auto-skip` | Pruned auto-skip data. | The auto-skip feature has been removed, so this command is no longer needed. | + +### Removed & Changed CLI Options + +- `--satellite`, `--sat`, `--no-satellite`, `--no-sat`: Removed. Use `--buildkit-host` (or configuration) explicitly to connect to a remote Buildkitd instance. +- `--auto-skip`, `--no-auto-skip`: The `auto-skip` feature, which depended on Earthly's cloud services, has + been removed. If you are interested in this feature being restored in the community edition see +- `--auth-token`: This flag has been removed since it was used for authenticating with Earthly Cloud. For registry authentication, use standard Docker authentication methods. +- The binary name in help texts and other places is now `earth` instead of `earthly`. + +### Environment Variable Changes + +All `EARTHLY_*` environment variables have been renamed to `EARTHBUILD_*` to reflect the project's new identity. The following environment variables are affected: + +#### Removed Environment Variables + +The following environment variables have been removed along with their associated features: + +- `EARTHLY_TOKEN` - Used for Earthly Cloud authentication +- `EARTHLY_AUTO_SKIP` - Controlled auto-skip functionality +- `EARTHLY_NO_AUTO_SKIP` - Disabled auto-skip functionality +- `EARTHLY_SATELLITE` - Selected satellite for builds +- `EARTHLY_NO_SATELLITE` - Disabled satellite usage + +#### Migration Strategy + +**Immediate:** EarthBuild will continue to recognize `EARTHLY_*` environment variables in the current version but will log deprecation warnings encouraging migration to `EARTHBUILD_*` variables. + +**Future Breaking Change:** In version `vX.X.X`, support for `EARTHLY_*` environment variables will be removed entirely. You must update your environment configurations before upgrading to that version. + +**Standard Variables Unchanged:** Some environment variables remain unchanged as they follow standard +conventions: + +- `DO_NOT_TRACK` - Standard analytics opt-out variable +- `GIT_USERNAME` - Git authentication username +- `GIT_PASSWORD` - Git authentication password +- `GITHUB_ACTIONS` - GitHub Actions environment detection + +--- + +## Detailed CLI Diff + +Here is a `diff` of the CLI help output to highlight the changes. + +```diff +NAME: +- earthly - The CI/CD framework that runs anywhere! ++ earth - The CI/CD framework that runs anywhere! + +USAGE: +- earthly [options] ++ earth [options] +- earthly [options] --image ++ earth [options] --image +- earthly [options] --artifact / [] ++ earth [options] --artifact / [] +- earthly [options] command [command options] ++ earth [options] command [command options] + + +COMMANDS: + bootstrap Bootstraps installation including buildkit image download and optionally shell autocompletion + docker-build *beta* Build a Dockerfile without an Earthfile +- account Create or manage an Earthly account + config Edits your configuration file + doc Document targets from an Earthfile + init *experimental* Initialize an Earthfile for the current project + ls List targets from an Earthfile +- org, orgs Create or manage your Earthly orgs +- project, projects Manage Earthly projects + prune Prune build cache +- prune-auto-skip Prune Earthly auto-skip data + registry, registries *beta* Manage registry access +- satellite, satellites, sat Create and manage Earthly Satellites +- cloud, clouds Configure Cloud Installations for BYOC plans +- secret, secrets *beta* Manage cloud secrets +- web *beta* Access the web UI via your default browser and print the url +- billing, bill *experimental* View Earthly billing info +- gha *experimental* Manage GitHub Actions integrations + help, h Shows a list of commands or help for one command + +GLOBAL OPTIONS: + --config value Path to config file [$EARTHBUILD_CONFIG] + --ssh-auth-sock value The SSH auth socket to use for ssh-agent forwarding (default: "/private/tmp/com.apple.launchd.ZviWbhl8ar/Listeners") [$EARTHBUILD_SSH_AUTH_SOCK] + --git-username value The git username to use for git HTTPS authentication [$GIT_USERNAME] + --git-password value The git password to use for git HTTPS authentication [$GIT_PASSWORD] + --verbose, -V Enable verbose logging (default: false) [$EARTHBUILD_VERBOSE] + --buildkit-host value The URL to use for connecting to a buildkit host + If empty, earthly will attempt to start a buildkitd instance via docker run [$EARTHBUILD_BUILDKIT_HOST] + Disable collection of analytics (default: false) [$EARTHBUILD_DISABLE_ANALYTICS, $DO_NOT_TRACK] + --env-file-path value Use values from this file as earthly environment variables; values are no longer used as --build-arg's or --secret's (default: ".env") [$EARTHBUILD_ENV_FILE_PATH] + --arg-file-path value Use values from this file as earthly buildargs (default: ".arg") [$EARTHBUILD_ARG_FILE_PATH] + --secret-file-path value Use values from this file as earthly secrets (default: ".secret") [$EARTHBUILD_SECRET_FILE_PATH] + --artifact, -a Output specified artifact; a wildcard (*) can be used to output all artifacts (default: false) + --image Output only docker image of the specified target (default: false) + --push Push docker images and execute RUN --push commands (default: false) [$EARTHBUILD_PUSH] + --ci Execute in CI mode. + Implies --no-output --strict (default: false) [$EARTHBUILD_CI] + --output Allow artifacts or images to be output, even when running under --ci mode (default: false) [$EARTHBUILD_OUTPUT] + --no-output Do not output artifacts or images + (using --push is still allowed) (default: false) [$EARTHBUILD_NO_OUTPUT] + --no-cache Do not use cache while building (default: false) [$EARTHBUILD_NO_CACHE] + --allow-privileged, -P Allow build to use the --privileged flag in RUN commands (default: false) [$EARTHBUILD_ALLOW_PRIVILEGED] + --max-remote-cache Saves all intermediate images too in the remote cache (default: false) [$EARTHBUILD_MAX_REMOTE_CACHE] + --save-inline-cache Enable cache inlining when pushing images (default: false) [$EARTHBUILD_SAVE_INLINE_CACHE] + --use-inline-cache Attempt to use any inline cache that may have been previously pushed + uses image tags referenced by SAVE IMAGE --push or SAVE IMAGE --cache-from (default: false) [$EARTHBUILD_USE_INLINE_CACHE] + --interactive, -i Enable interactive debugging (default: false) [$EARTHBUILD_INTERACTIVE] + --strict Disallow usage of features that may create unrepeatable builds (default: false) [$EARTHBUILD_STRICT] + --buildkit-image value The docker image to use for the buildkit daemon (default: "docker.io/earthly/buildkitd:v0.8.15") [$EARTHBUILD_BUILDKIT_IMAGE] + --remote-cache value A remote docker image tag use as explicit cache and optionally additional attributes to set in the image (Format: "[,=,=,...]") [$EARTHBUILD_REMOTE_CACHE] + --disable-remote-registry-proxy Don't use the Docker registry proxy when transferring images (default: false) [$EARTHBUILD_DISABLE_REMOTE_REGISTRY_PROXY] + --github-annotations Enable GitHub Actions workflow specific output. When enabled, errors and warnings are reported as annotations in GitHub. (default: false) [$GITHUB_ACTIONS] + --help, -h show help + --version, -v print the version +``` + +## Syntax + +The core syntax of Earthfiles is largely unchanged. + +Again, this will be logged as a warning in `v0.8.x` and removed, treated as an error, in `v0.9.x`. + +The exception here is that the `PROJECT` command is removed entirely since it related to the cloud offering. + +Built-in arguments are renamed from `ARG EARTHLY_*` to `ARG EARTHBUILD_*`. + +## CI + +### GitHub Actions + +If you use the github actions CI integration (formerly +[`github.com/earthly/actions-setup`](github.com/earthly/actions-setup)), you should update your workflow yaml to +point to [`github.com/earthbuild/actions-setup`](github.com/earthbuild/actions-setup) instead. + +```diff + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Setup Earthly +- uses: earthly/actions-setup@main ++ uses: earthbuild/actions-setup@main + with: +- earthly-version: v0.8.5 # example ++ version: v0.9.0 # example, use the latest earthbuild version + - name: Run build +- run: earthly --ci +all ++ run: earth --ci +all +``` + +## Hint 🤖 + +It's 2025. +Provide this document to your agent of choice to pick up the heavy lifting at your org. + +