Configuration

GitLab Access

Gitconductor uses a GitLab Personal Access Token to read groups, projects, and repository metadata.

To create a GitLab Personal Access Token:

1. Log in to GitLab.

2. Click your user icon.

3. Click Preferences in the dropdown.

4. Click Access tokens or Personal access tokens in the sidebar.

5. Click Add new token.

6. Select legacy if your GitLab instance asks for a token type.

7. Give the token a useful name.

8. Set an expiry date. For closed systems, the longest permissible expiry is usually easiest.

9. Select the scopes needed for your workflow:

   • read_user

   • read_repository

   • read_api

   • write_repository

10. Click Generate token.

11. Copy the token immediately; GitLab will not show it again.

For read-only inspection, you may not need every write scope. For recursive git commands such as push, the token and your git credentials must allow the operation on the target projects.

You can pass the token via an environment variable:

export GITCONDUCTOR_GITLAB_API_KEY=<my-private-key>

Settings File

Gitconductor can load settings from a TOML file. By default, the CLI looks for:

~/.config/gitconductor/gitconductor.toml

You can override this path with GITCONDUCTOR_CONFIG or the top-level --cfg option.

Example:

gitconductor_gitlab_url = "https://gitlab.com"
gitconductor_gitlab_api_key = "glpat-..."

Environment Variables

GITCONDUCTOR_CONFIG

Path to the Gitconductor TOML settings file.

GITCONDUCTOR_GITLAB_API_KEY

GitLab Personal Access Token.

GITCONDUCTOR_GITLAB_URL

GitLab instance URL. Defaults to https://gitlab.com when neither the environment nor the settings file provides a URL.

Saved Hierarchy State

After gitconductor clone runs, Gitconductor writes a .gitconductor.pkl state file at the top of the cloned hierarchy. Later recursive commands load that state and infer the current group, subgroup, or project from the current working directory.

Use --state when you need to point a command at a specific saved hierarchy state file.