Getting started
Red Hat associate
If you are a Red Hat associate getting started on the CKI team, start with the internal onboarding documentation.
Development setup
Linux distribution
To start contributing, you don’t need any specific Linux distribution. While we encourage everyone to develop on Fedora Workstation or Fedora Silverblue, this is not a requirement. Where Fedora/RHEL-specific software is needed, container-based alternative workflows are provided.
Python version
In general, you are encouraged to use the latest stable version.
For the GitLab pipeline, code needs to be compatible with the minimal Python version across all pipeline images.
For services outside the pipeline, code needs to be compatible with the Fedora Python version used in all container images.
Install dependencies
We need to install direnv, tox and git.
Fedora Workstation
All should be packaged for most distributions and be installable with something like
sudo dnf install tox direnv git
RHEL 9
-
Install Git
sudo dnf install git
-
Install tox from EPEL for RHEL 9
sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm sudo dnf install tox
-
Install direnv from Fedora Koji
sudo dnf install https://kojipkgs.fedoraproject.org/packages/direnv/2.32.1/6.fc39/$(arch)/direnv-2.32.1-6.fc39.$(arch).rpm
Setup direnv
If you’ve just installed direnv, follow the instructions in the direnv setup doc, to hook it to your shell.
Git config
Configure a global .gitignore file and add entries for direnv to it via something like
IGNORE_FILE=$HOME/.config/git/excludes
git config --global core.excludesfile "${IGNORE_FILE}"
mkdir -p "${IGNORE_FILE%/*}"
echo "/.envrc" >> "${IGNORE_FILE}"
echo "/.direnv/" >> "${IGNORE_FILE}"
gitlab-ci-local
gitlab-ci-local is required to use the cki-dev.sh script.
You can add it to your direnv
by:
macOS:
echo "PATH_add .local/bin" > .envrc
curl -sL https://github.com/firecow/gitlab-ci-local/releases/latest/download/macos.gz | gzip -d > .local/bin/gitlab-ci-local
chmod +x .local/bin/gitlab-ci-local
Linux:
echo "PATH_add .local/bin" > .envrc
curl -sL https://github.com/firecow/gitlab-ci-local/releases/latest/download/linux.gz | gzip -d > .local/bin/gitlab-ci-local
chmod +x .local/bin/gitlab-ci-local
Cloning CKI repositories and creating forks
For both GitLab instances, create api
GitLab personal access tokens. The
tokens are going to be stored in the COM_GITLAB_TOKEN_PERSONAL
and
CEE_GITLAB_TOKEN_PERSONAL
environment variables below.
The following bash commands temporarily bootstrap cki-tools, and then use the
included repo-manager
module to clone all repositories including forks and
setup pip:
mkdir ~/git-temp ~/git-cki
cd ~/git-temp
echo "export GITLAB_TOKENS='{\"gitlab.com\":\"COM_GITLAB_TOKEN_PERSONAL\", \"gitlab.cee.redhat.com\":\"CEE_GITLAB_TOKEN_PERSONAL\"}'" >> .envrc
echo 'export COM_GITLAB_TOKEN_PERSONAL="your-secret-token-from-gitlab-com"' >> .envrc
echo 'export CEE_GITLAB_TOKEN_PERSONAL="your-secret-token-from-gitlab-cee"' >> .envrc
echo 'export REQUESTS_CA_BUNDLE=/etc/pki/tls/certs/ca-bundle.crt' >> .envrc
cp .envrc ~/git-cki/
git clone git@gitlab.com:cki-project/cki-tools
cd cki-tools
printf 'layout python python3.11\nsource_up\n' > .envrc
direnv allow
python3 -m pip install -e .
python3 -m cki.cki_tools.repo_manager --directory ~/git-cki --fork fork --venv --force
cd ~/git-cki
rm -rf ~/git-temp
The venv setup depends on the ability to install the required dependencies. This can fail if e.g. no wheels are available for your Python version or the required development packages are not available to compile the requirements from source.
For Fedora, you can fix most of these via
dnf install -y gcc krb5-devel libpq-devel openldap-devel python3-devel
Linting and tests
Linting is implemented in cki_lint.sh, while unit tests and code coverage
checks are implemented in cki_test.sh.
Both scripts are normally invoked in a
clean environment through the tox
command.
The same environments are used in GitLab pipelines on MRs, default branches, etc.
cki-dev.sh
It’s highly recommended to use the cki-dev.sh script to run
linting and testing since it will run in the same environment
as the GitLab CI pipeline (normally in the cki-tools:production
container image).
This script is a wrapper around gitlab-ci-local, a tool that allows to run
GitLab CI jobs locally.
You can get the list of available jobs checking the .gitlab-ci.yml
file
or simply running:
cki-dev.sh --list
To run a GitLab job locally, you can use:
cki-dev.sh <job_name>
Example:
cki-dev.sh linting
cki-dev.sh tests
Check the cki-lib README.cki_dev.md for more details.
Extras
You can pass arguments to cki_lint.sh and cki_test.sh following the
cki-lib README.cki_lint.md and cki-lib README.cki_test.md files.
For example, with the environment variable
CKI_PYTEST_ARGS
, the following code runs only on test_name
in
tests/test_file_name.py
:
CKI_PYTEST_ARGS="tests/test_file_name.py::class_name::test_name" \
cki_test.sh
If using cki-dev.sh
(recommended), you can pass the arguments to the script simply by:
cki-dev.sh tests -- --variable CKI_PYTEST_ARGS="tests/test_file_name.py::class_name::test_name"
Note that if directly using tox
instead,
you need to pass all environment variables that you want to override with
TOX_OVERRIDE=testenv.passenv=<var_name>
.
For example, to run only the test_name
in tests/test_file_name.py
,
you can use:
TOX_OVERRIDE=testenv.passenv=CKI_PYTEST_ARGS \
CKI_PYTEST_ARGS="tests/test_file_name.py::class_name::test_name" \
tox -e test
Check the cki-lib README.cki_lint.md and cki-lib README.cki_test.md files for all the available options.
If using tox
, to run it in a different Python version, explicitly specify the Python
interpreter via
python3.9 -m tox
Individual tests can also be run directly on the host via any of
python3 -m unittest tests.test_module
python3 -m unittest tests/test_file_name.py
pytest tests/test_file_name.py