GitLab CI/CD Setup Guide for Codity.ai

This guide covers best practices for configuring GitLab CI/CD pipelines to work seamlessly with Codity.ai's automated test generation and monitoring.

Why GitLab CI Works Well with Codity.ai

GitLab CI is well-integrated with Codity.ai and requires minimal configuration. Most pipelines work out-of-the-box because:

  • Automatic path handling (no manual PYTHONPATH needed)
  • Job names are defined in .gitlab-ci.yml and easy to configure
  • Built-in support for monorepos with multiple jobs

Critical Configuration Points

1. Pipeline Configuration File

  • Must be named .gitlab-ci.yml in repository root
  • Why: GitLab automatically detects this file

2. Job Names

  • Should contain keywords: test, python, go, ruby, javascript, jest, pytest, rspec
  • Why: Helps Codity identify test jobs vs lint/deploy jobs

Examples:

  • test
  • python-test
  • jest-tests
  • build (might be skipped if no test keyword)

3. Working Directory (Optional)

  • Only needed if your project files are in a subdirectory
  • Use before_script with cd command
  • Important: The path must actually exist in your repository

4. Merge Request Pipelines

  • GitLab automatically runs pipelines on merge requests
  • No special configuration needed (works by default)
  • Use -v or --verbose flags for better logs
  • Why: Provides detailed error information for auto-fixing

Sample GitLab CI Configuration

Python with pytest

# .gitlab-ci.yml
image: python:3.11

stages:
  - test

python-test:
  stage: test
  script:
    # Only change to subdirectory if your files are actually there
    # - cd backend
    - pip install pytest
    - pip install -r requirements.txt
    - pytest -v

Go with testing

# .gitlab-ci.yml
image: golang:1.21

stages:
  - test

go-test:
  stage: test
  script:
    # Only change to subdirectory if go.mod is actually there
    # - cd services
    - go test -v ./...

JavaScript/TypeScript with Jest

# .gitlab-ci.yml
image: node:18

stages:
  - test

jest-test:
  stage: test
  script:
    # Only change to subdirectory if package.json is actually there
    # - cd frontend
    - npm install
    - npm test -- --verbose

Ruby with RSpec

# .gitlab-ci.yml
image: ruby:3.2

stages:
  - test

rspec-test:
  stage: test
  before_script:
    # Only change to subdirectory if Gemfile is actually there
    # - cd api
    - gem install bundler
    - bundle install
  script:
    - bundle exec rspec --format documentation

Java with JUnit/Gradle

# .gitlab-ci.yml
image: gradle:7.6-jdk17

stages:
  - test

java-test:
  stage: test
  script:
    # Only change to subdirectory if build.gradle is actually there
    # - cd service
    - chmod +x gradlew
    - ./gradlew test --info

Multi-language Monorepo

# .gitlab-ci.yml
stages:
  - test

python-backend-test:
  stage: test
  image: python:3.11
  before_script:
    - cd backend
  script:
    - pip install pytest
    - pytest -v

javascript-frontend-test:
  stage: test
  image: node:18
  before_script:
    - cd frontend
  script:
    - npm install
    - npm test -- --verbose

go-services-test:
  stage: test
  image: golang:1.21
  before_script:
    - cd services
  script:
    - go test -v ./...

Advanced: Using Different Directories per Job

# .gitlab-ci.yml
stages:
  - test

# Backend tests (Python in /backend directory)
backend-test:
  stage: test
  image: python:3.11
  before_script:
    - cd backend  # ONLY if backend/ directory exists
  script:
    - pip install pytest
    - pytest -v

# Frontend tests (JavaScript in /frontend directory)
frontend-test:
  stage: test
  image: node:18
  before_script:
    - cd frontend  # ONLY if frontend/ directory exists
  script:
    - npm install
    - npm test

# API tests (Ruby in /api directory)
api-test:
  stage: test
  image: ruby:3.2
  before_script:
    - cd api  # ONLY if api/ directory exists
    - bundle install
  script:
    - bundle exec rspec

Understanding Working Directory

Important: Paths Must Actually Exist

When you use cd backend, the directory must exist in your repository:

✅ CORRECT - Directory exists:
my-repo/
├── backend/              ← This directory EXISTS
│   ├── requirements.txt
│   ├── src/
│   └── tests/
└── .gitlab-ci.yml

❌ INCORRECT - Directory doesn't exist:
my-repo/
├── src/                  ← Your code is here, not in /backend
│   ├── requirements.txt
│   └── tests/
└── .gitlab-ci.yml        ← Says "cd backend" (WRONG!)

How to Check Your Project Structure

Run this command in your repository root:

ls -la

You should see your actual directories. Examples:

Scenario 1: Root-level project

my-repo/
├── package.json          ← Files at root level
├── src/
├── tests/
└── .gitlab-ci.yml

Solution: Don't use "cd" command

Scenario 2: Backend subdirectory

my-repo/
├── backend/              ← Backend code is here
│   ├── requirements.txt
│   └── tests/
└── .gitlab-ci.yml

Solution: Add "- cd backend" in before_script or at start of script

Scenario 3: Multiple subdirectories

my-repo/
├── frontend/
│   └── package.json
├── backend/
│   └── requirements.txt
├── services/
│   └── go.mod
└── .gitlab-ci.yml

