XGIC GitLab GraphQL Client

XGIC GitLab GraphQL Client (xgic-gitlab-graphql) — a clean, extensible, Python-first client for GitLab’s GraphQL API (namespace: xgic.gitlab.graphql).

Goal: Replace fragile CLI-based automation (glab) with a reliable, strongly-typed Python library that Grok Build (and humans) can use comfortably. Start with Issues + child Tasks (proper Work Item hierarchy), Merge Requests, Labels, Milestones, and Releases. Designed from day one to grow into full GraphQL coverage and structured data (estimates, actuals, etc.).

Why this exists

• Official GitLab CLI escaping problems with long descriptions and complex content
• Need for real hierarchical Tasks instead of Markdown checklists
• Desire to move work data into structured, queryable fields
• Grok Build works best when it can simply import a well-designed Python library

Key features (phase 1)

• High-level methods: create_issue(), create_task(parent_id), create_issue_with_tasks(), create_merge_request()
• Proper parent-child Task hierarchy via GitLab Work Items
• Clean data models (Issue, Task, MergeRequest) instead of raw dicts
• Centralized error handling and GraphQL execution
• Minimal dependencies (just requests)
• Cross-platform (Windows + Linux)
• Easy to install and reuse across projects

Testing

See TESTING.md for unit vs opt-in integration tests and the env contract (GITLAB_URL, GITLAB_TOKEN).

Installation

Primary path for Grok Build and all consumers — install the published package from PyPI:

uv pip install xgic-gitlab-graphql
# optional: pin for automation (use the current version from PyPI / the badge above)
# uv pip install "xgic-gitlab-graphql==X.Y.Z"

Do not hardcode package versions in long-lived docs. Prefer the unpinned install or pin to the current release shown by the PyPI badge / project page.

Development (editable)

Editable installs are for working on this repository only (not the default for agents or production automation):

git clone https://github.com/xgic/gitlab-graphql.git
cd gitlab-graphql
uv pip install -e ".[dev]"

Python 3.14+ required. Build/smoke with uv. Official releases use OIDC Trusted Publishing (python-package-release.md). No Makefiles.

Compatibility

See docs/COMPATIBILITY.md for:

• Minimum supported version = GitLab EE (aligned with GitLab’s maintenance policy; validated against current stable EE with a released PyPI client)
• Preferred client package pin for automation (current PyPI version — not hard-coded here) vs GitLab EE support floor
• Policy: do not ship client changes solely to support outdated self-managed EE pins

Quick start (Python)

from xgic.gitlab.graphql import GitLabClient

client = GitLabClient(
    token="glpat-xxxxxxxxxxxxxxxxxxxx",
    url="https://gitlab.com"   # or your self-hosted instance
)

# Create a parent issue
issue = client.create_issue(
    title="Implement new reporting feature",
    description="High-level description here...",
    namespace_path="group/project",
    labels=["feature", "backend"],
)

# Create child tasks under it
task1 = client.create_task(
    parent_id=issue.id,
    title="Design database schema",
    description="...",
    namespace_path="group/project",
)

task2 = client.create_task(
    parent_id=issue.id,
    title="Implement API endpoints",
    namespace_path="group/project",
)

print(f"Issue created: {issue.web_url}")
print(f"Tasks created under it.")

Recommended for Grok Build: Use the convenience method create_issue_with_tasks(...) whenever possible.

Project Structure

See docs/ARCHITECTURE.md and docs/development-workflow.md for layout and responsibilities.

Documentation

• docs/ADR-001-GitLab-GraphQL-Client.md
• docs/ARCHITECTURE.md
• docs/BASE-STANDARDS-FOR-ORCHESTRATED-REPOS.md
• docs/development-workflow.md
• docs/grok-playbooks.md
• docs/GROK_BUILD_INTEGRATION.md

Engineering Tooling Philosophy

• Build backend: hatchling (namespace packages, uv)
• Environment / packaging: uv + pip
• Linting / formatting: ruff (Google docstrings)
• Type checking: pyright (strict)
• Testing: pytest
• Primary interface: Python library (import, not CLI)

Follows XGIC CLI standard + no Makefiles noted throughout.

Status

Core client implemented (auth, queries/mutations for work items hierarchy + pagination, models, common queries). Base standards in place. Phase 1 complete for initial use cases.

See CHANGELOG.md for details.

Multi-repo standards

Portfolio standards, ADRs, and community health:

• https://github.com/xgic/ai
• Community health
• BASE-STANDARDS
• Python namespace convention

License

Copyright 2026 XGIC.
Licensed under the Apache License, Version 2.0.
See NOTICE.

Contributing

See CONTRIBUTING.md. Use GitHub Flow: issue-named branches, Conventional Commits, human review in the GitHub UI before merge to main.