esp-matter/.gitlab-ci.yml

stages:
    - docker_build
    - build
    - target_test
    - docs

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH

variables:
    ESP_MATTER_PATH: "$CI_PROJECT_DIR"
    BR_PATH: "$CI_PROJECT_DIR/esp-thread-br"
    IDF_GITHUB_ASSETS: "dl.espressif.com/github_assets"
    GIT_STRATEGY: fetch
    GIT_SUBMODULE_STRATEGY: none
    IDF_SKIP_CHECK_SUBMODULES: 1
    # This folder was on the runner host
    MATTER_CACHE_DIR: /cache/matter_build
    # This variable represents the latest idf version supported for the target branch.
    # Note: Do change this variable in case of idf version change MR.
    IDF_CHECKOUT_REF: "v5.4.1"
    # This variable represents the short hash of the connectedhomeip submodule.
    # Note: Do change this short hash on submodule update MRs.
    CHIP_SHORT_HASH: "87cf8e5030"
    DOCKER_IMAGE_NAME: "espressif/chip-idf"

.add_gitlab_ssh_key: &add_gitlab_ssh_key |
  mkdir -p ~/.ssh
  chmod 700 ~/.ssh
  echo -n $GITLAB_KEY >> ~/.ssh/id_rsa_base64
  base64 --decode --ignore-garbage ~/.ssh/id_rsa_base64 > ~/.ssh/id_rsa
  chmod 600 ~/.ssh/id_rsa
  echo -e "Host gitlab.espressif.cn\n\tStrictHostKeyChecking no\n" >> ~/.ssh/config

.get_build_caches: &get_build_caches
  - |
    if [ -d ${MATTER_CACHE_DIR}/ ]; then
      echo "get matter_build cache ..."
      mkdir -p .git/modules/
      mkdir -p ~/.cache/pip/
      mkdir -p ~/.cipd-cache-dir/
      mkdir -p ~/.espressif/dist/
      time rsync -a ${MATTER_CACHE_DIR}/git_modules/ .git/modules/ || true
      time rsync -a ${MATTER_CACHE_DIR}/cache_pip/ ~/.cache/pip/ || true
      time rsync -a ${MATTER_CACHE_DIR}/cipd_cache_dir/ ~/.cipd-cache-dir/ || true
      time rsync -a ${MATTER_CACHE_DIR}/espressif_dist/ ~/.espressif/dist/ || true
    fi

.update_build_caches: &update_build_caches
  - |
    if [ -d ${MATTER_CACHE_DIR}/ ]; then
      echo "update matter_build cache ..."
      time rsync -a .git/modules/ ${MATTER_CACHE_DIR}/git_modules/ || true
      time rsync -a ~/.cache/pip/ ${MATTER_CACHE_DIR}/cache_pip/ || true
      time rsync -a ~/.cipd-cache-dir/ ${MATTER_CACHE_DIR}/cipd_cache_dir/ || true
      time rsync -a ~/.espressif/dist/ ${MATTER_CACHE_DIR}/espressif_dist/ || true
    fi

.setup_ot_rcp: &setup_ot_rcp
  - cd ${IDF_PATH}
  - ./install.sh
  - . ./export.sh
  # fetch submodules
  - export PYTHONPATH=${IDF_PATH}/tools/ci/python_packages/:${PYTHONPATH}
  - pip install python-gitlab
  - cd examples/openthread/ot_rcp
  - idf.py set-target esp32h2
  - idf.py build

.setup_idf: &setup_idf
  - source ${IDF_PATH}/export.sh
  - export PYTHONPATH=${IDF_PATH}/tools/ci/python_packages/:${PYTHONPATH}
  - pip install python-gitlab
  - cd ${IDF_PATH}

.setup_matter: &setup_matter
   - cd ${ESP_MATTER_PATH}
   - ./install.sh --no-host-tool --no-bootstrap
   - rm -rf connectedhomeip/connectedhomeip  # Remove submodule directory
   - ln -s ${CHIP_SUBMODULE_PATH} connectedhomeip/connectedhomeip  # Create symlink to specified CHIP_SUBMODULE_PATH
   - cd ${ESP_MATTER_PATH}
   - . ./export.sh

