Package: gitlab-configuration-as-code
GitLab Configuration as Code (GCasC)Manage GitLab configuration as code to make it easily manageable, traceable and reproducible.Table of ContentsIntroductionQuick startConfigure clientPrepare GitLab configurationRun GCasCCLIDocker imageExamplesBuildingDocker imagePython packageTestingContributionLicenseIntroductionWhen configuring your GitLab instance, part of the settings you put inOmnibusorHelm Chartconfiguration, and the rest you configure through GitLab UI
orAPI. 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 Code
has 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 configuration
process one is used to executing in the web UI.GCasCoffers a functionality to configure:appearanceapplication settingsfeatureslicense... more coming soon!It gives you also a way to:include external files or other Yamls using!includedirectiveinject environment variables into configuration using!envdirective
into your Yaml configuration.
 
Visitour documentation sitefor detailed information on how to use it.Configuring your GitLab instance is as simple as this:appearance:title:"YourGitLabinstancetitle"logo:"http://path-to-your-logo/logo.png"settings:elasticsearch:url:http://elasticsearch.mygitlab.comusername:!envELASTICSEARCH_USERNAMEpassword:!envELASTICSEARCH_PASSWORDrecaptcha_enabled:yesterms:'#TermsofService\n\n*GitLabrocks*!!'plantuml:enabled:trueurl:'http://plantuml.url'features:-name:sourcegraphvalue:truegroups:-mygroup1projects:-mygroup2/myprojectusers:-myuserlicense:starts_at:2019-11-17expires_at:2019-12-17plan:premiumuser_limit:30data:!includegitlab.licNote:GCasC supports only Python 3+. Because Python 2.7 end of life is January 1st, 2020 we do not consider support
for Python 2.Quick startHere you will learn how to quickly start withGCasC.Important!Any execution ofGCasCmay override properties you define in your Yaml files. Don't try it directly
on your production environment.Visitour documentation sitefor detailed information on how to use it.Configure clientYou can configure client in two ways:using configuration file:[global]
url = https://gitlab.yourdomain.com
ssl_verify = true
timeout = 5
private_token = <personal_access_token>
api_version = 4By defaultGCasCis trying to find client configuration file in following paths:"/etc/python-gitlab.cfg",
"/etc/gitlab.cfg",
"~/.python-gitlab.cfg",
"~/.gitlab.cfg",You can provide a path to your configuration file inGITLAB_CLIENT_CONFIG_FILEenvironment 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: trueYou can combine both methods and configuration settings will be searched in the following order:configuration fileenvironment variables (due to limitations inpython-gitlabif 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 instructionsAdditionally you can customize HTTP session to enable mutual TLS authentication. To configure this, you should
provide two additional environment variables:GITLAB_CLIENT_CONFIG_FILE=<path_to_client_certificate>GITLAB_CLIENT_KEY=<path_to_client_key>Prepare GitLab configurationGitLab configuration must be defined in Yaml file. You can provide a configuration in a single file, or you can
split it into multiple Yaml files and inject them.For information how to prepare GitLab configuration Yaml file visitour documentation site.Forsettingsconfiguration, which definesApplication Settings,
the structure is flexible. For examplesettings:elasticsearch:url:http://elasticsearch.mygitlab.comusername:elastic_userpassword:elastic_passwordandsettings:elasticsearch_url:http://elasticsearch.mygitlab.comelasticsearch_username:elastic_userelasticsearch_password:elastic_passwordare exactly the same and matchelasticsearch_url,elasticsearch_usernameandelasticsearch_passwordsettings.
This means you can flexibly structure your configuration Yaml, where a map child keys are prefixed by parent key (hereelasticsearchparent key was a prefix forurl,usernameandpasswordkeys). 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!includeor!envdirectives respectively. Example is shown below:settings:elasticsearch:url:http://elasticsearch.mygitlab.comusername:!envELASTICSEARCH_USERNAMEpassword:!envELASTICSEARCH_PASSWORDterms:!includetos.mdlicense:!includelicense.ymlwhere:settings.elasticsearch.usernameandsettings.elasticsearch.passwordare injected from environment variablesELASTICSEARCH_USERNAMEandELASTICSEARCH_PASSWORDrespectivelysettings.termsandlicenseare injected fromtos.mdplain text file andlicense.ymlYaml file respectively.
In this scenario, yourlicense.ymlmay look like this:starts_at:2019-11-17expires_at:2019-12-17plan:premiumuser_limit:30data:!includegitlab.licRun GCasCTo runGCasCyou can leverage CLI or Docker image.Docker image is a preferred way, because it is simple
and does not require from you installing any additional libraries. Also, Docker image was designed that it can be
easily used in your CI/CD pipelines.When running locally, you may benefit from runningGCasCin TEST mode (default mode isAPPLY), where no changes
will be applied, but validation will be performed and differences will be logged. Just setGITLAB_MODEenvironment variable toTEST.exportGITLAB_MODE=TESTCLIGCasClibrary is available inPyPI.To install CLI runpip install gitlab-configuration-as-code. Then you can simply executegcasc//TODO add more information on CLI usageCurrently, CLI is limited and does not support passing any arguments to it, but behavior can only be configured
using environment variables. Support for CLI arguments may appear in future releases.Docker imageImage is available inDocker Hub.GCasCDocker image working directory is/workspace. Thus you can quickly launchgcascwith:dockerrun-v$(pwd):/workspacehoffmannlaroche/gcascIt will try to find both GitLab client configuration and GitLab configuration in/workspacedirectory. You can modify
the behavior by passing environment variables:GITLAB_CLIENT_CONFIG_FILEto provide path to GitLab client configuration fileGITLAB_CONFIG_FILEto provide a path to GitLab configuration filedockerrun-eGITLAB_CLIENT_CONFIG_FILE=/gitlab/client.cfg-eGITLAB_CONFIG_FILE=/gitlab/config.yml
-v$(pwd):/gitlabhoffmannlaroche/gcascYou can also configure a GitLab client using environment variables. More details about the configuration of GitLab client
are availablein this documentation.ExamplesWe provide a few examples to give you a quick starting place to useGCasC. They can be found inexamplesdirectory.gitlab.cfgis example GitLab client file configuration.basicis an example GitLab configuration using a single configuration file.environment_variablesshows how environment variables can be injected
into GitLab configuration file using!envdirective.modularizedshows how you can split single GitLab configuration file into smaller
and inject files containing static text using!includedirective.BuildingDocker imageUsemaketo build a basic Docker image quickly.makedocker-buildWhen usingmakeyou can additionally passDOCKER_IMAGE_NAMEto change defaultgcasc:latestto another image name:makedocker-buildDOCKER_IMAGE_NAME=mygcasc:1.0To get more control over builds you can usedocker builddirectly:dockerbuilds-tgcasc[:TAG].Dockerfile comes with two build arguments you may use to customize your image by providing--build-argparameter
todocker buildcommand:GCASC_PATHdefines the path whereGCasClibrary will be copied. Defaults to/opt/gcasc.WORKSPACEdefines a working directory when you runGCasCimage. Defaults to/workspace.Python packageUsemaketo build source distribution (sdist), Wheel binary distribution and Sphinx documentation.makebuildBoth source and Wheel distributions will be placed indistdirectory. Documentation page will be placed
inbuild/docsdirectory.Remember to run tests before building your distribution!TestingBefore 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 installtoxto 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-epy37# run flake8 linter and black code formattertox-eflake# run black code formattertox-eblackInstead of usingtoxdirectly, it is recommended to usemake:# run testsmaketest# run flake8 linter and black code formattermakelintContributionEveryone is warm welcome to contribute!Please make sure to read theContributing GuideandCode of Conductbefore making a pull request.LicenseProject is released underApache License, Version 2.0 license.