Add Troubleshooting section

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
This commit is contained in:
CrazyMax 2020-09-21 18:22:47 +02:00
parent 1f11648765
commit 5281740ad2
No known key found for this signature in database
GPG Key ID: 3248E46B6BB8C7F7
2 changed files with 356 additions and 291 deletions

View File

@ -3,6 +3,10 @@ name: Bug report
about: Create a report to help us improve about: Create a report to help us improve
--- ---
### Troubleshooting
Before sumbitting a bug report please read the [Troubleshooting section](https://github.com/docker/build-push-action#troubleshooting) in the README.
### Behaviour ### Behaviour
#### Steps to reproduce this issue #### Steps to reproduce this issue

View File

@ -30,6 +30,7 @@ ___
* [Customizing](#customizing) * [Customizing](#customizing)
* [inputs](#inputs) * [inputs](#inputs)
* [outputs](#outputs) * [outputs](#outputs)
* [Troubleshooting](#troubleshooting)
* [Keep up-to-date with GitHub Dependabot](#keep-up-to-date-with-github-dependabot) * [Keep up-to-date with GitHub Dependabot](#keep-up-to-date-with-github-dependabot)
* [Limitation](#limitation) * [Limitation](#limitation)
@ -44,8 +45,8 @@ build-secrets, remote cache, etc. and different builder deployment/namespacing o
The default behavior of this action is to use the [Git context invoked by your workflow](https://github.com/docker/build-push-action/blob/master/src/context.ts#L35). The default behavior of this action is to use the [Git context invoked by your workflow](https://github.com/docker/build-push-action/blob/master/src/context.ts#L35).
> :warning: Subdir for this context is [not yet supported](https://github.com/docker/build-push-action/issues/120). <details>
> For the moment you can use the [path context](#path-context). <summary><b>Show workflow</b></summary>
```yaml ```yaml
name: ci name: ci
@ -81,6 +82,7 @@ jobs:
name: Image digest name: Image digest
run: echo ${{ steps.docker_build.outputs.digest }} run: echo ${{ steps.docker_build.outputs.digest }}
``` ```
</details>
If you use this action in a private repository, you have to pass the [GitHub Token](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) If you use this action in a private repository, you have to pass the [GitHub Token](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)
as a secret named `GIT_AUTH_TOKEN` to be able to authenticate against it with buildx: as a secret named `GIT_AUTH_TOKEN` to be able to authenticate against it with buildx:
@ -97,10 +99,16 @@ as a secret named `GIT_AUTH_TOKEN` to be able to authenticate against it with bu
GIT_AUTH_TOKEN=${{ github.token }} GIT_AUTH_TOKEN=${{ github.token }}
``` ```
> :warning: Subdir for Git context is [not yet supported](https://github.com/docker/build-push-action/issues/120).
> For the moment you can use the [path context](#path-context).
### Path context ### Path context
You can also use the `PATH` context alongside the [`actions/checkout`](https://github.com/actions/checkout/) action. You can also use the `PATH` context alongside the [`actions/checkout`](https://github.com/actions/checkout/) action.
<details>
<summary><b>Show workflow</b></summary>
```yaml ```yaml
name: ci name: ci
@ -137,9 +145,13 @@ jobs:
push: true push: true
tags: user/app:latest tags: user/app:latest
``` ```
</details>
### Isolated builders ### Isolated builders
<details>
<summary><b>Show workflow</b></summary>
```yaml ```yaml
name: ci name: ci
@ -176,9 +188,13 @@ jobs:
builder: ${{ steps.builder2.outputs.name }} builder: ${{ steps.builder2.outputs.name }}
target: mytarget2 target: mytarget2
``` ```
</details>
### Multi-platform image ### Multi-platform image
<details>
<summary><b>Show workflow</b></summary>
```yaml ```yaml
name: ci name: ci
@ -217,6 +233,7 @@ jobs:
user/app:latest user/app:latest
user/app:1.0.0 user/app:1.0.0
``` ```
</details>
## Advanced usage ## Advanced usage
@ -224,6 +241,9 @@ jobs:
For testing purposes you may need to create a [local registry](https://hub.docker.com/_/registry) to push images into. For testing purposes you may need to create a [local registry](https://hub.docker.com/_/registry) to push images into.
<details>
<summary><b>Show workflow</b></summary>
```yaml ```yaml
name: ci name: ci
@ -259,12 +279,16 @@ jobs:
run: | run: |
docker buildx imagetools inspect localhost:5000/name/app:latest docker buildx imagetools inspect localhost:5000/name/app:latest
``` ```
</details>
### Leverage GitHub cache ### Leverage GitHub cache
You can leverage [GitHub cache](https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows) You can leverage [GitHub cache](https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)
using [actions/cache](https://github.com/actions/cache) with this action. using [actions/cache](https://github.com/actions/cache) with this action.
<details>
<summary><b>Show workflow</b></summary>
```yaml ```yaml
name: ci name: ci
@ -302,6 +326,7 @@ jobs:
cache-from: type=local,src=/tmp/.buildx-cache cache-from: type=local,src=/tmp/.buildx-cache
cache-to: type=local,dest=/tmp/.buildx-cache cache-to: type=local,dest=/tmp/.buildx-cache
``` ```
</details>
### Complete workflow ### Complete workflow
@ -322,6 +347,9 @@ might want to use:
| `push` | `refs/heads/my/branch` | `a5df687` | `sha-a5df687`, `my-branch` | Yes | | `push` | `refs/heads/my/branch` | `a5df687` | `sha-a5df687`, `my-branch` | Yes |
| `push tag` | `refs/tags/v1.2.3` | | `v1.2.3`, `v1.2`, `v1`, `latest` | Yes | | `push tag` | `refs/tags/v1.2.3` | | `v1.2.3`, `v1.2`, `v1`, `latest` | Yes |
<details>
<summary><b>Show workflow</b></summary>
```yaml ```yaml
name: ci name: ci
@ -404,6 +432,7 @@ jobs:
org.opencontainers.image.revision=${{ github.sha }} org.opencontainers.image.revision=${{ github.sha }}
org.opencontainers.image.licenses=${{ github.event.repository.license.spdx_id }} org.opencontainers.image.licenses=${{ github.event.repository.license.spdx_id }}
``` ```
</details>
### Update DockerHub repo description ### Update DockerHub repo description
@ -411,6 +440,9 @@ You can update the [Docker Hub repository description](https://docs.docker.com/d
a third-party action called [Docker Hub Description](https://github.com/peter-evans/dockerhub-description) a third-party action called [Docker Hub Description](https://github.com/peter-evans/dockerhub-description)
with this action. with this action.
<details>
<summary><b>Show workflow</b></summary>
```yaml ```yaml
name: ci name: ci
@ -448,6 +480,7 @@ jobs:
DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }} DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
DOCKERHUB_REPOSITORY: user/app DOCKERHUB_REPOSITORY: user/app
``` ```
</details>
## Customizing ## Customizing
@ -503,6 +536,34 @@ Following outputs are available
|---------------|---------|---------------------------------------| |---------------|---------|---------------------------------------|
| `digest` | String | Image content-addressable identifier also called a digest | | `digest` | String | Image content-addressable identifier also called a digest |
## Troubleshooting
While pushing to a registry, you may encounter these kinds of issues:
* `failed commit on ref "layer-sha256:...": invalid content digest in response: invalid checksum digest format`
* `failed commit on ref "layer-sha256:...": no response`
* `failed commit on ref "manifest-sha256:...": unexpected status: 401 Unauthorized`
* `unexpected response: 401 Unauthorized`
These issues are not directly related to this action but are rather linked to [buildx](https://github.com/docker/buildx),
[buildkit](https://github.com/moby/buildkit), [containerd](https://github.com/containerd/containerd) or the registry
on which you're pushing your image. The quality of error message depends on the registry and are usually not very informative.
To help you solve this, you should first enable debugging in the
[setup-buildx action step](https://github.com/docker/setup-buildx-action):
```yaml
-
name: Set up Docker Buildx
uses: docker/setup-buildx-action@v1
with:
buildkitd-flags: --debug
```
Next you can test pushing with containerd using [this workflow](https://github.com/crazy-max/ghaction-setup-containerd#build-and-push-docker-image).
Do not forget to set `ctr --debug` for the pushing step. If it works then open an issue on
[buildkit](https://github.com/moby/buildkit) repository.
## Keep up-to-date with GitHub Dependabot ## Keep up-to-date with GitHub Dependabot
Since [Dependabot](https://docs.github.com/en/github/administering-a-repository/keeping-your-actions-up-to-date-with-github-dependabot) Since [Dependabot](https://docs.github.com/en/github/administering-a-repository/keeping-your-actions-up-to-date-with-github-dependabot)