linux-bash-scripts/gitlab2gitea/README.md

GitLab to Gitea Migration Script

Note: This script is still work in progess!

Description

This script is designed to migrate repositories from GitLab to Gitea.

Author(s)

• Enrico Ludwig <enrico.ludwig@zion-networks.de>

License

MIT License. For more details, refer to the LICENSE file.

Precedence of Settings

Settings will be applied in the following order:

1. Command-line arguments
2. .env file
3. Environment variables
4. Default values

Usage

python3 gitlab2gitea.py [options]

Arguments and Environment Variables

Argument	Environment Variable	Description
--help		Show help message and exit.
--gitlab-url <GITLAB_URL>	GITLAB_URL	The full URL to your Gitlab instance (e.g. https://gitlab.myhost.com)
--gitlab-token <GITLAB_TOKEN>	GITLAB_TOKEN	The access token from your Gitlab instance (see here)
--gitlab-api-version <GITLAB_API_VERSION>	GITLAB_API_VERSION	GitLab API version (default: v4).
--gitea-url <GITEA_URL>	GITEA_URL	The full URL to your Gitea instance (e.g. https://gitea.myhost.com)
--gitea-token <GITEA_TOKEN>	GITEA_TOKEN	The access token from your Gitea instance (example URL to find the settings: https://gitea.myhost.com/user/settings/applications)
--gitea-api-version <GITEA_API_VERSION>	GITEA_API_VERSION	Gitea API version (default: v1).
--no-create-missing-groups	NO_CREATE_MISSING_GROUPS	Do not create missing groups on Gitea (default: False).
--no-create-missing-users	NO_CREATE_MISSING_USERS	Do not create missing users on Gitea (default: False).
--no-create-missing-projects	NO_CREATE_MISSING_PROJECTS	Do not create missing projects on Gitea (default: False).
--no-update-existing-groups	NO_UPDATE_EXISTING_GROUPS	Do not update existing groups on Gitea (default: False).
--no-update-existing-users	NO_UPDATE_EXISTING_USERS	Do not update existing users on Gitea (default: False).
--no-update-existing-projects	NO_UPDATE_EXISTING_PROJECTS	Do not update existing projects on Gitea (default: False).
--only-groups	ONLY_GROUPS	Migrate only groups (default: False).
--only-users	ONLY_USERS	Migrate only users (default: False).
--only-projects	ONLY_PROJECTS	Migrate only projects (default: False).
--quiet	QUIET	Enable quiet mode (default: False).
--debug	DEBUG	Enable debug mode (default: False).
--trace	TRACE	Enable trace mode (default: False).
--dry-run	DRY_RUN	Enable dry-run mode (default: False).
--log-file <LOG_FILE>	LOG_FILE	Log file (default: gitlab2gitea.log). If not set, logs will be only printed to stdout.
--append-log	APPEND_LOG	Append to log file instead of overwriting (default: False).

Example

python3 gitlab2gitea.py \
  --gitlab-url <GITLAB_URL> \
  --gitlab-token <GITLAB_TOKEN> \
  --gitea-url <GITEA_URL> \
  --gitea-token <GITEA_TOKEN>

Notes & Caveats

• Mutually Exclusive Options: Some options cannot be used together, such as:

  • --only-groups and --only-users
  • --only-groups and --only-projects
  • --only-users and --only-projects

• Reserved Usernames: Gitea has reserved usernames like "ghost" and "notifications"; these should be avoided.

Script Overview

The script performs the following actions:

1. Reading Configuration: Fetch configuration from environment variables, .env file, and command-line arguments.
2. Check Endpoints: Validates access to GitLab and Gitea endpoints.
3. Migration:
   • Groups: Compares, creates, and updates groups between GitLab and Gitea.
   • Users: Compares, creates, and updates users between GitLab and Gitea.
   • Projects: (Implementation pending for creating and updating projects).

---

Note: For complete usage, ensure you have the required Python packages by running:

pip install -r requirements.txt

For any issues, please refer to the contact details provided in the author's contact information section.