gitconductor¶
Contents:
gitconductor¶
gitconductor is a command-line tool and Python library for managing git operations over nested GitLab groups using the official GitLab Python API. It makes it easier to traverse complex group/sub-group hierarchies, perform recursive git operations, without the need for submodule interdependencies, accessing only the sub-groups/projects for which the user has access.
Features¶
Recursive group traversal — operate on entire GitLab group trees, not just individual projects
Git operations across nested groups (clone, pull, status, etc.)
Unified CLI and Python API
Built on top of the official GitLab Python API
Designed for automation, scripting, and bulk maintenance
Installation¶
pip install gitconductor
Gitlab Access¶
Access to Gitlab is controlled via Personal Access Tokens. To generate:
Login to Gitlab.
Click to user icon.
Click preferences in the drop down.
Click “Personal access tokens” on the left side bar.
Click the “Add new token” button in the top right.
Select “legacy”.
Give it a helpful name.
Set the expiry date - for closed systems the longest permissable time of 1 year is easiest.
Click the tick box for:
read_user
read_repository
read_api
write_repository
Click the “Generate token” button below.
Copy the new token (noting it can’t be viewed again after).
Configuration¶
Configuration file¶
Gitconductor can store settings in a file. By default, this is at “~/.config/gitconductor/gitconductor.toml”. The location can be changed via the GITCONDUCTOR_CONFIG environment variable. Alternatively, a path can be passed via the top-level --cfg CLI argument.
Environment Variables¶
GITCONDUCTOR_CONFIG: Gitconductor configuration YAML file location.GITCONDUCTOR_GITLAB_API_KEY: Gitlab Private Access Token.GITCONDUCTOR_GITLAB_URL: Gitlab main URL.
GitLab API Keys¶
Keys can be set up in two ways:
Via an environment variable:
export GITCONDUCTOR_GITLAB_API_KEY=<my-private-key>Via the “gitconductor.toml” file in the
gitconductor_gitlab_api_keyvariable.
Usage (CLI)¶
Clone¶
To clone a Gitlab project at, for example, https://gitlab.com/ejb90-group.
gitconductor clone ejb90-group
Branch¶
gitconductor branch <name>
Checkout¶
gitconductor checkout <name>
Pull¶
…
Visualisation¶
Tree¶
To visualise the hierarchy of Groups/Projects as a Run, run:
gitconductor viz tree
Results in:
ejb90-group
└── models
├── model-a
├── model-b
├── model-c
└── subgroup-1
├── model-a
└── model-b
Table¶
To visualise the hierarchy of Groups/Projects as a Table, run:
gitconductor viz table
Results in:
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name ┃ Tree ┃ Branch ┃ Path ┃ Remote ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ model-a │ ejb90-group/models/model-a │ main │ ejb90-group/models/model-a │ git@gitlab.com:ejb90-group/models/model-a.git │
│ model-b │ ejb90-group/models/model-b │ main │ ejb90-group/models/model-b │ git@gitlab.com:ejb90-group/models/model-b.git │
│ model-c │ ejb90-group/models/model-c │ main │ ejb90-group/models/model-c │ git@gitlab.com:ejb90-group/models/model-c.git │
│ model-a │ ejb90-group/models/subgroup-1/model-a │ main │ ejb90-group/models/subgroup-1/model-a │ git@gitlab.com:ejb90-group/models/subgroup-1/subgroup-1-model-a.git │
│ model-b │ ejb90-group/models/subgroup-1/model-b │ main │ ejb90-group/models/subgroup-1/model-b │ git@gitlab.com:ejb90-group/models/subgroup-1/subgroup-1-model-b.git │
└───────────────┴───────────────────────────────────────┴────────┴───────────────────────────────────────┴─────────────────────────────────────────────────────────────────────┘
Access¶
To see who has access to a given hierarchy of Groups/Projects, run:
gitconductor viz access
Results in:
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ Group/Project ┃ User ┃ Access Level ┃ Public Email ┃ Expiry ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━┩
│ ejb90-group │ Ellis │ Owner │ │ │
│ ejb90-group/models │ mobot │ Reporter │ │ │
└────────────────────┴───────┴──────────────┴──────────────┴────────┘
Python¶
Gitconductor can also inspect and maniupulate cloned repositories as Python packages. A repository is treated as a Python package when it contains either pyproject.toml or setup.py. Python commands run recursively from the current Gitconductor group, subgroup, or project, so you can work across a whole clone or narrow the operation by changing into a subgroup directory first.
Generate Requirements¶
Generate a requirements.txt file containing direct references to each Python package in the repository tree:
gitconductor py-requirements
By default, Gitconductor writes to requirements.txt and will not overwrite an existing file unless --force is passed:
gitconductor py-requirements --force
To choose a different output file:
gitconductor py-requirements --fname model-requirements.txt
A pyproject.toml-style dependences snippet is also possible with the --pyproject argument:
gitconductor py-requirements --pyproject
Install Python Packages¶
Install every Python package in the current Gitlab Group tree into the active Python environment:
gitconductor py-installer
By default this runs uv pip install <path> for each Python package it finds. To install packages in editable mode:
gitconductor py-installer --editable
You can pass a different package-manager command with --package-manager:
gitconductor py-installer --package-manager "python -m pip"
To install from a specific package index:
gitconductor py-installer --index https://example.com/simple
Usage (Python API)¶
group = gitlab.GitlabGroup(
gitlab_url=ctx.obj["url"],
gitlab_key=ctx.obj["key"],
name=name,
root=directory,
)
group.recursive_command("clone")
Development & Contributing¶
Contributions welcome — feel free to open issues or submit PRs. See CONTRIBUTING.md.
License¶
MIT License • © 2026