cicd.yaml

# CI/CD workflow for the groundlight-sdk-python repository. We lint, test, deploy docs, and publish
# to pypi.
name: cicd
on:
  workflow_dispatch:
  push:

env:
  PYTHON_VERSION: "3.11"
  POETRY_VERSION: "1.7.1"
jobs:
  # Run our linter on every push to the repository.
  lint:
    runs-on: ubuntu-latest
    steps:
      - name: get code
        uses: actions/checkout@v4
      - name: install python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ env.PYTHON_VERSION }}
      - name: install poetry
        uses: snok/install-poetry@v1
        with:
          version: ${{ env.POETRY_VERSION }}
      - name: show python version ${{ env.PYTHON_VERSION }}
        run: |
          poetry run python --version
      - name: install linter dependencies
        run: |
          make install-lint
      - name: lint
        run: |
          make lint

  # Run integration tests against the API. For efficiency, we only run one version of python on
  # non-main branches.
  test-simple:
    runs-on: ubuntu-latest
    steps:
      - name: get code
        uses: actions/checkout@v4
      - name: install python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ env.PYTHON_VERSION }}
      - name: install poetry
        uses: snok/install-poetry@v1
        with:
          version: ${{ env.POETRY_VERSION }}
      - name: show python version ${{ env.PYTHON_VERSION }}
        run: |
          poetry run python --version
      - name: install dependencies (without extras)
        run: make install
      # TODO: Should we run all tests against the prod API?
      - name: run tests
        env:
          # This is associated with the "sdk-integ-test" user, credentials on 1password
          GROUNDLIGHT_API_TOKEN: ${{ secrets.GROUNDLIGHT_API_TOKEN }}
        run: make test-integ
      - name: run docs tests
        run: make test-docs
        env:
          # This is associated with the "sdk-test-prod" user, credentials on 1password
          GROUNDLIGHT_API_TOKEN: ${{ secrets.GROUNDLIGHT_API_TOKEN_PROD }}

  # Check that the docs build. (No broken links, etc.)
  test-docs:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: docs/
    steps:
      - name: Get code
        uses: actions/checkout@v4
      - name: Setup npm
        uses: actions/setup-node@v3
        with:
          node-version: 21
          cache: npm
      - name: Install dependencies
        run: npm install
      - name: Build website
        run: npm run build

  # Checks that the API reference docs built with sphinx build
  test-api-reference-docs:
    runs-on: ubuntu-latest
    steps:
      - name: get code
        uses: actions/checkout@v4
      - name: install python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ env.PYTHON_VERSION }}
      - name: Install poetry
        uses: snok/install-poetry@v1
        with:
          version: ${{ env.POETRY_VERSION }}
      - name: Setup npm
        uses: actions/setup-node@v3
        with:
          node-version: 21
          cache: npm
      - name: Install dependencies
        run: make install-sphinx-deps
      - name: Build API documentation
        run: |
          make apidocs

  # Run integration tests against the API (only on the main branch, though). The comprehensive
  # version runs a matrix of python versions for better coverage.
  # This tests runs on
  # - merges to main
  # - releases
  # - branch names ending with "-fulltest"
  test-comprehensive:
    if: >-
      github.ref == 'refs/heads/main' ||
      startsWith(github.ref, 'refs/tags/v') ||
      endsWith(github.ref, '-fulltest')
    needs:
      - test-simple
      - test-docs
    runs-on: ubuntu-latest
    strategy:
      # fail-fast=false works best for flaky tests with manual "retry failed".
      # Of course we should get rid of the race conditions that make these tests flaky.
      # Some AI lied to me and said I could just put "max-retry" here but you can't.
      fail-fast: false
      matrix:
        python-version: [
            #"3.6",   # Default on Ubuntu18.04 but openapi-generator fails
            # "3.7",  # Removed support as of 0.17
            # "3.8",  # Removed support as of 0.19
            "3.9",
            "3.10",
            "3.11",
            "3.12",
            "3.13",
          ]
        install_extras: [true, false]
    steps:
      - name: get code
        uses: actions/checkout@v4
        # Pillow may need these to function
      - name: install potential system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \
          libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk \
          libharfbuzz-dev libfribidi-dev libxcb1-dev
      - name: install modern python for poetry
        uses: actions/setup-python@v4
        with:
          # We use this python to install poetry -- we choose a modern version
          python-version: ${{ env.PYTHON_VERSION }}
      - name: install poetry
        uses: snok/install-poetry@v1
        with:
          version: ${{ env.POETRY_VERSION }}
      - name: install python for python-sdk venv
        uses: actions/setup-python@v4
        with:
          # We use this python for the sdk venv
          python-version: ${{ matrix.python-version }}
      - name: choose python version ${{ matrix.python-version }}
        run: |
          # set the environment to use the matrix python version
          poetry env use python${{ matrix.python-version }}
          poetry run python --version
      - name: show python version ${{ matrix.python-version }}
        run: |
          poetry run python --version
      - name: install dependencies
        run: make install
      - name: install extras
        if: matrix.install_extras
        run: make install-extras
      # TODO: Should we run all tests against the prod API?
      - name: run tests
        env:
          # This is associated with the "sdk-integ-test" user, credentials on 1password
          GROUNDLIGHT_API_TOKEN: ${{ secrets.GROUNDLIGHT_API_TOKEN }}
        run: make test-integ
      - name: run docs tests
        run: make test-docs
        env:
          # This is associated with the "sdk-test-prod" user, credentials on 1password
          GROUNDLIGHT_API_TOKEN: ${{ secrets.GROUNDLIGHT_API_TOKEN_PROD }}

  # Run the auto-formatter when we're not on the main branch or creating a release. This will push a
  # new commit to the PR branch if needed.
  format:
    if: startsWith(github.ref, 'refs/heads/') && github.ref != 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: get code
        uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}
      - name: install python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ env.PYTHON_VERSION }}
      - name: install poetry
        uses: snok/install-poetry@v1
        with:
          version: ${{ env.POETRY_VERSION }}
      - name: show python version ${{ env.PYTHON_VERSION }}
        run: |
          poetry run python --version
      - name: install linter dependencies
        run: |
          make install-lint
      - name: run formatter
        run: |
          make format
      - name: check for modified files
        id: git-check
        run: |
          git status
          echo ::set-output name=modified::$(if git diff-index --quiet HEAD --; then echo "false"; else echo "true"; fi)
      - name: push changes (if needed)
        if: steps.git-check.outputs.modified == 'true'
        run: |
          git config --global user.name 'Auto-format Bot'
          git config --global user.email 'autoformatbot@groundlight.ai'
          git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
          git commit -am "Automatically reformatting code"
          git push

  # Build and deploy the docs on all pushes to the `main` branch. Note that we don't require a code
  # release -- we don't want to couple documentation updates with code releases.
  # TODO: We'd like to build on pushes on any branch when docs/** changes. But then only deploy if
  # we are on the `main` branch and docs/** has changes.
  deploy-docs:
    if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
    needs:
      - test-comprehensive
      - test-api-reference-docs
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: docs/
    steps:
      - name: Get code
        uses: actions/checkout@v4
        # Pillow may need these to function
      - name: install potential system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \
          libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk \
          libharfbuzz-dev libfribidi-dev libxcb1-dev
      - name: Install poetry
        uses: snok/install-poetry@v1
        with:
          version: ${{ env.POETRY_VERSION }}
      - name: Setup npm
        uses: actions/setup-node@v3
        with:
          node-version: 21
          cache: npm
      - name: Install dependencies
        run: npm install
      - name: Install sphinx dependencies
        run: |
          cd ..
          make install-sphinx-deps
      - name: Build website
        run: |
          cd ..
          make docs-comprehensive
      - name: Deploy website (if on main branch)
        # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/build
          # Someday we might want to set the destination to a staging dir for PR's
          #destination_dir: staging
          # The following lines assign commit authorship to the official
          # GH-Actions bot for deploys to `gh-pages` branch:
          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
          # The GH actions bot is used by default if you didn't specify the two fields.
          # You can swap them out with your own user credentials.
          user_name: github-actions[bot]
          user_email: 41898282+github-actions[bot]@users.noreply.github.com

  # When a release is created on github (and comprehensive tests passed), publish the groundlight
  # package to public pypi.
  publish-python-package:
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    needs:
      - test-comprehensive
      - lint
    env:
      POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_PUBLISH_TOKEN }}
    steps:
      - name: get code
        uses: actions/checkout@v4
      - name: install potential system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev \
          libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk \
          libharfbuzz-dev libfribidi-dev libxcb1-dev
      - name: install python
        uses: actions/setup-python@v4
        with:
          python-version: ${{ env.PYTHON_VERSION }}
      - name: install poetry
        uses: snok/install-poetry@v1
        with:
          version: ${{ env.POETRY_VERSION }}
      - name: show python version ${{ env.PYTHON_VERSION }}
        run: |
          poetry run python --version
      - name: build package
        run: poetry build
      - name: configure poetry and publish
        run: poetry publish