.build_matter_examples: &build_matter_examples
    - export MATTER_EXAMPLES_PATH=$ESP_MATTER_PATH/connectedhomeip/connectedhomeip/examples
    - cd $MATTER_EXAMPLES_PATH/all-clusters-app/esp32
    - idf.py build
    - cd $MATTER_EXAMPLES_PATH/temperature-measurement-app/esp32
    - idf.py build
    - cd $MATTER_EXAMPLES_PATH/lock-app/esp32
    - idf.py build
    - cd $MATTER_EXAMPLES_PATH/pigweed-app/esp32
    - idf.py build
    - cd $MATTER_EXAMPLES_PATH/persistent-storage/esp32
    - idf.py build

.build_external_platform_example: &build_external_platform_example
    - rm -rf ${ESP_MATTER_PATH}/../platform
    - mkdir -p ${ESP_MATTER_PATH}/../platform
    - cp -r ${CHIP_SUBMODULE_PATH}/src/platform/ESP32 $ESP_MATTER_PATH/../platform/ESP32_custom
    - cp ${ESP_MATTER_PATH}/examples/common/external_platform/BUILD.gn $ESP_MATTER_PATH/../platform/ESP32_custom
    - cd ${ESP_MATTER_PATH}/examples/light
    - cp sdkconfig.defaults sdkconfig.defaults.backup
    - cp sdkconfig.defaults.ext_plat_ci sdkconfig.defaults
    - idf.py set-target esp32
    - idf.py build
    - cp sdkconfig.defaults.backup sdkconfig.defaults

.build_esp32c6_thread_example: &build_esp32c6_thread_example
    - cd $ESP_MATTER_PATH/examples/light
    - cp sdkconfig.defaults.esp32c6 sdkconfig.defaults.c6_backup
    - cp sdkconfig.defaults.c6_thread sdkconfig.defaults.esp32c6
    - idf.py set-target esp32c6
    - idf.py build
    - cp sdkconfig.defaults.c6_backup sdkconfig.defaults.esp32c6

.build_esp32c6_wifi_thread_example: &build_esp32c6_wifi_thread_example
    - cd $ESP_MATTER_PATH/examples/light
    - cp sdkconfig.defaults.esp32c6 sdkconfig.defaults.c6_backup
    - cp sdkconfig.defaults.c6_wifi_thread sdkconfig.defaults.esp32c6
    - idf.py set-target esp32c6
    - idf.py build
    - cp sdkconfig.defaults.c6_backup sdkconfig.defaults.esp32c6

.build_controller_otbr_example: &build_controller_otbr_example
    - cd $ESP_MATTER_PATH/examples/controller
    - idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.defaults.otbr" set-target esp32s3 build

build_image:
  stage: docker_build
  image: espressif/dind:1
  tags:
    - amd64
    - dind
    - internet
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_COMMIT_BRANCH == "main"
  before_script:
    - mkdir -p $HOME/.docker
    - echo $DOCKER_AUTH_CONFIG > $HOME/.docker/config.json
  script:
    - cd ${ESP_MATTER_PATH}
    - chip_head_commit=$(git rev-parse HEAD:connectedhomeip/connectedhomeip)
    - chip_head_in_readme=$(awk -F'[][]' '/commit \[.* of connectedhomeip/{print $2}' README.md)

    # Check both conditions and collect errors
    - validation_error=0
    - |
      if echo "$chip_head_commit" | grep -q "^${chip_head_in_readme}"; then
          echo "README.md is in sync with the connectedhomeip submodule"
      else
          echo "ERROR:Please update the README.md file with the latest commit hash of the connectedhomeip submodule"
          validation_error=1
      fi

    - |
      if echo "${chip_head_commit}" | grep -q "^${CHIP_SHORT_HASH}"; then
          echo "The CHIP_SHORT_HASH variable is set to correct value. Matches with current head commit"
      else
          echo "ERROR: The CHIP_SHORT_HASH seems to be incorrect or you have updated the submodule but not the CHIP_SHORT_HASH variable above"
          validation_error=1
      fi

    # Validate if we have the latest ZAP common and cluster select files
    # python3 is not installed in dind image, so we need to install it
    - apk add --no-cache python3
    # update the submodule to so that script runs based on that submodule
    - git submodule update --init --depth 1 connectedhomeip/connectedhomeip
    - python3 components/esp_matter/zap_common/generate_zap_common_files.py
    - python3 components/esp_matter/utils/cluster_select/generate_cluster_select_files.py
    - |
      if git diff --quiet components/esp_matter/zap_common; then
          echo "ZAP common files are up to date."
      else
          echo "ERROR: ZAP common files are not up to date."
          echo "       Please run ./components/esp_matter/zap_common/generate_zap_common_files.py and commit the changes."
          validation_error=1
      fi
    - |
      if git diff --quiet components/esp_matter/utils/cluster_select; then
          echo "Cluster select files are up to date."
      else
          echo "ERROR: Cluster select files are not up to date."
          echo "       Please run ./components/esp_matter/utils/cluster_select/generate_cluster_select_files.py and commit the changes."
          validation_error=1
      fi

    # Exit with collected error status
    - if [ $validation_error -ne 0 ]; then exit 1; fi

    - TAG="chip_${CHIP_SHORT_HASH}_idf_${IDF_VERSION}"
    - echo $TAG
    - |
      url="https://hub.docker.com/v2/repositories/${DOCKER_IMAGE_NAME}/tags/${TAG}"
      if wget -q --spider "$url"; then
          echo "No Differences detected. The docker image with ${TAG} is present in docker hub. Skipping docker build "
      else
          echo "Differences detected. The docker image with ${TAG} is not present on docker hub. Triggering docker build due to submdoule update or idf version change in CI."
          cd ${ESP_MATTER_PATH}/tools/docker/chip_idf
          docker build --build-arg CHIP_CHECKOUT_REF=${chip_head_commit} --build-arg IDF_CHECKOUT_REF=${IDF_VERSION} --tag ${DOCKER_IMAGE_NAME}:${TAG} .
          docker push ${DOCKER_IMAGE_NAME}:${TAG}
      fi
  parallel:
    matrix:
      # Change the idf version here in case of idf version change MR.
      - IDF_VERSION:
          - "v4.4.3"
          - "v5.4.1"

