Manage GitLab configuration as code
GitLab Configuration as Code (GCasC)
Manage GitLab configuration as code to make it easily manageable, traceable and reproducible.
When configuring your GitLab instance, part of settings you put in Omnibus or Helm Chart configuration, and the rest you configure through GitLab UI or API. Due to tons of configuration options in UI, making you GitLab work as you intend is a complex process.
Our intention is to let you automate things you do through UI in a simple way. The Configuration as Code has been designed to configure GitLab based on human-readable declarative configuration files. Writing such a file should be feasible without being a GitLab expert, just translating into code a configuration process one is used to executing in the web UI.
Configuring your GitLab instance is as simple as this:
settings: elasticsearch: url: http://elasticsearch.mygitlab.com username: !env ELASTICSEARCH_USERNAME password: !env ELASTICSEARCH_PASSWORD recaptcha_enabled: yes terms: '# Terms of Service\n\n *GitLab rocks*!!' plantuml: enabled: true url: 'http://plantuml.url' license: starts_at: 2019-11-17 expires_at: 2019-12-17 plan: premium user_limit: 30 data: !include gitlab.lic
Note: GCasC supports only Python 3+. Because Python 2.7 end of life is January 1st, 2020 we do not consider support for Python 2.
|Environment variable||Description||Default value||Example|
||Path to GitLab main configuration. It is our Configuration as Code entry point.||
||Determine if any changes, when detected, should be applied. Valid values:
||Version of GitLab API. Current latest:
||Path to GitLab client configuration||
||URL to GitLab instance. Used only if
||Flag if SSL certificate of GitLab instance should be verified. Used only if
||Required. Private token used to access GitLab API. Used only if
||Path to client certificate used for mutual TLS authentication to access GitLab API.||
||Path to client key used for mutual TLS authentication to access GitLab API.||
GCasC targets https://docs.gitlab.com/12.4/ee/api/settings.html
Only for Enterprise Edition. FOSS/Community Edition instance will fail when trying to configure license
GCasC offers a way to manage your GitLab instance licenses. The clue is that despite license is just a single file, you need to configure other properties of license so GCasC do not upload new (but already used) license with every execution. That way it is able to recognize that exactly the same license is already in use and skips uploading new one. Otherwise you could end with very long license history.
All license properties are required to be able to configure it. Otherwise GCasC will fail.
||Date in format yyyy-MM-dd when license starts||
||Date in format yyyy-MM-dd when license ends||
||Plan of your GitLab instance license. Valid values:
||Number of licensed users||
||Content of your license file that you received from GitLab sales||
Example license configuration:
license: starts_at: 2019-11-17 expires_at: 2019-12-17 plan: premium user_limit: 30 data: | azhxWFZqbk1BOUsrTVxug6AdfzIzWXI1WUVsdWNKRk53V2hiV1FlTUN2TTRS NkhSVFFhZ3hCajd4bGlLMkhhcUxhd1EySHh2TjJTXG40U3ZNUWM0ZzhqYTE5 T1lcbkJnNERFOVBORkpxK3FsaHZxNFFVSG9GL0NEWWF0elkyOE9SUE41Ny9v WWo0a3JMQXFN91AcxWpjZmV3b1xuU0NsZmM3UTEzZ3VQMVVhNHJaZ2lVOFgr cGNYMFNMU1Y1a0x4UkpNMnhIOWlLZ3NFTzlRYTZIUU4wZlZEXG5Lc0ZrV2Zu
Important! Beware of storing your license in
data field directly as text. This is insecure and may lead
to leakage of your license. Use
!include directives to inject license to
license.data field securely from
external source. Also keep your license file itself safe and secure!
Using GCasC Docker image
How to build
When using make you can additionally pass
DOCKER_IMAGE_NAME to change default
gcasc:latest to other image name:
make docker-build DOCKER_IMAGE_NAME=mygcasc:1.0
To get more control over building you can use
docker build directly:
docker build -t gcasc[:TAG] .
How to use
GCasC Docker image working directory is
/workspace. Thus you can quickly launch
docker run -v $(pwd):/workspace hoffmannlaroche/gcasc
It will try to find both GitLab client configuration and GitLab configuration in
/workspace directory. You can modify
the behavior by passing environment variables as defined in TODO anchor here
Bring your own config file: docker run -it --rm -v /path/to/python-gitlab.cfg:/python-gitlab.cfg -e GITLAB_CFG=/python-gitlab.cfg python-gitlab <command> ...
Docker image can be use
docker run -v $(pwd):/workspace hoffmannlaroche/gcasc
docker run -e GITLAB_CLIENT_CONFIG_FILE=/gitlab/client.cfg -e GITLAB_CONFIG_FILE=/gitlab/config.yml -v $(pwd):/gitlab hoffmannlaroche/gcasc
We provide few examples to give you a quick starting place to use GCasC. They can be found in
gitlab.cfgis example GitLab client file configuration.
basicis example GitLab configuration using single configuration file.
environment_variablesshows how environment variables can be injected into GitLab configuration file using
modularizedshows how you can split single GitLab configuration file into smaller and inject files containing static text using
Before submitting a pull request make sure that the tests still succeed with your change. Unit tests run using Github Actions and passing tests are mandatory to get merge requests accepted.
You need to install
tox to run unit tests locally:
# run the unit tests for python 3, python 2, and the flake8 tests: tox # run tests in one environment only: tox -e py37 # run flake8 linter and black code formatter tox -e flake # run black code formatter tox -e black
Instead of using
tox directly, it is recommended to use
# run tests make test # run flake8 linter and black code formatter make lint
Everyone is warm welcome to contribute!
Project is released under Apache License, Version 2.0 license.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size gitlab_configuration_as_code-0.1b2-py3-none-any.whl (24.6 kB)||File type Wheel||Python version py3||Upload date||Hashes View hashes|
Hashes for gitlab_configuration_as_code-0.1b2-py3-none-any.whl