build-deploy.yml

# Build a Python package, Docker image and documentation (with Sphinx).
# If on `dev` branch or git tag (and the workflow is running in the 'acockburn/appdaemon' repository):
#  - Deploy Docker image to Docker Hub
#  - Deploy Python package to PyPi
name: Build and deploy

on:
  push:
    branches: ["**"]
    tags: ["*"]
  pull_request:
    branches: ["dev"]

# Cancel a currently running workflow from the same PR, branch or tag when a new workflow is triggered:
# Taken from https://stackoverflow.com/a/72408109
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

env:
  # github.repository as <account>/<repo>
  IMAGE_NAME: acockburn/appdaemon

jobs:
  build_docs:
    name: Documentation
    runs-on: ubuntu-latest
    permissions:
      packages: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # https://github.com/actions/setup-python
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: 'pip' # caching pip dependencies
          # Manually set 'doc-requirements.txt' as the file to use for dependencies, since `requirements.txt` contains runtime dependencies.
          cache-dependency-path: 'doc-requirements.txt'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r doc-requirements.txt
      # Invoke sphinx to build the documentation
      - name: Build documentation
        # Options:
        # -T Display the full traceback when an unhandled exception occurs
        # -E Don't use a saved environment (the structure caching all cross-references), but rebuild it completely.
        # -b Select the builder
        # -d Select a different cache directory
        # -D Override a configuration value set in the conf.py file
        # -W Turn warnings into errors. This means that the build stops at the first warning and sphinx-build exits with exit status 1
        # --keep-going With -W option, keep going processing when getting warnings to the end of build, and sphinx-build exits with exit status 1.
        run: python -m sphinx -T -E -b html -d _build/doctrees -D language=en -W --keep-going . _build/html
        working-directory: docs
      # Save the generated documentation as an artifact in Github
      - name: Upload documentation
        uses: actions/upload-artifact@v4
        with:
          name: python-doc-package
          path: docs/_build/

  # The Python package is required in the subsequent Docker image build
  build_package:
    name: Python package
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # https://github.com/actions/setup-python
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: 'pip' # caching pip dependencies
          # Manually set 'dev-requirements.txt' as the file to use for dependencies, since `requirements.txt` contains runtime dependencies.
          cache-dependency-path: 'dev-requirements.txt'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r dev-requirements.txt
      - name: Build Python package
        run: python -m build
      - name: Upload Python package
        uses: actions/upload-artifact@v4
        with:
          name: python-package
          path: dist/
      # Publish package only on Git tag
      - name: Publish package
        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
        uses: pypa/gh-action-pypi-publish@release/v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}

  # After building the Python package, build the Docker image
  build_image:
    name: Docker image
    runs-on: ubuntu-latest
    needs: ['build_package']
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Download Python package
        uses: actions/download-artifact@v4.1.8
        with:
          name: python-package
          path: dist/
      - name: Setup Docker buildx
        uses: docker/setup-buildx-action@v3.6.1
      # Login against a Docker registry (only with a tag or push on `dev` branch)
      # https://github.com/docker/login-action
      - name: Log into Docker Hub
        if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags') || github.ref_name == 'dev') && github.repository == 'AppDaemon/appdaemon'
        uses: docker/login-action@v3.3.0
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_PASSWORD }}
      # Extract metadata (tags, labels) for Docker
      # https://github.com/docker/metadata-action
      - name: Extract Docker metadata
        id: meta
        uses: docker/metadata-action@v5.5.1
        with:
          images: ${{ env.IMAGE_NAME }}
          # Customize the generation of Docker `latest` tag
          # Tag with `latest` the git tags that do not have a "pre-release" component in the end (e.g. `3.0.0`)
          # Avoid tagging with `latest` the git tag that have a "pre-release" component in the end (e.g. `3.0.0b1`)
          # If no git tag, fallback to branch or PR name
          tags: |
            # If the git tag follows PEP440 conventions, use it as the resulting docker tag (both releases and pre-releases)
            type=pep440,pattern={{version}}

            # If the git tag does NOT have a pre-release ending (e.g. `3.0.0`), it is a release version to be tagged as `latest`
            type=match,value=latest,pattern=pattern=^\d\.\d+\.\d+$

            # If no git tag is used, fallback to tagging with branch or PR name
            type=ref,event=branch
            type=ref,event=pr

      # Build and push Docker image with Buildx (push image only with a tag or push on `dev` branch)
      # https://github.com/docker/build-push-action
      - name: Build and push Docker image
        id: build-and-push
        uses: docker/build-push-action@v6.7.0
        with:
          context: .
          push: ${{github.event_name == 'push' && (startsWith(github.ref, 'refs/tags') || github.ref_name == 'dev') && github.repository == 'AppDaemon/appdaemon'}}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          platforms: linux/arm64/v8, linux/amd64, linux/arm/v7, linux/arm/v6
          cache-from: type=gha
          cache-to: type=gha,mode=max