# Gitlabracadabra <!-- omit in toc -->
🧹 GitLabracadabra 🧙
:alembic: Adds some magic to GitLab :crystal\_ball:
GitLab'racadabra is a GitOps way to configure a [GitLab](https://gitlab.com/) instance
from a YAML configuration, using the [API](https://docs.gitlab.com/ce/api/README.html).
It is able to create GitLab's [groups](doc/group.md), [projects](doc/project.md),
[users](doc/user.md) and [application settings](doc/application_settings.md).
:thumbsup: It's also able to mirror :
- Git repositories, using the `mirrors` parameter in [Mirroring repositories](doc/project.md#mirroring-repositories).
- container (Docker) images, using the `image_mirrors` parameter. See [Mirroring container images](doc/image_mirrors.md).
- packages, using the `package_mirrors` parameter. See [Mirroring packages](doc/package_mirrors.md).
It is based on [Python GitLab](https://github.com/python-gitlab/python-gitlab).
## Table of Contents <!-- omit in toc -->
- [Installation](#installation)
- [Using Debian packages](#using-debian-packages)
- [Using pip](#using-pip)
- [Using docker image](#using-docker-image)
- [From source](#from-source)
- [Configuration](#configuration)
- [Action file(s)](#action-files)
- [Using gitlabracadabra in GitLab CI](#using-gitlabracadabra-in-gitlab-ci)
- [Contributing](#contributing)
## Installation
### Using Debian packages
Debian package is available [from artifacts](https://gitlab.com/gitlabracadabra/gitlabracadabra/-/jobs/artifacts/main/browse/debian/output?job=build-deb) and can be installed with:
```shell
apt install gitlabracadabra_*.deb
gitlabracadabra --verbose --dry-run
```
Note: Debian 11 bullseye or later is required.
### Using pip
```shell
pip install gitlabracadabra
```
### Using docker image
There are also [Docker/OCI images](https://gitlab.com/gitlabracadabra/gitlabracadabra/container_registry).
Example usage:
```shell
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:v2.5.1' \
--verbose --dry-run
```
Other images are available. Examples:
- `registry.gitlab.com/gitlabracadabra/gitlabracadabra/main`: Current `main`
- `registry.gitlab.com/gitlabracadabra/gitlabracadabra/main:b1cd3482bf9583c5db863c359e12cafcdb7119bf`: A specific commit of `main`
### From source
Local installation (in `$HOME/.local`):
```shell
# On Debian or Ubuntu
sudo apt install -y --no-install-recommends \
python3-build \
python3-github \
python3-gitlab \
python3-html5lib \
python3-jsonschema \
python3-packaging \
python3-pygit2 \
python3-semantic-version \
python3-vcr \
python3-venv \
python3-yaml \
python3-pip \
python3-coverage \
python3-pytest
# On Alpine
sudo apk add \
py3-build \
py3-pygithub \
py3-requests-toolbelt \
py3-html5lib \
py3-jsonschema \
py3-packaging \
py3-pygit2 \
py3-semantic-version \
py3-vcrpy \
py3-yaml \
py3-pip \
py3-coverage \
py3-pytest
# On others
pip install build
# Build and install
python3 -m build
version="$(grep __version__ gitlabracadabra/__init__.py | awk -F "'" '{print $2}')"
pip install --user "dist/gitlabracadabra-$version"*.whl
# Test
pytest-3 # or pytest
~/.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`:
```ini
[global]
default = gitlab
[gitlab]
url = https://gitlab.com
private_token = T0K3N
```
More information in [Python GitLab documentation](https://python-gitlab.readthedocs.io/en/stable/cli-usage.html#content).
Alternatively, you can use the following environment variables:
- `GITLAB_URL`: GitLab URL
- `GITLAB_PRIVATE_TOKEN` or `GITLAB_OAUTH_TOKEN`: authentication
- `GITLAB_TLS_VERIFY`: either `true` or `false`, or a CA path. Ignored when emty.
## Action file(s)
GitLabracadabra *actions* are configured with a YAML file.
See [GitLabracadabra's own action file](https://gitlab.com/gitlabracadabra/gitlabracadabra/blob/main/gitlabracadabra.yml)
or read:
- [Action file syntax](doc/action_file.md)
- list of parameters:
- [for projects](doc/project.md)
- [for groups](doc/group.md)
- [for users](doc/user.md)
- [for application settings](doc/application_settings.md)
## 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](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#creating-a-personal-access-token)
- [Define](https://docs.gitlab.com/ee/ci/variables/README.html#create-a-custom-variable-in-the-ui) the
`GITLAB_PRIVATE_TOKEN` **protected** variable
- Use it in your jobs to configure `python-gitlab`. Example `.gitlab-ci.yml`:
```yaml
default:
image:
name: 'registry.gitlab.com/gitlabracadabra/gitlabracadabra:v2.5.1'
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 != "main"'
apply:
stage: deploy
script:
- gitlabracadabra --verbose
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
```
## Contributing
- File bugs and feature requests in
[GitLab issues](https://gitlab.com/gitlabracadabra/gitlabracadabra/-/issues).
Security issues should be marked as **confidential**.
- Propose documentation or code improvements in
[GitLab merge requests](https://gitlab.com/gitlabracadabra/gitlabracadabra/-/merge_requests).
This repository enforces commit message convention, to check this locally install the
[commitlint](https://github.com/conventional-changelog/commitlint/#what-is-commitlint)
hook:
```shell
npm install @commitlint/{config-conventional,cli}
echo 'npx commitlint --edit' >> .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg
```
See also:
- Setting up [a development environment](doc/dev_setup.md)
- [Configuring VS code](doc/vscode.md)
- [Releasing GitLabracadabra](doc/release.md).
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/gitlabracadabra/gitlabracadabra",
"name": "gitlabracadabra",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "gitlab api yaml",
"author": "Mathieu Parent",
"author_email": "math.parent@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/24/ff/d0cc76a5511576f5afa6f86855c2cfe9563474f575a7adfcd6ecd5724273/gitlabracadabra-2.5.1.tar.gz",
"platform": null,
"description": "# Gitlabracadabra <!-- omit in toc -->\n\n\ud83e\uddf9 GitLabracadabra \ud83e\uddd9\n\n:alembic: Adds some magic to GitLab :crystal\\_ball:\n\nGitLab'racadabra is a GitOps way to configure a [GitLab](https://gitlab.com/) instance\nfrom a YAML configuration, using the [API](https://docs.gitlab.com/ce/api/README.html).\n\nIt is able to create GitLab's [groups](doc/group.md), [projects](doc/project.md),\n[users](doc/user.md) and [application settings](doc/application_settings.md).\n\n:thumbsup: It's also able to mirror :\n\n- Git repositories, using the `mirrors` parameter in [Mirroring repositories](doc/project.md#mirroring-repositories).\n- container (Docker) images, using the `image_mirrors` parameter. See [Mirroring container images](doc/image_mirrors.md).\n- packages, using the `package_mirrors` parameter. See [Mirroring packages](doc/package_mirrors.md).\n\nIt is based on [Python GitLab](https://github.com/python-gitlab/python-gitlab).\n\n## Table of Contents <!-- omit in toc -->\n\n- [Installation](#installation)\n - [Using Debian packages](#using-debian-packages)\n - [Using pip](#using-pip)\n - [Using docker image](#using-docker-image)\n - [From source](#from-source)\n- [Configuration](#configuration)\n- [Action file(s)](#action-files)\n- [Using gitlabracadabra in GitLab CI](#using-gitlabracadabra-in-gitlab-ci)\n- [Contributing](#contributing)\n\n## Installation\n\n### Using Debian packages\n\nDebian package is available [from artifacts](https://gitlab.com/gitlabracadabra/gitlabracadabra/-/jobs/artifacts/main/browse/debian/output?job=build-deb) and can be installed with:\n\n```shell\napt install gitlabracadabra_*.deb\n\ngitlabracadabra --verbose --dry-run\n```\n\nNote: Debian 11 bullseye or later is required.\n\n### Using pip\n\n```shell\npip install gitlabracadabra\n```\n\n### Using docker image\n\nThere are also [Docker/OCI images](https://gitlab.com/gitlabracadabra/gitlabracadabra/container_registry).\n\nExample usage:\n\n```shell\nsudo docker run -ti \\\n -v \"$HOME/.python-gitlab.cfg:/home/gitlabracadabra/.python-gitlab.cfg:ro\" \\\n -v \"$PWD/gitlabracadabra.yml:/app/gitlabracadabra.yml:ro\" \\\n 'registry.gitlab.com/gitlabracadabra/gitlabracadabra:v2.5.1' \\\n --verbose --dry-run\n```\n\nOther images are available. Examples:\n\n- `registry.gitlab.com/gitlabracadabra/gitlabracadabra/main`: Current `main`\n- `registry.gitlab.com/gitlabracadabra/gitlabracadabra/main:b1cd3482bf9583c5db863c359e12cafcdb7119bf`: A specific commit of `main`\n\n### From source\n\nLocal installation (in `$HOME/.local`):\n\n```shell\n# On Debian or Ubuntu\nsudo apt install -y --no-install-recommends \\\n python3-build \\\n python3-github \\\n python3-gitlab \\\n python3-html5lib \\\n python3-jsonschema \\\n python3-packaging \\\n python3-pygit2 \\\n python3-semantic-version \\\n python3-vcr \\\n python3-venv \\\n python3-yaml \\\n python3-pip \\\n python3-coverage \\\n python3-pytest\n# On Alpine\nsudo apk add \\\n py3-build \\\n py3-pygithub \\\n py3-requests-toolbelt \\\n py3-html5lib \\\n py3-jsonschema \\\n py3-packaging \\\n py3-pygit2 \\\n py3-semantic-version \\\n py3-vcrpy \\\n py3-yaml \\\n py3-pip \\\n py3-coverage \\\n py3-pytest\n# On others\npip install build\n\n# Build and install\npython3 -m build\nversion=\"$(grep __version__ gitlabracadabra/__init__.py | awk -F \"'\" '{print $2}')\"\npip install --user \"dist/gitlabracadabra-$version\"*.whl\n\n# Test\npytest-3 # or pytest\n~/.local/bin/gitlabracadabra --verbose --dry-run\n```\n\n## Configuration\n\nGitLabracadabra uses the same configuration file as Python GitLab CLI to store\nconnection parameters.\n\nExample `~/.python-gitlab.cfg`:\n\n```ini\n[global]\ndefault = gitlab\n\n[gitlab]\nurl = https://gitlab.com\nprivate_token = T0K3N\n```\n\nMore information in [Python GitLab documentation](https://python-gitlab.readthedocs.io/en/stable/cli-usage.html#content).\n\nAlternatively, you can use the following environment variables:\n\n- `GITLAB_URL`: GitLab URL\n- `GITLAB_PRIVATE_TOKEN` or `GITLAB_OAUTH_TOKEN`: authentication\n- `GITLAB_TLS_VERIFY`: either `true` or `false`, or a CA path. Ignored when emty.\n\n## Action file(s)\n\nGitLabracadabra *actions* are configured with a YAML file.\n\nSee [GitLabracadabra's own action file](https://gitlab.com/gitlabracadabra/gitlabracadabra/blob/main/gitlabracadabra.yml)\nor read:\n\n- [Action file syntax](doc/action_file.md)\n- list of parameters:\n - [for projects](doc/project.md)\n - [for groups](doc/group.md)\n - [for users](doc/user.md)\n - [for application settings](doc/application_settings.md)\n\n## Using gitlabracadabra in GitLab CI\n\nSince job token probably won't have enough permissions, you'll need to use a personal access token:\n\n- [create a personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#creating-a-personal-access-token)\n- [Define](https://docs.gitlab.com/ee/ci/variables/README.html#create-a-custom-variable-in-the-ui) the\n`GITLAB_PRIVATE_TOKEN` **protected** variable\n- Use it in your jobs to configure `python-gitlab`. Example `.gitlab-ci.yml`:\n\n```yaml\ndefault:\n image:\n name: 'registry.gitlab.com/gitlabracadabra/gitlabracadabra:v2.5.1'\n entrypoint: [\"\"]\n before_script:\n - |\n cat << EOF > ~/.python-gitlab.cfg\n [global]\n default = gitlab\n [gitlab]\n url = ${CI_SERVER_URL:-https://gitlab.com}\n private_token = ${GITLAB_PRIVATE_TOKEN}\n # job_token = ${GITLAB_JOB_TOKEN}\n EOF\n\nstages:\n - test\n - deploy\n\ntest:\n stage: test\n script:\n - gitlabracadabra --verbose --dry-run\n rules:\n - if: '$CI_COMMIT_BRANCH != \"main\"'\n\napply:\n stage: deploy\n script:\n - gitlabracadabra --verbose\n rules:\n - if: '$CI_COMMIT_BRANCH == \"main\"'\n```\n\n## Contributing\n\n- File bugs and feature requests in\n [GitLab issues](https://gitlab.com/gitlabracadabra/gitlabracadabra/-/issues).\n Security issues should be marked as **confidential**.\n- Propose documentation or code improvements in\n [GitLab merge requests](https://gitlab.com/gitlabracadabra/gitlabracadabra/-/merge_requests).\n\n This repository enforces commit message convention, to check this locally install the\n [commitlint](https://github.com/conventional-changelog/commitlint/#what-is-commitlint)\n hook:\n\n ```shell\n npm install @commitlint/{config-conventional,cli}\n echo 'npx commitlint --edit' >> .git/hooks/commit-msg\n chmod +x .git/hooks/commit-msg\n ```\n\nSee also:\n\n- Setting up [a development environment](doc/dev_setup.md)\n- [Configuring VS code](doc/vscode.md)\n- [Releasing GitLabracadabra](doc/release.md).\n",
"bugtrack_url": null,
"license": "LGPL3",
"summary": "Adds some magic to GitLab",
"version": "2.5.1",
"project_urls": {
"Homepage": "https://gitlab.com/gitlabracadabra/gitlabracadabra"
},
"split_keywords": [
"gitlab",
"api",
"yaml"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6342e322bbf8ad5fbf4650409cefd32344ae959e9832ce9ceb502501a6cd2dc7",
"md5": "2141ac70d39d2717831bac82f1623007",
"sha256": "e4f733e7eb1c2341b11f69d749d6f6a1523cfa0290835f3001a2741fb414f79f"
},
"downloads": -1,
"filename": "gitlabracadabra-2.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2141ac70d39d2717831bac82f1623007",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 684882,
"upload_time": "2024-11-25T15:50:09",
"upload_time_iso_8601": "2024-11-25T15:50:09.079160Z",
"url": "https://files.pythonhosted.org/packages/63/42/e322bbf8ad5fbf4650409cefd32344ae959e9832ce9ceb502501a6cd2dc7/gitlabracadabra-2.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "24ffd0cc76a5511576f5afa6f86855c2cfe9563474f575a7adfcd6ecd5724273",
"md5": "80eeb936dd878717f9d360547ab35ece",
"sha256": "6b324efd24839de2c9ab8e33338e3f2aafab5d0d12a82b18ff2f3350f123c569"
},
"downloads": -1,
"filename": "gitlabracadabra-2.5.1.tar.gz",
"has_sig": false,
"md5_digest": "80eeb936dd878717f9d360547ab35ece",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 482072,
"upload_time": "2024-11-25T15:50:11",
"upload_time_iso_8601": "2024-11-25T15:50:11.882942Z",
"url": "https://files.pythonhosted.org/packages/24/ff/d0cc76a5511576f5afa6f86855c2cfe9563474f575a7adfcd6ecd5724273/gitlabracadabra-2.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-25 15:50:11",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "gitlabracadabra",
"gitlab_project": "gitlabracadabra",
"lcname": "gitlabracadabra"
}
JSON