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

619
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>
```yaml
name: ci
on: on:
push: push:
branches: master branches: master
jobs: jobs:
path-context: path-context:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- -
name: Checkout name: Checkout
uses: actions/checkout@v2 uses: actions/checkout@v2
- -
name: Set up QEMU name: Set up QEMU
uses: docker/setup-qemu-action@v1 uses: docker/setup-qemu-action@v1
- -
name: Set up Docker Buildx name: Set up Docker Buildx
uses: docker/setup-buildx-action@v1 uses: docker/setup-buildx-action@v1
- -
name: Login to DockerHub name: Login to DockerHub
uses: docker/login-action@v1 uses: docker/login-action@v1
with: with:
username: ${{ secrets.DOCKERHUB_USERNAME }} username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }} password: ${{ secrets.DOCKERHUB_TOKEN }}
- -
name: Build and push name: Build and push
uses: docker/build-push-action@v2 uses: docker/build-push-action@v2
with: with:
context: . context: .
file: ./Dockerfile file: ./Dockerfile
platforms: linux/amd64,linux/arm64,linux/386 platforms: linux/amd64,linux/arm64,linux/386
push: true push: true
tags: user/app:latest tags: user/app:latest
``` ```
</details>
### Isolated builders ### Isolated builders
```yaml <details>
name: ci <summary><b>Show workflow</b></summary>
```yaml
name: ci
on: on:
push: push:
branches: master branches: master
jobs: jobs:
multi-builders: multi-builders:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- -
uses: docker/setup-buildx-action@v1 uses: docker/setup-buildx-action@v1
id: builder1 id: builder1
- -
uses: docker/setup-buildx-action@v1 uses: docker/setup-buildx-action@v1
id: builder2 id: builder2
- -
name: Builder 1 name name: Builder 1 name
run: echo ${{ steps.builder1.outputs.name }} run: echo ${{ steps.builder1.outputs.name }}
- -
name: Builder 2 name name: Builder 2 name
run: echo ${{ steps.builder2.outputs.name }} run: echo ${{ steps.builder2.outputs.name }}
- -
name: Build against builder1 name: Build against builder1
uses: docker/build-push-action@v2 uses: docker/build-push-action@v2
with: with:
builder: ${{ steps.builder1.outputs.name }} builder: ${{ steps.builder1.outputs.name }}
target: mytarget1 target: mytarget1
- -
name: Build against builder2 name: Build against builder2
uses: docker/build-push-action@v2 uses: docker/build-push-action@v2
with: with:
builder: ${{ steps.builder2.outputs.name }} builder: ${{ steps.builder2.outputs.name }}
target: mytarget2 target: mytarget2
``` ```
</details>
### Multi-platform image ### Multi-platform image
```yaml <details>
name: ci <summary><b>Show workflow</b></summary>
```yaml
name: ci
on: on:
push: push:
branches: master branches: master
jobs: jobs:
multi: multi:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- -
name: Checkout name: Checkout
uses: actions/checkout@v2 uses: actions/checkout@v2
- -
name: Set up QEMU name: Set up QEMU
uses: docker/setup-qemu-action@v1 uses: docker/setup-qemu-action@v1
- -
name: Set up Docker Buildx name: Set up Docker Buildx
uses: docker/setup-buildx-action@v1 uses: docker/setup-buildx-action@v1
- -
name: Login to DockerHub name: Login to DockerHub
uses: docker/login-action@v1 uses: docker/login-action@v1
with: with:
username: ${{ secrets.DOCKERHUB_USERNAME }} username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }} password: ${{ secrets.DOCKERHUB_TOKEN }}
- -
name: Build and push name: Build and push
uses: docker/build-push-action@v2 uses: docker/build-push-action@v2
with: with:
context: . context: .
file: ./Dockerfile file: ./Dockerfile
platforms: linux/386,linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64,linux/ppc64le,linux/s390x platforms: linux/386,linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64,linux/ppc64le,linux/s390x
push: true push: true
tags: | tags: |
user/app:latest user/app:latest
user/app:1.0.0 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>
```yaml
name: ci
on: on:
push: push:
branches: master branches: master
jobs: jobs:
local-registry: local-registry:
runs-on: ubuntu-latest runs-on: ubuntu-latest
services: services:
registry: registry:
image: registry:2 image: registry:2
ports: ports:
- 5000:5000 - 5000:5000
steps: steps:
- -
name: Set up QEMU name: Set up QEMU
uses: docker/setup-qemu-action@v1 uses: docker/setup-qemu-action@v1
- -
name: Set up Docker Buildx name: Set up Docker Buildx
uses: docker/setup-buildx-action@v1 uses: docker/setup-buildx-action@v1
with: with:
driver-opts: network=host driver-opts: network=host
- -
name: Build and push to local registry name: Build and push to local registry
uses: docker/build-push-action@v2 uses: docker/build-push-action@v2
with: with:
push: true push: true
tags: localhost:5000/name/app:latest tags: localhost:5000/name/app:latest
- -
name: Inspect name: Inspect
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.
```yaml <details>
name: ci <summary><b>Show workflow</b></summary>
```yaml
name: ci
on: on:
push: push:
branches: master branches: master
jobs: jobs:
github-cache: github-cache:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- -
name: Set up Docker Buildx name: Set up Docker Buildx
uses: docker/setup-buildx-action@v1 uses: docker/setup-buildx-action@v1
- -
name: Cache Docker layers name: Cache Docker layers
uses: actions/cache@v2 uses: actions/cache@v2
with: with:
path: /tmp/.buildx-cache path: /tmp/.buildx-cache
key: ${{ runner.os }}-buildx-${{ github.sha }} key: ${{ runner.os }}-buildx-${{ github.sha }}
restore-keys: | restore-keys: |
${{ runner.os }}-buildx- ${{ runner.os }}-buildx-
- -
name: Login to DockerHub name: Login to DockerHub
uses: docker/login-action@v1 uses: docker/login-action@v1
with: with:
username: ${{ secrets.DOCKERHUB_USERNAME }} username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }} password: ${{ secrets.DOCKERHUB_TOKEN }}
- -
name: Build and push name: Build and push
uses: docker/build-push-action@v2 uses: docker/build-push-action@v2
with: with:
push: true push: true
tags: user/app:latest tags: user/app:latest
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,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>
```yaml
name: ci
on: on:
schedule: schedule:
- cron: '0 10 * * *' # everyday at 10am - cron: '0 10 * * *' # everyday at 10am
push: push:
branches: branches:
- '**' - '**'
tags: tags:
- 'v*.*.*' - 'v*.*.*'
pull_request: pull_request:
jobs: jobs:
docker: docker:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- -
name: Checkout name: Checkout
uses: actions/checkout@v2 uses: actions/checkout@v2
- -
name: Prepare name: Prepare
id: prep id: prep
run: | run: |
DOCKER_IMAGE=name/app DOCKER_IMAGE=name/app
VERSION=noop VERSION=noop
if [ "${{ github.event_name }}" = "schedule" ]; then if [ "${{ github.event_name }}" = "schedule" ]; then
VERSION=nightly VERSION=nightly
elif [[ $GITHUB_REF == refs/tags/* ]]; then elif [[ $GITHUB_REF == refs/tags/* ]]; then
VERSION=${GITHUB_REF#refs/tags/} VERSION=${GITHUB_REF#refs/tags/}
elif [[ $GITHUB_REF == refs/heads/* ]]; then elif [[ $GITHUB_REF == refs/heads/* ]]; then
VERSION=$(echo ${GITHUB_REF#refs/heads/} | sed -r 's#/+#-#g') VERSION=$(echo ${GITHUB_REF#refs/heads/} | sed -r 's#/+#-#g')
if [ "${{ github.event.repository.default_branch }}" = "$VERSION" ]; then if [ "${{ github.event.repository.default_branch }}" = "$VERSION" ]; then
VERSION=edge 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>
```yaml
name: ci
on: on:
push: push:
branches: master branches: master
jobs: jobs:
main: main:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- -
name: Set up QEMU name: Set up QEMU
uses: docker/setup-qemu-action@v1 uses: docker/setup-qemu-action@v1
- -
name: Set up Docker Buildx name: Set up Docker Buildx
uses: docker/setup-buildx-action@v1 uses: docker/setup-buildx-action@v1
- -
name: Login to DockerHub name: Login to DockerHub
uses: docker/login-action@v1 uses: docker/login-action@v1
with: with:
username: ${{ secrets.DOCKERHUB_USERNAME }} username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }} password: ${{ secrets.DOCKERHUB_TOKEN }}
- -
name: Build and push name: Build and push
uses: docker/build-push-action@v2 uses: docker/build-push-action@v2
with: with:
push: true push: true
tags: user/app:latest tags: user/app:latest
- -
name: Update repo description name: Update repo description
uses: peter-evans/dockerhub-description@v2 uses: peter-evans/dockerhub-description@v2
env: env:
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }} DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }} DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
DOCKERHUB_REPOSITORY: user/app 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.