Simulates the complete GitLab CI/CD pipeline locally before pushing code to the repository. This script runs all the same checks that would run in GitHub Actions, GitLab CI, or Gitea Actions.

Usage

# Run from project root
bash scripts/test-ci-pipeline.sh

# Or make it executable and run directly
chmod +x scripts/test-ci-pipeline.sh
./scripts/test-ci-pipeline.sh

Pipeline Stages

The script executes the following stages in order:

1. LINT Stage

Black: Code formatting check
Ruff: Linting and code quality
MyPy: Type checking (strict mode)

2. TEST Stage

Unit Tests: Runs pytest with coverage
Security Scan: Bandit (if installed)

3. BUILD Stage

Poetry Check: Validates pyproject.toml configuration
Dependency Resolution: Tests if all dependencies can be installed
Docker Validation: Checks Dockerfile syntax

4. INTEGRATION Stage (Optional)

API Health Check: Tests if local API is running

Output

The script provides:

✅ Color-coded output for easy readability
📊 Real-time progress for each job
📄 Summary report at the end
📝 Written report saved to ci-pipeline-report-TIMESTAMP.txt

Example Output

╔═══════════════════════════════════════════════════════╗
║       LOCAL CI/CD PIPELINE SIMULATION                ║
║       GitLab CI Pipeline                             ║
╚═══════════════════════════════════════════════════════╝

=====================================
STAGE: LINT
=====================================

>>> JOB: lint:black
Running: poetry run black --check src/ tests/
✅ PASSED: Black code formatting

>>> JOB: lint:ruff
Running: poetry run ruff check src/ tests/
✅ PASSED: Ruff linting

>>> JOB: lint:mypy
Running: poetry run mypy src/
✅ PASSED: MyPy type checking

...

╔═══════════════════════════════════════════════════════╗
║          ✅ PIPELINE PASSED SUCCESSFULLY ✅           ║
╚═══════════════════════════════════════════════════════╝

Total Tests:  8
Passed:       8
Failed:       0
Duration:     6s

Exit Codes

0: All checks passed ✅
1: One or more checks failed ❌

Requirements

Poetry: For dependency management
Python 3.12+: As specified in pyproject.toml
Docker/Podman (optional): For Docker validation stage
MongoDB (optional): For integration tests

When to Run

Run this script:

✅ Before every commit to ensure code quality
✅ Before creating a pull request
✅ After making significant changes
✅ To verify CI/CD pipeline compatibility

Integration with Git

You can add this as a Git pre-push hook:

#!/bin/bash
# .git/hooks/pre-push

echo "Running CI pipeline validation..."
bash scripts/test-ci-pipeline.sh

if [ $? -ne 0 ]; then
    echo "❌ CI pipeline validation failed. Push aborted."
    exit 1
fi

echo "✅ CI pipeline validation passed. Proceeding with push..."
exit 0

Continuous Integration Compatibility

This script simulates:

✅ GitHub Actions (.github/workflows/build-deploy.yml)
✅ GitLab CI (.gitlab-ci.yml)
✅ Gitea Actions (.gitea/workflows/ci.yml)

All checks performed locally will also pass in the actual CI/CD platforms.

📝 Report Files

After running the validation script, you'll find:

ci-pipeline-report-TIMESTAMP.txt: Plain text summary
CI_VALIDATION_REPORT.md: Comprehensive markdown report with details

🚀 Quick Start

# First time setup
poetry install

# Run validation
bash scripts/test-ci-pipeline.sh

# If all passes, commit and push
git add .
git commit -m "your commit message"
git push

🔧 Troubleshooting

"poetry: command not found"

Install Poetry: https://python-poetry.org/docs/#installation

"Black would reformat X files"

Run: poetry run black src/ tests/

"Ruff found X errors"

Run: poetry run ruff check --fix src/ tests/

"MyPy found X errors"

Fix type errors or add type ignores where appropriate.

Docker validation fails

Ensure Docker or Podman is installed:

Ubuntu/Debian: sudo apt install docker.io
Fedora: sudo dnf install podman podman-compose

📚 Additional Resources

CLAUDE.md - Project documentation for AI assistants
README.md - Project overview
TODO.md - Development roadmap
CI_VALIDATION_REPORT.md - Latest validation report