From 5b1ff3e29dfc143c800a9b195b6ddf1550884a6f Mon Sep 17 00:00:00 2001 From: Kieran Mann Date: Fri, 20 Jun 2025 14:42:56 -0700 Subject: [PATCH 01/10] start on a migration doc. TODO: skeleton the full document --- MIGRATION.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 MIGRATION.md diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000000..26e37bcc45 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,132 @@ +# 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. + +## Features removed + +In earthly's original monitization model, they offered managed hosting of `earthly/buildkitd` instances +through their "satellite" product. + +This included clouds, accounts, billing, cloud secret management and "value add" features like "auto skip." + +In the community fork of earthly, no monetization is attempted; therefore these features no longer make sense +and have been removed from the earthly CLI binary. + +### CLI Commands + +```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 earthly 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 Earthly 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 Earthly 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 [$EARTHLY_CONFIG] + --ssh-auth-sock value The SSH auth socket to use for ssh-agent forwarding (default: "/private/tmp/com.apple.launchd.ZviWbhl8ar/Listeners") [$EARTHLY_SSH_AUTH_SOCK] + --auth-token value Force Earthly account login to authenticate with supplied token [$EARTHLY_TOKEN] + --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) [$EARTHLY_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 [$EARTHLY_BUILDKIT_HOST] + Disable collection of analytics (default: false) [$EARTHLY_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") [$EARTHLY_ENV_FILE_PATH] + --arg-file-path value Use values from this file as earthly buildargs (default: ".arg") [$EARTHLY_ARG_FILE_PATH] + --secret-file-path value Use values from this file as earthly secrets (default: ".secret") [$EARTHLY_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) [$EARTHLY_PUSH] + --ci Execute in CI mode. + Implies --no-output --strict (default: false) [$EARTHLY_CI] + --output Allow artifacts or images to be output, even when running under --ci mode (default: false) [$EARTHLY_OUTPUT] + --no-output Do not output artifacts or images + (using --push is still allowed) (default: false) [$EARTHLY_NO_OUTPUT] + --no-cache Do not use cache while building (default: false) [$EARTHLY_NO_CACHE] + --auto-skip Skip buildkit if target has already been built (default: false) [$EARTHLY_AUTO_SKIP] + --allow-privileged, -P Allow build to use the --privileged flag in RUN commands (default: false) [$EARTHLY_ALLOW_PRIVILEGED] + --max-remote-cache Saves all intermediate images too in the remote cache (default: false) [$EARTHLY_MAX_REMOTE_CACHE] + --save-inline-cache Enable cache inlining when pushing images (default: false) [$EARTHLY_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) [$EARTHLY_USE_INLINE_CACHE] + --interactive, -i Enable interactive debugging (default: false) [$EARTHLY_INTERACTIVE] + --strict Disallow usage of features that may create unrepeatable builds (default: false) [$EARTHLY_STRICT] +- --satellite value, --sat value The name of satellite to use for this build. [$EARTHLY_SATELLITE] + --no-satellite, --no-sat Disables the use of a selected satellite for this build. (default: false) [$EARTHLY_NO_SATELLITE] + --buildkit-image value The docker image to use for the buildkit daemon (default: "docker.io/earthly/buildkitd:v0.8.15") [$EARTHLY_BUILDKIT_IMAGE] + --remote-cache value A remote docker image tag use as explicit cache and optionally additional attributes to set in the image (Format: "[,=,=,...]") [$EARTHLY_REMOTE_CACHE] + --disable-remote-registry-proxy Don't use the Docker registry proxy when transferring images (default: false) [$EARTHLY_DISABLE_REMOTE_REGISTRY_PROXY] +- --no-auto-skip Disable auto-skip functionality (default: false) [$EARTHLY_NO_AUTO_SKIP] + --github-annotations Enable Git Hub Actions workflow specific output (default: false) [$GITHUB_ACTIONS] + --help, -h show help + --version, -v print the version +``` + +TODO: + +- `--no-satellite` Is there an equivalent? +- what is `--github-annotations`? + +Commands removed + +- Billing +- + +### CLI Options + +- Autoskip TODO: add a link to a ticket to bring this back + +## 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 + - name: Run build + run: earthly --ci +all +``` From 10d49bfabe6c0aced37ea62af0c5c55e2c150cb1 Mon Sep 17 00:00:00 2001 From: Kieran Mann Date: Fri, 20 Jun 2025 15:13:40 -0700 Subject: [PATCH 02/10] Work on migration doc. TODO: provide actual links to buildkitd hosting instructions --- MIGRATION.md | 122 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 93 insertions(+), 29 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 26e37bcc45..341b123e20 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -7,17 +7,80 @@ 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. -## Features removed +In response, the community has forked the project under the name `EarthBuild` to continue its development and maintenance. -In earthly's original monitization model, they offered managed hosting of `earthly/buildkitd` instances -through their "satellite" product. +## What to Expect from EarthBuild -This included clouds, accounts, billing, cloud secret management and "value add" features like "auto skip." + +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. -In the community fork of earthly, no monetization is attempted; therefore these features no longer make sense -and have been removed from the earthly CLI binary. +- **Stability**: The immediate goal of EarthBuild is to provide a 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. -### CLI Commands +## 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. + +### 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 CI + +### 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)" +``` + +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 runners documentation](remote-runners.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 https://github.com/EarthBuild/earthbuild/issues/3 +- `--auth-token`: This flag is now only used for authenticating with registries, not Earthly Cloud. +- The binary name in help texts and other places is now `earth` instead of `earthly`. + +--- + +## Detailed CLI Diff + +Here is a `diff` of the CLI help output to highlight the changes. ```diff NAME: @@ -36,16 +99,16 @@ USAGE: COMMANDS: - bootstrap Bootstraps earthly installation including buildkit image download and optionally shell autocompletion + 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 Earthly configuration file + 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 Earthly build cache + 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 @@ -59,7 +122,7 @@ COMMANDS: GLOBAL OPTIONS: --config value Path to config file [$EARTHLY_CONFIG] --ssh-auth-sock value The SSH auth socket to use for ssh-agent forwarding (default: "/private/tmp/com.apple.launchd.ZviWbhl8ar/Listeners") [$EARTHLY_SSH_AUTH_SOCK] - --auth-token value Force Earthly account login to authenticate with supplied token [$EARTHLY_TOKEN] +- --auth-token value Force Earthly account login to authenticate with supplied token [$EARTHLY_TOKEN] --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) [$EARTHLY_VERBOSE] @@ -78,7 +141,7 @@ GLOBAL OPTIONS: --no-output Do not output artifacts or images (using --push is still allowed) (default: false) [$EARTHLY_NO_OUTPUT] --no-cache Do not use cache while building (default: false) [$EARTHLY_NO_CACHE] - --auto-skip Skip buildkit if target has already been built (default: false) [$EARTHLY_AUTO_SKIP] +- --auto-skip Skip buildkit if target has already been built (default: false) [$EARTHLY_AUTO_SKIP] --allow-privileged, -P Allow build to use the --privileged flag in RUN commands (default: false) [$EARTHLY_ALLOW_PRIVILEGED] --max-remote-cache Saves all intermediate images too in the remote cache (default: false) [$EARTHLY_MAX_REMOTE_CACHE] --save-inline-cache Enable cache inlining when pushing images (default: false) [$EARTHLY_SAVE_INLINE_CACHE] @@ -87,30 +150,16 @@ GLOBAL OPTIONS: --interactive, -i Enable interactive debugging (default: false) [$EARTHLY_INTERACTIVE] --strict Disallow usage of features that may create unrepeatable builds (default: false) [$EARTHLY_STRICT] - --satellite value, --sat value The name of satellite to use for this build. [$EARTHLY_SATELLITE] - --no-satellite, --no-sat Disables the use of a selected satellite for this build. (default: false) [$EARTHLY_NO_SATELLITE] +- --no-satellite, --no-sat Disables the use of a selected satellite for this build. (default: false) [$EARTHLY_NO_SATELLITE] --buildkit-image value The docker image to use for the buildkit daemon (default: "docker.io/earthly/buildkitd:v0.8.15") [$EARTHLY_BUILDKIT_IMAGE] --remote-cache value A remote docker image tag use as explicit cache and optionally additional attributes to set in the image (Format: "[,=,=,...]") [$EARTHLY_REMOTE_CACHE] --disable-remote-registry-proxy Don't use the Docker registry proxy when transferring images (default: false) [$EARTHLY_DISABLE_REMOTE_REGISTRY_PROXY] - --no-auto-skip Disable auto-skip functionality (default: false) [$EARTHLY_NO_AUTO_SKIP] - --github-annotations Enable Git Hub Actions workflow specific output (default: false) [$GITHUB_ACTIONS] + --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 ``` -TODO: - -- `--no-satellite` Is there an equivalent? -- what is `--github-annotations`? - -Commands removed - -- Billing -- - -### CLI Options - -- Autoskip TODO: add a link to a ticket to bring this back - ## CI ### GitHub Actions @@ -127,6 +176,21 @@ point to [`github.com/earthbuild/actions-setup`](github.com/earthbuild/actions-s - 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: earthly --ci +all ++ run: earth --ci +all ``` + + +The `--github-annotations` flag or the `GITHUB_ACTIONS=true` environment variable can be used to enable more detailed output for GitHub Actions, including annotations for errors and warnings directly in your workflow runs. + + +## Hint 🤖 + +It's 2025. +Provide this document to your agent of choice to pick up the heavy lifting at your org. + + \ No newline at end of file From 2bfdb357b420e5d3f45b4d70f808676a1bebf079 Mon Sep 17 00:00:00 2001 From: Kieran Mann Date: Tue, 1 Jul 2025 11:04:22 -0700 Subject: [PATCH 03/10] small updates to migration doc after last meeting --- MIGRATION.md | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 341b123e20..fd73861c92 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -35,18 +35,30 @@ The command-line tool has been renamed from `earthly` to `earth`. You will need + earth +all ``` -In CI +In the `earthlybuild/actions-setup` github action, we've aliased `earthly` to `earth`, logging the deprecated +usage, to ease the switch. + + +In version `vX.X.X` 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 @@ -160,6 +172,12 @@ GLOBAL OPTIONS: --version, -v print the version ``` +## Syntax + + + + + ## CI ### GitHub Actions @@ -185,7 +203,15 @@ point to [`github.com/earthbuild/actions-setup`](github.com/earthbuild/actions-s ``` -The `--github-annotations` flag or the `GITHUB_ACTIONS=true` environment variable can be used to enable more detailed output for GitHub Actions, including annotations for errors and warnings directly in your workflow runs. +The `--github-annotations` flag or the `GITHUB_ACTIONS=true` environment variable can be used to enable more +detailed output for GitHub Actions, including annotations for errors and warnings directly in your workflow +runs. + +## Syntax + +Largely unchanged + +Note things we'll depreacte in `v0.9` ## Hint 🤖 @@ -193,4 +219,4 @@ The `--github-annotations` flag or the `GITHUB_ACTIONS=true` environment variabl It's 2025. Provide this document to your agent of choice to pick up the heavy lifting at your org. - \ No newline at end of file + \ No newline at end of file From 5bc42451e95d6f2a26b47700e56a55dab758485a Mon Sep 17 00:00:00 2001 From: Kieran Mann Date: Tue, 22 Jul 2025 10:59:55 -0700 Subject: [PATCH 04/10] Fix typo Co-authored-by: Mariappan Ramasamy <142216110+kp-mariappan-ramasamy@users.noreply.github.com> --- MIGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index fd73861c92..5d6f3d03ce 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -211,7 +211,7 @@ runs. Largely unchanged -Note things we'll depreacte in `v0.9` +Note things we'll deprecate in `v0.9` ## Hint 🤖 From 91176bc905381b09bc9b03a53d8802ffd4b01cba Mon Sep 17 00:00:00 2001 From: Kieran Mann Date: Tue, 22 Jul 2025 11:00:04 -0700 Subject: [PATCH 05/10] Improve wording Co-authored-by: Squirrel --- MIGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index 5d6f3d03ce..4922d2bb85 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -18,7 +18,7 @@ In response, the community has forked the project under the name `EarthBuild` to --> 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 stable, reliable build tool for the community. +- **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. From e3b9a1749db2a4460101fcd03eb2b96592592c9f Mon Sep 17 00:00:00 2001 From: Kieran Mann Date: Tue, 22 Jul 2025 11:14:48 -0700 Subject: [PATCH 06/10] work on finalizing migration doc: specify changes to env variables --- MIGRATION.md | 94 +++++++++++++++++++++++++++++++--------------------- 1 file changed, 57 insertions(+), 37 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 4922d2bb85..58aadc08f9 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -39,7 +39,7 @@ In the `earthlybuild/actions-setup` github action, we've aliased `earthly` to `e usage, to ease the switch. -In version `vX.X.X` we will release a breaking change that removes the alias. +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. @@ -84,10 +84,38 @@ The following commands and flags, mostly related to Earthly Cloud, have been rem - `--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 https://github.com/EarthBuild/earthbuild/issues/3 -- `--auth-token`: This flag is now only used for authenticating with registries, not Earthly Cloud. + 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 @@ -132,41 +160,36 @@ COMMANDS: help, h Shows a list of commands or help for one command GLOBAL OPTIONS: - --config value Path to config file [$EARTHLY_CONFIG] - --ssh-auth-sock value The SSH auth socket to use for ssh-agent forwarding (default: "/private/tmp/com.apple.launchd.ZviWbhl8ar/Listeners") [$EARTHLY_SSH_AUTH_SOCK] -- --auth-token value Force Earthly account login to authenticate with supplied token [$EARTHLY_TOKEN] + --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) [$EARTHLY_VERBOSE] + --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 [$EARTHLY_BUILDKIT_HOST] - Disable collection of analytics (default: false) [$EARTHLY_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") [$EARTHLY_ENV_FILE_PATH] - --arg-file-path value Use values from this file as earthly buildargs (default: ".arg") [$EARTHLY_ARG_FILE_PATH] - --secret-file-path value Use values from this file as earthly secrets (default: ".secret") [$EARTHLY_SECRET_FILE_PATH] + 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) [$EARTHLY_PUSH] + --push Push docker images and execute RUN --push commands (default: false) [$EARTHBUILD_PUSH] --ci Execute in CI mode. - Implies --no-output --strict (default: false) [$EARTHLY_CI] - --output Allow artifacts or images to be output, even when running under --ci mode (default: false) [$EARTHLY_OUTPUT] + 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) [$EARTHLY_NO_OUTPUT] - --no-cache Do not use cache while building (default: false) [$EARTHLY_NO_CACHE] -- --auto-skip Skip buildkit if target has already been built (default: false) [$EARTHLY_AUTO_SKIP] - --allow-privileged, -P Allow build to use the --privileged flag in RUN commands (default: false) [$EARTHLY_ALLOW_PRIVILEGED] - --max-remote-cache Saves all intermediate images too in the remote cache (default: false) [$EARTHLY_MAX_REMOTE_CACHE] - --save-inline-cache Enable cache inlining when pushing images (default: false) [$EARTHLY_SAVE_INLINE_CACHE] + (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) [$EARTHLY_USE_INLINE_CACHE] - --interactive, -i Enable interactive debugging (default: false) [$EARTHLY_INTERACTIVE] - --strict Disallow usage of features that may create unrepeatable builds (default: false) [$EARTHLY_STRICT] -- --satellite value, --sat value The name of satellite to use for this build. [$EARTHLY_SATELLITE] -- --no-satellite, --no-sat Disables the use of a selected satellite for this build. (default: false) [$EARTHLY_NO_SATELLITE] - --buildkit-image value The docker image to use for the buildkit daemon (default: "docker.io/earthly/buildkitd:v0.8.15") [$EARTHLY_BUILDKIT_IMAGE] - --remote-cache value A remote docker image tag use as explicit cache and optionally additional attributes to set in the image (Format: "[,=,=,...]") [$EARTHLY_REMOTE_CACHE] - --disable-remote-registry-proxy Don't use the Docker registry proxy when transferring images (default: false) [$EARTHLY_DISABLE_REMOTE_REGISTRY_PROXY] -- --no-auto-skip Disable auto-skip functionality (default: false) [$EARTHLY_NO_AUTO_SKIP] + 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 @@ -174,6 +197,10 @@ GLOBAL OPTIONS: ## Syntax +Largely unchanged + +Note things we'll deprecate in `v0.9` + @@ -207,13 +234,6 @@ The `--github-annotations` flag or the `GITHUB_ACTIONS=true` environment variabl detailed output for GitHub Actions, including annotations for errors and warnings directly in your workflow runs. -## Syntax - -Largely unchanged - -Note things we'll deprecate in `v0.9` - - ## Hint 🤖 It's 2025. From ac0d682345cbcc74c97b7fa7ec756d40e6a57195 Mon Sep 17 00:00:00 2001 From: Kieran Mann Date: Tue, 22 Jul 2025 11:31:55 -0700 Subject: [PATCH 07/10] action more easy todos --- MIGRATION.md | 67 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 39 insertions(+), 28 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 58aadc08f9..bede08f11a 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -11,11 +11,12 @@ In response, the community has forked the project under the name `EarthBuild` to ## 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. @@ -24,7 +25,20 @@ EarthBuild is a community-driven project. This means development is no longer ba ## 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. +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 @@ -38,10 +52,11 @@ The command-line tool has been renamed from `earthly` to `earth`. You will need 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 @@ -50,6 +65,7 @@ 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)" @@ -67,18 +83,18 @@ The following commands and flags, mostly related to Earthly Cloud, have been rem ### 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 runners documentation](remote-runners.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. | +| 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 @@ -97,7 +113,7 @@ All `EARTHLY_*` environment variables have been renamed to `EARTHBUILD_*` to ref 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_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 @@ -113,7 +129,7 @@ conventions: - `DO_NOT_TRACK` - Standard analytics opt-out variable - `GIT_USERNAME` - Git authentication username -- `GIT_PASSWORD` - Git authentication password +- `GIT_PASSWORD` - Git authentication password - `GITHUB_ACTIONS` - GitHub Actions environment detection --- @@ -197,13 +213,13 @@ GLOBAL OPTIONS: ## Syntax -Largely unchanged +The core syntax of Earthfiles is largely unchanged. -Note things we'll deprecate in `v0.9` +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 @@ -229,14 +245,9 @@ point to [`github.com/earthbuild/actions-setup`](github.com/earthbuild/actions-s + run: earth --ci +all ``` - -The `--github-annotations` flag or the `GITHUB_ACTIONS=true` environment variable can be used to enable more -detailed output for GitHub Actions, including annotations for errors and warnings directly in your workflow -runs. - ## Hint 🤖 It's 2025. Provide this document to your agent of choice to pick up the heavy lifting at your org. - \ No newline at end of file + From 69b2de01d013d3aac1c9b67394690ec76f7a20b0 Mon Sep 17 00:00:00 2001 From: Kieran Mann Date: Wed, 18 Feb 2026 08:44:23 -0800 Subject: [PATCH 08/10] apply Janis review: centralize on EARTH_ naming --- MIGRATION.md | 54 ++++++++++++++++++++++++++-------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index bede08f11a..c49d43f208 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -37,8 +37,8 @@ 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`. +These changes include renaming of configuration variables from `EARTHLY_*` to `EARTH_*`, removal of Earthfile syntax related to cloud +hosting like `PROJECT` and naming of built-in arguments like `ARG EARTHLY_GIT_PROJECT_NAME` to `ARG EARTH_GIT_PROJECT_NAME`. ### Binary Name Change @@ -106,7 +106,7 @@ The following commands and flags, mostly related to Earthly Cloud, have been rem ### 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: +All `EARTHLY_*` environment variables have been renamed to `EARTH_*` to reflect the project's new identity. The following environment variables are affected: #### Removed Environment Variables @@ -120,7 +120,7 @@ The following environment variables have been removed along with their associate #### 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. +**Immediate:** EarthBuild will continue to recognize `EARTHLY_*` environment variables in the current version but will log deprecation warnings encouraging migration to `EARTH_*` 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. @@ -176,36 +176,36 @@ COMMANDS: 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] + --config value Path to config file [$EARTH_CONFIG] + --ssh-auth-sock value The SSH auth socket to use for ssh-agent forwarding (default: "/private/tmp/com.apple.launchd.ZviWbhl8ar/Listeners") [$EARTH_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] + --verbose, -V Enable verbose logging (default: false) [$EARTH_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] + If empty, earthly will attempt to start a buildkitd instance via docker run [$EARTH_BUILDKIT_HOST] + Disable collection of analytics (default: false) [$EARTH_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") [$EARTH_ENV_FILE_PATH] + --arg-file-path value Use values from this file as earthly buildargs (default: ".arg") [$EARTH_ARG_FILE_PATH] + --secret-file-path value Use values from this file as earthly secrets (default: ".secret") [$EARTH_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] + --push Push docker images and execute RUN --push commands (default: false) [$EARTH_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] + Implies --no-output --strict (default: false) [$EARTH_CI] + --output Allow artifacts or images to be output, even when running under --ci mode (default: false) [$EARTH_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] + (using --push is still allowed) (default: false) [$EARTH_NO_OUTPUT] + --no-cache Do not use cache while building (default: false) [$EARTH_NO_CACHE] + --allow-privileged, -P Allow build to use the --privileged flag in RUN commands (default: false) [$EARTH_ALLOW_PRIVILEGED] + --max-remote-cache Saves all intermediate images too in the remote cache (default: false) [$EARTH_MAX_REMOTE_CACHE] + --save-inline-cache Enable cache inlining when pushing images (default: false) [$EARTH_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] + uses image tags referenced by SAVE IMAGE --push or SAVE IMAGE --cache-from (default: false) [$EARTH_USE_INLINE_CACHE] + --interactive, -i Enable interactive debugging (default: false) [$EARTH_INTERACTIVE] + --strict Disallow usage of features that may create unrepeatable builds (default: false) [$EARTH_STRICT] + --buildkit-image value The docker image to use for the buildkit daemon (default: "docker.io/earthly/buildkitd:v0.8.15") [$EARTH_BUILDKIT_IMAGE] + --remote-cache value A remote docker image tag use as explicit cache and optionally additional attributes to set in the image (Format: "[,=,=,...]") [$EARTH_REMOTE_CACHE] + --disable-remote-registry-proxy Don't use the Docker registry proxy when transferring images (default: false) [$EARTH_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 @@ -219,7 +219,7 @@ Again, this will be logged as a warning in `v0.8.x` and removed, treated as an e 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_*`. +Built-in arguments are renamed from `ARG EARTHLY_*` to `ARG EARTH_*`. ## CI From 64b70a139089ed645275b2b51853ddffe3cf6b4c Mon Sep 17 00:00:00 2001 From: Kieran Mann Date: Wed, 18 Feb 2026 08:47:22 -0800 Subject: [PATCH 09/10] a few manual edits. TODO: make decision re: logging warnings/supporting EARTH_* variants --- MIGRATION.md | 21 ++++----------------- 1 file changed, 4 insertions(+), 17 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index c49d43f208..a8e8d1b34d 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -61,19 +61,7 @@ We recommend using this period of overlap to update your CI configuration in pre ### 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? +To switch to EarthBuild, you will need to use [the new installation scripts](https://www.earthbuild.dev/install.html). You should remove the old `earthly` binary from your systems to avoid confusion. @@ -122,10 +110,9 @@ The following environment variables have been removed along with their associate **Immediate:** EarthBuild will continue to recognize `EARTHLY_*` environment variables in the current version but will log deprecation warnings encouraging migration to `EARTH_*` 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. +**Future Breaking Change:** In version `v0.9.0` and onwards, 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: +**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 @@ -250,4 +237,4 @@ point to [`github.com/earthbuild/actions-setup`](github.com/earthbuild/actions-s It's 2025. Provide this document to your agent of choice to pick up the heavy lifting at your org. - + From 5ccb05610b6e3f6fc87895a72ea320293038e2d8 Mon Sep 17 00:00:00 2001 From: Kieran Mann Date: Wed, 18 Feb 2026 09:49:18 -0800 Subject: [PATCH 10/10] a few tweaks to migration guide --- MIGRATION.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index a8e8d1b34d..b2035f76e4 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -226,15 +226,21 @@ point to [`github.com/earthbuild/actions-setup`](github.com/earthbuild/actions-s + uses: earthbuild/actions-setup@main with: - earthly-version: v0.8.5 # example -+ version: v0.9.0 # example, use the latest earthbuild version ++ version: v0.8.17 # example, use the latest earthbuild version - name: Run build - run: earthly --ci +all + run: earth --ci +all ``` -## Hint 🤖 +## Other repositories + +For other repositories in the earthly ecosystem, we've created EarthBuild forks: -It's 2025. -Provide this document to your agent of choice to pick up the heavy lifting at your org. + +- [earthly/lib](https://github.com/earthly/lib) -> [earthbuild/lib](https://github.com/EarthBuild/lib) +- [earthly/dind](https://github.com/earthly/dind) -> [earthbuild/dind](https://github.com/EarthBuild/dind) +- [earthly/actions-setup](https://github.com/earthly/actions-setup) -> [earthbuild/actions-setup](https://github.com/EarthBuild/actions-setup) + +## Hint 🤖 - +Provide this document to your agent of choice to pick up the heavy lifting at your org. \ No newline at end of file