GitLab Label Mover

A tool to migrate labels from a GitLab project to a group, updating all issues and merge requests to use the new group labels. Developed by Nikolai von Krusenstiern.

Features

• Migrate labels from a project to a group
• Update issues and merge requests to use the new group labels
• Dry-run mode to preview changes without executing them
• Support for custom environment files
• Backup option to create a backup of labels before migration

Installation

Prerequisites

• Python 3.9 or higher
• Required dependencies (automatically installed when using pip):
  • python-gitlab: For interacting with the GitLab API
  • python-dotenv: For loading environment variables from .env files

Install from PyPI

The easiest way to install GitLab Label Mover is from PyPI:

pip install gitlab-label-mover

This will install the package and create a gitlab-label-mover command that you can run from anywhere.

If you prefer using Poetry:

poetry add gitlab-label-mover

For a clean, isolated installation (recommended for command-line tools), use pipx:

pipx install gitlab-label-mover

After installation, you can run the tool directly from your command line:

# Show help
gitlab-label-mover --help

# Run in preview mode
gitlab-label-mover

# Execute the migration
gitlab-label-mover --execute

Install from Source

Alternatively, you can install from source:

1. Clone the repository:

   git clone https://github.com/nkrusens/gitlab-label-mover.git
   cd gitlab-label-mover
   

2. Install using Poetry (recommended):

   # Install dependencies and the package in development mode
   poetry install
   
   # Activate the virtual environment
   poetry shell
   

   Or using pip:

   # Install the package in development mode
   pip install -e .
   

3. Create and configure your environment file:

   cp example.env .env
   # Edit .env with your GitLab details
   

Usage

Using the Command Line Tool

After installation, you can run GitLab Label Mover directly from the command line:

gitlab-label-mover [options]

The command will be available in your PATH, so you can run it from any directory.

From Source Directory

If you're running from the source directory without installing the package, make sure you have the dependencies installed in your environment, then use the provided script:

# Make the script executable (first time only)
chmod +x ./gitlab-label-mover

# Run the script
./gitlab-label-mover [options]

The script will automatically detect whether you're running from source or using an installed package.

Command-line Options

usage: gitlab-label-mover [-h] [--execute] [--backup] [--env-file ENV_FILE] [--project-id PROJECT_ID] [--group-id GROUP_ID] [--debug]

GitLab Label Mover - Migrate labels from a project to a group

options:
  -h, --help               show this help message and exit
  --execute                Execute the migration (without this flag, only a preview is shown)
  --backup                 Create a backup of labels before migration
  --env-file ENV_FILE      Path to a custom environment file (default: .env)
  --project-id PROJECT_ID  Override the project ID from the environment file
  --group-id GROUP_ID      Override the group ID from the environment file
  --debug                  Enable detailed debug logging

By default, configuration is read from .env file in the current directory.

Examples

# Perform a dry run (no changes will be made)
gitlab-label-mover

# Execute the migration
gitlab-label-mover --execute

# Create a backup before executing the migration
gitlab-label-mover --execute --backup

# Use a custom environment file
gitlab-label-mover --env-file custom.env

# Override project and group IDs
gitlab-label-mover --project-id 123 --group-id 456

# Show version information
gitlab-label-mover --version

# Enable debug logging
gitlab-label-mover --debug

Environment Configuration

Create a .env file with the following variables:

GITLAB_URL=https://gitlab.example.com
GITLAB_PRIVATE_TOKEN=your_private_token
GITLAB_SUBGROUP_PROJECT_ID=your_project_id
GITLAB_ROOT_GROUP_ID=your_group_id

See example.env for more details.

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/nkrusens/gitlab-label-mover.git
cd gitlab-label-mover

# Install dependencies with Poetry using the Makefile
make install

# Activate the virtual environment
poetry shell

Development Commands

The project includes a Makefile to simplify common development tasks:

# Show available commands
make help

# Run tests
make test

# Run linting checks
make lint

# Format code
make format

# Clean build artifacts
make clean

Version Management

Use Poetry's version management through the Makefile. The commands automatically update all version references, commit the changes, and create a git tag:

# Bump patch version (0.0.x)
make bump-patch

# Bump minor version (0.x.0)
make bump-minor

# Bump major version (x.0.0)
make bump-major

Each command will:

1. Update the version in pyproject.toml using Poetry
2. Update the version in src/gitlab_label_mover/init.py
3. Commit the changes with a message "Bump version to X.Y.Z"
4. Create an annotated git tag "vX.Y.Z"

Building and Publishing

# Build the package
make build

# Test publishing to TestPyPI (recommended before publishing to PyPI)
make publish-test

# Publish to PyPI (maintainers only)
make publish

After publishing to TestPyPI, you can install the package with:

pip install --index-url https://test.pypi.org/simple/ gitlab-label-mover

Note for maintainers: After publishing to PyPI, update the README badges to use the PyPI badges:

[![PyPI version](https://badge.fury.io/py/gitlab-label-mover.svg)](https://badge.fury.io/py/gitlab-label-mover)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/pypi/pyversions/gitlab-label-mover.svg)](https://pypi.org/project/gitlab-label-mover/)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

• Nikolai von Krusenstiern - GitHub

Links

• GitLab Repository
• PyPI Package