.. _ci-templates-helpers:

ci-templates-helpers
=====================

Every container built with ci-templates includes some common bash functions
that can be used by scripts in your container.

To access the functions, source the `ci-templates-helper.sh` like this:

.. code-block:: bash

   source "${FDO_CI_BASH_HELPERS}"

.. note:: `FDO_CI_BASH_HELPERS` is an environment variable indicating the path
           where `ci-templates-helper.sh` is stored inside the container

.. warning:: Sourcing the helper script automatically sets up an ERR trap.
             When a command returns a non-zero exit code, the script will log
             the error with its return code and then exit.

Examples
--------

Below are some examples of the helper functions available. See the
`ci-templates-helpers.sh` for the complete list of functions.

``fdo_log_section_start_collapsed``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Creates a collapsible section in the GitLab CI job log.

**Parameters:**

- ``$1``: Section name (unique identifier)
- ``$2``: Section description (description that appears in the log)

**Example:**

.. code-block:: bash

    fdo_log_section_start_collapsed run_android_cts "Android cts results"
    # This verbose log output is collapsed in the CI job log
    eval /android-tools/android-cts/tools/cts-tradefed run commandAndExit cts-dev
    fdo_log_section_end run_android_cts

``fdo_curl_with_retry``
~~~~~~~~~~~~~~~~~~~~~~~

A wrapper around ``curl`` that automatically retries failed requests to handle
intermittent network issues.

**Parameters:** Accepts all ``curl`` options.

**Example:**

.. code-block:: bash

  fdo_curl_with_retry "${MESA3D_URL}/-/commit/${MESA3D_LIBGLAPI_COMMIT}.patch" \
    -o "${TMP}/mesa-${MESA3D_LLVM_COMMIT}/${MESA3D_LIBGLAPI_COMMIT}.patch"