Metadata-Version: 2.1
Name: gitlab-configuration-as-code
Version: 0.1b2
Summary: Manage GitLab configuration as code
Home-page: https://github.com/Roche/gitlab-configuration-as-code
Author: Mateusz Filipowicz
Author-email: mateusz.filipowicz@roche.com
License: Apache-2.0
Keywords: gitlab,configuration-as-code
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Description-Content-Type: text/markdown
Requires-Dist: python-gitlab (>=1.13.0)
Requires-Dist: PyYAML (>=5.1.2)

[![Build Status](https://travis-ci.org/Roche/gitlab-configuration-as-code.svg?branch=master)](https://travis-ci.org/Roche/gitlab-configuration-as-code)
[![Docker Pull count](https://img.shields.io/docker/pulls/hoffmannlaroche/gcasc)](https://hub.docker.com/r/hoffmannlaroche/gcasc)
[![PyPI](https://img.shields.io/pypi/v/gitlab-configuration-as-code)](https://pypi.org/project/gitlab-configuration-as-code)
[![Last Commit](https://img.shields.io/github/last-commit/Roche/gitlab-configuration-as-code)]()
[![Python versions](https://img.shields.io/badge/python-3.6%20%7C%203.7%20%7C%203.8-blue)]()
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)]()

# GitLab Configuration as Code (*GCasC*)

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


## Introduction

When configuring your GitLab instance, part of settings you put in [Omnibus](https://docs.gitlab.com/12.4/omnibus/settings/README.html) 
or [Helm Chart](https://docs.gitlab.com/charts/charts/) configuration, and the rest you configure through GitLab UI 
or [API](https://docs.gitlab.com/12.4/ee/api/settings.html). 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:
```yaml
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.

## Quick start


## Usage

| **Environment variable**    | **Description**                                                                                                                  | **Default value**                | **Example**                     |
|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------|----------------------------------|---------------------------------|
| `GITLAB_CONFIG_FILE`        | Path to GitLab main configuration. It is our Configuration as Code entry point.                                                  | `./gitlab.yml`                   | `/home/myuser/gitlabconf.yml`   |
| `GITLAB_MODE`               | Determine if any changes, when detected, should be applied. Valid values: `APPLY`, `TEST`                                        | `APPLY`                          | `TEST`                          |
| `GITLAB_CLIENT_API_VERSION` | Version of GitLab API. Current latest: `4`                                                                                       | `4`                              | `4`                             |
| `GITLAB_CLIENT_CONFIG_FILE` | Path to GitLab client configuration                                                                                              | `/etc/gitlab.cfg, ~/.gitlab.cfg` | `/home/myuser/gitlabclient.cfg` |
| `GITLAB_CLIENT_URL`         | URL to GitLab instance. Used only if `GITLAB_CLIENT_CONFIG_FILE` not provided or invalid.                                        | `https://gitlab.com`             | `https://mygitlab.mydomain.com` |
| `GITLAB_CLIENT_SSL_VERIFY`  | Flag if SSL certificate of GitLab instance should be verified. Used only if `GITLAB_CLIENT_CONFIG_FILE` not provided or invalid. | `true`                           | `false`                         |
| `GITLAB_CLIENT_TOKEN`       | **Required**. Private token used to access GitLab API. Used only if `GITLAB_CLIENT_CONFIG_FILE` not provided or invalid.         |                                  | `-uub91Jax13P1iaLkC3za0`        |
| `GITLAB_CLIENT_CERT`        | Path to client certificate used for mutual TLS authentication to access GitLab API.                                              |                                  | `/home/myuser/client.crt`       |
| `GITLAB_CLIENT_KEY`         | Path to client key used for mutual TLS authentication to access GitLab API.                                                      |                                  | `/home/myuser/key.pem`          |


### GitLab Configuration

#### Application Settings


GCasC targets 
https://docs.gitlab.com/12.4/ee/api/settings.html

#### License

**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.

| **Property**         | **Description**                                                                      | **Example**             |
|----------------------|--------------------------------------------------------------------------------------|-------------------------|
| `license.starts_at`  | Date in format yyyy-MM-dd when license starts                                        | `2019-11-21`            |
| `license.expires_at` | Date in format yyyy-MM-dd when license ends                                          | `2019-12-21`            |
| `license.plan`       | Plan of your GitLab instance license. Valid values: `starter`, `premium`, `ultimate` | `premium`               |
| `license.user_limit` | Number of licensed users                                                             | `120`                   |
| `license.data`       | Content of your license file that you received from GitLab sales                     | `azhxWFZqb1BsrTVxug...` |

Example license configuration:
```yaml
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 `!env` or `!include` directives to inject license to `license.data` field securely from
external source. Also keep your license file itself safe and secure!

### Client configuration


#### Authentication


### Using _GCasC_ Docker image

#### How to build

```yaml
make docker-build
```
When using make you can additionally pass `DOCKER_IMAGE_NAME` to change default `gcasc:latest` to other image name:
```bash
make docker-build DOCKER_IMAGE_NAME=mygcasc:1.0
```

To get more control over building you can use `docker build` directly:
```bash
docker build -t gcasc[:TAG] .
```

#### How to use

_GCasC_ Docker image working directory is `/workspace`. Thus you can quickly launch `gcasc` with:
```bash
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`


### Examples

We provide few examples to give you a quick starting place to use _GCasC_. They can be found in [`examples`](examples) directory.
1. [`gitlab.cfg`](examples/gitlab.cfg) is example GitLab client file configuration.
2. [`basic`](examples/basic/gitlab.yml) is example GitLab configuration using single configuration file.
3. [`environment_variables`](examples/environment_variables) shows how environment variables can be injected 
into GitLab configuration file using `!env` directive.
4. [`modularized`](examples/modularized) shows how you can split single GitLab configuration file into smaller 
and inject files containing static text using `!include` directive.

## Testing

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:

```bash
# 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 `make`:
```bash
# run tests
make test

# run flake8 linter and black code formatter
make lint
```

## Troubleshooting


## Contribution

Everyone is warm welcome to contribute!

Please make sure to read the [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) 
before making a pull request.

## License

Project is released under [Apache License, Version 2.0 license](LICENSE).