Solution: Different "cd" command for each job

Common Issues and Solutions

Issue: "pytest: command not found"

Cause: Dependencies not installed or wrong directory Solution:

  1. Check if you're in the correct directory (use pwd in script)
  2. Ensure pip install pytest runs before tests
  3. Verify requirements.txt exists in the directory

Issue: "ENOENT: no such file or directory, open 'package.json'"

Cause: npm commands running in wrong directory Solution:

  1. Find where package.json actually is: find . -name "package.json"
  2. Add - cd <directory> before npm commands
  3. Example: If package.json is in ./frontend, use - cd frontend

Issue: "go.mod file not found"

Cause: Go commands running in wrong directory Solution:

  1. Find where go.mod actually is: find . -name "go.mod"
  2. Add - cd <directory> before go commands

Issue: "Could not find Gemfile"

Cause: Bundle commands running in wrong directory Solution:

  1. Find where Gemfile actually is: find . -name "Gemfile"
  2. Add - cd <directory> in before_script

Issue: "Pipeline doesn't run on merge requests"

Cause: GitLab should run by default, but check project settings Solution:

  1. Go to Settings > CI/CD > General pipelines
  2. Ensure "Merge request pipelines" is enabled

Issue: "Job fails with 'cd: no such file or directory'"

Cause: The directory you're trying to cd into doesn't exist Solution:

  1. Remove the cd command if files are at root level
  2. Verify directory name matches exactly (case-sensitive)
  3. Check directory exists: ls -la in repository

Checklist Before Committing

  • File is named .gitlab-ci.yml and at repository root
  • Job names contain test-related keywords
  • If using cd command, verify the directory actually exists
  • Test commands use verbose flags (-v, --verbose)
  • Pipeline runs successfully on test merge request
  • No path errors in CI logs

Language-Specific Notes

Python

  • GitLab handles PYTHONPATH automatically - no manual setup needed!
  • Use official Python Docker images (e.g., python:3.11)
  • Install dependencies before running tests
  • Common locations: /, /backend, /api, /src

JavaScript/TypeScript

  • Must have package.json in the directory where you run npm install
  • Use official Node Docker images (e.g., node:18)
  • For monorepos, create separate jobs for each package
  • Common locations: /, /frontend, /web, /client, /app

Go

  • Must have go.mod in the directory where you run go test
  • Use official Go Docker images (e.g., golang:1.21)
  • Use ./... to run all tests in subdirectories
  • Common locations: /, /services, /cmd, /pkg

Ruby

  • Must have Gemfile in the directory where you run bundle install
  • Use official Ruby Docker images (e.g., ruby:3.2)
  • Install bundler before bundle install
  • Common locations: /, /app, /api, /lib

Java

  • Must have build.gradle or pom.xml in the directory
  • Use Gradle or Maven Docker images
  • Make gradlew executable: chmod +x gradlew
  • Common locations: /, /service, /app, /backend

How Codity.ai Monitors GitLab CI

  1. Pipeline Detection: Automatically detects .gitlab-ci.yml in repository
  2. Job Filtering: Identifies test jobs by checking job names for test keywords
  3. Log Retrieval: Fetches logs from completed jobs
  4. Failure Analysis: Identifies failed tests and error patterns
  5. Auto-Fix: Automatically fixes failing tests (up to 3 attempts)
  6. Status Updates: Posts comments on merge request with test results

Testing Your Configuration

  1. Create .gitlab-ci.yml in repository root
  2. Commit and push to a branch
  3. Create a merge request
  4. Check that pipeline runs automatically
  5. Verify Codity.ai detects and monitors the pipeline
  6. Check pipeline logs in GitLab CI/CD tab for any errors

Best Practices

DO

  • Use descriptive job names with test keywords
  • Use official Docker images for language runtimes
  • Use before_script for setup commands (cd, install dependencies)
  • Use script for actual test commands
  • Keep jobs focused on one language/service
  • Use verbose test output flags

DON'T

  • Don't use cd if files are at repository root
  • Don't use incorrect paths that don't exist
  • Don't mix multiple languages in one job (use separate jobs instead)
  • Don't forget to install dependencies before running tests
  • Don't skip stages definition

Quick Reference: Finding Your Project Files

# Find all package.json files
find . -name "package.json"

# Find all go.mod files
find . -name "go.mod"

# Find all Gemfiles
find . -name "Gemfile"

# Find all requirements.txt files
find . -name "requirements.txt"

# Find all build.gradle files
find . -name "build.gradle"

# List directory structure
ls -R

The output will show you exactly where your files are, so you can set the correct directory.

Example: Determining Correct Directory

Command:

find . -name "package.json"

Output:

./frontend/package.json

Conclusion: Your package.json is in ./frontend, so use:

before_script:
  - cd frontend

GitLab CI Variables Reference

Useful GitLab CI variables you can use:

  • $CI_PROJECT_DIR - Full path to repository
  • $CI_COMMIT_SHA - Current commit SHA
  • $CI_MERGE_REQUEST_IID - Merge request ID
  • $CI_COMMIT_BRANCH - Current branch name

Example using variables:

script:
  - echo "Working in $CI_PROJECT_DIR"
  - cd $CI_PROJECT_DIR/backend
  - pytest -v

Need help? Check the GitLab CI/CD documentation