Repository files navigation

Manage GitLab configuration as code to make it easily manageable, traceable and reproducible.

• Introduction
• Quick start
  • Configure client
  • Prepare GitLab configuration
  • Run GCasC
    • CLI
    • Docker image
  • Examples
• Building
  • Docker image
  • Python package
• Testing
• Contribution
• License

When configuring your GitLab instance, part of the settings you put inOmnibusorHelm Chart configuration, and the rest you configure through GitLab UIorAPI. Due to tons of configuration options in UI,making GitLab work as you intend is a complex process.

We intend to let you automate things you do through now UI in a simple way. The Configuration as Codehas been designed to configure GitLab based on human-readable declarative configuration files written in Yaml.Writing such a file should be feasible without being a GitLab expert, just translating into code a configurationprocess one is used to executing in the web UI.

GCasC offers a functionality to configure:

• appearance
• application settings
• features
• Instance CI/CD variables
• license
• ... more coming soon!

It gives you also a way to:

• include external files or other Yamls using!include directive
• inject environment variables into configuration using!env directiveinto your Yaml configuration.

Visitour documentation site for detailed information on how to use it.

Configuring your GitLab instance is as simple as this:

appearance:title:"Your GitLab instance title"logo:"http://path-to-your-logo/logo.png"settings:elasticsearch:url:http://elasticsearch.mygitlab.comusername:!env ELASTICSEARCH_USERNAMEpassword:!env ELASTICSEARCH_PASSWORDrecaptcha_enabled:yesterms:'# Terms of Service\n\n *GitLab rocks*!!'plantuml:enabled:trueurl:'http://plantuml.url'instance_variables:anotherVariable:'another value'MY_VARIABLE:value:!env MY_VARIABLEprotected:falsemasked:truefeatures:  -name:sourcegraphvalue:truegroups:      -mygroup1projects:      -mygroup2/myprojectusers:      -myuserlicense:starts_at:2019-11-17expires_at:2019-12-17plan:premiumuser_limit:30data:!include gitlab.lic

Note: GCasC supports only Python 3+. Because Python 2.7 end of life is January 1st, 2020 we do not consider supportfor Python 2.

Here you will learn how to quickly start withGCasC.

Important! Any execution ofGCasC may override properties you define in your Yaml files. Don't try it directlyon your production environment.

Visitour documentation site for detailed information on how to use it.

You can configure client in two ways:

• using configuration file:

  [global]url = https://gitlab.yourdomain.comssl_verify = truetimeout = 5private_token = <personal_access_token>api_version = 4

  By defaultGCasC is trying to find client configuration file in following paths:

  "/etc/python-gitlab.cfg","/etc/gitlab.cfg","~/.python-gitlab.cfg","~/.gitlab.cfg",

BYou can provide a path to your configuration file inGITLAB_CLIENT_CONFIG_FILE environment variable.

• using environment variables:

  GITLAB_CLIENT_URL=<gitlab_url># path to GitLab, default: https://gitlab.comGITLAB_CLIENT_API_VERSION=<gitlab_api_version># GitLab API version, default: 4GITLAB_CLIENT_TOKEN=<personal_access_token># GitLab personal access tokenGITLAB_CLIENT_SSL_VERIFY=<ssl_verify># Flag if SSL certificate should be verified, default: true

You can combine both methods and configuration settings will be searched in the following order:

• configuration file
• environment variables (due to limitations inpython-gitlab if using configuration file onlyGITLAB_CLIENT_TOKENenvironment variable will be used)

Personal access token is mandatory in any client configuration approach and you can configure your it by followingthese instructions

Additionally you can customize HTTP session to enable mutual TLS authentication. To configure this, you shouldprovide two additional environment variables:

GITLAB_CLIENT_CONFIG_FILE=<path_to_client_certificate>GITLAB_CLIENT_KEY=<path_to_client_key>

GitLab configuration must be defined in Yaml file. You can provide a configuration in a single file, or you cansplit it into multiple Yaml files and inject them.

For information how to prepare GitLab configuration Yaml file visitour documentation site.

Forsettings configuration, which definesApplication Settings,the structure is flexible. For example

settings:elasticsearch:url:http://elasticsearch.mygitlab.comusername:elastic_userpassword:elastic_password

andB

settings:elasticsearch_url:http://elasticsearch.mygitlab.comelasticsearch_username:elastic_userelasticsearch_password:elastic_password

