Gitlab

Introduction

Gitlab is a Dev(Sec)Ops platform to handle all the elements in the software development life cycle.

Main features:

• Git repository management
• Software development planning
• Continuous Integration and Continuous Deployment (CI/CD)

The service can be accessed at [1] with your PIC account.

The groups inside gitlab are not synced with the LDAP groups, if you want to have access to some specific group or project in gitlab you have to request it through the application.

Official Gitlab documentation

The official Gitlab documentation can be found here: https://docs.gitlab.com/

Make sure that the documentation you are viewing applies to the Free (Community Edition) distribution and the version deployed at gitlab.pic.es. You can easily find the version number in the Help menu.

The official documentation can be overwhelming, here are some useful links:

• Generate an SSH key pair
• git LFS
• Web IDE
• CI/CD .yaml file syntax reference
• GitLab CI/CD Caching
• GitLab Pages

Best practices / recommendations

General rules

• Make small and atomic changes Commit / push often.
• Use branches for dedicated/long developments
• Keep the main branch stable the tests should always pass (yes you should have tests!!)
• Write descriptive commit messages Avoid messages like “changes”, “test” or “.”
• Adopt a branching strategy gitflow, trunk-based,...
• Do code reviews if possible Specially if working in a team

Our contributions

• Use git!! If you work alone or in a team, use it!
• Do not upload big binary files to a git repository Git is not for data, it is for code. If you still want to do it you can use git LFS (see above).
• Use .gitignore to track only relevant files official docs and some examples
• Do not track jupyter notebooks (.ipynb) pair them with a script using jupytext
• Do not upload confidential data passwords, ssh keys, etc will be there forever

GitLab CI/CD Cache

GitLab Runners at PIC support S3 distributed caching to speed up pipelines by reusing dependencies (e.g., Python `venv` or `pip` packages) across job runs.

• Official docs: GitLab Caching Documentation
• Retention policy: Unused cache files are automatically deleted after 30 days.

Cache vs. Artifacts (Important)

It is very common to confuse caches and artifacts. Please use them correctly:

• Use Cache for dependencies: Cache is meant to store downloaded internet dependencies (like `node_modules/`, Python `venv/`, or `.cache/pip/`) to speed up future pipeline runs. It is not meant for system-wide packages (e.g., `apt-get install`) or custom binaries. Also, the cache is not guaranteed to exist (your job must always be capable of installing things from scratch if the cache is missing).
• Use Artifacts for build results: Artifacts are used to pass intermediate files (compiled code, test reports, generated HTML) between different stages of the same pipeline execution, or to let users download them. Do not use the cache to pass files between stages.

Quick example (Python)

image: python:3.10

cache:
  key: "python-deps-$CI_COMMIT_REF_SLUG"
  paths:
    - .cache/pip
    - venv/

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

stages:
  - build
  - test

build_job:
  stage: build
  script:
    # Always check and install from scratch if the cache is missing/empty
    - if [ ! -d "venv" ]; then python -m venv venv; fi
    - source venv/bin/activate
    - pip install -r requirements.txt

test_job:
  stage: test
  script:
    - source venv/bin/activate
    - pytest

GitLab Pages

You can publish static websites (documentation, Sphinx, Doxygen, HTML/JS) directly from your CI/CD pipeline under https://pages.pic.es.

• Official docs: GitLab Pages User Guide

Requirements & Quick example

To publish a website, your pipeline configuration must meet three simple requirements:

1. The job must be named exactly pages.
2. The website files must be generated in or moved to the public/ directory.
3. The public/ directory must be defined as a job artifact.

pages:
  stage: deploy
  script:
    - mkdir public
    - echo "<h1>GitLab Pages at PIC</h1>" > public/index.html
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Troubleshooting

Errors in CI/CD jobs

• pods XXXX is forbidden: exceeded quota: There's a limit on the amount of resources that can be used simultaneously for CI/CD jobs. This takes into account your own jobs and jobs from other projects. You should be able to retry the pipeline after some period to wait for resources to be freed. If it doesn't work contact the administrator.
• ERROR: Preparation failed: couldn't prepare overwrites: invalid build requests specified: the resource "XXXXXX" requested "X" is higher than limit allowed "X": Your job requested more than the allowed resources. Lower down the amount of resources requested.
• ERROR: Job failed (system failure): Error in container build: exit code: 137, reason: 'OOMKilled': The job exceeded the memory limit and it was killed. Try increasing the memory requested for you CI/CD job. If this is not enough contact the servicea administrator.

Configure resource limits in CI/CD jobs

Gitlab CI/CD jobs run as pods on one of PIC's kubernetes clusters. Pods can have resource requests and limits. Resource requests are effectively allocated for the pod, which will be killed if it exceeds the resource limits.

Default resources are:

• 1GiB memory and 0.5 cpu requested
• 2GiB memory and 1 cpu limit

Default resources can be overwritten by setting environment variables in the job configuration in .gitlab-ci.yml like this:

cicd_job:

 image: python:3.11-slim
 variables:
   KUBERNETES_CPU_REQUEST: "1"
   KUBERNETES_CPU_LIMIT: "2"
   KUBERNETES_MEMORY_REQUEST: "4Gi"
   KUBERNETES_MEMORY_LIMIT: "6Gi"

Maximum resources that can be overwritten are:

• 6 GiB memory and 2 cpu requested
• 8 GiB memory and 4 cpu limit