diff --git a/README.md b/README.md index f48e7b928..91be51f58 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) @@ -188,6 +189,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 a8b7083e6..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 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 +```