Skip to content

Commit

Permalink
docs: named contexts
Browse files Browse the repository at this point in the history
Signed-off-by: CrazyMax <[email protected]>
  • Loading branch information
crazy-max committed Oct 7, 2022
1 parent 6a6e8c7 commit 0f5a7d4
Show file tree
Hide file tree
Showing 3 changed files with 100 additions and 75 deletions.
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)

Expand Down
76 changes: 2 additions & 74 deletions docs/advanced/export-docker.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
```
95 changes: 95 additions & 0 deletions docs/advanced/named-contexts.md
Original file line number Diff line number Diff line change
@@ -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
```

0 comments on commit 0f5a7d4

Please sign in to comment.