feedzai · ar-neto · Dec 9, 2025 · Nov 14, 2025 · reluzita · Nov 17, 2025
diff --git a/.github/ci_scripts_docs.md b/.github/ci_scripts_docs.md
@@ -0,0 +1,173 @@
+# CI Scripts Documentation
+
+This document describes the shell scripts and utilities used by the continuous integration workflows in the FairGBM project. These scripts handle setup, testing, and workflow orchestration across different platforms and build configurations. They are primarily called by the GitHub Actions workflows documented in [ci_workflows_docs.md](./ci_workflows_docs.md).
+
+The documentation below showcases each CI script's functionality.
+
+## append_comment.sh
+This script allows for updating a GitHub issue/PR comment by appending new text to an existing comment. It retrieves the original comment via the GitHub API, formats the new content, and patches the comment with the combined text.
+
+```mermaid
+graph TD
+G[fairgbm/.ci/append_comment.sh, variables: comment_id=$1, body=$2]
+    G --> H{if '$GITHUB_ACTIONS' is null}
+    H --true--> J1{If the number of arguments is different to 2}
+    H --false--> J2[echo 'Must be run inside GitHub Actions CI']
+    J1 --> L1(Retrieve 'old_comment_body' by making a request to the GIthub API to obtain the comment from the '$GITHUB_API_URL/repos/microsoft/LightGBM/issues/comments/$comment_id' endpoint)
+    J1 --true--> L2[echo 'echo 'Usage: $0 <COMMENT_ID> <BODY>'']
+
+    G --> M(Status check on 'Body')
+    M --> O[/Body/]
+    L1 --> N[/old_comment_body/]
+    N --> P('old_comment' and 'body' is formatted into data)
+    O --> P
+    P --> Q[/data/]
+    Q --> R(curl -sL \
+  -X PATCH \
+  -H 'Accept: application/vnd.github.v3+json' \
+  -H 'Authorization: token $SECRETS_WORKFLOW' \
+  -d '$data' \
+  '$GITHUB_API_URL/repos/microsoft/LightGBM/issues/comments/$comment_id')
+
+    R -->S[end]
+```
+
+## fairgbm/.ci/get_workflow_status.py
+```mermaid
+graph TD
+A[fairgbm/.ci/get_workflow_status.py]
+    A --> C[/trigger code phrase that starts the pipelines/]
+    C --> D(Obtains the most recent runs in the current PR via 'get_runs')
+    D --> E[/recent runs/]
+    E --> F(obtains status via 'get_status')
+    F --> G[/run status/]
+    G --> H{if 'status' is not 'in-progress'}
+    H --true--> I1[break]
+    H --> I2{if 'status' is failure'}
+    I2 --true--> J[exit]
+```
+
+## fairgbm/.ci/install_opencl.ps1
+Perform the OpenCL Installation
+
+## fairgbm/.ci/lint_r_code.R
+Linting utility for R code
+
+## fairgbm/.ci/rerun_workflow.sh
+Made to rerun a given workflow inside a pull request
+
+```mermaid
+graph TD
+A[fairgbm/.ci/rerun_workflow.sh, variables: workflow_id=$1, pr_number=$2, pr_branch=$3]
+    A --> B{If '$GITHUB_ACTIONS' is not empty}
+    B --false--> C2[echo 'Must be run inside GitHub Actions CI']
+    B --true--> C1{If the number of parameters is different than 3}
+    C1 --true--> D2[echo 'Usage: $0 <WORKFLOW_ID> <PR_NUMBER> <PR_BRANCH>']
+    C1 --false--> D1(obtain runs from the Github API)
+    D1 --> E[/runs/]
+    E --> F{If 'run''s length is above 0}
+    F --> G1(Make a request to prompt the workflow via the Gihtub API)
+    G1 --> H[end]
+```
+
+## fairgbm/.ci/run_rhub_solaris_checks.R
+Run Solaris checks
+
+## fairgbm/.ci/set_commit_status.sh
+Set a status with a given name to the specified commit.
+
+```mermaid
+graph TD
+A[fairgbm/.ci/set_commit_status.sh, variables: name=$1, status=$2, sha=$3]
+    A --> B{If '$GITHUB_ACTIONS' is not empty}
+    B --false--> C2[echo 'Must be run inside GitHub Actions CI']
+    B --true--> C1{If the number of parameters is different than 3}
+    C1 --true--> D2[echo 'Usage: $0 <NAME> <STATUS> <SHA>']
+    C1 --false--> D1(status check with the 'status' variable)
+    D1 --> E(Request to the Github API with the name and status variables)
+    A --> E
+    E --> F[/data/]
+    F --> G(Request to the Github API URL to prompt the commit status update with the 'data' and the 'sha' variables)
+    A --> G
+    G --> H[end]
+```
+
+## fairgbm/.ci/setup.sh
+Setup script for different platforms
+```mermaid
+graph TD
+A[fairgbm/.ci/setup.sh]
+  A --> B{If the OS is 'macos'}
+  B --true--> C1{if the compiler is 'clang'}
+  C1 --true--> D(brew install libomp)
+  C1 --true--> E{if 'Azure' is true}
+  E --true--> F1(sudo xcode-select -s /Applications/Xcode_10.3.app/Contents/Developer)
+  F1 --> F2[exit]
+  C1 --false--> G{if the task is not 'mpi'}
+  G --true--> H(brew install gcc)
+  B --true--> I{ig the task is 'mpi'}
+  I --true--> J1(brew install open-mpi)
+  B --true--> K1{If the task is 'swig'}
+  K1 --true--> L1(brew install swig)
+  B --true--> M(Download the miniforge conda script)
+
+  B --false--> N{If 'IN_UBUNTU_LATEST_CONTAINER' is true}
+  N --true--> O(install the necessary packages)
+  N --true--> P{if the compiler is 'clang'}
+  P --true--> Q(install clang)
+  B --false--> R{if the task is 'mpi'}
+  R --true--> S(install the necessary packages)
+  B --false--> T{if the task is 'gpu'}
+  T --true--> U1(install the relevant packages)
+  T --true--> U2{if 'IN_UBUNTU_LATEST_CONTAINER' is true}
+  U2 --true--> U3(install the relevant packages)
+  B --false--> V{if the task is 'cuda' or 'cuda_exp'}
+
+  D --> X{If task is different from 'r-package' or 'r-rchk'}
+  H --> X
+  J1 --> X
+  L1 --> X
+  M --> X
+  O --> X
+  Q --> X
+  S --> X
+  U1 --> X
+  U3 --> X
+  T --> X
+  V2 --> X
+  V4 --> X
+  V5 --> X
+  X4 --> X
+
+
+  V --true--> V2(install the relevant packages)
+  V --true--> V3{if the compiler is 'clang'}
+  V3 --true--> V4(install the relevant packages)
+  V --true--> V5(install the relevant packages)
+
+  B --false--> W{if 'SETUP_CONDA' is not false}
+  W --true--> W1(Download the relevant miniconda files)
+
+  X --true--> X1{if 'SETUP_CONDA' is not false}
+  X1 --true--> X3(install the conda package)
+  W1 --true--> X4(run the relevant scripts)
+```
+
+## fairgbm/.ci/test.sh
+Runs the test scripts for the different platforms and tasks
+
+
+## fairgbm/.ci/test_r_package.sh, fairgbm/.ci/test_r_package_valgrind.sh, fairgbm/.ci/test_r_package_windows.ps1 and fairgbm/.ci/test_windows.ps1
+These are test scripts for R in different platforms.
+
+## fairgbm/.ci/trigger_dispatch_run.sh
+Trigger manual workflow run by a dispatch event.
+
+## Scripts Status and Maintenance Notes
+
+### Legacy Scripts
+The following scripts reference the original LightGBM repository and may be candidates for removal or adaptation:
+- **append_comment.sh** - References `microsoft/LightGBM` in API calls; may not be actively used in FairGBM workflows
+- **get_workflow_status.py** - May be legacy from LightGBM fork
+- **rerun_workflow.sh** - Check if still used in current CI pipelines
+- **run_rhub_solaris_checks.R** - Solaris support may not be required for FairGBM
diff --git a/.github/ci_workflows_docs.md b/.github/ci_workflows_docs.md
@@ -0,0 +1,115 @@
+# CI Workflows Documentation
+
+This document describes the continuous integration (CI) workflows used in the FairGBM project. These workflows automate testing, validation, and publishing processes across different platforms and configurations. They can be triggered automatically on code changes (e.g. Pull Requests) or manually as needed.
+
+The workflows utilize GitHub Actions and coordinate with the scripts documented in [ci_scripts_docs.md](./ci_scripts_docs.md).
+
+The documentation below showcases each CI workflow's functionality.
+
+## .github/workflows/cuda.yml
+This script aims to test the project's CUDA support with the following different configurations:
+- Source build - Python 3.7, GCC compiler, CUDA 11.2.2
+- Pip install - Python 3.8, Clang compiler, CUDA 10.0
+- Wheel install - Python 3.9, GCC compiler, CUDA 9.0
+
+It triggers on pushing and creating pull requests to master.
+Set environment variables:
+  - github_actions: 'true'
+  - os_name: linux
+  - task: cuda
+  - conda_env: test-env 
+
+The steps are presented below:
+### 1. Setup or update software on host machine
+This step aims to setup the host machine with the necessary images and packages (Ubuntu image, Nvidia docker engine resources and docker)
+
+### 2. Setup and run tests
+This step aims to run the tests after the setup is done. This is achieved by setting up all the necessary variables and then running the docker image with any of the configuration combinations specified above.
+
+## .github/workflows/linkchecker.yml
+As the name suggests, this workflow is meant to check for broken links in the documentation. It is triggered with a cron schedule - once a day at 08:00am UTC. Otherwise, it can be triggered manually.
+
+Set environment variables:
+  - CONDA_ENV: test-env
+  - GITHUB_ACTIONS: 'true'
+  - OS_NAME: 'linux'
+  - PYTHON_VERSION: 3.9
+  - TASK: 'check-links'
+
+The steps are disclosed below:
+
+### 1. Checkout repository
+This step checks out the relevant repo's last 5 commits without any submodules. The shallow clone with 5 commits (instead of just 1) allows for basic git operations and link checking against recent changes while keeping checkout time fast. This behaviour is caused by the `fetch-depth: 5` and the `submodules: false`, respectively.
+
+### 2. Setup and run tests
+Exports the relevant environment variables, and runs the [`.ci/setup.sh`](/.github/ci_scripts_docs.md#fairgbmcisetupsh) , which will install the necessary dependencies, and the [`.ci/test.sh`](/.github/ci_scripts_docs.md#fairgbmcitestsh), which will perform the link checking.
+
+## .github/workflows/python_package.yml
+This workflow is meant to test  the FairGBM package the following configuration combinations:
+- sdist - Source distribution build (Python 3.9, Ubuntu)
+- bdist - Binary distribution build (Python 3.8, Ubuntu)
+- if-else - Tests conditional compilation paths (Python 3.8, Ubuntu)
+- mpi + pip - MPI parallel learning via pip (Python 3.7, Ubuntu)
+- mpi + wheel - MPI parallel learning via wheel (Python 3.7, Ubuntu)
+
+This workflow is triggered on pushing and opening pull requests to the `master` and the `main-fairgbm`.
+
+Set environment variables:
+- CONDA_ENV: test-env
+- GITHUB_ACTIONS: 'true'
+
+This workflow's steps are the following:
+
+### 1. Checkout repository
+Checkout the actions repository, while only fetching the last 5 commits. In this instance however, the submodules are also fetched.
+
+### 2. Setup and run tests
+The relevant environment variables are set. Subsequently, the [`.ci/setup.sh`](/.github/ci_scripts_docs.md#fairgbmcisetupsh) and the [`.ci/test.sh`](/.github/ci_scripts_docs.md#fairgbmcitestsh) tasks are executed.
+
+## .github/workflows/python_publish.yml
+This workflow is meant to publish a python package into pypi. It is triggered on push with tags that match the `v*` expression.
+
+The steps are explained below.
+
+### 2. Set up Python
+This step sets up python 3.7.
+
+### 3. Install dependencies
+As the name implies, this step install all the necesary dependencies.
+
+### 4. Build package
+This step [builds](https://pypi.org/project/build/) the designated python package.
+
+### 5. Publish package
+This step publishes the built package.
+
+## .github/workflows/static_analysis.yml
+This workflow performs static code analysis. It is triggered by pushing or creating pull requests to master.
+
+The set environment variables are the following:
+- COMPILER: 'gcc'
+- CONDA_ENV: test-env
+- GITHUB_ACTIONS: 'true'
+- OS_NAME: 'linux'
+- PYTHON_VERSION: 3.9
+
+The steps are explained below. 
+
+
+### 1. Checkout repository
+The first step in this task is to checkout the relevant action's repository.
+
+### 2. Setup and run tests
+The following step runs the [`.ci/setup.sh`](/.github/ci_scripts_docs.md#fairgbmcisetupsh) and the [`.ci/test.sh`](/.github/ci_scripts_docs.md#fairgbmcitestsh) scripts. In this instance, this means to that the Python/C++ code is verified for style guidelines.
+
+### r-check-docs
+The next task is geared towards documentation and its steps are explained below.
+
+### 1. Checkout repository
+As explained above, this step checks out the relevant actions repository, its 5 latest commits and its submodules.
+
+### 2. Install packages
+This step installs the relevant R packages
+
+### 3. Test documentation
+This step checks for any changes made to the R documentation.