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

docs: update GitLab links

parent b9af542a

.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

+27 −27
Original line number Diff line number Diff line
@@ -5,8 +5,8 @@ your application with [Ansible](https://www.ansible.com/). 


## 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
@@ -70,7 +70,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).
@@ -150,8 +150,8 @@ Deployment jobs also support _optional_ **hook scripts** from your project, loca 
> 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`)

> 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)



### Manage remote repositories authentication
@@ -174,7 +174,7 @@ When such a file is detected, the Ansible template replaces each `${some_env}` p 
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):
@@ -203,7 +203,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),
@@ -216,7 +216,7 @@ You may also add and propagate your own custom variables, by pushing them to the 
### Ansible commands overrides



Instead of creating hook scripts, you can also override and/or decorate the Ansible commands 

using predefined `.ansible-commands` template block, referenced by the [`!reference` directive](https://docs.gitlab.com/ee/ci/yaml/#reference-tags).

using predefined `.ansible-commands` template block, referenced by the [`!reference` directive](https://docs.gitlab.com/ci/yaml/#reference-tags).



By default, the `.ansible-commands`, block is composed as below:
@@ -246,12 +246,12 @@ You can use this mechanism to source to the current shell your own environmental 


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: `$` -> `$$`).
@@ -264,7 +264,7 @@ This template can be configured with the following **environment variables**: 
| ------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------- |

| `image` / `ANSIBLE_IMAGE` | The Docker image used to run Ansible. The image may contain your Ansible sources. <br/>:warning: **set the version required by your project** | `registry.hub.docker.com/cytopia/ansible:latest-tools` <br/>[![Trivy Badge](https://to-be-continuous.gitlab.io/doc/secu/trivy-badge-ANSIBLE_IMAGE.svg)](https://to-be-continuous.gitlab.io/doc/secu/trivy-ANSIBLE_IMAGE) |

| `project-dir` / `ANSIBLE_PROJECT_DIR` | Ansible project root directory                                                       | `.`                                            |

| `base-app-name` / `ANSIBLE_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` / `ANSIBLE_BASE_APP_NAME` | Base application name                  | `$CI_PROJECT_NAME` ([see GitLab doc](https://docs.gitlab.com/ci/variables/predefined_variables/)) |

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

| :lock: `ANSIBLE_VAULT_PASSWORD` | The Ansible vault password used to decrypt vars.                                     | **has to be defined in gitlab secret if used** |

| :lock: `ANSIBLE_PRIVATE_KEY`    | The Ansible SSH private key to use in all stages (can be overridden per env)         | **has to be defined in gitlab secret if used** |
@@ -387,7 +387,7 @@ In addition to a textual report in the console, this job produces the following 


| Report         | Format                                                                       | Usage             |

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

| `$ANSIBLE_PROJECT_DIR/reports/ansible-lint-*.codeclimate.json` | [codeclimate format](https://ansible-lint.readthedocs.io/usage/#id2) | [GitLab integration](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportscodequality) |

| `$ANSIBLE_PROJECT_DIR/reports/ansible-lint-*.codeclimate.json` | [codeclimate format](https://ansible-lint.readthedocs.io/usage/#id2) | [GitLab integration](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportscodequality) |



## Examples
@@ -543,7 +543,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
@@ -598,7 +598,7 @@ This [blog post about OIDC impersonation through Workload Identify Federation][g 
[gcp-adc]: https://cloud.google.com/docs/authentication/client-libraries

[gcp-provider]: https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference#running-terraform-outside-of-google-cloud

[gcp-iam-principals]: https://cloud.google.com/iam/docs/principal-identifiers

[gcp-gitlab-wif]: https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/

[gcp-gitlab-wif]: https://docs.gitlab.com/ci/cloud_services/google_cloud/

[gcp-wif-example]: https://blog.salrashid.dev/articles/2021/understanding_workload_identity_federation/#oidc-impersonated



#### Configuration
@@ -608,15 +608,15 @@ The variant requires the additional configuration parameters: 
| Input / Variable                                          | Description                                                                                                                                                                                                          | Default value    |

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

| `gcp-oidc-aud` / `GCP_OIDC_AUD`                           | The `aud` claim for the JWT token                                                                                                                                                                                    | `$CI_SERVER_URL` |

| `gcp-oidc-provider` / `GCP_OIDC_PROVIDER`                 | Default Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/)                                                          | _none_           |

| `gcp-oidc-provider` / `GCP_OIDC_PROVIDER`                 | Default Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/)                                                          | _none_           |

| `gcp-oidc-account` / `GCP_OIDC_ACCOUNT`                   | Default Service Account to which impersonate with OpenID Connect authentication                                                                                                                                      | _none_           |

| `gcp-review-oidc-provider` / `GCP_REVIEW_OIDC_PROVIDER`   | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `review` environment _(only define to override default)_      | _none_           |

| `gcp-review-oidc-provider` / `GCP_REVIEW_OIDC_PROVIDER`   | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `review` environment _(only define to override default)_      | _none_           |

| `gcp-review-oidc-account` / `GCP_REVIEW_OIDC_ACCOUNT`     | Service Account to which impersonate with OpenID Connect authentication on `review` environment _(only define to override default)_                                                                                  | _none_           |

| `gcp-integ-oidc-provider` / `GCP_INTEG_OIDC_PROVIDER`     | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `integration` environment _(only define to override default)_ | _none_           |

| `gcp-integ-oidc-provider` / `GCP_INTEG_OIDC_PROVIDER`     | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `integration` environment _(only define to override default)_ | _none_           |

| `gcp-integ-oidc-account` / `GCP_INTEG_OIDC_ACCOUNT`       | Service Account to which impersonate with OpenID Connect authentication on `integration` environment _(only define to override default)_                                                                             | _none_           |

| `gcp-staging-oidc-provider` / `GCP_STAGING_OIDC_PROVIDER` | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `staging` environment _(only define to override default)_     | _none_           |

| `gcp-staging-oidc-provider` / `GCP_STAGING_OIDC_PROVIDER` | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `staging` environment _(only define to override default)_     | _none_           |

| `gcp-staging-oidc-account` / `GCP_STAGING_OIDC_ACCOUNT`   | Service Account to which impersonate with OpenID Connect authentication on `staging` environment _(only define to override default)_                                                                                 | _none_           |

| `gcp-prod-oidc-provider` / `GCP_PROD_OIDC_PROVIDER`       | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `production` environment _(only define to override default)_  | _none_           |

| `gcp-prod-oidc-provider` / `GCP_PROD_OIDC_PROVIDER`       | Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `production` environment _(only define to override default)_  | _none_           |

| `gcp-prod-oidc-account` / `GCP_PROD_OIDC_ACCOUNT`         | Service Account to which impersonate with OpenID Connect authentication on `production` environment _(only define to override default)_                                                                              | _none_           |



#### Example
@@ -655,7 +655,7 @@ This variant use the OIDC and [AWS STS](https://docs.aws.amazon.com/fr_fr/STS/la 


- [Create an OpenID Connect (OIDC) identity provider in IAM

  ](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)

- [Configure a web identity role](https://docs.gitlab.com/ee/ci/cloud_services/aws/#configure-a-role-and-trust)

- [Configure a web identity role](https://docs.gitlab.com/ci/cloud_services/aws/#configure-a-role-and-trust)



#### Configuration
@@ -666,11 +666,11 @@ The variant requires the additional configuration parameters : 
| Input / Variable                                          | Description                                                                                                                                                                            | Default value    |

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

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

| `aws-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_           |

