cki_prepare function

The cki_prepare function is a unified preparation function used by CKI shell scripts (cki_lint.sh, cki_test.sh, etc.) to handle common setup tasks including dependency installation, cki-lib version management, and package overrides.

Usage

cki_prepare "script_name" "cki_lib_extras" "$@"

Parameters

• script_name: The full script name (e.g., “cki_lint.sh”, “cki_test.sh”) - used for exec restart
• cki_lib_extras: The cki-lib extras to install (e.g., “lint”, “test”)
• "$@": All script arguments to pass (normally used in case of restart, see workflow)

Examples

# For linting scripts
cki_prepare "cki_lint.sh" "lint" "$@"

# For testing scripts  
cki_prepare "cki_test.sh" "test" "$@"

Environment Variables

Core Control Variables

CKI_SKIP_PREPARE

Type: Boolean (true/false)
Default: false
Description: Skip the entire preparation phase if set to true.

export CKI_SKIP_PREPARE=true
./cki_lint.sh  # Will skip all preparation steps

cki_lib_pip_url

Type: Git URL
Default: Unset
Description: Override the cki-lib package with a custom version from a Git repository.

# Use a specific branch/commit
export cki_lib_pip_url="git+https://gitlab.com/cki-project/cki-lib.git@my-feature-branch"
./cki_lint.sh

# Use a different repository
export cki_lib_pip_url="git+https://github.com/user/cki-lib-fork.git@main"
./cki_test.sh

Automatic Version Management

When running in GitLab CI/CD merge request jobs (CI_MERGE_REQUEST_PROJECT_ID is set), the function automatically checks if the installed cki-lib version matches the latest production commit. If not, it automatically sets cki_lib_pip_url to update to the latest version.

This behavior occurs when:

• CI_MERGE_REQUEST_PROJECT_ID environment variable is set
• cki_lib_pip_url is not already set
• project actually uses cki-lib (i.e. setup.cfg contains a reference to git+https://gitlab.com/cki-project/cki-lib.git)

Package Override Variables

Any environment variable ending in _pip_url that contains a Git URL will be treated as a package override. The function will:

1. Extract the package name from the URL
2. Uninstall the existing package
3. Install the override version

Pattern: {package_name}_pip_url

# Override multiple packages
export cki_tools_pip_url="git+https://gitlab.com/cki-project/cki-tools.git@dev"
export my_package_pip_url="git+https://github.com/user/my-package.git@feature"
./cki_lint.sh

Note: The cki_lib_pip_url override is handled specially and will trigger a script restart.

Workflow

The cki_prepare function follows this workflow:

1. Skip Check: Return early if CKI_SKIP_PREPARE=true
2. Pip Setup: Configure pip installation with appropriate flags
3. Version Check: In CI/MR jobs, if cki_lib_pip_url is not already set and the installed version doesn’t match the production tag, point cki_lib_pip_url to it
4. Override Handling: If cki_lib_pip_url is set and SKIP_CKI_LIB_OVERRIDE is not set:
   • Uninstall current cki-lib
   • Install override version
   • Install cki-lib extras for the override version
   • Set SKIP_CKI_LIB_OVERRIDE=true and restart script with exec
5. Additional Overrides: Process any other *_pip_url variables (skips invalid Git URLs gracefully)

Integration

Scripts using cki_prepare should:

1. Source cki_utils.sh
2. Call cki_prepare early in the script
3. Pass all script arguments ("$@") to handle restarts properly

#!/usr/bin/env bash
set -Eeuo pipefail

# shellcheck source-path=SCRIPTDIR
. cki_utils.sh

cki_prepare "cki_lint.sh" "lint" "$@"

# Rest of script logic...