diff --git a/README.md b/README.md
index adf5a74..5d80f2f 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 d2d9c89..22174a2 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 0000000..76cf200
--- /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
+```