.build_examples_template:
  stage: build
  image: ${DOCKER_IMAGE_NAME}:chip_${CHIP_SHORT_HASH}_idf_${IDF_CHECKOUT_REF}
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" ||  $CI_PIPELINE_SOURCE == "push" || $CI_COMMIT_BRANCH == "main"
  tags:
    - build
    # runner: `sudo mkdir -p /cache/matter_build/`
    # gitlab-runner config: `volumes = ["/cache:/cache:rw"]`
    - matter_cache
  before_script:
    - *add_gitlab_ssh_key
    - *get_build_caches
    - *setup_idf
    - cd ${ESP_MATTER_PATH}
    - mkdir -p ${REPOS_PATH}
    - *setup_matter
    # update caches only when setup succeed
    - *update_build_caches
  variables:
    REPOS_PATH: "$CI_PROJECT_DIR/repos"
    IDF_CCACHE_ENABLE: 1


.build_managed_component_light_example:
  stage: build
  image: ${DOCKER_IMAGE_NAME}:chip_${CHIP_SHORT_HASH}_idf_${IDF_CHECKOUT_REF}
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" ||  $CI_PIPELINE_SOURCE == "push" || $CI_COMMIT_BRANCH == "main"
  tags:
    - build
    - matter_cache
  before_script:
    - *add_gitlab_ssh_key
    - *get_build_caches
    - *setup_idf
    - pip install 'idf-component-manager~=2.1.2'
    - cd ${ESP_MATTER_PATH}
    - mkdir -p ${REPOS_PATH}
    - *update_build_caches
  variables:
    REPOS_PATH: "$CI_PROJECT_DIR/repos"
    IDF_CCACHE_ENABLE: 1

build_esp_matter_examples_pytest_C6_idf_v5_1:
  extends:
        - .build_examples_template
  needs:
    - job: build_image
      optional: true
  artifacts:
    paths:
      - "examples/**/build*/size.json"
      - "examples/**/build*/build_log.txt"
      - "examples/**/build*/*.bin"
      - "examples/**/build*/flasher_args.json"
      - "examples/**/build*/config/sdkconfig.json"
      - "examples/**/build*/bootloader/*.bin"
      - "examples/**/build*/partition_table/*.bin"
    when: always
    expire_in: 4 days
  script:
    - cd ${ESP_MATTER_PATH}
    - pip install -r tools/ci/requirements-build.txt
    - python tools/ci/build_apps.py ./examples --pytest_c6

