Docker Release

Note

The Earthly target specified for this release must accept two arguments: container and tag. These arguments must then be used when saving the image at the end of the target:

docker:
    ARG container="image_name"
    ARG tag="latest"

    SAVE IMAGE ${container}:${tag}

Without this, Forge will be unable to locat the image generated by the target.

The docker release type publishes the image generated by the release target to configured container registries.

Config

Note

If the release is configured to trigger on a tag event, then the tag field will automatically be set to the semantic version included in the git tag (overriding any value configured in the blueprint). For example, a tag for project foo might look like: foo/v1.0.0. When the release runs, it will automatically tag images using v1.0.0 instead of the value specified in the tag field.

Field	Description	Type	Required	Default
tag	The tag to publish the image with	string	yes	N/A

How it Works

The docker release calls the configured Earthly target and expects a container image to be generated (using SAVE IMAGE). The configured target should accept two arguments: container and tag. The target is called and passed values for these arguments which should be used when saving the image (see note above).

Once the target successfully completes, the local docker daemon is searched to ensure the expected image was created. At this point, if there is no currently triggered event, the release will stop.

In the case where a release event is firing, the produced image will then be retagged using any registries configured in global.ci.registries as well as the tag specified in the configuration. Each uniquely tagged image created by this process is then pushed. Note that Forge assumes appropriate authentication has already been configured for private registries. Underneath the hood the docker CLI is used, so any supported authentication formats should work.

Mutli-platform images

It's possible to produce multi-platform images by specifying the platforms field in the target configuration. For example:

project: {
    ci: targets: docker: {
        platforms: ["linux/amd64", "linux/arm64"]
    }
}

This will cause the target to produce two images: one for the linux/amd64 platform and the other for the linux/arm64 platform. The docker release type will automatically detect multi-platform builds and adjust its strategy accordingly. It starts by validating that the expected images for each platform are present in the local docker daemon. It then uses the same tag strategy to retag and push these images. The only difference is tags have the platform appended to the end (e.g., image:tag_linux_amd64).

Once all images have been pushed, a final multi-platform image is created that drops the suffix (e.g., image:tag) and contains entries pointing to each of the previously pushed images. Docker clients that natively support multi-platform images will be able to pull down the correct architecture from this image.