diff options
Diffstat (limited to 'doc/ci/examples')
-rw-r--r-- | doc/ci/examples/authenticating-with-hashicorp-vault/index.md | 87 | ||||
-rw-r--r-- | doc/ci/examples/deployment/composer-npm-deploy.md | 4 | ||||
-rw-r--r-- | doc/ci/examples/deployment/index.md | 6 | ||||
-rw-r--r-- | doc/ci/examples/end_to_end_testing_webdriverio/index.md | 2 | ||||
-rw-r--r-- | doc/ci/examples/index.md | 3 | ||||
-rw-r--r-- | doc/ci/examples/laravel_with_gitlab_and_envoy/index.md | 3 | ||||
-rw-r--r-- | doc/ci/examples/semantic-release.md | 17 |
7 files changed, 56 insertions, 66 deletions
diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md index 7bb14c4c900..f45c60bdd1f 100644 --- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md +++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md @@ -1,21 +1,21 @@ --- stage: Verify -group: Pipeline Authoring +group: Pipeline Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: tutorial --- -# Authenticating and reading secrets with HashiCorp Vault **(PREMIUM)** +# Authenticating and reading secrets with HashiCorp Vault (Deprecated) **(PREMIUM)** -This tutorial demonstrates how to authenticate, configure, and read secrets with HashiCorp's Vault from GitLab CI/CD. +WARNING: +Authenticating with HashiCorp Vault by using `CI_JOB_JWT` was [deprecated in GitLab 15.9](../../../update/deprecations.md#old-versions-of-json-web-tokens-are-deprecated) +and the token is scheduled to be removed in GitLab 16.5. This change is a breaking change. +Use [ID tokens to authenticate with HashiCorp Vault](../../secrets/id_token_authentication.md#automatic-id-token-authentication-with-hashicorp-vault) +instead. -NOTE: -[GitLab Premium](https://about.gitlab.com/pricing/) supports read access to a -HashiCorp Vault, and enables you to -[use Vault secrets in a CI job](../../secrets/index.md#use-vault-secrets-in-a-ci-job). -For more information, see [Using external secrets in CI](../../secrets/index.md). +This tutorial demonstrates how to authenticate, configure, and read secrets with HashiCorp's Vault from GitLab CI/CD. -## Requirements +## Prerequisites This tutorial assumes you are familiar with GitLab CI/CD and Vault. @@ -29,7 +29,7 @@ You must replace the `vault.example.com` URL below with the URL of your Vault se ## How it works -Each job has JSON Web Token (JWT) provided as CI/CD variable named `CI_JOB_JWT`. This JWT can be used to authenticate with Vault using the [JWT Auth](https://developer.hashicorp.com/vault/docs/auth/jwt#jwt-authentication) method. +ID tokens are JSON Web Tokens (JWTs) used for OIDC authentication with third-party services. If a job has at least one ID token defined, the `secrets` keyword automatically uses that token to authenticate with Vault. The following fields are included in the JWT: @@ -53,6 +53,7 @@ The following fields are included in the JWT: | `job_id` | Always | ID of this job | | `ref` | Always | Git ref for this job | | `ref_type` | Always | Git ref type, either `branch` or `tag` | +| `ref_path` | Always | Fully qualified ref for the job. For example, `refs/heads/main`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119075) in GitLab 16.0. | | `ref_protected` | Always | `true` if this Git ref is protected, `false` otherwise | | `environment` | Job specifies an environment | Environment this job specifies ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9) | | `environment_protected` | Job specifies an environment | `true` if specified environment is protected, `false` otherwise ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9) | @@ -80,6 +81,7 @@ Example JWT payload: "job_id": "1212", "ref": "auto-deploy-2020-04-01", "ref_type": "branch", + "ref_path": "refs/heads/auto-deploy-2020-04-01", "ref_protected": "true", "environment": "production", "environment_protected": "true" @@ -254,61 +256,36 @@ $ vault write auth/jwt/config \ For the full list of available configuration options, see Vault's [API documentation](https://developer.hashicorp.com/vault/api-docs/auth/jwt#configure). -The following job, when run for the default branch, is able to read secrets under `secret/myproject/staging/`, but not the secrets under `secret/myproject/production/`: +In GitLab, create the following [CI/CD variables](../../variables/index.md#for-a-project) to provide details about your Vault server: -```yaml -read_secrets: - image: vault:latest - script: - # Check job's ref name - - echo $CI_COMMIT_REF_NAME - # and is this ref protected - - echo $CI_COMMIT_REF_PROTECTED - # Vault's address can be provided here or as CI/CD variable - - export VAULT_ADDR=http://vault.example.com:8200 - # Authenticate and get token. Token expiry time and other properties can be configured - # when configuring JWT Auth - https://developer.hashicorp.com/vault/api-docs/auth/jwt#parameters-1 - - export VAULT_TOKEN="$(vault write -field=token auth/jwt/login role=myproject-staging jwt=$CI_JOB_JWT)" - # Now use the VAULT_TOKEN to read the secret and store it in an environment variable - - export PASSWORD="$(vault kv get -field=password secret/myproject/staging/db)" - # Use the secret - - echo $PASSWORD - # This will fail because the role myproject-staging can not read secrets from secret/myproject/production/* - - export PASSWORD="$(vault kv get -field=password secret/myproject/production/db)" -``` - -NOTE: -If you're using a Vault instance provided by HashiCorp Cloud Platform, -you need to export the `VAULT_NAMESPACE` variable. Its default value is `admin`. +- `VAULT_SERVER_URL` - The URL of your Vault server, for example `https://vault.example.com:8200`. +- `VAULT_AUTH_ROLE` - Optional. The role to use when attempting to authenticate. If no role is specified, Vault uses the [default role](https://developer.hashicorp.com/vault/api-docs/auth/jwt#default_role) specified when the authentication method was configured. +- `VAULT_AUTH_PATH` - Optional. The path where the authentication method is mounted. Default is `jwt`. +- `VAULT_NAMESPACE` - Optional. The [Vault Enterprise namespace](https://developer.hashicorp.com/vault/docs/enterprise/namespaces) to use for reading secrets and authentication. If no namespace is specified, Vault uses the root (`/`) namespace. The setting is ignored by Vault Open Source. -![read secrets staging example](img/vault-read-secrets-staging.png) - -The following job is able to authenticate using the `myproject-production` role and read secrets under `/secret/myproject/production/`: +The following job, when run for the default branch, can read secrets under `secret/myproject/staging/`, but not the secrets under `secret/myproject/production/`: ```yaml -read_secrets: - image: vault:latest +job_with_secrets: + id_tokens: + VAULT_ID_TOKEN: + aud: https://example.vault.com + secrets: + STAGING_DB_PASSWORD: + vault: secret/myproject/staging/db/password@secrets # authenticates using $VAULT_ID_TOKEN script: - # Check job's ref name - - echo $CI_COMMIT_REF_NAME - # and is this ref protected - - echo $CI_COMMIT_REF_PROTECTED - # Vault's address can be provided here or as CI/CD variable - - export VAULT_ADDR=http://vault.example.com:8200 - # Authenticate and get token. Token expiry time and other properties can be configured - # when configuring JWT Auth - https://developer.hashicorp.com/vault/api-docs/auth/jwt#parameters-1 - - export VAULT_TOKEN="$(vault write -field=token auth/jwt/login role=myproject-production jwt=$CI_JOB_JWT)" - # Now use the VAULT_TOKEN to read the secret and store it in environment variable - - export PASSWORD="$(vault kv get -field=password secret/myproject/production/db)" - # Use the secret - - echo $PASSWORD + - access-staging-db.sh --token $STAGING_DB_PASSWORD ``` -![read secrets production example](img/vault-read-secrets-production.png) +In this example: + +- `@secrets` - The vault name, where your Secrets Engines are enabled. +- `secret/myproject/staging/db` - The path location of the secret in Vault. +- `password` The field to be fetched within the referenced secret. ### Limit token access to Vault secrets -You can control `CI_JOB_JWT` access to Vault secrets by using Vault protections +You can control ID token access to Vault secrets by using Vault protections and GitLab features. For example, restrict the token by: - Using Vault [bound claims](https://developer.hashicorp.com/vault/docs/auth/jwt#bound-claims) diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index 533b6519d9a..20083413f66 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: tutorial --- diff --git a/doc/ci/examples/deployment/index.md b/doc/ci/examples/deployment/index.md index 67b4ec6b279..664ce84c488 100644 --- a/doc/ci/examples/deployment/index.md +++ b/doc/ci/examples/deployment/index.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: tutorial --- @@ -13,7 +13,7 @@ used with GitLab CI/CD. Dpl can be used to deploy to any of the [supported providers](https://github.com/travis-ci/dpl#supported-providers). -## Requirements +## Prerequisite To use Dpl you need at least Ruby 1.9.3 with ability to install gems. diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md index 7b5690e2d3d..3385aca1ef2 100644 --- a/doc/ci/examples/end_to_end_testing_webdriverio/index.md +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Insights +group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments author: Vincent Tunru author_gitlab: Vinnl diff --git a/doc/ci/examples/index.md b/doc/ci/examples/index.md index 6738c55b6fa..f2871e50617 100644 --- a/doc/ci/examples/index.md +++ b/doc/ci/examples/index.md @@ -2,7 +2,6 @@ stage: Verify group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -comments: false type: index --- @@ -76,7 +75,7 @@ choose one of these templates: - [dotNET Core (`dotNET-Core.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/dotNET-Core.gitlab-ci.yml) - [Elixir (`Elixir.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Elixir.gitlab-ci.yml) - [Flutter (`Flutter.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Flutter.gitlab-ci.yml) -- [Golang (`Go.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Go.gitlab-ci.yml) +- [Go (`Go.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Go.gitlab-ci.yml) - [Gradle (`Gradle.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Gradle.gitlab-ci.yml) - [Grails (`Grails.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Grails.gitlab-ci.yml) - [iOS with fastlane (`iOS-Fastlane.gitlab-ci.yml`)](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/iOS-Fastlane.gitlab-ci.yml) diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index 062bd602c29..cf12943d279 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -2,7 +2,6 @@ stage: Verify group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/articles/laravel_with_gitlab_and_envoy/index.html' author: Mehran Rasulian author_gitlab: mehranrasulian --- @@ -126,7 +125,7 @@ We'll use this variable in the `.gitlab-ci.yml` later, to easily connect to our ![variables page](img/variables_page.png) -We also need to add the public key to **Project** > **Settings** > **Repository** as a [Deploy Key](../../../user/project/deploy_keys/index.md), which gives us the ability to access our repository from the server through [SSH protocol](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project). +We also need to add the public key to **Project** > **Settings** > **Repository** as a [Deploy Key](../../../user/project/deploy_keys/index.md), which gives us the ability to access our repository from the server through the SSH protocol. ```shell # As the deployer user on the server diff --git a/doc/ci/examples/semantic-release.md b/doc/ci/examples/semantic-release.md index 9f299448d52..2146d76e4d6 100644 --- a/doc/ci/examples/semantic-release.md +++ b/doc/ci/examples/semantic-release.md @@ -90,7 +90,7 @@ As part of publishing a package, semantic-release increases the version number i <!-- markdownlint-disable MD044 --> -1. On the top bar, in the upper right, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. On the left sidebar, select **Access Tokens**. 1. In the **Token name** box, enter a token name. 1. Under **select scopes**, select the **api** checkbox. @@ -168,3 +168,18 @@ Then, install the module: ```shell npm install --save @gitlab-examples/semantic-release-npm ``` + +## Troubleshooting + +### Deleted Git tags reappear + +A [Git tag](../../user/project/repository/tags/index.md) deleted from the repository +can sometimes be recreated by `semantic-release` when GitLab runners use a cached +version of the repository. If the job runs on a runner with a cached repository that +still has the tag, `semantic-release` recreates the tag in the main repository. + +To avoid this behavior, you can either: + +- Configure the runner with [`GIT_STRATEGY: clone`](../runners/configure_runners.md#git-strategy). +- Include the [`git fetch --prune-tags` command](https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---prune-tags) + in your CI/CD script. |