UPGRADE.md

Upgrade notes

v1 to v2

• Input path is now called context for consistency with other Docker build tools
• path defaults to current git repository so checkout action is not required in a workflow
• Rename dockerfile input to file for consistency with other Docker build tools
• Rename always_pull input to pull for consistency with other Docker build tools
• Add builder input to be able to choose a builder instance through our setup-buildx action
• Add platforms input to support multi-platform builds
• Add allow input
• Add load input
• Add outputs input
• Add cache-from input (cache_froms removed)
• Add cache-to input
• Add secrets input
• Review tags input
• Remove repository input. See Simple workflow for migration
• Remove username, password and registry inputs. Login support moved to docker/login-action repo
• Remove tag_with_sha, tag_with_ref, add_git_labels inputs. See Tags with ref and Git labels for migration
• Handle Git context
• Add digest output

Simple workflow

# v1
steps:
  -
    name: Checkout code
    uses: actions/checkout@v2
  -
    name: Build and push Docker images
    uses: docker/build-push-action@v1
    with:
      username: ${{ secrets.DOCKER_USERNAME }}
      password: ${{ secrets.DOCKER_PASSWORD }}
      repository: myorg/myrepository
      always_pull: true
      build_args: arg1=value1,arg2=value2
      cache_froms: myorg/myrepository:latest
      tags: latest

# v2
steps:
  -
    name: Checkout code
    uses: actions/checkout@v2
  -
    name: Set up Docker Buildx
    uses: docker/setup-buildx-action@v1
  -
    name: Login to DockerHub
    uses: docker/login-action@v1
    with:
      username: ${{ secrets.DOCKER_USERNAME }}
      password: ${{ secrets.DOCKER_PASSWORD }}
  -
    name: Build and push
    uses: docker/build-push-action@v2
    with:
      context: .
      file: ./Dockerfile
      pull: true
      push: true
      build-args: |
        arg1=value1
        arg2=value2
      cache-from: type=registry,ref=myorg/myrepository:latest
      cache-to: type=inline
      tags: myorg/myrepository:latest

Tags with ref and Git labels

# v1
steps:
  -
    name: Checkout code
    uses: actions/checkout@v2
  -
    name: Build and push Docker images
    uses: docker/build-push-action@v1
    with:
      username: ${{ secrets.DOCKER_USERNAME }}
      password: ${{ secrets.DOCKER_PASSWORD }}
      repository: myorg/myrepository
      push: ${{ github.event_name != 'pull_request' }}
      tag_with_ref: true
      tag_with_sha: true
      add_git_labels: true

# v2
steps:
  -
    name: Checkout
    uses: actions/checkout@v2
  -
    name: Prepare
    id: prep
    run: |
      DOCKER_IMAGE=myorg/myrepository
      VERSION=edge
      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')
      elif [[ $GITHUB_REF == refs/pull/* ]]; then
        VERSION=pr-${{ github.event.number }}
      fi
      TAGS="${DOCKER_IMAGE}:${VERSION}"
      if [ "${{ github.event_name }}" = "push" ]; then
        TAGS="$TAGS,${DOCKER_IMAGE}:sha-${GITHUB_SHA::8}"
      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
  -
    name: Login to DockerHub
    if: github.event_name != 'pull_request'
    uses: docker/login-action@v1 
    with:
      username: ${{ secrets.DOCKER_USERNAME }}
      password: ${{ secrets.DOCKER_PASSWORD }}
  -
    name: Build and push
    uses: docker/build-push-action@v2
    with:
      context: .
      file: ./Dockerfile
      push: ${{ github.event_name != 'pull_request' }}
      tags: ${{ steps.prep.outputs.tags }}
      labels: |
        org.opencontainers.image.source=${{ github.event.repository.clone_url }}
        org.opencontainers.image.created=${{ steps.prep.outputs.created }}
        org.opencontainers.image.revision=${{ github.sha }}

You can also use the Docker meta action to handle tags and labels based on GitHub actions events and Git metadata. A workflow example is available in the README.