ci_cd.yml

name: GitHub CI

# run only on main branch.  This avoids duplicated actions on PRs
on:
  pull_request:
  push:
    tags:
      - "*"
    branches:
      - main
  workflow_dispatch:
    inputs:
      api_branch:
        description: "Branch of the 'ansys-api-acp' repository used during the build."
        required: false
      docker_image_suffix:
        description: "Suffix of the 'acp' docker image used for testing. For example, ':latest', or '@sha256:<hash>' (without quotes)."
        required: false

env:
  MAIN_PYTHON_VERSION: "3.12"
  PACKAGE_NAME: "ansys-acp-core"
  DOCUMENTATION_CNAME: "acp.docs.pyansys.com"
  API_BRANCH: ${{ github.event.inputs.api_branch || '' }}
  DOCKER_IMAGE_NAME: "ghcr.io/ansys/acp${{ github.event.inputs.docker_image_suffix || ':latest' }}"

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  code-style:
    name: "Pre-commit Check"
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}

      - name: Pip cache
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: pip-${{ runner.os }}-${{ hashFiles('poetry.lock') }}-precommit
          restore-keys: |
            pip-${{ runner.os }}

      # pre-commit needs all dev dependencies, since it also checks the test and example files
      - name: Install library, with all optional groups
        run: |
          pip install -U pip
          pip install 'poetry!=1.7.0'
          poetry install --with dev,test --all-extras

      - name: Build API package from custom branch
        if: "${{ env.API_BRANCH != '' }}"
        run: |
          python3.10 -m venv .api_builder_venv
          . .api_builder_venv/bin/activate
          python -m pip install --upgrade pip wheel
          mkdir .api_package
          python -m pip wheel --no-deps --wheel-dir .api_package git+https://github.com/ansys/ansys-api-acp.git@${{ env.API_BRANCH }}

      - name: Install custom API branch package
        if: "${{ env.API_BRANCH != '' }}"
        # The --no-deps flag is added since this may cause dependency conflicts with
        # other transitive dependencies. For example, when a newer version of protobuf
        # is installed.
        run: |
          poetry run pip install --no-deps --force-reinstall .api_package/*.whl

      - name: Run pre-commit
        run: |
          poetry run pre-commit run --all-files || ( git status --short ; git diff ; exit 1 )

  doc-style:
    name: "Documentation style"
    runs-on: ubuntu-latest
    steps:
      - uses: ansys/actions/doc-style@v8
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

  build-wheelhouse:
    name: "Build wheelhouse"
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python-version: ['3.10', '3.11', '3.12']
        should-release:
          - ${{ github.event_name == 'push' && contains(github.ref, 'refs/tags') }}
        exclude:
          - should-release: false
            os: macos-latest
    steps:
      - name: "Build wheelhouse and perform smoke test"
        uses: ansys/actions/build-wheelhouse@v8
        with:
          library-name: ${{ env.PACKAGE_NAME }}
          operating-system: ${{ matrix.os }}
          python-version: ${{ matrix.python-version }}

  check-vulnerabilities:
    name: "Check library vulnerabilities"
    runs-on: ubuntu-latest
    steps:
      - uses: ansys/actions/check-vulnerabilities@v8.1
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}
          token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}
          python-package-name: 'ansys-acp-core'
          dev-mode: ${{ github.ref != 'refs/heads/main' }}
          extra-targets: "plotting"

  testing-direct-launch:
    name: Testing with direct launch mode
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      - uses: actions/checkout@v4
      - name: Login in Github Container registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      # Python version is determined by the base image
      - name: Build docker image
        run: docker build -t test_runner -f dockerfiles/DirectLaunchTest.Dockerfile .
      - name: Run tests
        run: |
          docker run \
          --mount type=bind,source="$(pwd)",target=/home/container/pyacp \
          -u $(id -u):$(id -g) \
          -e ANSYSLMD_LICENSE_FILE=$ANSYSLMD_LICENSE_FILE \
          test_runner
        env:
          ANSYSLMD_LICENSE_FILE: "1055@${{ secrets.LICENSE_SERVER }}"
      - name: "Upload coverage to Codecov"
        uses: codecov/codecov-action@v5
        env:
          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
        with:
          files: coverage.xml
          flags: 'direct-launch,server-latest'

  testing-minimum-deps:
    name: Testing with minimum dependencies
    runs-on: ubuntu-latest
    timeout-minutes: 30
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]
        server-version: ["latest"]
    steps:
      - uses: actions/checkout@v4

      - name: Pip cache
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: pip-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('poetry.lock') }}-testing-minimum-deps
          restore-keys: |
            pip-${{ runner.os }}-${{ matrix.python-version }}

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: |
            3.10
            ${{ matrix.python-version }}

      - name: Install library, with only the 'main' group
        run: |
          pip install -U pip
          pip install 'poetry!=1.7.0'
          poetry install --only main

      - name: Check that PyACP can be imported
        run: |
          poetry run python -c "import ansys.acp.core"

      - name: Install the 'test' group
        run: |
          poetry install --with test

      - name: Build API package from custom branch
        if: "${{ env.API_BRANCH != '' }}"
        run: |
          python3.10 -m venv .api_builder_venv
          . .api_builder_venv/bin/activate
          python -m pip install --upgrade pip wheel
          mkdir .api_package
          python -m pip wheel --no-deps --wheel-dir .api_package git+https://github.com/ansys/ansys-api-acp.git@${{ env.API_BRANCH }}

      - name: Install custom API branch package
        if: "${{ env.API_BRANCH != '' }}"
        # The --no-deps flag is added since this may cause dependency conflicts with
        # other transitive dependencies. For example, when a newer version of protobuf
        # is installed.
        run: |
          poetry run pip install --no-deps --force-reinstall .api_package/*.whl

      - name: Login in Github Container registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Unit testing
        working-directory: tests/unittests
        run: |
          docker pull $IMAGE_NAME
          poetry run pytest -v --license-server=1055@$LICENSE_SERVER --no-server-log-files --docker-image=$IMAGE_NAME --cov=ansys.acp.core --cov-report=term --cov-report=xml --cov-report=html -m "not plotting"
        env:
          LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}
          IMAGE_NAME: ghcr.io/ansys/acp:${{ matrix.server-version }}

      - name: "Upload coverage to Codecov"
        uses: codecov/codecov-action@v5
        env:
          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
        with:
          files: coverage.xml
          flags: 'server-${{ matrix.server-version }},python-${{ matrix.python-version }},minimum-deps'

  testing:
    name: Testing
    runs-on: ubuntu-latest
    timeout-minutes: 30
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]
        server-version: ["latest"]
        include:
          - python-version: "3.12"
            server-version: "2024R2"
          - python-version: "3.12"
            server-version: "2025R1"
          - python-version: "3.12"
            server-version: "2025R2"

    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: |
            3.10
            ${{ matrix.python-version }}

      - name: Pip cache
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: pip-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('poetry.lock') }}-testing
          restore-keys: |
            pip-${{ runner.os }}-${{ matrix.python-version }}

      - name: Install library, with test group
        run: |
          pip install -U pip
          pip install 'poetry!=1.7.0'
          poetry install --with test --extras plotting

      - name: Build API package from custom branch
        if: "${{ env.API_BRANCH != '' }}"
        run: |
          python3.10 -m venv .api_builder_venv
          . .api_builder_venv/bin/activate
          python -m pip install --upgrade pip wheel
          mkdir .api_package
          python -m pip wheel --no-deps --wheel-dir .api_package git+https://github.com/ansys/ansys-api-acp.git@${{ env.API_BRANCH }}

      - name: Install custom API branch package
        if: "${{ env.API_BRANCH != '' }}"
        # The --no-deps flag is added since this may cause dependency conflicts with
        # other transitive dependencies. For example, when a newer version of protobuf
        # is installed.
        run: |
          poetry run pip install --no-deps --force-reinstall .api_package/*.whl

      - name: Login in Github Container registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Unit testing
        working-directory: tests/unittests
        run: |
          docker pull $IMAGE_NAME
          poetry run pytest -v --license-server=1055@$LICENSE_SERVER --no-server-log-files --docker-image=$IMAGE_NAME --cov=ansys.acp.core --cov-report=term --cov-report=xml --cov-report=html
        env:
          LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}
          IMAGE_NAME: ghcr.io/ansys/acp:${{ matrix.server-version }}

      - name: "Upload coverage to Codecov"
        uses: codecov/codecov-action@v5
        env:
          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
        with:
          files: coverage.xml
          flags: 'server-${{ matrix.server-version }},python-${{ matrix.python-version }}'

      - name: Benchmarks
        working-directory: tests/benchmarks
        run: |
          poetry run pytest -v --license-server=1055@$LICENSE_SERVER --no-server-log-files --docker-image=$IMAGE_NAME --build-benchmark-image --benchmark-json benchmark_output.json --benchmark-group-by=fullname ${{ (matrix.python-version == env.MAIN_PYTHON_VERSION && matrix.server-version == 'latest') && ' ' || '--validate-benchmarks-only' }}
        env:
          LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}
          IMAGE_NAME: ghcr.io/ansys/acp:${{ matrix.server-version }}

      - name: Store benchmark result
        uses: benchmark-action/github-action-benchmark@v1
        with:
          name: 'PyACP benchmarks'
          tool: 'pytest'
          output-file-path: tests/benchmarks/benchmark_output.json
          benchmark-data-dir-path: benchmarks
          auto-push: true
          github-token: ${{ secrets.GITHUB_TOKEN }}
        if: matrix.python-version == env.MAIN_PYTHON_VERSION && matrix.server-version == 'latest' && github.ref == 'refs/heads/main'

  doctest:
    name: Test documentation snippets
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}

      - name: Pip cache
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: pip-${{ runner.os }}-${{ hashFiles('poetry.lock') }}-doctest
          restore-keys: |
            pip-${{ runner.os }}

      - name: Install library, with test,dev groups
        run: |
          pip install -U pip
          pip install 'poetry!=1.7.0'
          poetry install --with test,dev --all-extras

      - name: Build API package from custom branch
        if: "${{ env.API_BRANCH != '' }}"
        run: |
          python3.10 -m venv .api_builder_venv
          . .api_builder_venv/bin/activate
          python -m pip install --upgrade pip wheel
          mkdir .api_package
          python -m pip wheel --no-deps --wheel-dir .api_package git+https://github.com/ansys/ansys-api-acp.git@${{ env.API_BRANCH }}

      - name: Install custom API branch package
        if: "${{ env.API_BRANCH != '' }}"
        # The --no-deps flag is added since this may cause dependency conflicts with
        # other transitive dependencies. For example, when a newer version of protobuf
        # is installed.
        run: |
          poetry run pip install --no-deps --force-reinstall .api_package/*.whl

      - name: Login in Github Container registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Install OS packages
        run: |
          sudo apt update
          sudo apt-get install pandoc xvfb

      - name: Configure Local Product Launcher for ACP
        working-directory: tests/unittests
        run: >
          poetry run
          ansys-launcher configure ACP docker_compose
          --image_name_acp=${{ env.DOCKER_IMAGE_NAME }}
          --image_name_filetransfer=ghcr.io/ansys/tools-filetransfer:latest
          --license_server=1055@$LICENSE_SERVER
          --keep_volume=False
          --overwrite_default
        env:
          LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}

      - name: Run doctest
        run: |
          docker pull $IMAGE_NAME
          docker pull ghcr.io/ansys/tools-filetransfer:latest
          xvfb-run poetry run make -C doc doctest
        env:
          LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}
          IMAGE_NAME: ${{ env.DOCKER_IMAGE_NAME }}
          PYACP_DOC_SKIP_GALLERY: "true"
          PYACP_DOC_SKIP_API: "true"

  docs:
    name: Build Documentation
    runs-on: ubuntu-latest
    timeout-minutes: 30
    continue-on-error: true
    strategy:
      matrix:
        build_type: ["quick", "full"]

    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}

      - name: Pip cache
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: pip-${{ runner.os }}-${{ hashFiles('poetry.lock') }}-docs
          restore-keys: |
            pip-${{ runner.os }}

      - name: Login in Github Container registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          password: ${{ secrets.PYANSYS_CI_BOT_PACKAGE_TOKEN }}
        if: ${{ matrix.build_type == 'full' }}

      - name: Install OS packages
        run: |
          sudo apt update
          sudo apt-get install pandoc xvfb

      - name: Install library, with dev group
        run: |
          pip install -U pip
          pip install 'poetry!=1.7.0'
          poetry install --with dev --all-extras

      - name: Build API package from custom branch
        if: "${{ env.API_BRANCH != '' }}"
        run: |
          python3.10 -m venv .api_builder_venv
          . .api_builder_venv/bin/activate
          python -m pip install --upgrade pip wheel
          mkdir .api_package
          python -m pip wheel --no-deps --wheel-dir .api_package git+https://github.com/ansys/ansys-api-acp.git@${{ env.API_BRANCH }}

      - name: Install custom API branch package
        if: "${{ env.API_BRANCH != '' }}"
        # The --no-deps flag is added since this may cause dependency conflicts with
        # other transitive dependencies. For example, when a newer version of protobuf
        # is installed.
        run: |
          poetry run pip install --no-deps --force-reinstall .api_package/*.whl

      - name: Configure Local Product Launcher for ACP
        run: >
          poetry run
          ansys-launcher configure ACP docker_compose
          --image_name_acp=${{ env.DOCKER_IMAGE_NAME }}
          --image_name_filetransfer=ghcr.io/ansys/tools-filetransfer:latest
          --license_server=1055@$LICENSE_SERVER
          --keep_volume=False
          --overwrite_default
        env:
          LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}
        if: ${{ matrix.build_type == 'full' }}

      - name: Launch MAPDL and DPF servers via docker-compose
        run: |
          docker compose -f ./docker-compose/docker-compose-extras.yaml up -d
        env:
          ANSYSLMD_LICENSE_FILE: "1055@${{ secrets.LICENSE_SERVER }}"
          ANSYS_DPF_ACCEPT_LA: "Y"
        if: ${{ matrix.build_type == 'full' }}

      - name: Build HTML
        run: |
          xvfb-run poetry run make -C doc html SPHINXOPTS="-W --keep-going -v $SPHINXOPT_NITPICKY"
        env:
          PYMAPDL_IP: "127.0.0.1"
          PYMAPDL_PORT: "50557"
          PYMAPDL_START_INSTANCE: "FALSE"
          PYDPF_COMPOSITES_DOCKER_CONTAINER_PORT: "50558"
          SPHINXOPT_NITPICKY: ${{ matrix.build_type == 'quick' && ' ' || '-n' }}
          PYACP_DOC_SKIP_GALLERY: ${{ matrix.build_type == 'quick' && 'true' || 'false' }}
          PYACP_DOC_SKIP_API: ${{ matrix.build_type == 'quick' && 'true' || 'false' }}

      - name: Stop and clean up MAPDL and DPF servers
        run: |
          docker compose -f ./docker-compose/docker-compose-extras.yaml down -v

      - name: Upload HTML Documentation
        uses: actions/upload-artifact@v4
        with:
          name: documentation-html
          path: doc/build/html
          retention-days: 7
        if: ${{ matrix.build_type == 'full' }}

      - name: Install OS packages for PDF build
        run: |
          sudo apt update
          sudo apt install build-essential zip pandoc texlive-latex-extra latexmk texlive-pstricks
        if: ${{ matrix.build_type == 'full' }}

      - name: Restart MAPDL and DPF servers via docker compose
        run: |
          docker compose -f ./docker-compose/docker-compose-extras.yaml up -d
        env:
          ANSYSLMD_LICENSE_FILE: "1055@${{ secrets.LICENSE_SERVER }}"
          ANSYS_DPF_ACCEPT_LA: "Y"
        if: ${{ matrix.build_type == 'full' }}

      - name: Build PDF Documentation
        run: xvfb-run poetry run make -C doc pdf
        if: ${{ matrix.build_type == 'full' }}

      - name: Upload PDF Documentation
        uses: actions/upload-artifact@v4
        with:
          name: documentation-pdf
          path: doc/build/latex/ansys-acp-core.pdf
          retention-days: 7
        if: ${{ matrix.build_type == 'full' }}

  build:
    name: Build library
    runs-on: ubuntu-latest
    needs: [code-style, testing, testing-minimum-deps, testing-direct-launch, doc-style, docs, build-wheelhouse, doctest] # TODO: add check-vulnerabilities once we know it works on main
    timeout-minutes: 30
    steps:
      - name: Build library source and wheel artifacts
        uses: ansys/actions/build-library@v8
        with:
          library-name: ${{ env.PACKAGE_NAME }}
          python-version: ${{ env.MAIN_PYTHON_VERSION }}

  release:
    name: Release project
    if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
    needs: [build]
    runs-on: ubuntu-latest
    steps:
      - name: Release to the public PyPI repository
        uses: ansys/actions/release-pypi-public@v8
        with:
          library-name: ${{ env.PACKAGE_NAME }}
          twine-username: "__token__"
          twine-token: ${{ secrets.PYPI_TOKEN }}

      - name: Release to GitHub
        uses: ansys/actions/release-github@v8
        with:
          library-name: ${{ env.PACKAGE_NAME }}

  upload_docs_dev:
    name: "Upload dev documentation"
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    needs: [build]
    steps:
      - name: Deploy the latest documentation
        uses: ansys/actions/doc-deploy-dev@v8
        with:
          cname: ${{ env.DOCUMENTATION_CNAME }}
          token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}
          force-orphan: false
          bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}

  upload_docs_release:
    name: Upload release documentation
    if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
    runs-on: ubuntu-latest
    needs: [release]
    steps:
      - name: Deploy the stable documentation
        uses: ansys/actions/doc-deploy-stable@v8
        with:
          cname: ${{ env.DOCUMENTATION_CNAME }}
          token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}
          bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}