diff --git a/README.md b/README.md index adf5a743d..5d80f2f65 100644 --- a/README.md +++ b/README.md @@ -22,12 +22,13 @@ ___ * [Secrets](docs/advanced/secrets.md) * [Isolated builders](docs/advanced/isolated-builders.md) * [Push to multi-registries](docs/advanced/push-multi-registries.md) - * [Copy between registries](docs/advanced/copy-between-registries.md) + * [Copy between registries](docs/advanced/copy-between-registries.md) * [Cache](docs/advanced/cache.md) * [Local registry](docs/advanced/local-registry.md) * [Export image to Docker](docs/advanced/export-docker.md) * [Share built image between jobs](docs/advanced/share-image-jobs.md) * [Test your image before pushing it](docs/advanced/test-before-push.md) + * [Named contexts](docs/advanced/named-contexts.md) * [Handle tags and labels](docs/advanced/tags-labels.md) * [Update DockerHub repo description](docs/advanced/dockerhub-desc.md) * [Customizing](#customizing) @@ -176,6 +177,7 @@ jobs: * [Export image to Docker](docs/advanced/export-docker.md) * [Share built image between jobs](docs/advanced/share-image-jobs.md) * [Test your image before pushing it](docs/advanced/test-before-push.md) +* [Named contexts](docs/advanced/named-contexts.md) * [Handle tags and labels](docs/advanced/tags-labels.md) * [Update DockerHub repo description](docs/advanced/dockerhub-desc.md) diff --git a/docs/advanced/export-docker.md b/docs/advanced/export-docker.md index d2d9c894a..22174a295 100644 --- a/docs/advanced/export-docker.md +++ b/docs/advanced/export-docker.md @@ -1,7 +1,7 @@ # Export image to Docker -You may want your build result to be available in the Docker client through `docker images` to be able to use it -in another step of your workflow: +You may want your build result to be available in the Docker client through +`docker images` to be able to use it in another step of your workflow: ```yaml name: ci @@ -33,75 +33,3 @@ jobs: run: | docker image inspect myimage:latest ``` - - -## Usage of the built image in other build steps - -[By default](https://github.com/docker/setup-buildx-action#customizing), `docker/setup-buildx-action@v2` -uses `docker-container` as a build driver, so the docker images are not available in the builder container. -To use them, you may use [build contexts](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#-additional-build-contexts---build-context): - -```yaml -name: ci - -on: - push: - branches: - - 'main' - -jobs: - docker: - runs-on: ubuntu-latest - steps: - - - name: Checkout - uses: actions/checkout@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v2 - - - name: Build base image - uses: docker/build-push-action@v3 - with: - context: base - load: true - tags: my-base-image:latest - - - name: Build image from my-base-image:latest - uses: docker/build-push-action@v3 - with: - context: . - build-contexts: | - base-image=docker-image://my-base-image:latest - tags: myimage:latest -``` - -Where `base-image`is the name of the base image (or stage name if specified) in your Dockerfile: -```Dockerfile -FROM base-image -``` - -### Bake alternative - -You may also want to use [bake](https://docs.docker.com/build/bake/build-contexts/#using-a-result-of-one-target-as-a-base-image-in-another-target) -and build the base image and the target image in one build step: -```terraform -# docker-bake.hcl -target "base" { - dockerfile = "baseapp.Dockerfile" -} - -target "app" { - contexts = { - baseapp = "target:base" - } -} -``` - -```yaml - - - name: Build - uses: docker/bake-action@v2 - with: - target: app -``` diff --git a/docs/advanced/named-contexts.md b/docs/advanced/named-contexts.md new file mode 100644 index 000000000..76cf20025 --- /dev/null +++ b/docs/advanced/named-contexts.md @@ -0,0 +1,95 @@ +# Named contexts + +You can define [additional build contexts](https://docs.docker.com/engine/reference/commandline/buildx_build/#build-context) +that can be accessed in your Dockerfile with `FROM name` or `--from=name`. When +Dockerfile defines a stage with the same name it is overwritten. + +This can be useful with GitHub Actions to reuse results from other builds or +pin an image to a spcific tag in your workflow. + +## Pin image to a specific tag + +Replace `alpine:latest` with a pinned one: + +```dockerfile +# syntax=docker/dockerfile:1 +FROM alpine +RUN echo "Hello World" +``` + +```yaml +name: ci + +on: + push: + branches: + - 'main' + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - + name: Checkout + uses: actions/checkout@v3 + - + name: Set up Docker Buildx + uses: docker/setup-buildx-action@v2 + - + name: Build + uses: docker/build-push-action@v3 + with: + context: . + build-contexts: | + alpine=docker-image://alpine:3.16 + tags: myimage:latest +``` + +## Usage of the built image in other build steps + +By default, the [`setup-buildx` action](https://github.com/docker/setup-buildx-action#about) +uses `docker-container` as a build driver, so built Docker images are not +available in the builder container. + +With named contexts you can reuse the built image: + +```dockerfile +# syntax=docker/dockerfile:1 +FROM alpine +RUN echo "Hello World" +``` + +```yaml +name: ci + +on: + push: + branches: + - 'main' + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - + name: Checkout + uses: actions/checkout@v3 + - + name: Set up Docker Buildx + uses: docker/setup-buildx-action@v2 + - + name: Build base image + uses: docker/build-push-action@v3 + with: + context: base + load: true + tags: my-base-image:latest + - + name: Build + uses: docker/build-push-action@v3 + with: + context: . + build-contexts: | + alpine=docker-image://my-base-image:latest + tags: myimage:latest +```