gitlabracadabra 1.1.0

Adds some magic to GitLab

Gitlabracadabra

🧹 GitLabracadabra 🧙

:alembic: Adds some magic to GitLab :crystal_ball:

GitLab'racadabra is a GitOps way to configure a GitLab instance from a YAML configuration, using the API.

It is able to create GitLab's groups, projects, users and application settings.

:thumbsup: It's also able to mirror :

• Git repositories, using the mirrors parameter in Mirroring repositories.
• container (Docker) images, using the image_mirrors parameter. See Mirroring container images.
• packages, using the package_mirrors parameter. See Mirroring packages.

It is based on Python GitLab.

Table of Contents

• Installation
  • Using Debian packages
  • Using pip
  • Using docker image
  • From source
• Configuration
• Action file(s)
• Using gitlabracadabra in GitLab CI
• Development

Installation

Using Debian packages

Debian package is available from artefacts and can be installed with:

apt install gitlabracadabra_*.deb

gitlabracadabra --verbose --dry-run

Note: Debian 10 buster or later is required.

Using pip

pip install gitlabracadabra

Using docker image

There are also Docker/OCI images.

Example usage:

sudo docker run -ti \
  -v "$HOME/.python-gitlab.cfg:/home/gitlabracadabra/.python-gitlab.cfg:ro" \
  -v "$PWD/gitlabracadabra.yml:/app/gitlabracadabra.yml:ro" \
  registry.gitlab.com/gitlabracadabra/gitlabracadabra:v1.1.0 \
  --verbose --dry-run

Other images are available. Examples:

• registry.gitlab.com/gitlabracadabra/gitlabracadabra/master: Current master
• registry.gitlab.com/gitlabracadabra/gitlabracadabra/master:a307c3aff01bccacc020b24d2ab39fc7a7d0df45: A specific commit of master

From source

Local installation (in $HOME/.local):

# On Debian >= 10 (buster) or Ubuntu >= 19.04
sudo apt install python3-jsonschema python3-gitlab python3-yaml python3-pygit2 python3-coverage python3-vcr
# On others
pip install -r requirements.txt

# Build, install and test
python3 setup.py build
python3 setup.py install --user
# python3 setup.py test
~/.local/bin/gitlabracadabra --verbose --dry-run

Configuration

GitLabracadabra uses the same configuration file as Python GitLab CLI to store connection parameters.

Example ~/.python-gitlab.cfg:

[global]
default = gitlab

[gitlab]
url = https://gitlab.com
private_token = T0K3N

More information in Python GitLab documentation.

Action file(s)

GitLabracadabra actions are configured with a YAML file.

See GitLabracadabra's own action file or read:

• Action file syntax
• list of parameters:
  • for projects
  • for groups
  • for users
  • for application settings

Using gitlabracadabra in GitLab CI

Since job token probably won't have enough permissions, you'll need to use a personal access token:

• create a personal access token
• Define the GITLAB_PRIVATE_TOKEN protected variable
• Use it in your jobs to configure python-gitlab. Example .gitlab-ci.yml:

default:
  image:
    name: registry.gitlab.com/gitlabracadabra/gitlabracadabra:v1.1.0
    entrypoint: [""]
  before_script:
    - |
        cat << EOF > ~/.python-gitlab.cfg
        [global]
        default = gitlab
        [gitlab]
        url = ${CI_SERVER_URL:-https://gitlab.com}
        private_token = ${GITLAB_PRIVATE_TOKEN}
        # job_token = ${GITLAB_JOB_TOKEN}
        EOF

stages:
  - test
  - deploy

test:
  stage: test
  script:
    - gitlabracadabra --verbose --dry-run
  rules:
    - if: '$CI_COMMIT_BRANCH != "master"'

apply:
  stage: deploy
  script:
    - gitlabracadabra --verbose
  rules:
    - if: '$CI_COMMIT_BRANCH == "master"'

Development

Configure <WORKSPACE>/.vscode/launch.json:

{
    "configurations": [
        {
            "name": "Docker: Python - General",
            "type": "docker",
            "request": "launch",
            "preLaunchTask": "docker-run: debug",
            "python": {
                "pathMappings": [
                    {
                        "localRoot": "${workspaceFolder}",
                        "remoteRoot": "/app"
                    }
                ],
                "projectType": "general"
            }
        }
    ]
}

Configure <WORKSPACE>/.vscode/tasks.json:

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "docker-build",
			"label": "docker-build",
			"platform": "python",
			"dockerBuild": {
				"tag": "gitlabracadabra:latest",
				"dockerfile": "${workspaceFolder}/Dockerfile",
				"context": "${workspaceFolder}",
				"pull": true
			}
		},
		{
			"type": "docker-run",
			"label": "docker-run: debug",
			"dependsOn": [
				"docker-build"
			],
			"dockerRun": {
				"network": "host"
			},
			"python": {
				"module": "gitlabracadabra.cli",
				"args": [ "-c <CONF_PATH>/.python-gitlab.cfg", "--dry-run",  "-g gitlab", "--debug", "--verbose","<CONF_PATH>/<ACTION_FILE>.yml"]
			}
		}
	]
}

NOTE: Docker Network host is important if you want to apply to a local gitlab.