build_esp_matter_examples_pytest_H2_idf_v5_1:
  extends:
        - .build_examples_template
  needs:
    - job: build_image
      optional: true
  artifacts:
    paths:
      - "examples/**/build*/size.json"
      - "examples/**/build*/build_log.txt"
      - "examples/**/build*/*.bin"
      - "examples/**/build*/flasher_args.json"
      - "examples/**/build*/config/sdkconfig.json"
      - "examples/**/build*/bootloader/*.bin"
      - "examples/**/build*/partition_table/*.bin"
      - "${IDF_PATH}/examples/openthread/ot_rcp/build/*.bin"
      - "${IDF_PATH}/examples/openthread/ot_rcp/build/partition_table/*.bin"
      - "${IDF_PATH}/examples/openthread/ot_rcp/build/bootloader/*.bin"
      - "${IDF_PATH}/examples/openthread/ot_rcp/build/config/sdkconfig.json"
      - "${IDF_PATH}/examples/openthread/ot_rcp/build/flasher_args.json"
    when: always
    expire_in: 4 days
  script:
    - *setup_ot_rcp
    - cd ${ESP_MATTER_PATH}/examples/thread_border_router
    - touch main/MatterProjConfig.h
    # Use different discriminators for TBR and light examples
    - echo "#define CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR 0xE00" >> main/MatterProjConfig.h
    - echo "CONFIG_CHIP_PROJECT_CONFIG=\"main/MatterProjConfig.h\"" >> sdkconfig.defaults
    - cd ${ESP_MATTER_PATH}/examples/light
    - echo "CONFIG_ENABLE_MEMORY_PROFILING=y" >> sdkconfig.defaults
    - cd ${ESP_MATTER_PATH}
    - pip install -r tools/ci/requirements-build.txt
    - python tools/ci/build_apps.py ./examples --pytest_h2

build_esp_matter_examples_pytest_C2_idf_v5_1:
  extends:
        - .build_examples_template
  needs:
    - job: build_image
      optional: true
  artifacts:
    paths:
      - "examples/**/build*/size.json"
      - "examples/**/build*/build_log.txt"
      - "examples/**/build*/*.bin"
      - "examples/**/build*/flasher_args.json"
      - "examples/**/build*/config/sdkconfig.json"
      - "examples/**/build*/bootloader/*.bin"
      - "examples/**/build*/partition_table/*.bin"
    when: always
    expire_in: 4 days
  script:
    - cd ${ESP_MATTER_PATH}
    - pip install -r tools/ci/requirements-build.txt
    - python tools/ci/build_apps.py ./examples --pytest_c2

build_ext_plat_c6_thread_controller_examples:
  extends:
        - .build_examples_template
  needs:
    - job: build_image
      optional: true
  script:
    - *build_external_platform_example
    - *build_esp32c6_thread_example
    - *build_esp32c6_wifi_thread_example
    - *build_controller_otbr_example

build_esp_matter_examples:
  extends:
        - .build_examples_template
  needs:
    - job: build_image
      optional: true
  artifacts:
    paths:
      - "examples/**/build*/size.json"
      - "examples/**/build*/build_log.txt"
      - "examples/**/build*/*.bin"
      - "examples/**/build*/flasher_args.json"
      - "examples/**/build*/config/sdkconfig.json"
      - "examples/**/build*/bootloader/*.bin"
      - "examples/**/build*/partition_table/*.bin"
    when: always
    expire_in: 4 days
  script:
     # mfg_test_app needs an secure boot signing key, generating one here
    - cd ${ESP_MATTER_PATH}/examples/mfg_test_app
    - openssl genrsa -out secure_boot_signing_key.pem 3072

    # steps for external platform build for blemesh_bridge app
    - cd ${ESP_MATTER_PATH}/examples/bridge_apps/blemesh_bridge
    - cp sdkconfig.defaults sdkconfig.defaults.backup
    - cp sdkconfig.defaults.ext_plat_ci sdkconfig.defaults

    - cd ${ESP_MATTER_PATH}
    - pip install -r tools/ci/requirements-build.txt
    - python tools/ci/build_apps.py ./examples --no_pytest
      --parallel-count ${CI_NODE_TOTAL:-1}
      --parallel-index ${CI_NODE_INDEX:-1}
  parallel: 2