are exactly the same and matchelasticsearch_url,elasticsearch_username andelasticsearch_password settings.This means you can flexibly structure your configuration Yaml, where a map child keys are prefixed by parent key (hereelasticsearch parent key was a prefix forurl,username andpassword keys). You only need to follow availableApplication Settings.

You can adjust your Yamls by splitting them into multiple or injecting environment variables into certain values using!include or!env directives respectively. Example is shown below:

settings:elasticsearch:url:http://elasticsearch.mygitlab.comusername:!env ELASTICSEARCH_USERNAMEpassword:!env ELASTICSEARCH_PASSWORDterms:!include tos.mdlicense:!include license.yml

where:

• settings.elasticsearch.username andsettings.elasticsearch.password are injected from environment variablesELASTICSEARCH_USERNAME andELASTICSEARCH_PASSWORD respectively

• settings.terms andlicense are injected fromtos.md plain text file andlicense.yml Yaml file respectively.In this scenario, yourlicense.yml may look like this:

starts_at:2019-11-17expires_at:2019-12-17plan:premiumuser_limit:30data:!include gitlab.lic

To runGCasC you can leverage CLI or Docker image.Docker image is a preferred way, because it is simpleand does not require from you installing any additional libraries. Also, Docker image was designed that it can beeasily used in your CI/CD pipelines.

When running locally, you may benefit from runningGCasC in TEST mode (default mode isAPPLY), where no changeswill be applied, but validation will be performed and differences will be logged. Just setGITLAB_MODEenvironment variable toTEST.

export GITLAB_MODE=TEST

GCasC library is available inPyPI.

To install CLI runpip install gitlab-configuration-as-code. Then you can simply execute

gcasc

//TODO add more information on CLI usage

Currently, CLI is limited and does not support passing any arguments to it, but behavior can only be configuredusing environment variables. Support for CLI arguments may appear in future releases.

Image is available inDocker Hub.

GCasC Docker image working directory is/workspace. Thus you can quickly launchgcasc with:

docker run -v$(pwd):/workspace hoffmannlaroche/gcasc

It will try to find both GitLab client configuration and GitLab configuration in/workspace directory. You can modifythe behavior by passing environment variables:

• GITLAB_CLIENT_CONFIG_FILE to provide path to GitLab client configuration file
• GITLAB_CONFIG_FILE to provide a path to GitLab configuration file

docker run -e GITLAB_CLIENT_CONFIG_FILE=/gitlab/client.cfg -e GITLAB_CONFIG_FILE=/gitlab/config.yml-v$(pwd):/gitlab hoffmannlaroche/gcasc

You can also configure a GitLab client using environment variables. More details about the configuration of GitLab clientare availablein this documentation.

We provide a few examples to give you a quick starting place to useGCasC. They can be found inexamples directory.

1. gitlab.cfg is example GitLab client file configuration.
2. basic is an example GitLab configuration using a single configuration file.
3. environment_variables shows how environment variables can be injectedinto GitLab configuration file using!env directive.
4. modularized shows how you can split single GitLab configuration file into smallerand inject files containing static text using!include directive.

Usemake to build a basic Docker image quickly.

make docker-build

When usingmake you can additionally passDOCKER_IMAGE_NAME to change defaultgcasc:latest to another image name:

make docker-build DOCKER_IMAGE_NAME=mygcasc:1.0

To get more control over builds you can usedocker build directly:

docker builds -t gcasc[:TAG].

Dockerfile comes with two build arguments you may use to customize your image by providing--build-arg parametertodocker build command:

• GCASC_PATH defines the path whereGCasC library will be copied. Defaults to/opt/gcasc.
• WORKSPACE defines a working directory when you runGCasC image. Defaults to/workspace.

Usemake to build source distribution (sdist), Wheel binary distribution and Sphinx documentation.

make build

Both source and Wheel distributions will be placed indist directory. Documentation page will be placedinbuild/docs directory.

Remember to run tests before building your distribution!

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 mandatoryto get merge requests accepted.

You need to installtox 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 formattertox -e flake# run black code formattertox -e black

Instead of usingtox directly, it is recommended to usemake:

# run testsmaketest# run flake8 linter and black code formattermake lint

Everyone is warm welcome to contribute!

Please make sure to read theContributing Guide andCode of Conductbefore making a pull request.

Mateusz

Benj Fassbind

Mariusz Kozakowski

Project is released underApache License, Version 2.0 license.