Earthly remote cache / EARTHLY_TOKEN not set in CI

By Kaveh Alemi·Latchkey

Remote cache and Earthly Satellites authenticate with an EARTHLY_TOKEN. When the token is missing or invalid in CI, remote cache push/pull and Satellite selection fail even though a local build would succeed.

What this error means

earthly reports it is not logged in, or a remote cache push fails with an auth error, because EARTHLY_TOKEN was not exported to the job.

Error: failed to authenticate: no Earthly token found. Set EARTHLY_TOKEN or run earthly account login
Error: remote cache: push to registry.example.com/cache failed: denied

Common causes

EARTHLY_TOKEN not exported to the job

Remote cache and Satellites need the token, but the secret was never set in the step environment, so Earthly runs unauthenticated.

Remote cache registry credentials missing

A remote cache backed by a registry needs push/pull credentials for that registry, separate from the build itself.

How to fix it

Export the token from a secret

1. Store the Earthly token as a CI secret.
2. Export EARTHLY_TOKEN in the job environment.
3. Confirm remote cache or Satellite auth now succeeds.

env:
  EARTHLY_TOKEN: ${{ secrets.EARTHLY_TOKEN }}

Authenticate the cache registry

For a registry-backed remote cache, log in to that registry so cache push and pull are authorized.

earthly --remote-cache=registry.example.com/cache:latest --push +build

How to prevent it

• Set EARTHLY_TOKEN as a CI secret for remote cache and Satellites.
• Authenticate the cache registry separately from the build.
• Rotate the token and update the secret in one place.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation