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:
- Create an account at pypi.org
- Go to "Your projects" -> "Publishing" -> "Add a new pending publisher"
- Set: GitHub owner=
szymonrychu, repo=gitlab-cicd-python-wrapper, workflow=pypi.yaml, environment=pypi - Create a GitHub environment named
pypiin your repo settings - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.