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

docs: update GitLab links

parent 23f0f3a6

.gitlab/merge_request_templates/initial.md

+11 −11
Original line number Diff line number Diff line
@@ -12,8 +12,8 @@ Template type: **build** / **analyse** / **package** / **deploy** / **acceptance 
* General:

    * [ ] add project logo (`logo.png` file) - preferably 256x256

    * [ ] defines a base (hidden) job

    * [ ] use [rules](https://docs.gitlab.com/ee/ci/yaml/#rules) instead of [only/except](https://docs.gitlab.com/ee/ci/yaml/#onlyexcept-advanced)

    * [ ] optimized [cache](https://docs.gitlab.com/ee/ci/caching/) configuration (wherever applicable)

    * [ ] use [rules](https://docs.gitlab.com/ci/yaml/#rules) instead of [only/except](https://docs.gitlab.com/ci/yaml/#onlyexcept-advanced)

    * [ ] optimized [cache](https://docs.gitlab.com/ci/caching/) configuration (wherever applicable)

* Publicly usable:

    * [ ] runners: untagged

    * [ ] no proxy configuration but support `http_proxy`/`https_proxy`/`no_proxy` configuration
@@ -38,9 +38,9 @@ Template type: **build** / **analyse** / **package** / **deploy** / **acceptance 
* Build & Test job:

    * (type here the used build & test tools/frameworks)

    * [ ] mapped to the `build` stage

    * [ ] unit tests report integration using [JUnit test report](https://docs.gitlab.com/ee/ci/junit_test_reports.html)

    * [ ] code coverage computing and [integration](https://docs.gitlab.com/ee/ci/yaml/#coverage)

    * [ ] optimized [cache](https://docs.gitlab.com/ee/ci/caching/) configuration

    * [ ] unit tests report integration using [JUnit test report](https://docs.gitlab.com/ci/testing/unit_test_reports/)

    * [ ] code coverage computing and [integration](https://docs.gitlab.com/ci/yaml/#coverage)

    * [ ] optimized [cache](https://docs.gitlab.com/ci/caching/) configuration

* (optional) Code analysis job(s):

    * (type here the used code analysis tools)

    * [ ] mapped to the `test` stage
@@ -59,7 +59,7 @@ Template type: **build** / **analyse** / **package** / **deploy** / **acceptance 
    * [ ] mapped to the `test` stage

    * [ ] can be enabled/disabled by configuration

    * [ ] whenever possible, code analysis on non-`master`, non-`develop` branches should be a partial/light analysis

    * [ ] if the analysis is time consuming it shall be [triggered manually](https://docs.gitlab.com/ee/ci/yaml/#whenmanual)

    * [ ] if the analysis is time consuming it shall be [triggered manually](https://docs.gitlab.com/ci/yaml/#whenmanual)

      by default, and automatable by configuration



### Packaging template checklist
@@ -79,14 +79,14 @@ Template type: **build** / **analyse** / **package** / **deploy** / **acceptance 
* Deployment jobs:

    * [ ] one hidden deploy job prototype

    * [ ] persist and propagate the `$CI_ENVIRONMENT_URL` variable as `environment_url` variable using a 

      [dotenv artifact](https://docs.gitlab.com/ee/ci/pipelines/job_artifacts.html#artifactsreportsdotenv)

      [dotenv artifact](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportsdotenv)

    * [ ] each env can be enabled/disabled by configuration

    * [ ] each env uses the [`resource_group`](https://docs.gitlab.com/ee/ci/yaml/#resource_group) feature to prevent 

    * [ ] each env uses the [`resource_group`](https://docs.gitlab.com/ci/yaml/#resource_group) feature to prevent 

      multiple pipelines from deploying to the same environment at the same time

    * [ ] **review** deployment job

        * mapped to the `deploy` stage

        * must be executed on non-`master`, non-`develop` branches only

        * must reference the **cleanup-review** job (see below) in its [`environment:on_stop`](https://docs.gitlab.com/ee/ci/yaml/#environmenton_stop)

        * must reference the **cleanup-review** job (see below) in its [`environment:on_stop`](https://docs.gitlab.com/ci/yaml/#environmenton_stop)

    * [ ] **integration** deployment job

        * mapped to the `deploy` stage

        * must be executed on `develop` branch only
@@ -101,7 +101,7 @@ Template type: **build** / **analyse** / **package** / **deploy** / **acceptance 
    * [ ] **review** cleanup job

        * mapped to the `deploy` stage

        * must be executed on non-`master`, non-`develop` branches only

        * must be associated to the [`environment:action:stop`](https://docs.gitlab.com/ee/ci/yaml/#environmentaction) event

        * must be associated to the [`environment:action:stop`](https://docs.gitlab.com/ci/yaml/#environmentaction) event

* (optional) Analysis job(s) (linters, dependency checks, ...) depending on the technologies:

    * [ ] mapped to the `test` stage
@@ -111,7 +111,7 @@ Template type: **build** / **analyse** / **package** / **deploy** / **acceptance 


* Acceptance test job:

    * [ ] mapped to the `acceptance` stage

    * [ ] tests report integration using [JUnit test report](https://docs.gitlab.com/ee/ci/junit_test_reports.html)

    * [ ] tests report integration using [JUnit test report](https://docs.gitlab.com/ci/testing/unit_test_reports/)

    * [ ] auto-evaluating the environment url to test based on the possible upstream `$environment_url` variable or via 

      an `environment_url.txt` file.

.gitlab/merge_request_templates/new_feature.md

+2 −2
Original line number Diff line number Diff line
@@ -8,8 +8,8 @@ Closes #999 
## Checklist



* General:

    * [ ] use [rules](https://docs.gitlab.com/ee/ci/yaml/#rules) instead of [only/except](https://docs.gitlab.com/ee/ci/yaml/#onlyexcept-advanced)

    * [ ] optimized [cache](https://docs.gitlab.com/ee/ci/caching/) configuration (wherever applicable)

    * [ ] use [rules](https://docs.gitlab.com/ci/yaml/#rules) instead of [only/except](https://docs.gitlab.com/ci/yaml/#onlyexcept-advanced)

    * [ ] optimized [cache](https://docs.gitlab.com/ci/caching/) configuration (wherever applicable)

* Publicly usable:

    * [ ] untagged runners

    * [ ] no proxy configuration but support `http_proxy`/`https_proxy`/`no_proxy`

CONTRIBUTING.md

+1 −1
Original line number Diff line number Diff line
@@ -61,7 +61,7 @@ To contribute: 


1. Create an issue describing the bug or enhancement you want to propose (select the right issue template).

2. Make sure the issue has been reviewed and agreed.

3. Create a Merge Request, from your **own** fork (see [forking workflow](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html) documentation).

3. Create a Merge Request, from your **own** fork (see [forking workflow](https://docs.gitlab.com/user/project/repository/forking_workflow/) documentation).

   Don't hesitate to mark your MR as `Draft` as long as you think it's not ready to be reviewed.



### Git Commit Conventions

README.md

+23 −23
Original line number Diff line number Diff line
@@ -4,8 +4,8 @@ This project implements a GitLab CI/CD template to deploy your application to [A 


## Usage



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.

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

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



### Use as a CI/CD component
@@ -67,7 +67,7 @@ _ongoing developments_ (a.k.a. _feature_ or _topic_ branches). 
When enabled, it deploys the result from upstream build stages to a dedicated and temporary environment.

It is only active for non-production, non-integration branches.



It is a strict equivalent of GitLab's [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/) feature.

It is a strict equivalent of GitLab's [Review Apps](https://docs.gitlab.com/ci/review_apps/) feature.



It also comes with a _cleanup_ job (accessible either from the _environments_ page, or from the pipeline view).
@@ -96,7 +96,7 @@ You're free to enable whichever or both, and you can also choose your deployment 
The AWS template supports two kinds of authentication:



1. basic authentication with AWS access key ID & secret access key,

2. or [federated authentication using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/).

2. or [federated authentication using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/).



#### Basic authentication
@@ -106,7 +106,7 @@ That means you'll have to manage AWS authentication by yourself, according to th 


For credentials management, we strongly advise to use [environment variables configuration](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html#envvars-list), managed as GitLab CI secret variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, possibly `AWS_ROLE_ARN`).



If you have to manage different set of authentication credentials depending on managed environments, you shall either use [GitLab scoped variables](https://docs.gitlab.com/ee/ci/environments/index.html#scoping-environments-with-specs) or our [scoped variables syntax](https://to-be-continuous.gitlab.io/doc/usage/#scoped-variables) to limit/override some variables values, using `$CI_ENVIRONMENT_NAME` as the conditional variable.

If you have to manage different set of authentication credentials depending on managed environments, you shall either use [GitLab scoped variables](https://docs.gitlab.com/ci/environments/#scoping-environments-with-specs) or our [scoped variables syntax](https://to-be-continuous.gitlab.io/doc/usage/#scoped-variables) to limit/override some variables values, using `$CI_ENVIRONMENT_NAME` as the conditional variable.



Example: different credentials for production (:warning: declared as project variables)
@@ -122,7 +122,7 @@ scoped__AWS_SECRET_ACCESS_KEY__if__CI_ENVIRONMENT_NAME__equals__production: "<my 


#### Federated authentication using OpenID Connect



The AWS template supports [OpenID Connect to retrieve temporary credentials](https://docs.gitlab.com/ee/ci/cloud_services/aws/).

The AWS template supports [OpenID Connect to retrieve temporary credentials](https://docs.gitlab.com/ci/cloud_services/aws/).



If you wish to use this authentication mode, please activate and configure the [OIDC variant](#oidc-variant).
@@ -182,8 +182,8 @@ The cleanup script is searched as follows: 
>     * `${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`)

>     * `${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/#for-a-project)

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

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

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



### Environments URL management
@@ -191,7 +191,7 @@ The cleanup script is searched as follows: 
The AWS 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-a-dynamic-environment-url): when the url cannot be known before the

* a [**dynamic way**](https://docs.gitlab.com/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):
@@ -220,7 +220,7 @@ the dynamically generated url. When detected by the template, it will use it as 


### Deployment output variables



Each deployment job produces _output variables_ that are propagated to downstream jobs (using [dotenv artifacts](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportsdotenv)):

Each deployment job produces _output variables_ that are propagated to downstream jobs (using [dotenv artifacts](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportsdotenv)):



* `$environment_type`: set to the type of environment (`review`, `integration`, `staging` or `production`),

* `$environment_name`: the application name (see below),
@@ -236,12 +236,12 @@ You may also add and propagate your own custom variables, by pushing them to the 


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/#for-a-project):

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

1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ci/variables/#for-a-project):

    * [**masked**](https://docs.gitlab.com/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/#protected-cicd-variables) if you want to secure some secrets 

    * [**protected**](https://docs.gitlab.com/ci/variables/#protected-cicd-variables) 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/#mask-a-cicd-variable), 

2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/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: `$` -> `$$`).
@@ -253,7 +253,7 @@ The AWS template uses some global configuration used throughout all jobs and env 
| Input / Variable | Description                            | Default value     |

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

| `cli-image` / `AWS_CLI_IMAGE` | the Docker image used to run AWS CLI commands| `registry.hub.docker.com/amazon/aws-cli:latest` <br/>[![Trivy Badge](https://to-be-continuous.gitlab.io/doc/secu/trivy-badge-AWS_CLI_IMAGE.svg)](https://to-be-continuous.gitlab.io/doc/secu/trivy-AWS_CLI_IMAGE) |

| `base-app-name` / `AWS_BASE_APP_NAME` | Base application name                  | `$CI_PROJECT_NAME` ([see GitLab doc](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)) |

| `base-app-name` / `AWS_BASE_APP_NAME` | Base application name                  | `$CI_PROJECT_NAME` ([see GitLab doc](https://docs.gitlab.com/ci/variables/predefined_variables/)) |

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

| `scripts-dir` / `AWS_SCRIPTS_DIR` | Directory where AWS scripts (deploy & cleanup) are located | `.` _(root project dir)_ |
@@ -486,9 +486,9 @@ The AWS template can be used in conjunction with template variants to cover spec 


### OIDC variant



This variant enables [OpenID Connect to retrieve temporary credentials](https://docs.gitlab.com/ee/ci/cloud_services/aws/).

This variant enables [OpenID Connect to retrieve temporary credentials](https://docs.gitlab.com/ci/cloud_services/aws/).



If you wish to use this authentication mode, please follow carefully [the GitLab guide](https://docs.gitlab.com/ee/ci/cloud_services/aws/), 

If you wish to use this authentication mode, please follow carefully [the GitLab guide](https://docs.gitlab.com/ci/cloud_services/aws/), 

then configure appropriately the related variables:



* `AWS_OIDC_ROLE_ARN` for any global/common access,
@@ -501,11 +501,11 @@ The variant supports the following configuration: 
| Input / Variable | Description                            | Default value     |

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

| `oidc-aud` / `AWS_OIDC_AUD` | The `aud` claim for the JWT | `$CI_SERVER_URL` |

| `oidc-role-arn` / `AWS_OIDC_ROLE_ARN` | Default IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) | _none_ (disabled) |

| `review-oidc-role-arn` / `AWS_REVIEW_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `review` env _(only define to override default)_ | _none_ (disabled) |

| `integ-oidc-role-arn` / `AWS_INTEG_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `integration` env _(only define to override default)_ | _none_ (disabled) |

| `staging-oidc-role-arn` / `AWS_STAGING_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `staging` env _(only define to override default)_ | _none_ (disabled) |

| `prod-oidc-role-arn` / `AWS_PROD_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `production` env _(only define to override default)_ | _none_ (disabled) |

| `oidc-role-arn` / `AWS_OIDC_ROLE_ARN` | Default IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) | _none_ (disabled) |

| `review-oidc-role-arn` / `AWS_REVIEW_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `review` env _(only define to override default)_ | _none_ (disabled) |

| `integ-oidc-role-arn` / `AWS_INTEG_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `integration` env _(only define to override default)_ | _none_ (disabled) |

| `staging-oidc-role-arn` / `AWS_STAGING_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `staging` env _(only define to override default)_ | _none_ (disabled) |

| `prod-oidc-role-arn` / `AWS_PROD_OIDC_ROLE_ARN` | IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `production` env _(only define to override default)_ | _none_ (disabled) |



#### Example
@@ -540,7 +540,7 @@ In order to be able to communicate with the Vault server, the variant requires t 
| :lock: `VAULT_ROLE_ID`   | The [AppRole](https://www.vaultproject.io/docs/auth/approle) RoleID | _none_ |

| :lock: `VAULT_SECRET_ID` | The [AppRole](https://www.vaultproject.io/docs/auth/approle) SecretID | _none_ |



By default, the variant will authentifacte using a [JWT ID token](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html). To use [AppRole](https://www.vaultproject.io/docs/auth/approle) instead the `VAULT_ROLE_ID` and `VAULT_SECRET_ID` should be defined as secret project variables.

By default, the variant will authentifacte using a [JWT ID token](https://docs.gitlab.com/ci/secrets/id_token_authentication/). To use [AppRole](https://www.vaultproject.io/docs/auth/approle) instead the `VAULT_ROLE_ID` and `VAULT_SECRET_ID` should be defined as secret project variables.



#### Usage

kicker.json

+7 −7
Original line number Diff line number Diff line
@@ -33,7 +33,7 @@ 
    {

      "id": "review",

      "name": "Review",

      "description": "Dynamic review environments for your topic branches (see GitLab [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/))",

      "description": "Dynamic review environments for your topic branches (see GitLab [Review Apps](https://docs.gitlab.com/ci/review_apps/))",

      "enable_with": "AWS_REVIEW_ENABLED",

      "variables": [

        {
@@ -123,7 +123,7 @@ 
    {

      "id": "oidc",

      "name": "OpenID Connect",

      "description": "Enables [federated authentication using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/)",

      "description": "Enables [federated authentication using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/)",

      "template_path": "templates/gitlab-ci-aws-oidc.yml",

      "variables": [

        {
@@ -133,27 +133,27 @@ 
        },

        {

          "name": "AWS_OIDC_ROLE_ARN",

          "description": "Default IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/)",

          "description": "Default IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/)",

          "advanced": true

        },

        {

          "name": "AWS_REVIEW_OIDC_ROLE_ARN",

          "description": "IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `review` env _(only define to override default)_",

          "description": "IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `review` env _(only define to override default)_",

          "advanced": true

        },

        {

          "name": "AWS_INTEG_OIDC_ROLE_ARN",

          "description": "IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `integration` env _(only define to override default)_",

          "description": "IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `integration` env _(only define to override default)_",

          "advanced": true

        },

        {

          "name": "AWS_STAGING_OIDC_ROLE_ARN",

          "description": "IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `staging` env _(only define to override default)_",

          "description": "IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `staging` env _(only define to override default)_",

          "advanced": true

        },

        {

          "name": "AWS_PROD_OIDC_ROLE_ARN",

          "description": "IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/aws/) on `production` env _(only define to override default)_",

          "description": "IAM Role ARN associated with GitLab to [authenticate using OpenID Connect](https://docs.gitlab.com/ci/cloud_services/aws/) on `production` env _(only define to override default)_",

          "advanced": true

        }

      ]