XGIC GitLab CLI

GitLab product commands for the modular XGIC CLI—ops under xgic gitlab ….

Namespace: xgic.cli.gitlab · Console group: xgic gitlab … · Brand: XGIC CLI only (ADR-0005)

Standards hub: xgic/ai · README standards

Vision

Self-managed GitLab operators need a stable, public-safe command surface for versioned ops— not a grab bag of one-off scripts. This module owns the GitLab product namespace under xgic. The GraphQL client library lives in gitlab-graphql; the Compose template and orchestration image producer live in gitlab and gitlab-dev.

One brand (xgic), clear ownership, and no private hosts or tracker IDs in the package.

Why this module exists

Ecosystem

Architecture: ADR-0001 · ADR-0005.

Quick start

Development (editable) — current primary path

uv pip install -e ../cli
uv pip install -e ".[dev]"
xgic gitlab --help
xgic gitlab info

Optional GraphQL extra (when GraphQL-backed commands ship):

uv pip install -e ".[graphql]"

Install (PyPI)

xgic-gitlab-cli 0.1.1 is on PyPI. Further cuts follow the hub python-package-release.md path (RC → TestPyPI → PyPI).

uv pip install "xgic-gitlab-cli"
xgic gitlab --help

Requirements

• Python 3.14+
• xgic-cli ≥ 0.2.2
• Docker / Docker Compose for stack ops (health / backup / restore)

Console commands

All product commands nest under xgic gitlab:

Configuration (no private host defaults)

Shared: --dry-run, --json.

Examples

# From a checked-out xgic/gitlab template directory
export GITLAB_URL=http://localhost:8929
xgic gitlab health --json
xgic gitlab backup \
  --secrets-file ./gitlab-secrets.json \
  --config-file ./gitlab.rb \
  --dry-run
xgic gitlab restore --dry-run
xgic gitlab restore --archive gitlab.tar.zst --dry-run
# after confirmation; destinations are optional and are not written during backup:
xgic gitlab restore \
  --archive gitlab.tar.zst \
  --secrets-dest ./restore/gitlab-secrets.json \
  --config-dest ./restore/gitlab.rb \
  --yes

xgic gitlab backup reads the live secrets and config files and does not write them back. The archive contains the GitLab backup tar, those two files, and backup-manifest.json. Registry, LFS, and packages are required unless --allow-missing names a component GitLab omitted. The manifest is a Pydantic model. Its restore_validation list records REST and GraphQL checks for a later validator. Restore compares a recorded product release with the running service before it extracts the archive. An archive with no recorded release is not a mismatch.

See docs/backup.md and docs/configuration.md.

Status

0.1.7. When --allow-missing includes registry, backup creation omits the container registry. LFS and packages stay required. TestPyPI 0.1.7rc1 passed smoke.

0.1.6. Pair creation copies the application tar in 1 MiB chunks, the same buffer the hash uses. The package depends on xgic-cli ≥ 0.2.2.

0.1.5. After gitlab-backup create, the newest application tar is copied into the landing directory when that directory is not the service volume. TestPyPI 0.1.5rc1 passed smoke. PyPI 0.1.4 leaves the tar inside the volume.

AI agent guidance

• Use xgic gitlab … for product ops; do not hardcode private GitLab hostnames in public artifacts or committed examples.
• Prefer fictional placeholders (https://gitlab.example.com) in docs and tests.
• Destructive restore always needs --yes; start with --dry-run.
• Follow hub public-safe rules before any public GitHub write.

Public safety

This package is public-safe only. Do not hardcode private GitLab hosts, internal inventory, or private tracker IDs. Operators configure endpoints via environment / flags.

Publishing

Follow python-package-release.md (publish after xgic-cli for stack releases). Tags: vX.Y.ZrcN → TestPyPI; vX.Y.Z → PyPI. The release milestone is titled X.Y.Z, matching the published version. Set it on every issue and pull request in that release. GitHub does not copy the issue milestone onto the pull request. The candidate and the final publish share it. Work tracking.

License

Apache License 2.0. See LICENSE and NOTICE.
Copyright form: Copyright 2026 XGIC.