Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: examples moved to docs website #718

Merged
merged 1 commit into from Nov 4, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
37 changes: 6 additions & 31 deletions README.md
Expand Up @@ -18,20 +18,7 @@ ___
* [Usage](#usage)
* [Git context](#git-context)
* [Path context](#path-context)
* [Advanced usage](#advanced-usage)
* [Multi-platform image](docs/advanced/multi-platform.md)
* [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)
* [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 Docker Hub repo description](docs/advanced/dockerhub-desc.md)
* [Examples](#examples)
* [Customizing](#customizing)
* [inputs](#inputs)
* [outputs](#outputs)
Expand Down Expand Up @@ -129,8 +116,8 @@ to the default Git context:

Building from the current repository automatically uses the [GitHub Token](https://docs.github.com/en/actions/security-guides/automatic-token-authentication),
so it does not need to be passed. If you want to authenticate against another
private repository, you have to use a [secret](docs/advanced/secrets.md) named
`GIT_AUTH_TOKEN` to be able to authenticate against it with Buildx:
private repository, you have to use a [secret](https://docs.docker.com/build/ci/github-actions/examples/#secrets)
named `GIT_AUTH_TOKEN` to be able to authenticate against it with Buildx:

```yaml
-
Expand Down Expand Up @@ -181,21 +168,9 @@ jobs:
tags: user/app:latest
```

## Advanced usage

* [Multi-platform image](docs/advanced/multi-platform.md)
* [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)
* [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 Docker Hub repo description](docs/advanced/dockerhub-desc.md)
## Examples

See https://docs.docker.com/build/ci/github-actions/examples/.

## Customizing

Expand Down
206 changes: 1 addition & 205 deletions docs/advanced/cache.md
@@ -1,207 +1,3 @@
# Cache

* [Inline cache](#inline-cache)
* [Registry cache](#registry-cache)
* [GitHub cache](#github-cache)
* [Cache backend API](#cache-backend-api)
* [Local cache](#local-cache)

> **Note**
>
> See [our guide](https://github.com/docker/buildx/blob/master/docs/guides/cache/index.md)
> for more details about cache storage backends.

## Inline cache

In most cases you want to use the [`type=inline` cache exporter](https://github.com/docker/buildx/blob/master/docs/guides/cache/inline.md).
However, note that the `inline` cache exporter only supports `min` cache mode. To enable `max` cache mode, push the
image and the cache separately by using the `registry` cache exporter as shown in the [next example](#registry-cache).

```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: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
uses: docker/build-push-action@v3
with:
context: .
push: true
tags: user/app:latest
cache-from: type=registry,ref=user/app:latest
cache-to: type=inline
```

## Registry cache

You can import/export cache from a cache manifest or (special) image configuration on the registry with the
[`type=registry` cache exporter](https://github.com/docker/buildx/blob/master/docs/guides/cache/registry.md).

```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: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
uses: docker/build-push-action@v3
with:
context: .
push: true
tags: user/app:latest
cache-from: type=registry,ref=user/app:buildcache
cache-to: type=registry,ref=user/app:buildcache,mode=max
```

## GitHub cache

### Cache backend API

> **Warning**
>
> This cache exporter is considered EXPERIMENTAL until further notice. Please
> provide feedback on [BuildKit repository](https://github.com/moby/buildkit)
> if you encounter any issues.

[GitHub Actions cache exporter](https://github.com/docker/buildx/blob/master/docs/guides/cache/gha.md)
backend uses the [GitHub Cache API](https://github.com/tonistiigi/go-actions-cache/blob/master/api.md)
to fetch and upload cache blobs. That's why this type of cache should be
exclusively used in a GitHub Action workflow as the `url` (`$ACTIONS_CACHE_URL`)
and `token` (`$ACTIONS_RUNTIME_TOKEN`) attributes are populated when a workflow
is started.

```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: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
uses: docker/build-push-action@v3
with:
context: .
push: true
tags: user/app:latest
cache-from: type=gha
cache-to: type=gha,mode=max
```

### Local cache

> **Warning**
>
> At the moment caches are copied over the existing cache, so it [keeps growing](https://github.com/docker/build-push-action/issues/252).
> The `Move cache` step is used as a workaround (see [moby/buildkit#1896](https://github.com/moby/buildkit/issues/1896) for more info).

You can also leverage [GitHub cache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
using the [actions/cache](https://github.com/actions/cache) and [`type=local` cache exporter](https://github.com/docker/buildx/blob/master/docs/guides/cache/local.md)
with this action:

```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: Cache Docker layers
uses: actions/cache@v3
with:
path: /tmp/.buildx-cache
key: ${{ runner.os }}-buildx-${{ github.sha }}
restore-keys: |
${{ runner.os }}-buildx-
-
name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
uses: docker/build-push-action@v3
with:
context: .
push: true
tags: user/app:latest
cache-from: type=local,src=/tmp/.buildx-cache
cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
-
# Temp fix
# https://github.com/docker/build-push-action/issues/252
# https://github.com/moby/buildkit/issues/1896
name: Move cache
run: |
rm -rf /tmp/.buildx-cache
mv /tmp/.buildx-cache-new /tmp/.buildx-cache
```
This page has moved to [Docker Docs website](https://docs.docker.com/build/ci/github-actions/examples/#cache)
57 changes: 1 addition & 56 deletions docs/advanced/copy-between-registries.md
@@ -1,58 +1,3 @@
# Copy images between registries

[Multi-platform images](https://docs.docker.com/build/building/multi-platform/)
built using Buildx can be copied from one registry to another using the
[`imagetools create` command](https://docs.docker.com/engine/reference/commandline/buildx_imagetools_create/):

```yaml
name: ci

on:
push:
branches:
- 'main'

jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
uses: actions/checkout@v3
-
name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Login to GitHub Container Registry
uses: docker/login-action@v2
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }}
-
name: Build and push
uses: docker/build-push-action@v3
with:
context: .
platforms: linux/amd64,linux/arm64
push: true
tags: |
user/app:latest
user/app:1.0.0
-
name: Push image to GHCR
run: |
docker buildx imagetools create \
--tag ghcr.io/user/app:latest \
--tag ghcr.io/user/app:1.0.0 \
user/app:latest
```
This page has moved to [Docker Docs website](https://docs.docker.com/build/ci/github-actions/examples/#copy-images-between-registries)
47 changes: 1 addition & 46 deletions docs/advanced/dockerhub-desc.md
@@ -1,48 +1,3 @@
# Update Docker Hub repo description

You can update the [Docker Hub repository description](https://docs.docker.com/docker-hub/repos/)
using a third party action called [Docker Hub Description](https://github.com/peter-evans/dockerhub-description)
with this action:

```yaml
name: ci

on:
push:
branches:
- 'main'

jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
uses: actions/checkout@v3
-
name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Login to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
uses: docker/build-push-action@v3
with:
context: .
push: true
tags: user/app:latest
-
name: Update repo description
uses: peter-evans/dockerhub-description@v2
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_PASSWORD }}
repository: user/app
```
This page has moved to [Docker Docs website](https://docs.docker.com/build/ci/github-actions/examples/#update-docker-hub-repository-description)