build_nopytest_remaining_examples_manual:
  extends:
        - .build_examples_template
  rules:
    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
      when: on_success
    - if: $CI_COMMIT_BRANCH != "main"
      when: manual
      allow_failure: true
  needs:
    - job: build_image
      optional: true
  artifacts:
    paths:
      - "examples/**/build*/size.json"
      - "examples/**/build*/build_log.txt"
      - "examples/**/build*/*.bin"
      - "examples/**/build*/flasher_args.json"
      - "examples/**/build*/config/sdkconfig.json"
      - "examples/**/build*/bootloader/*.bin"
      - "examples/**/build*/partition_table/*.bin"
    when: always
    expire_in: 4 days
  script:
    - cd ${ESP_MATTER_PATH}
    - pip install -r tools/ci/requirements-build.txt
    - python tools/ci/build_apps.py ./examples --no_pytest_remaining
      --parallel-count ${CI_NODE_TOTAL:-1}
      --parallel-index ${CI_NODE_INDEX:-1}
  parallel: 2


build_esp_matter_examples_pytest_C3_idf_v4_4:
  extends:
        - .build_examples_template
  image: ${DOCKER_IMAGE_NAME}:chip_${CHIP_SHORT_HASH}_idf_${IDF_CHECKOUT_REF}
  needs:
    - job: build_image
      optional: true
  artifacts:
    paths:
      - "examples/**/build*/size.json"
      - "examples/**/build*/build_log.txt"
      - "examples/**/build*/*.bin"
      - "examples/**/build*/flasher_args.json"
      - "examples/**/build*/config/sdkconfig.json"
      - "examples/**/build*/bootloader/*.bin"
      - "examples/**/build*/partition_table/*.bin"
    when: always
    expire_in: 4 days
  script:
    - cd ${ESP_MATTER_PATH}
    # idf v4.4 requires jinja < 3.1 so lets install the dependencies for idf v4.4
    - pip install -r requirements_idf_v4.4.txt
    - pip install -r tools/ci/requirements-build.txt
    - python tools/ci/build_apps.py ./examples --pytest_c3
  variables:
    IDF_CHECKOUT_REF: "v4.4.3"

pytest_esp32c3_esp_matter_dut:
  stage: target_test
  image: ${DOCKER_IMAGE_NAME}:chip_${CHIP_SHORT_HASH}_idf_${IDF_CHECKOUT_REF}
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_COMMIT_BRANCH == "main" || $CI_PIPELINE_SOURCE == "push"
  needs:
    - build_esp_matter_examples_pytest_C3_idf_v4_4
  script:
    - cd ${ESP_MATTER_PATH}
    - rm -rf connectedhomeip/connectedhomeip
    - ln -s ${CHIP_SUBMODULE_PATH} connectedhomeip/connectedhomeip
    - pip install -r tools/ci/requirements-pytest.txt
    - pytest examples/ --target esp32c3 -m esp_matter_dut --junitxml=XUNIT_RESULT.xml
  tags: ["esp32c3", "esp_matter_dut"]
  variables:
    IDF_CHECKOUT_REF: "v4.4.3"

pytest_esp32c6_esp_matter_dut:
  stage: target_test
  image: ${DOCKER_IMAGE_NAME}:chip_${CHIP_SHORT_HASH}_idf_${IDF_CHECKOUT_REF}
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event' ||  $CI_COMMIT_BRANCH == "main" || $CI_PIPELINE_SOURCE == "push"
  needs:
    - build_esp_matter_examples_pytest_C6_idf_v5_1
  script:
    - cd ${ESP_MATTER_PATH}
    - rm -rf connectedhomeip/connectedhomeip
    - ln -s ${CHIP_SUBMODULE_PATH} connectedhomeip/connectedhomeip
    - pip install -r tools/ci/requirements-pytest.txt
    - pytest examples/ --target esp32c6 -m esp_matter_dut --junitxml=XUNIT_RESULT.xml
  tags: ["esp32c6", "esp_matter_dut"]

pytest_esp32c2_esp_matter_dut:
  stage: target_test
  image: ${DOCKER_IMAGE_NAME}:chip_${CHIP_SHORT_HASH}_idf_${IDF_CHECKOUT_REF}
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event' ||  $CI_COMMIT_BRANCH == "main" || $CI_PIPELINE_SOURCE == "push"
  needs:
    - build_esp_matter_examples_pytest_C2_idf_v5_1
  script:
    - cd ${ESP_MATTER_PATH}
    - rm -rf connectedhomeip/connectedhomeip
    - ln -s ${CHIP_SUBMODULE_PATH} connectedhomeip/connectedhomeip
    - pip install -r tools/ci/requirements-pytest.txt
    - pytest examples/ --target esp32c2 -m esp_matter_dut --junitxml=XUNIT_RESULT.xml --baud 74880
  tags: ["esp32c2", "esp_matter_dut"]

