Skip to main content

Gitlab CICD Python Wrapper

Pydantic models wrapping every GitLab CI/CD YAML keyword with 1:1 mapping to GitLab CI/CD YAML reference.

Features

  • Programmatic pipeline generation using Python-native objects
  • Validation framework for existing pipelines
  • Comment-preserving round-trip serialization (load -> validate -> write = identical YAML)
  • GitLab CI/CD Component parsing with input validation
  • Both sync and async APIs
  • CLI validator and pre-commit hook

Installation

pip install gitlab-cicd-python-wrapper

Or with Poetry:

poetry add gitlab-cicd-python-wrapper

Compatibility Matrix

GitLab Version Pipeline Coverage Component Coverage Notes
17.x Full Full All keywords as of 17.9
16.x Full Partial Components GA in 17.0
15.x Partial N/A Deprecated keywords still accepted

Quick Start

Generate a Pipeline

from gitlab_cicd_python_wrapper import Pipeline, Job, Image, Artifacts

pipeline = Pipeline(
    stages=["build", "test", "deploy"],
    jobs={
        "build": Job(
            stage="build",
            image=Image(name="python:3.11"),
            script=["pip install -r requirements.txt", "python setup.py build"],
            artifacts=Artifacts(paths=["dist/"]),
        ),
        "test": Job(
            stage="test",
            script=["pytest"],
            needs=["build"],
        ),
    },
)

print(pipeline.to_yaml())

Validate an Existing Pipeline

from gitlab_cicd_python_wrapper import Pipeline

# Load and validate
pipeline = Pipeline.from_yaml(".gitlab-ci.yml")
print(f"Stages: {pipeline.stages}")
print(f"Jobs: {list(pipeline.jobs.keys())}")

# Validate without loading
errors = Pipeline.validate_file(".gitlab-ci.yml")
if errors:
    for err in errors:
        print(f"Error: {err}")

Round-Trip Editing (Comments Preserved)

from gitlab_cicd_python_wrapper import Pipeline

# Load -> modify -> save preserves comments and formatting
pipeline = Pipeline.from_yaml(".gitlab-ci.yml")
pipeline.to_yaml("validated-output.yml")
# Output is byte-identical to input for unmodified pipelines

CLI Validator

# Validate pipeline files
gitlab-cicd-validate .gitlab-ci.yml

