Update example with explanations

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

.github/workflows/ci.yml

@@ -233,73 +233,3 @@ jobs:
         name: Dump context
         if: always()
         uses: crazy-max/ghaction-dump-context@v1
-
-  tags-labels:
-    runs-on: ubuntu-latest
-    services:
-      registry:
-        image: registry:2
-        ports:
-          - 5000:5000
-    steps:
-      -
-        name: Checkout
-        uses: actions/checkout@v2.3.2
-      -
-        name: Prepare
-        id: prep
-        run: |
-          DOCKER_IMAGE=localhost:5000/name/app
-          VERSION=noop
-          if [[ $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
-          TAGS="${DOCKER_IMAGE}:${VERSION}"
-          if [ "${{ github.event_name }}" != "pull_request" ]; then
-            TAGS="${DOCKER_IMAGE}:sha-${GITHUB_SHA::8}"
-          fi
-          if [[ $VERSION =~ ^v[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
-            MINOR=${VERSION%.*}
-            MAJOR=${MINOR%.*}
-            TAGS="$TAGS,${DOCKER_IMAGE}:${MINOR},${DOCKER_IMAGE}:${MAJOR},${DOCKER_IMAGE}:latest"
-          fi
-          echo ::set-output name=version::${VERSION}
-          echo ::set-output name=tags::${TAGS}
-          echo ::set-output name=created::$(date -u +'%Y-%m-%dT%H:%M:%SZ')
-      -
-        name: Set up QEMU
-        uses: docker/setup-qemu-action@v1
-      -
-        name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v1
-        with:
-          driver-opts: network=host
-      -
-        name: Build and push
-        uses: ./
-        with:
-          context: ./test
-          file: ./test/Dockerfile
-          push: true
-          tags: ${{ steps.prep.outputs.tags }}
-          labels: |
-            org.opencontainers.image.created=${{ steps.prep.outputs.created }}
-            org.opencontainers.image.source=${{ github.repositoryUrl }}
-            org.opencontainers.image.version=${{ steps.prep.outputs.version }}
-            org.opencontainers.image.revision=${{ github.sha }}
-            org.opencontainers.image.licenses=${{ github.event.repository.license.name }}
-      -
-        name: Inspect
-        run: |
-          docker buildx imagetools inspect localhost:5000/name/app:${{ steps.prep.outputs.version }}
-      -
-        name: Dump context
-        if: always()
-        uses: crazy-max/ghaction-dump-context@v1

.github/workflows/example.yml

@@ -0,0 +1,100 @@
+name: example
+
+on:
+  schedule:
+    - cron: '0 10 * * 0' # everyday sunday at 10am
+  push:
+    branches:
+      - '**'
+    tags:
+      - 'v*.*.*'
+  pull_request:
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    services:
+      registry:
+        image: registry:2
+        ports:
+          - 5000:5000
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2.3.2
+      -
+        name: Prepare
+        id: prep
+        run: |
+          DOCKER_IMAGE=localhost:5000/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
+          if [[ $GITHUB_REF != refs/tags/* ]] && [[ "${{ github.event_name }}" = "push"  ]]; then
+            TAGS="${DOCKER_IMAGE}:sha-${GITHUB_SHA::8}"
+          fi
+          TAGS="${DOCKER_IMAGE}:${VERSION}"
+          if [[ $VERSION =~ ^v[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
+            MINOR=${VERSION%.*}
+            MAJOR=${MINOR%.*}
+            TAGS="$TAGS,${DOCKER_IMAGE}:${MINOR},${DOCKER_IMAGE}:${MAJOR},${DOCKER_IMAGE}:latest"
+          fi
+          echo ::set-output name=version::${VERSION}
+          echo ::set-output name=tags::${TAGS}
+          echo ::set-output name=created::$(date -u +'%Y-%m-%dT%H:%M:%SZ')
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+        with:
+          driver-opts: network=host
+      -
+        name: Build and export to Docker client
+        uses: ./
+        with:
+          context: ./test
+          file: ./test/Dockerfile
+          outputs: type=docker
+          tags: ${{ steps.prep.outputs.tags }}
+          labels: |
+            org.opencontainers.image.created=${{ steps.prep.outputs.created }}
+            org.opencontainers.image.source=${{ github.repositoryUrl }}
+            org.opencontainers.image.version=${{ steps.prep.outputs.version }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.licenses=${{ github.event.repository.license.name }}
+      -
+        name: Build and push to local registry
+        uses: ./
+        with:
+          context: ./test
+          file: ./test/Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.prep.outputs.tags }}
+          labels: |
+            org.opencontainers.image.created=${{ steps.prep.outputs.created }}
+            org.opencontainers.image.source=${{ github.repositoryUrl }}
+            org.opencontainers.image.version=${{ steps.prep.outputs.version }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.licenses=${{ github.event.repository.license.name }}
+      -
+        name: Inspect image
+        run: |
+          docker image inspect localhost:5000/name/app:${{ steps.prep.outputs.version }}
+      -
+        name: Check manifest
+        if: github.event_name != 'pull_request'
+        run: |
+          docker buildx imagetools inspect localhost:5000/name/app:${{ steps.prep.outputs.version }}
+      -
+        name: Dump context
+        if: always()
+        uses: crazy-max/ghaction-dump-context@v1

README.md

@@ -22,9 +22,9 @@ ___
   * [Path context](#path-context)
   * [Isolated builders](#isolated-builders)
   * [Multi-platform image](#multi-platform-image)
+* [Advanced usage](#advanced-usage)
   * [Local registry](#local-registry)
   * [Leverage GitHub cache](#leverage-github-cache)
-  * [Tags and labels handling](#tags-and-labels-handling)
   * [Complete workflow](#complete-workflow)
   * [Update DockerHub repo description](#update-dockerhub-repo-description)
 * [Customizing](#customizing)
@@ -42,7 +42,10 @@ build-secrets, remote cache, etc. and different builder deployment/namespacing o
 
 ### Git context
 
-The default behavior of this action is to use the Git context invoked by your workflow (`https://github.com/owner/repo#ref`).
+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).
+> For the moment you can use the [path context](#path-context).
 
 ```yaml
 name: ci
@@ -215,6 +218,8 @@ jobs:
             user/app:1.0.0
 ```
 
+## Advanced usage
+
 ### Local registry
 
 For testing purposes you may need to create a [local registry](https://hub.docker.com/_/registry) to push images into.
@@ -298,40 +303,37 @@ jobs:
           cache-to: type=local,dest=/tmp/.buildx-cache
 ```
 
-### Tags and labels handling
+### Complete workflow
 
 If you come from [`v1`](https://github.com/docker/build-push-action/tree/releases/v1#readme) and you want an
 "automatic" tag management through Git reference and [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md)
 for labels, you will have to do it in a dedicated step [for now](https://github.com/docker/build-push-action/issues/116).
 
-The workflow below with the `Prepare` step will generate a
+The following workflow with the `Prepare` step will generate some [outputs](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjobs_idoutputs)
-[`tags` output](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjobs_idoutputs):
+to handle tags and labels based on GitHub actions events. This is just an example to show many cases that you
+might want to use:
 
-* On `pull_request` event with `refs/pull/2/merge` ref and `a123b57` sha:
+| Event           | Ref                           | Commit SHA | Docker Tag                         | Pushed |
-  * `user/app:pr-2`
+|-----------------|-------------------------------|------------|------------------------------------|--------|
-* On `push` event with `refs/heads/<default_branch>` ref and `676cae2` sha:
+| `schedule`      |                               |            | `nightly`                          | Yes    |
-  * `user/app:sha-676cae2`
+| `pull_request`  | `refs/pull/2/merge`           | `a123b57`  | `pr-2`                             | No     |
-  * `user/app:edge`
+| `push`          | `refs/heads/<default_branch>` | `676cae2`  | `sha-676cae2`, `edge`              | Yes    |
-* On `push` event with `refs/heads/dev` ref and `cf20257` sha:
+| `push`          | `/refs/heads/dev`             | `cf20257`  | `sha-676cae2`, `dev`               | Yes    |
-  * `user/app:sha-cf20257`
+| `push`          | `/refs/heads/my/branch`       | `a5df687`  | `sha-a5df687`, `my-branch`         | Yes    |
-  * `user/app:dev`
+| `push tag`      | `/refs/tags/v1.2.3`           |            | `v1.2.3`, `v1.2`, `v1`, `latest`   | Yes    |
-* On `push tags` event with `refs/tags/v1.2.3` ref and `9258794` sha:
-  * `user/app:sha-9258794`
-  * `user/app:v1.2.3`
-  * `user/app:v1.2`
-  * `user/app:v1`
-  * `user/app:latest`
 
 ```yaml
 name: ci
 
 on:
+  schedule:
+    - cron: '0 10 * * *' # everyday at 10am
   push:
-    branches: master
+    branches:
+      - '**'
     tags:
       - 'v*.*.*'
   pull_request:
-    branches: master
 
 jobs:
   docker:
@@ -346,7 +348,9 @@ jobs:
         run: |
           DOCKER_IMAGE=name/app
           VERSION=noop
-          if [[ $GITHUB_REF == refs/tags/* ]]; then
+          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')
@@ -356,7 +360,7 @@ jobs:
           elif [[ $GITHUB_REF == refs/pull/* ]]; then
             VERSION=pr-${{ github.event.number }}
           fi
-          if [ "${{ github.event_name }}" != "pull_request" ]; then
+          if [[ $GITHUB_REF != refs/tags/* ]] && [[ "${{ github.event_name }}" = "push"  ]]; then
             TAGS="${DOCKER_IMAGE}:sha-${GITHUB_SHA::8}"
           fi
           TAGS="${DOCKER_IMAGE}:${VERSION}"
@@ -368,69 +372,6 @@ jobs:
           echo ::set-output name=version::${VERSION}
           echo ::set-output name=tags::${TAGS}
           echo ::set-output name=created::$(date -u +'%Y-%m-%dT%H:%M:%SZ')
-      -
-        name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v1
-      -
-        name: Build and push
-        id: docker_build
-        uses: docker/build-push-action@v2
-        with:
-          context: .
-          file: ./Dockerfile
-          tags: ${{ steps.prep.outputs.tags }}
-          labels: |
-            org.opencontainers.image.created=${{ steps.prep.outputs.created }}
-            org.opencontainers.image.source=${{ github.repositoryUrl }}
-            org.opencontainers.image.version=${{ steps.prep.outputs.version }}
-            org.opencontainers.image.revision=${{ github.sha }}
-            org.opencontainers.image.licenses=${{ github.event.repository.license.name }}
-```
-
-### Complete workflow
-
-* On `pull_request` event, Docker image `name/app:edge` is **built**.
-* On `push` event, Docker image `name/app:edge` is **built** and **pushed** to DockerHub.
-* On `schedule` event, Docker image `name/app:nightly` is **built** and **pushed** to DockerHub.
-* On `push tags` event, Docker image `name/app:<version>` and `name/app:latest` is **built** and **pushed** to DockerHub.
-
-```yaml
-name: ci
-
-on:
-  schedule:
-    - cron: '0 10 * * *' # everyday at 10am
-  push:
-    branches: master
-    tags:
-      - 'v*.*.*'
-  pull_request:
-    branches: master
-
-jobs:
-  docker:
-    runs-on: ubuntu-latest
-    steps:
-      -
-        name: Checkout
-        uses: actions/checkout@v2
-      -
-        name: Prepare
-        id: prep
-        run: |
-          DOCKER_IMAGE=name/app
-          VERSION=edge
-          if [[ $GITHUB_REF == refs/tags/* ]]; then
-            VERSION=${GITHUB_REF#refs/tags/}
-          fi
-          if [ "${{ github.event_name }}" = "schedule" ]; then
-            VERSION=nightly
-          fi
-          TAGS="${DOCKER_IMAGE}:${VERSION}"
-          if [[ $VERSION =~ ^v[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$ ]]; then
-            TAGS="$TAGS,${DOCKER_IMAGE}:latest"
-          fi
-          echo ::set-output name=tags::${TAGS}
       -
         name: Set up QEMU
         uses: docker/setup-qemu-action@v1
@@ -446,6 +387,7 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
       -
         name: Build and push
+        id: docker_build
         uses: docker/build-push-action@v2
         with:
           context: .
@@ -453,6 +395,12 @@ jobs:
           platforms: linux/amd64,linux/arm64,linux/386
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.prep.outputs.tags }}
+          labels: |
+            org.opencontainers.image.created=${{ steps.prep.outputs.created }}
+            org.opencontainers.image.source=${{ github.repositoryUrl }}
+            org.opencontainers.image.version=${{ steps.prep.outputs.version }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.licenses=${{ github.event.repository.license.name }}
 ```
 
 ### Update DockerHub repo description