actions
/
docker-build-push
mirror of https://github.com/docker/build-push-action.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #133 from crazy-max/troubleshooting-section 

Add Troubleshooting section in README
pull/138/head
CrazyMax 2020-09-21 21:18:03 +02:00 committed by GitHub
parent 1f11648765 65a1a173ac
commit 3a24abd18b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 361 additions and 291 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/ISSUE_TEMPLATE/bug_report.md vendored
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 doc](https://github.com/docker/build-push-action/blob/master/TROUBLESHOOTING.md).
### Behaviour ### Behaviour
#### Steps to reproduce this issue #### Steps to reproduce this issue

617
README.md
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,10 +45,10 @@ 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
on: on:
@ -80,7 +81,8 @@ 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,126 +99,141 @@ 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.
```yaml <details>
name: ci <summary><b>Show workflow</b></summary>
on: ```yaml
push: name: ci
branches: master
jobs: on:
path-context: push:
runs-on: ubuntu-latest branches: master
steps:
- jobs:
name: Checkout path-context:
uses: actions/checkout@v2 runs-on: ubuntu-latest
- steps:
name: Set up QEMU -
uses: docker/setup-qemu-action@v1 name: Checkout
- uses: actions/checkout@v2
name: Set up Docker Buildx -
uses: docker/setup-buildx-action@v1 name: Set up QEMU
- uses: docker/setup-qemu-action@v1
name: Login to DockerHub -
uses: docker/login-action@v1 name: Set up Docker Buildx
with: uses: docker/setup-buildx-action@v1
username: ${{ secrets.DOCKERHUB_USERNAME }} -
password: ${{ secrets.DOCKERHUB_TOKEN }} name: Login to DockerHub
- uses: docker/login-action@v1
name: Build and push with:
uses: docker/build-push-action@v2 username: ${{ secrets.DOCKERHUB_USERNAME }}
with: password: ${{ secrets.DOCKERHUB_TOKEN }}
context: . -
file: ./Dockerfile name: Build and push
platforms: linux/amd64,linux/arm64,linux/386 uses: docker/build-push-action@v2
push: true with:
tags: user/app:latest context: .
``` file: ./Dockerfile
platforms: linux/amd64,linux/arm64,linux/386
push: true
tags: user/app:latest
```
</details>
### Isolated builders ### Isolated builders
```yaml <details>
name: ci <summary><b>Show workflow</b></summary>
on: ```yaml
push: name: ci
branches: master
jobs: on:
multi-builders: push:
runs-on: ubuntu-latest branches: master
steps:
- jobs:
uses: docker/setup-buildx-action@v1 multi-builders:
id: builder1 runs-on: ubuntu-latest
- steps:
uses: docker/setup-buildx-action@v1 -
id: builder2 uses: docker/setup-buildx-action@v1
- id: builder1
name: Builder 1 name -
run: echo ${{ steps.builder1.outputs.name }} uses: docker/setup-buildx-action@v1
- id: builder2
name: Builder 2 name -
run: echo ${{ steps.builder2.outputs.name }} name: Builder 1 name
- run: echo ${{ steps.builder1.outputs.name }}
name: Build against builder1 -
uses: docker/build-push-action@v2 name: Builder 2 name
with: run: echo ${{ steps.builder2.outputs.name }}
builder: ${{ steps.builder1.outputs.name }} -
target: mytarget1 name: Build against builder1
- uses: docker/build-push-action@v2
name: Build against builder2 with:
uses: docker/build-push-action@v2 builder: ${{ steps.builder1.outputs.name }}
with: target: mytarget1
builder: ${{ steps.builder2.outputs.name }} -
target: mytarget2 name: Build against builder2
``` uses: docker/build-push-action@v2
with:
builder: ${{ steps.builder2.outputs.name }}
target: mytarget2
```
</details>
### Multi-platform image ### Multi-platform image
```yaml <details>
name: ci <summary><b>Show workflow</b></summary>
on: ```yaml
push: name: ci
branches: master
jobs: on:
multi: push:
runs-on: ubuntu-latest branches: master
steps:
- jobs:
name: Checkout multi:
uses: actions/checkout@v2 runs-on: ubuntu-latest
- steps:
name: Set up QEMU -
uses: docker/setup-qemu-action@v1 name: Checkout
- uses: actions/checkout@v2
name: Set up Docker Buildx -
uses: docker/setup-buildx-action@v1 name: Set up QEMU
- uses: docker/setup-qemu-action@v1
name: Login to DockerHub -
uses: docker/login-action@v1 name: Set up Docker Buildx
with: uses: docker/setup-buildx-action@v1
username: ${{ secrets.DOCKERHUB_USERNAME }} -
password: ${{ secrets.DOCKERHUB_TOKEN }} name: Login to DockerHub
- uses: docker/login-action@v1
name: Build and push with:
uses: docker/build-push-action@v2 username: ${{ secrets.DOCKERHUB_USERNAME }}
with: password: ${{ secrets.DOCKERHUB_TOKEN }}
context: . -
file: ./Dockerfile name: Build and push
platforms: linux/386,linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64,linux/ppc64le,linux/s390x uses: docker/build-push-action@v2
push: true with:
tags: | context: .
user/app:latest file: ./Dockerfile
user/app:1.0.0 platforms: linux/386,linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64,linux/ppc64le,linux/s390x
``` push: true
tags: |
user/app:latest
user/app:1.0.0
```
</details>
## Advanced usage ## Advanced usage
@ -224,84 +241,92 @@ 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.
```yaml <details>
name: ci <summary><b>Show workflow</b></summary>
on: ```yaml
push: name: ci
branches: master
jobs: on:
local-registry: push:
runs-on: ubuntu-latest branches: master
services:
registry: jobs:
image: registry:2 local-registry:
ports: runs-on: ubuntu-latest
- 5000:5000 services:
steps: registry:
- image: registry:2
name: Set up QEMU ports:
uses: docker/setup-qemu-action@v1 - 5000:5000
- steps:
name: Set up Docker Buildx -
uses: docker/setup-buildx-action@v1 name: Set up QEMU
with: uses: docker/setup-qemu-action@v1
driver-opts: network=host -
- name: Set up Docker Buildx
name: Build and push to local registry uses: docker/setup-buildx-action@v1
uses: docker/build-push-action@v2 with:
with: driver-opts: network=host
push: true -
tags: localhost:5000/name/app:latest name: Build and push to local registry
- uses: docker/build-push-action@v2
name: Inspect with:
run: | push: true
docker buildx imagetools inspect localhost:5000/name/app:latest tags: localhost:5000/name/app:latest
``` -
name: Inspect
run: |
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.
```yaml <details>
name: ci <summary><b>Show workflow</b></summary>
on: ```yaml
push: name: ci
branches: master
jobs: on:
github-cache: push:
runs-on: ubuntu-latest branches: master
steps:
- jobs:
name: Set up Docker Buildx github-cache:
uses: docker/setup-buildx-action@v1 runs-on: ubuntu-latest
- steps:
name: Cache Docker layers -
uses: actions/cache@v2 name: Set up Docker Buildx
with: uses: docker/setup-buildx-action@v1
path: /tmp/.buildx-cache -
key: ${{ runner.os }}-buildx-${{ github.sha }} name: Cache Docker layers
restore-keys: | uses: actions/cache@v2
${{ runner.os }}-buildx- with:
- path: /tmp/.buildx-cache
name: Login to DockerHub key: ${{ runner.os }}-buildx-${{ github.sha }}
uses: docker/login-action@v1 restore-keys: |
with: ${{ runner.os }}-buildx-
username: ${{ secrets.DOCKERHUB_USERNAME }} -
password: ${{ secrets.DOCKERHUB_TOKEN }} name: Login to DockerHub
- uses: docker/login-action@v1
name: Build and push with:
uses: docker/build-push-action@v2 username: ${{ secrets.DOCKERHUB_USERNAME }}
with: password: ${{ secrets.DOCKERHUB_TOKEN }}
push: true -
tags: user/app:latest name: Build and push
cache-from: type=local,src=/tmp/.buildx-cache uses: docker/build-push-action@v2
cache-to: type=local,dest=/tmp/.buildx-cache with:
``` push: true
tags: user/app:latest
cache-from: type=local,src=/tmp/.buildx-cache
cache-to: type=local,dest=/tmp/.buildx-cache
```
</details>
### Complete workflow ### Complete workflow
@ -322,88 +347,92 @@ 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 |
```yaml <details>
name: ci <summary><b>Show workflow</b></summary>
on: ```yaml
schedule: name: ci
- cron: '0 10 * * *' # everyday at 10am
push:
branches:
- '**'
tags:
- 'v*.*.*'
pull_request:
jobs: on:
docker: schedule:
runs-on: ubuntu-latest - cron: '0 10 * * *' # everyday at 10am
steps: push:
- branches:
name: Checkout - '**'
uses: actions/checkout@v2 tags:
- - 'v*.*.*'
name: Prepare pull_request:
id: prep
run: | jobs:
DOCKER_IMAGE=name/app docker:
VERSION=noop runs-on: ubuntu-latest
if [ "${{ github.event_name }}" = "schedule" ]; then steps:
VERSION=nightly -
elif [[ $GITHUB_REF == refs/tags/* ]]; then name: Checkout
VERSION=${GITHUB_REF#refs/tags/} uses: actions/checkout@v2
elif [[ $GITHUB_REF == refs/heads/* ]]; then -
VERSION=$(echo ${GITHUB_REF#refs/heads/} | sed -r 's#/+#-#g') name: Prepare
if [ "${{ github.event.repository.default_branch }}" = "$VERSION" ]; then id: prep
VERSION=edge run: |
DOCKER_IMAGE=name/app
VERSION=noop
if [ "${{ github.event_name }}" = "schedule" ]; then
VERSION=nightly
elif [[ $GITHUB_REF == refs/tags/* ]]; then
VERSION=${GITHUB_REF#refs/tags/}
elif [[ $GITHUB_REF == refs/heads/* ]]; then
VERSION=$(echo ${GITHUB_REF#refs/heads/} | sed -r 's#/+#-#g')
if [ "${{ github.event.repository.default_branch }}" = "$VERSION" ]; then
VERSION=edge
fi
elif [[ $GITHUB_REF == refs/pull/* ]]; then
VERSION=pr-${{ github.event.number }}
fi fi
elif [[ $GITHUB_REF == refs/pull/* ]]; then TAGS="${DOCKER_IMAGE}:${VERSION}"
VERSION=pr-${{ github.event.number }} if [[ $VERSION =~ ^v[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
fi MINOR=${VERSION%.*}
TAGS="${DOCKER_IMAGE}:${VERSION}" MAJOR=${MINOR%.*}
if [[ $VERSION =~ ^v[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then TAGS="$TAGS,${DOCKER_IMAGE}:${MINOR},${DOCKER_IMAGE}:${MAJOR},${DOCKER_IMAGE}:latest"
MINOR=${VERSION%.*} elif [ "${{ github.event_name }}" = "push" ]; then
MAJOR=${MINOR%.*} TAGS="$TAGS,${DOCKER_IMAGE}:sha-${GITHUB_SHA::8}"
TAGS="$TAGS,${DOCKER_IMAGE}:${MINOR},${DOCKER_IMAGE}:${MAJOR},${DOCKER_IMAGE}:latest" fi
elif [ "${{ github.event_name }}" = "push" ]; then echo ::set-output name=version::${VERSION}
TAGS="$TAGS,${DOCKER_IMAGE}:sha-${GITHUB_SHA::8}" echo ::set-output name=tags::${TAGS}
fi echo ::set-output name=created::$(date -u +'%Y-%m-%dT%H:%M:%SZ')
echo ::set-output name=version::${VERSION} -
echo ::set-output name=tags::${TAGS} name: Set up QEMU
echo ::set-output name=created::$(date -u +'%Y-%m-%dT%H:%M:%SZ') uses: docker/setup-qemu-action@v1
- -
name: Set up QEMU name: Set up Docker Buildx
uses: docker/setup-qemu-action@v1 uses: docker/setup-buildx-action@v1
- -
name: Set up Docker Buildx name: Login to DockerHub
uses: docker/setup-buildx-action@v1 if: github.event_name != 'pull_request'
- uses: docker/login-action@v1
name: Login to DockerHub with:
if: github.event_name != 'pull_request' username: ${{ secrets.DOCKERHUB_USERNAME }}
uses: docker/login-action@v1 password: ${{ secrets.DOCKERHUB_TOKEN }}
with: -
username: ${{ secrets.DOCKERHUB_USERNAME }} name: Build and push
password: ${{ secrets.DOCKERHUB_TOKEN }} id: docker_build
- uses: docker/build-push-action@v2
name: Build and push with:
id: docker_build context: .
uses: docker/build-push-action@v2 file: ./Dockerfile
with: platforms: linux/amd64,linux/arm64,linux/386
context: . push: ${{ github.event_name != 'pull_request' }}
file: ./Dockerfile tags: ${{ steps.prep.outputs.tags }}
platforms: linux/amd64,linux/arm64,linux/386 labels: |
push: ${{ github.event_name != 'pull_request' }} org.opencontainers.image.title=${{ github.event.repository.name }}
tags: ${{ steps.prep.outputs.tags }} org.opencontainers.image.description=${{ github.event.repository.description }}
labels: | org.opencontainers.image.url=${{ github.event.repository.html_url }}
org.opencontainers.image.title=${{ github.event.repository.name }} org.opencontainers.image.source=${{ github.event.repository.clone_url }}
org.opencontainers.image.description=${{ github.event.repository.description }} org.opencontainers.image.version=${{ steps.prep.outputs.version }}
org.opencontainers.image.url=${{ github.event.repository.html_url }} org.opencontainers.image.created=${{ steps.prep.outputs.created }}
org.opencontainers.image.source=${{ github.event.repository.clone_url }} org.opencontainers.image.revision=${{ github.sha }}
org.opencontainers.image.version=${{ steps.prep.outputs.version }} org.opencontainers.image.licenses=${{ github.event.repository.license.spdx_id }}
org.opencontainers.image.created=${{ steps.prep.outputs.created }} ```
org.opencontainers.image.revision=${{ github.sha }} </details>
org.opencontainers.image.licenses=${{ github.event.repository.license.spdx_id }}
```
### Update DockerHub repo description ### Update DockerHub repo description
@ -411,43 +440,47 @@ 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.
```yaml <details>
name: ci <summary><b>Show workflow</b></summary>
on: ```yaml
push: name: ci
branches: master
jobs: on:
main: push:
runs-on: ubuntu-latest branches: master
steps:
- jobs:
name: Set up QEMU main:
uses: docker/setup-qemu-action@v1 runs-on: ubuntu-latest
- steps:
name: Set up Docker Buildx -
uses: docker/setup-buildx-action@v1 name: Set up QEMU
- uses: docker/setup-qemu-action@v1
name: Login to DockerHub -
uses: docker/login-action@v1 name: Set up Docker Buildx
with: uses: docker/setup-buildx-action@v1
username: ${{ secrets.DOCKERHUB_USERNAME }} -
password: ${{ secrets.DOCKERHUB_TOKEN }} name: Login to DockerHub
- uses: docker/login-action@v1
name: Build and push with:
uses: docker/build-push-action@v2 username: ${{ secrets.DOCKERHUB_USERNAME }}
with: password: ${{ secrets.DOCKERHUB_TOKEN }}
push: true -
tags: user/app:latest name: Build and push
- uses: docker/build-push-action@v2
name: Update repo description with:
uses: peter-evans/dockerhub-description@v2 push: true
env: tags: user/app:latest
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} -
DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }} name: Update repo description
DOCKERHUB_REPOSITORY: user/app uses: peter-evans/dockerhub-description@v2
``` env:
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
DOCKERHUB_REPOSITORY: user/app
```
</details>
## Customizing ## Customizing
@ -503,6 +536,10 @@ 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
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
## 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)

29
TROUBLESHOOTING.md Normal file
View File

@ -0,0 +1,29 @@
# Troubleshooting
## Errors on pushing to registry
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.