Part 2: Outputs
To copy the files for this example ( Part 2 ) run
earthly --artifact github.com/earthly/earthly/examples/tutorial/go:main+part2/part2 ./part2
Examples in Python, JavaScript and Java are at the bottom of this page.
Not All Targets Produce Output
Targets have the ability to produce output outside of the build environment. You can save files and docker images to your local machine or push them to remote repositories. Targets can also run commands that affect the local environment outside of the build, such as running database migrations, but not all targets produce output. Let's take a look at which commands produce output and how to use them.
Saving Files
We've already seen how the command SAVE ARTIFACT copies a file or directory from the build environment into the target's artifact environment.
This gives us the ability to copy files between targets, but it does not allow us to save any files to our local machine.
build:
COPY main.go .
RUN go build -o output/example main.go
SAVE ARTIFACT output/example
docker:
# COPY command copies files from the +build target
COPY +build/example .
ENTRYPOINT ["/go-workdir/example"]
SAVE IMAGE go-example:latest
In order to save the file locally , we need to add AS LOCAL
to the command.
build:
COPY main.go .
RUN go build -o output/example main.go
SAVE ARTIFACT output/example AS LOCAL local-output/go-example
If we run this example with earthly +build
, we'll see a local-output
directory show up locally with a go-example
file inside of it.
Saving Docker Images
Saving Docker images to your local machine is easy with the SAVE IMAGE
command.
build:
COPY main.go .
RUN go build -o output/example main.go
SAVE ARTIFACT output/example
docker:
COPY +build/example .
ENTRYPOINT ["/go-workdir/example"]
SAVE IMAGE go-example:latest
In this example, running earthly +docker
will save an image named go-example
with the tag latest
.
~$ earthly +docker
...
~$ docker image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
go-example latest 08b9f749023d 19 seconds ago 297MB
# or podman
~$ podman image ls
REPOSITORY TAG IMAGE ID CREATED SIZE
go-example latest 08b9f749023d 19 seconds ago 297MB
NOTE
If we run a target as a reference in FROM
or COPY
, outputs will not be produced. Take this Earthfile for example.
build:
COPY main.go .
RUN go build -o output/example main.go
SAVE ARTIFACT output/example AS LOCAL local-output/go-example
docker:
COPY +build/example .
ENTRYPOINT ["/go-workdir/example"]
SAVE IMAGE go-example:latest
In this case, running earthly +docker
will not produce any output. In other words, you will not have a local-output/go-example
written locally, but running earthly +build
will still produce output as expected.
The exception to this rule is the BUILD
command. If you want to use COPY
or FROM
and still have Earthly create local-output/go-example
locally, you'll need to use the BUILD
command to do so.
build:
COPY main.go .
RUN go build -o output/example main.go
SAVE ARTIFACT output/example AS LOCAL local-output/go-example
docker:
BUILD +build
COPY +build/example .
ENTRYPOINT ["/go-workdir/example"]
SAVE IMAGE go-example:latest
Running earthly +docker
in this case will now output local-output/go-example
locally.
The Push Flag
Docker Images
In addition to saving files and images locally, we can also push them to remote repositories.
docker:
COPY +build/example .
ENTRYPOINT ["/go-workdir/example"]
SAVE IMAGE --push go-example:latest
Note that adding the --push
flag to SAVE IMAGE
is not enough, we'll also need to invoke push when we run earthly. earthly --push +docker
.
External Changes
You can also use --push
as part of a RUN
command to define commands that have an effect external to the build. These kinds of effects are only allowed to take place if the entire build succeeds.
This allows you to push to remote repositories.
release:
RUN --push --secret GITHUB_TOKEN=+secrets/GH_TOKEN github-release upload
earthly --push +release
But also allows you to do things like run database migrations.
migrate:
FROM +build
RUN --push bundle exec rails db:migrate
earthly --push +migrate
Or apply terraform changes
apply:
RUN --push terraform apply -auto-approve
earthly --push +apply
NOTE
Just like saving files, any command that uses --push
will only produce output if called directly, earthly --push +target-with-push
or via a BUILD
command. Calling a target via FROM
or COPY
will not invoke --push
.
More Examples
Last updated
Was this helpful?