Commit fcd0e607 authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

Merge branch 'dreglad-master-patch-35357' into 'master' 

README.md template minor refinement

See merge request to-be-continuous/tools/template-skeleton-2!11
parents e766330f 918eb96f

{{cookiecutter.project_slug}}/README.md

+35 −35
Original line number Diff line number Diff line 
# GitLab CI template for {{cookiecutter.template_name}}

{% if cookiecutter.template_type == 'build' %}

This project implements a GitLab CI/CD template to build, test and analyse your [{{cookiecutter.template_name}}]({{cookiecutter.refdoc_url}}) projects.

This project implements a GitLab CI/CD template to build, test, and analyse your [{{cookiecutter.template_name}}]({{cookiecutter.refdoc_url}}) projects.



## Usage



This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component-in-a-cicd-configuration) 

This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component) 

or using the legacy [`include:project`](https://docs.gitlab.com/ee/ci/yaml/index.html#includeproject) syntax.



### Use as a CI/CD component



Add the following to your `gitlab-ci.yml`:

Add the following to your `.gitlab-ci.yml`:



```yaml

include:

  # 1: include the component

  - component: gitlab.com/to-be-continuous/{{cookiecutter.project_slug}}/gitlab-ci-{{cookiecutter.project_slug}}@1.0.0

  - component: $CI_SERVER_FQDN/to-be-continuous/{{cookiecutter.project_slug}}/gitlab-ci-{{cookiecutter.project_slug}}@1.0.0

    # 2: set/override component inputs

    inputs:

      # ⚠ this is only an example
@@ -23,7 +23,7 @@ include: 


### Use as a CI/CD template (legacy)



Add the following to your `gitlab-ci.yml`:

Add the following to your `.gitlab-ci.yml`:



```yaml

include:
@@ -64,12 +64,12 @@ If you're using the SonarQube template to analyse your {{cookiecutter.template_P 


```properties

# see: https://docs.sonarqube.org/latest/analysis/languages/{{cookiecutter.project_slug}}/

# set your source directory(ies) here (relative to the sonar-project.properties file)

# set your source directories here (relative to the sonar-project.properties file)

sonar.sources=.

# exclude unwanted directories and files from being analysed

sonar.exclusions=output/**,**/*_test.{{cookiecutter.template_prefix}}



# set your tests directory(ies) here (relative to the sonar-project.properties file)

# set your tests directories here (relative to the sonar-project.properties file)

sonar.tests=.

sonar.test.inclusions=**/*_test.{{cookiecutter.template_prefix}}
@@ -118,38 +118,38 @@ It uses the following variables: 
| --------------------- | -------------------------------------- | ----------------- |

| `publish-enabled` / `{{cookiecutter.template_PREFIX}}_PUBLISH_ENABLED` | Variable to enable the publish job     | _none_ (disabled) |

| `publish-args` / `{{cookiecutter.template_PREFIX}}_PUBLISH_ARGS`    | Arguments used by the publish job      | `publish --with-default-args` |

| :lock: `{{cookiecutter.template_PREFIX}}_PUBLISH_LOGIN` | Login to use to publish           | **has to be defined** |

| :lock: `{{cookiecutter.template_PREFIX}}_PUBLISH_PASSWORD` | Password to use to publish     | **has to be defined** |

| :lock: `{{cookiecutter.template_PREFIX}}_PUBLISH_LOGIN` | Login to use to publish           | **must be defined** |

| :lock: `{{cookiecutter.template_PREFIX}}_PUBLISH_PASSWORD` | Password to use to publish     | **must be defined** |



### Secrets management



Here are some advices about your **secrets** (variables marked with a :lock:):



1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui):

    * [**masked**](https://docs.gitlab.com/ee/ci/variables/#mask-a-custom-variable) to prevent them from being inadvertently

1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#define-a-cicd-variable-in-the-ui):

    * [**masked**](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable) to prevent them from being inadvertently

      displayed in your job logs,

    * [**protected**](https://docs.gitlab.com/ee/ci/variables/#protect-a-custom-variable) if you want to secure some secrets

    * [**protected**](https://docs.gitlab.com/ee/ci/variables/#protect-a-cicd-variable) if you want to secure some secrets

      you don't want everyone in the project to have access to (for instance production secrets).

2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/ee/ci/variables/#masked-variable-requirements), 

2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable), 

  simply define its value as the [Base64](https://en.wikipedia.org/wiki/Base64) encoded value prefixed with `@b64@`:

  it will then be possible to mask it and the template will automatically decode it prior to using it.

3. Don't forget to escape special characters (ex: `$` -> `$$`).

3. Don't forget to escape special characters (e.g.: `$` -> `$$`).

{%- elif cookiecutter.template_type == 'deploy' %}

This project implements a GitLab CI/CD template to deploy your application to [{{cookiecutter.template_name}}]({{cookiecutter.refdoc_url}}).



## Usage



This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component-in-a-cicd-configuration) 

This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component) 

or using the legacy [`include:project`](https://docs.gitlab.com/ee/ci/yaml/index.html#includeproject) syntax.



### Use as a CI/CD component



Add the following to your `gitlab-ci.yml`:

Add the following to your `.gitlab-ci.yml`:



```yaml

include:

  # 1: include the component

  - component: gitlab.com/to-be-continuous/{{cookiecutter.project_slug}}/gitlab-ci-{{cookiecutter.project_slug}}@1.0.0

  - component: $CI_SERVER_FQDN/to-be-continuous/{{cookiecutter.project_slug}}/gitlab-ci-{{cookiecutter.project_slug}}@1.0.0

    # 2: set/override component inputs

    inputs:

      # ⚠ this is only an example
@@ -161,7 +161,7 @@ include: 


### Use as a CI/CD template (legacy)



Add the following to your `gitlab-ci.yml`:

Add the following to your `.gitlab-ci.yml`:



```yaml

include:
@@ -181,7 +181,7 @@ variables: 


## Understand



This chapter introduces key notions and principle to understand how this template works.

This chapter introduces key notions and principles to understand how this template works.



### Managed deployment environments
@@ -235,10 +235,10 @@ The {{cookiecutter.template_name}} template supports the following authenticatio 
### Deployment context variables



In order to manage the various deployment environments, this template provides a couple of **dynamic variables**

that you might use in your hook scripts, deployment manifests and other deployment resources:

that you might use in your hook scripts, deployment manifests, and other deployment resources:



* `${environment_type}`: the current deployment environment type (`review`, `integration`, `staging` or `production`)

* `${environment_name}`: a generated application name to use for the current deployment environment (ex: `myapp-review-fix-bug-12` or `myapp-staging`) - _details below_

* `${environment_name}`: a generated application name to use for the current deployment environment (e.g.: `myapp-review-fix-bug-12` or `myapp-staging`) - _details below_



#### Generated environment name
@@ -268,7 +268,7 @@ Examples (with an application's base name `myapp`): 


> TODO: explain here the supported techniques to deploy and cleanup the environments.

>

> You should also explained clearly what is expected from the template user and what is the lookup policy in case the template

> You should also explain clearly what is expected from the template user and what is the lookup policy in case the template

> implements one.

>

> Example:
@@ -289,22 +289,22 @@ The cleanup script is searched as follows: 
3. if not found: the cleanup job will fail.



> :information_source: Your deployment (and cleanup) scripts have to be able to cope with various environments, each with different application names, exposed routes, settings, ...

> Part of this complexity can be handled by the lookup policies described above (ex: one script per env) and also by using available environment variables:

> Part of this complexity can be handled by the lookup policies described above (e.g.: one script per env) and also by using available environment variables:

>

> 1. [deployment context variables](#deployment-context-variables) provided by the template:

>     * `${environment_type}`: the current environment type (`review`, `integration`, `staging` or `production`)

>     * `${environment_name}`: the application name to use for the current environment (ex: `myproject-review-fix-bug-12` or `myproject-staging`)

>     * `${environment_name}`: the application name to use for the current environment (e.g.: `myproject-review-fix-bug-12` or `myproject-staging`)

>     * `${hostname}`: the environment hostname, extracted from the current environment url (after late variable expansion - see below)

> 2. any [GitLab CI variable](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)

> 3. any [custom variable](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project)

>     (ex: `${SECRET_TOKEN}` that you have set in your project CI/CD variables)

> 3. any [custom variable](https://docs.gitlab.com/ee/ci/variables/#for-a-project)

>     (e.g.: `${SECRET_TOKEN}` that you have set in your project CI/CD variables)



### Environments URL management



The {{cookiecutter.template_name}} template supports two ways of providing your environments url:



* a **static way**: when the environments url can be determined in advance, probably because you're exposing your routes through a DNS you manage,

* a [**dynamic way**](https://docs.gitlab.com/ee/ci/environments/#set-dynamic-environment-urls-after-a-job-finishes): when the url cannot be known before the

* a [**dynamic way**](https://docs.gitlab.com/ee/ci/environments/#set-a-dynamic-environment-url): when the url cannot be known before the

  deployment job is executed.



The **static way** can be implemented simply by setting the appropriate configuration variable(s) depending on the environment (see environments configuration chapters):
@@ -357,7 +357,7 @@ Here are some advices about your **secrets** (variables marked with a :lock:): 
2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable), 

  simply define its value as the [Base64](https://en.wikipedia.org/wiki/Base64) encoded value prefixed with `@b64@`: 

  it will then be possible to mask it and the template will automatically decode it prior to using it.

3. Don't forget to escape special characters (ex: `$` -> `$$`).

3. Don't forget to escape special characters (e.g.: `$` -> `$$`).



### Global configuration
@@ -369,7 +369,7 @@ The {{cookiecutter.template_name}} template uses some global configuration used 
| `base-app-name` / `{{cookiecutter.template_PREFIX}}_BASE_APP_NAME`      | Base application name                  | `$CI_PROJECT_NAME` ([see GitLab doc](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)) |

| `api-url` / `{{cookiecutter.template_PREFIX}}_API_URL`            | Default {{cookiecutter.template_name}} API url | _none_ |

| :lock: `{{cookiecutter.template_PREFIX}}_API_TOKEN`          | Default {{cookiecutter.template_name}} API token | _none_ |

| `environment-url` / `{{cookiecutter.template_PREFIX}}_ENVIRONMENT_URL`    | Default environments url _(only define for static environment URLs declaration)_<br/>_supports late variable expansion (ex: `https://%{environment_name}.{{cookiecutter.project_slug}}.acme.com`)_ | _none_ |

| `environment-url` / `{{cookiecutter.template_PREFIX}}_ENVIRONMENT_URL`    | Default environments url _(only define for static environment URLs declaration)_<br/>_supports late variable expansion (e.g.: `https://%{environment_name}.{{cookiecutter.project_slug}}.acme.com`)_ | _none_ |

| `scripts-dir` / `{{cookiecutter.template_PREFIX}}_SCRIPTS_DIR`        | Directory where deploy & cleanup scripts are located | `.` _(root project dir)_ |



### Review environments configuration
@@ -384,7 +384,7 @@ Here are variables supported to configure review environments: 
| Input / Variable         | Description                            | Default value     |

| ------------------------ | -------------------------------------- | ----------------- |

| `review-project` / `{{cookiecutter.template_PREFIX}}_REVIEW_PROJECT`     | Project ID for `review` env | _none_ (disabled) |

| `review-app-name` / `{{cookiecutter.template_PREFIX}}_REVIEW_APP_NAME`    | Application name for `review` env      | `"{{ '${' }}{{cookiecutter.template_PREFIX}}_BASE_APP_NAME}-${CI_ENVIRONMENT_SLUG}"` (ex: `myproject-review-fix-bug-12`) |

| `review-app-name` / `{{cookiecutter.template_PREFIX}}_REVIEW_APP_NAME`    | Application name for `review` env      | `"{{ '${' }}{{cookiecutter.template_PREFIX}}_BASE_APP_NAME}-${CI_ENVIRONMENT_SLUG}"` (e.g.: `myproject-review-fix-bug-12`) |

| `review-api-url` / `{{cookiecutter.template_PREFIX}}_REVIEW_API_URL`     | API url for `review` env _(only define to override default)_ | `${{cookiecutter.template_PREFIX}}_API_URL` |

| :lock: `{{cookiecutter.template_PREFIX}}_REVIEW_API_TOKEN`   | API token for `review` env _(only define to override default)_ | `${{cookiecutter.template_PREFIX}}_API_TOKEN` |

| `review-environment-url` / `{{cookiecutter.template_PREFIX}}_REVIEW_ENVIRONMENT_URL`| The review environments url _(only define for static environment URLs declaration and if different from default)_ | `${{cookiecutter.template_PREFIX}}_ENVIRONMENT_URL` |
@@ -444,18 +444,18 @@ Here are variables supported to configure the production environment: 
This project implements a GitLab CI/CD template to run your automated tests with [{{cookiecutter.template_name}}]({{cookiecutter.refdoc_url}}).



## Usage



This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component-in-a-cicd-configuration) 

**component: $CI_SERVER_FQDN**

This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component) 

or using the legacy [`include:project`](https://docs.gitlab.com/ee/ci/yaml/index.html#includeproject) syntax.



### Use as a CI/CD component



Add the following to your `gitlab-ci.yml`:

Add the following to your `.gitlab-ci.yml`:



```yaml

include:

  # 1: include the component

  - component: gitlab.com/to-be-continuous/{{cookiecutter.project_slug}}/gitlab-ci-{{cookiecutter.project_slug}}@1.0.0

  - component: $CI_SERVER_FQDN/to-be-continuous/{{cookiecutter.project_slug}}/gitlab-ci-{{cookiecutter.project_slug}}@1.0.0

    # 2: set/override component inputs

    inputs:

      review-enabled: true # ⚠ this is only an example
@@ -463,7 +463,7 @@ include: 


### Use as a CI/CD template (legacy)



Add the following to your `gitlab-ci.yml`:

Add the following to your `.gitlab-ci.yml`:



```yaml

include: