From faee0750d08787993727f10a008c70aa63f8814c Mon Sep 17 00:00:00 2001 From: Kamil Trzcinski Date: Wed, 5 Aug 2015 12:30:34 +0200 Subject: Update documentation --- doc/docker/using_docker_images.md | 33 +++++++++++++++++++++++++++++++++ doc/variables/README.md | 32 ++++++++++++++++++++++++++++++-- doc/yaml/README.md | 16 ++++++++++++++++ 3 files changed, 79 insertions(+), 2 deletions(-) diff --git a/doc/docker/using_docker_images.md b/doc/docker/using_docker_images.md index a88bb62..ef449cd 100644 --- a/doc/docker/using_docker_images.md +++ b/doc/docker/using_docker_images.md @@ -66,6 +66,39 @@ Alias hostname for the service is made from the image name: 1. Everything after `:` is stripped, 2. '/' is replaced to `_`. +### Configuring services +Many services accept environment variables, which allow you to easily change database names or set account names depending on the environment. + +GitLab Runner 0.5.0 and up passes all YAML-defined variables to created service containers. + +1. To configure database name for [postgres](https://registry.hub.docker.com/u/library/postgres/) service, +you need to set POSTGRES_DB. + + ```yaml + services: + - postgres + + variables: + POSTGRES_DB: gitlab + ``` + +1. To use [mysql](https://registry.hub.docker.com/u/library/mysql/) service with empty password for time of build, +you need to set MYSQL_ALLOW_EMPTY_PASSWORD. + + ```yaml + services: + - mysql + + variables: + MYSQL_ALLOW_EMPTY_PASSWORD: yes + ``` + +For other possible configuration variables check the +https://registry.hub.docker.com/u/library/mysql/ or https://registry.hub.docker.com/u/library/postgres/ +or README page for any other Docker image. + +**Note: All variables will passed to all service containers. It's not designed to distinguish which variable should go where.** + ### Overwrite image and services It's possible to overwrite `docker-image` and specify services from `.gitlab-ci.yml`. If you add to your YAML the `image` and the `services` these parameters diff --git a/doc/variables/README.md b/doc/variables/README.md index d61474a..04c6bf1 100644 --- a/doc/variables/README.md +++ b/doc/variables/README.md @@ -1,6 +1,17 @@ ## Variables When receiving a build from GitLab CI, the runner prepares the build environment. -It starts by setting a list of **predefined variables** (Environment Variables) and a list of **user-defined variables** (Secure Variables) +It starts by setting a list of **predefined variables** (Environment Variables) and a list of **user-defined variables** + +The variables can be overwritten. They take precedence over each other in this order: +1. Secure variables +1. YAML-defined variables +1. Predefined variables + +For example, if you define: +1. API_TOKEN=SECURE as Secure Variable +1. API_TOKEN=YAML as YAML-defined variable + +The API_TOKEN will take the Secure Variable value: `SECURE`. ### Predefined variables (Environment Variables) @@ -36,8 +47,25 @@ export CI_SERVER_REVISION="" export CI_SERVER_VERSION="" ``` +### YAML-defined variables +**This feature requires GitLab Runner 0.5.0 or higher** + +GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in build environment. +The variables are stored in repository and are meant to store non-sensitive project configuration, ie. RAILS_ENV or DATABASE_URL. + +```yaml +variables: + DATABASE_URL: "postgres://postgres@postgres/my_database" +``` + +These variables can be later used in all executed commands and scripts. + +The YAML-defined variables are also set to all created service containers, thus allowing to fine tune them. + +More information about Docker integration can be found in [Using Docker Images](../docker/using_docker_images.md). + ### User-defined variables (Secure Variables) -**This feature requires `gitlab-runner` with version equal or greater than 0.4.0.** +**This feature requires GitLab Runner 0.4.0 or higher** GitLab CI allows you to define per-project **Secure Variables** that are set in build environment. The secure variables are stored out of the repository (the `.gitlab-ci.yml`). diff --git a/doc/yaml/README.md b/doc/yaml/README.md index 301144a..4caecca 100644 --- a/doc/yaml/README.md +++ b/doc/yaml/README.md @@ -55,6 +55,7 @@ There are a few `keywords` that can't be used as job names: | stages | optional | Define build stages | | types | optional | Alias for `stages` | | before_script | optional | Define commands prepended for each job's script | +| variables | optional | Define build variables | ### image and services This allows to specify a custom Docker image and a list of services that can be used for time of the build. @@ -94,6 +95,21 @@ There are also two edge cases worth mentioning: ### types Alias for [stages](#stages). +### variables +**This feature requires `gitlab-runner` with version equal or greater than 0.5.0.** + +GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in build environment. +The variables are stored in repository and are meant to store non-sensitive project configuration, ie. RAILS_ENV or DATABASE_URL. + +```yaml +variables: + DATABASE_URL: "postgres://postgres@postgres/my_database" +``` + +These variables can be later used in all executed commands and scripts. + +The YAML-defined variables are also set to all created service containers, thus allowing to fine tune them. + ## Jobs `.gitlab-ci.yml` allows you to specify an unlimited number of jobs. Each job has to have a unique `job_name`, which is not one of the keywords mentioned above. -- cgit v1.2.1