pytest_esp32h2_esp_matter_dut:
  stage: target_test
  image: ${DOCKER_IMAGE_NAME}:chip_${CHIP_SHORT_HASH}_idf_${IDF_CHECKOUT_REF}
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_COMMIT_BRANCH == "main" || $CI_PIPELINE_SOURCE == "push"
  needs:
    - build_esp_matter_examples_pytest_H2_idf_v5_1
  script:
    - cd ${ESP_MATTER_PATH}
    - rm -rf connectedhomeip/connectedhomeip
    - ln -s ${CHIP_SUBMODULE_PATH} connectedhomeip/connectedhomeip
    - pip install -r tools/ci/requirements-pytest.txt
    - pytest examples/ --target esp32h2 -m esp_matter_dut --junitxml=XUNIT_RESULT.xml
  tags: ["esp32h2", "esp_matter_dut"]

build_upstream_examples:
    extends:
        - .build_examples_template
    when: manual
    script:
        - *build_matter_examples

build_managed_component_light:
    extends:
        - .build_managed_component_light_example
    needs:
      - job: build_image
        optional: true
    script:
        - cd ${ESP_MATTER_PATH}/examples/managed_component_light
        - idf.py set-target esp32c3
        - idf.py build

build_docs:
    stage: build
    image: $CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.1:1-1
    rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_COMMIT_BRANCH == "main" || $CI_PIPELINE_SOURCE == "push"
    tags:
        - build
    variables:
        ESP_DOCS_LATEST_BRANCH_NAME: "main"
    artifacts:
        when: always
        paths:
            - docs/_build/*/*/*.txt
            - docs/_build/*/*/html/*
        expire_in: 1 days
    script:
        - cd docs
        - pip install -r requirements.txt
        - build-docs -t esp32 esp32s3 esp32c2 esp32c3 esp32c6 esp32h2 esp32p4 -l en

.deploy_docs_template:
    stage: docs
    image: $CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.1:1-1
    tags:
        - docs
    needs:
        - build_docs
    variables:
        ESP_DOCS_LATEST_BRANCH_NAME: "main"
    script:
        - source ${CI_PROJECT_DIR}/docs/utils.sh
        - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
        - export GIT_VER=$(git describe --always)
        - pip install -r ${CI_PROJECT_DIR}/docs/requirements.txt
        - deploy-docs

deploy_docs_preview:
    extends:
        - .deploy_docs_template
    rules:
      - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_COMMIT_BRANCH == "main" || $CI_PIPELINE_SOURCE == "push"
    variables:
        TYPE: "preview"
        DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/"
        DOCS_DEPLOY_PRIVATEKEY: "$DOCS_PREVIEW_DEPLOY_KEY"
        DOCS_DEPLOY_SERVER: "$DOCS_PREVIEW_SERVER"
        DOCS_DEPLOY_SERVER_USER: "$DOCS_PREVIEW_SERVER_USER"
        DOCS_DEPLOY_PATH: "$DOCS_PREVIEW_PATH"
        DOCS_DEPLOY_URL_BASE: "https://$DOCS_PREVIEW_SERVER_URL/$DOCS_PREVIEW_PATH"

deploy_docs_production:
    extends:
        - .deploy_docs_template
    only:
      refs:
        - main
        - /^release\/v.*$/
    variables:
        TYPE: "preview"
        DOCS_BUILD_DIR: "${CI_PROJECT_DIR}/docs/_build/"
        DOCS_DEPLOY_PRIVATEKEY: "$DOCS_PROD_DEPLOY_KEY"
        DOCS_DEPLOY_SERVER: "$DOCS_PROD_SERVER"
        DOCS_DEPLOY_SERVER_USER: "$DOCS_PROD_SERVER_USER"
        DOCS_DEPLOY_PATH: "$DOCS_PROD_PATH"
        DOCS_DEPLOY_URL_BASE: "https://$DOCS_PROD_SERVER/$DOCS_PROD_PATH"