# Validate multiple files
gitlab-cicd-validate .gitlab-ci.yml .gitlab/ci/*.yml

# Validate component templates
gitlab-cicd-validate --component templates/build.yml

# JSON output
gitlab-cicd-validate --format json .gitlab-ci.yml

# Strict mode (fail on warnings)
gitlab-cicd-validate --strict .gitlab-ci.yml

Pre-commit Hook

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/szymonrychu/gitlab-cicd-python-wrapper
    rev: v0.1.0
    hooks:
      - id: gitlab-cicd-validate
        args: ['--strict']
      - id: gitlab-cicd-validate-components

This validates .gitlab-ci.yml and any YAML files under .gitlab/ci/ automatically, plus component templates under templates/.

Component Parsing

Parse and validate GitLab CI/CD components with input validation:

from gitlab_cicd_python_wrapper import Component

# Load a component template
component = Component.from_yaml("templates/deploy.yml")

# Inspect the spec
for name, input_def in component.spec.inputs.items():
    print(f"{name}: type={input_def.type}, default={input_def.default}")

# Validate inputs (raises ValueError on failure)
resolved = component.validate_inputs({
    "stage": "deploy",
    "environment": "production",
    "timeout": 3600,
})

# Render with inputs interpolated (returns a Pipeline)
pipeline = component.render({
    "stage": "deploy",
    "environment": "production",
    "timeout": 3600,
})
print(pipeline.to_yaml())

Dynamic Child Pipelines

Generate pipelines dynamically for use with trigger:include:

from gitlab_cicd_python_wrapper import Pipeline, Job

services = ["api", "web", "worker"]

jobs = {}
for svc in services:
    jobs[f"build-{svc}"] = Job(
        stage="build",
        image="docker:latest",
        script=[f"docker build -t {svc} services/{svc}/"],
        tags=["docker"],
    )

child = Pipeline(stages=["build"], jobs=jobs)
child.to_yaml("generated-pipeline.yml")

# Parent pipeline triggers it:
# trigger:
#   include:
#     - artifact: generated-pipeline.yml
#       job: generate-pipeline

Async API

import asyncio
from gitlab_cicd_python_wrapper import AsyncPipeline, AsyncComponent

async def main():
    # Pipeline
    pipeline = await AsyncPipeline.from_yaml(".gitlab-ci.yml")
    print(f"Stages: {pipeline.stages}")
    print(f"Jobs: {list(pipeline.jobs.keys())}")
    await AsyncPipeline.to_yaml(pipeline, "validated-output.yml")

    # Component
    component = await AsyncComponent.from_yaml("templates/build.yml")
    resolved = component.validate_inputs({"image": "python:3.12"})

asyncio.run(main())

Docker

Run the validator as a container:

docker run --rm -v $(pwd):/data szymonrychu/gitlab-cicd-python-wrapper /data/.gitlab-ci.yml

PyPI Configuration

To publish this library to PyPI using GitHub Actions trusted publishing:

  1. Create an account at pypi.org
  2. Go to "Your projects" -> "Publishing" -> "Add a new pending publisher"
  3. Set: GitHub owner=szymonrychu, repo=gitlab-cicd-python-wrapper, workflow=pypi.yaml, environment=pypi
  4. Create a GitHub environment named pypi in your repo settings
  5. Push a semantic version tag (e.g., v0.1.0) to trigger the publish workflow

Development

# Install dependencies
mise install
poetry install

# Run tests
poetry run pytest

# Run linters
pre-commit run --all-files

# Run CLI
poetry run gitlab-cicd-validate .gitlab-ci.yml

License

MIT

Metadata

Release files for gitlab-cicd-python-wrapper 0.0.46

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gitlab-cicd-python-wrapper 0.0.46
File Size Uploaded Provenance Actions
gitlab_cicd_python_wrapper-0.0.46.tar.gz 12.2 kB With provenance Details for gitlab_cicd_python_wrapper-0.0.46.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gitlab-cicd-python-wrapper 0.0.46
File Interpreter ABI Platform Actions
gitlab_cicd_python_wrapper-0.0.46-py3-none-any.whl Python 3 none any Details for gitlab_cicd_python_wrapper-0.0.46-py3-none-any.whl

Total release size: 31.6 kB

Release files / gitlab_cicd_python_wrapper-0.0.46.tar.gz

Download URL gitlab_cicd_python_wrapper-0.0.46.tar.gz
Size 12.2 kB
Tags Source
SHA-256 checksum
How to use checksums
b5e71a58bf2c343e423ea5e38f2e2c549d3de29b5531c459db6b7b9e9e51122d
BLAKE2b-256 checksum
How to use checksums
7f7042ca1c22728be77e85b9c8b4c80fa079fc1d641e2591247975d72eccaac9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 7, 2026.

Transparency log

Release files / gitlab_cicd_python_wrapper-0.0.46-py3-none-any.whl

Download URL gitlab_cicd_python_wrapper-0.0.46-py3-none-any.whl
Size 19.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6d48ecf05f3d6aba95f1755f0f5a21ae01356c7e70fd803ac5e485cb31fa6d88
BLAKE2b-256 checksum
How to use checksums
6421a392abc70b19ec9269a8c4383df7d651ce137e565855b752b171ca0a4b1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 7, 2026.

Transparency log

Security for gitlab-cicd-python-wrapper 0.0.46

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gitlab_cicd_python_wrapper-0.0.46.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.46 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page