| `aws-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_           |

| `aws-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_           |

| `aws-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_           |

| `aws-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_           |

| `aws-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_           |

| `aws-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_           |

| `aws-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_           |

| `aws-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_           |

| `aws-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_           |



#### Example

kicker.json

+8 −8
Original line number Diff line number Diff line
@@ -105,7 +105,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/))",

      "variables": [

        {

          "name": "ANSIBLE_REVIEW_APP_NAME",
@@ -411,7 +411,7 @@ 
      "variables": [

        {

          "name": "GCP_OIDC_AUD",

          "description": "The `aud` claim for the JWT token _(only required for [OIDC authentication](https://docs.gitlab.com/ee/ci/cloud_services/aws/))_",

          "description": "The `aud` claim for the JWT token _(only required for [OIDC authentication](https://docs.gitlab.com/ci/cloud_services/aws/))_",

          "default": "$CI_SERVER_URL",

          "advanced": true

        },
@@ -421,7 +421,7 @@ 
        },

        {

          "name": "GCP_OIDC_PROVIDER",

          "description": "Default Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/)"

          "description": "Default Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/)"

        },

        {

          "name": "GCP_REVIEW_OIDC_ACCOUNT",
@@ -430,7 +430,7 @@ 
        },

        {

          "name": "GCP_REVIEW_OIDC_PROVIDER",

          "description": "Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `review` environment",

          "description": "Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `review` environment",

          "advanced": true

        },

        {
@@ -440,7 +440,7 @@ 
        },

        {

          "name": "GCP_INTEG_OIDC_PROVIDER",

          "description": "Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `integration` environment",

          "description": "Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `integration` environment",

          "advanced": true

        },

        {
@@ -450,7 +450,7 @@ 
        },

        {

          "name": "GCP_STAGING_OIDC_PROVIDER",

          "description": "Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `staging` environment",

          "description": "Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `staging` environment",

          "advanced": true

        },

        {
@@ -460,7 +460,7 @@ 
        },

        {

          "name": "GCP_PROD_OIDC_PROVIDER",

          "description": "Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ee/ci/cloud_services/google_cloud/) on `production` environment",

          "description": "Workload Identity Provider associated with GitLab to [authenticate with OpenID Connect](https://docs.gitlab.com/ci/cloud_services/google_cloud/) on `production` environment",

          "advanced": true

        }

      ]
@@ -473,7 +473,7 @@ 
      "variables": [

        {

          "name": "AWS_OIDC_AUD",

          "description": "The `aud` claim for the JWT token _(only required for [OIDC authentication](https://docs.gitlab.com/ee/ci/cloud_services/aws/))_",

          "description": "The `aud` claim for the JWT token _(only required for [OIDC authentication](https://docs.gitlab.com/ci/cloud_services/aws/))_",

          "default": "$CI_SERVER_URL",

          "advanced": true

        },

templates/gitlab-ci-ansible-aws.yml

+5 −5

File changed.

Preview size limit exceeded, changes collapsed.