diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-05-05 21:09:43 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-05-05 21:09:43 +0300 |
| commit | 38ceebb9b3a541f8530b379d5b5ab5e13ffc58ed (patch) | |
| tree | 7a0494f677459f96e6deda30da4069b7c038eca4 /doc | |
| parent | 0d09054d162458364ce3fc431506c182e2a5fa4f (diff) | |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
48 files changed, 415 insertions, 358 deletions
diff --git a/doc/.vale/gitlab/Substitutions.yml b/doc/.vale/gitlab/Substitutions.yml index ddded21ae42..730ed4b00aa 100644 --- a/doc/.vale/gitlab/Substitutions.yml +++ b/doc/.vale/gitlab/Substitutions.yml @@ -19,4 +19,5 @@ swap: rspec: RSpec self hosted: self-managed self-hosted: self-managed + x509: X.509 yaml: YAML diff --git a/doc/README.md b/doc/README.md index 4cf20e48492..1a37a2f41aa 100644 --- a/doc/README.md +++ b/doc/README.md @@ -286,7 +286,7 @@ The following documentation relates to the DevOps **Release** stage: | [Canary Deployments](user/project/canary_deployments.md) **(PREMIUM)** | Employ a popular CI strategy where a small portion of the fleet is updated to the new version first. | | [Deploy Boards](user/project/deploy_boards.md) **(PREMIUM)** | View the current health and status of each CI environment running on Kubernetes, displaying the status of the pods in the deployment. | | [Environments and deployments](ci/environments.md) | With environments, you can control the continuous deployment of your software within GitLab. | -| [Environment-specific variables](ci/variables/README.md#limiting-environment-scopes-of-environment-variables) | Limit the scope of variables to specific environments. | +| [Environment-specific variables](ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) | Limit the scope of variables to specific environments. | | [GitLab CI/CD](ci/README.md) | Explore the features and capabilities of Continuous Deployment and Delivery with GitLab. | | [GitLab Pages](user/project/pages/index.md) | Build, test, and deploy a static site directly from GitLab. | | [Protected Runners](ci/runners/README.md#protected-runners) | Select Runners to only pick jobs for protected branches and tags. | @@ -315,7 +315,7 @@ The following documentation relates to the DevOps **Configure** stage: | [Installing Applications](user/project/clusters/index.md#installing-applications) | Deploy Helm, Ingress, and Prometheus on Kubernetes. | | [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md) | Enable and use slash commands from within Mattermost. | | [Multiple Kubernetes Clusters](user/project/clusters/index.md#multiple-kubernetes-clusters-premium) **(PREMIUM)** | Associate more than one Kubernetes clusters to your project. | -| [Protected variables](ci/variables/README.md#protected-environment-variables) | Restrict variables to protected branches and tags. | +| [Protected variables](ci/variables/README.md#protect-a-custom-variable) | Restrict variables to protected branches and tags. | | [Serverless](user/project/clusters/serverless/index.md) | Run serverless workloads on Kubernetes. | | [Slack slash commands](user/project/integrations/slack_slash_commands.md) | Enable and use slash commands from within Slack. | | [Manage your infrastructure with Terraform](user/infrastructure/index.md) | Manage your infrastructure as you run your CI/CD pipeline. | diff --git a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md index 884bb44cfda..a919dd769f7 100644 --- a/doc/administration/monitoring/gitlab_self_monitoring_project/index.md +++ b/doc/administration/monitoring/gitlab_self_monitoring_project/index.md @@ -15,7 +15,11 @@ All administrators at the time of creation of the project and group will be adde as maintainers of the group and project, and as an admin, you'll be able to add new members to the group in order to give them maintainer access to the project. -This project will be used for self monitoring your GitLab instance. +This project is used to self monitor your GitLab instance. Metrics are not yet +fully integrated, and the dashboard does not aggregate any data on Omnibus installations. GitLab plans +to provide integrated self-monitoring metrics in a future release. You can +currently use the project to configure your own [custom metrics](../../../user/project/integrations/prometheus.md#adding-custom-metrics) using +metrics exposed by the [GitLab exporter](../prometheus/gitlab_metrics.md#metrics-available). ## Creating the self monitoring project diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index b1d61a08552..27b3144024b 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -214,6 +214,20 @@ p.each do |project| end ``` +### Bulk update to disable the Slack Notification service + +To disable notifications for all projects that have Slack service enabled, do: + +```ruby +# Grab all projects that have the Slack notifications enabled +p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN services s ON p.id = s.project_id WHERE s.type = 'SlackService' AND s.active = true") + +# Disable the service on each of the projects that were found. +p.each do |project| + project.slack_service.update_attribute(:active, false) +end +``` + ## Wikis ### Recreate diff --git a/doc/api/README.md b/doc/api/README.md index e08006a7f7f..76bb3506f38 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -454,6 +454,12 @@ The resulting cURL call for a project with id `5` and a group id of `17` is then curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/share/17 ``` +NOTE: **Note:** +Path parameters that are required to be URL-encoded must be followed. If not, +it will not match an API endpoint and respond with a 404. If there's something +in front of the API (for example, Apache), ensure that it won't decode the URL-encoded +path parameters. + ## Namespaced path encoding If using namespaced API calls, make sure that the `NAMESPACE/PROJECT_PATH` is @@ -470,15 +476,16 @@ A project's **path** is not necessarily the same as its **name**. A project's path can be found in the project's URL or in the project's settings under **General > Advanced > Change path**. -## Branches and tags name encoding +## File path, branches, and tags name encoding -If your branch or tag contains a `/`, make sure the branch/tag name is -URL-encoded. +If a file path, branch or tag contains a `/`, make sure it is URL-encoded. For example, `/` is represented by `%2F`: ```plaintext +GET /api/v4/projects/1/repository/files/src%2FREADME.md?ref=master GET /api/v4/projects/1/branches/my%2Fbranch/commits +GET /api/v4/projects/1/repository/tags/my%2Ftag ``` ## Encoding API parameters of `array` and `hash` types diff --git a/doc/api/commits.md b/doc/api/commits.md index 23db7d0f0e7..ec25f3a41ac 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -755,7 +755,7 @@ Example response if commit is GPG signed: } ``` -Example response if commit is x509 signed: +Example response if commit is X.509 signed: ```json { diff --git a/doc/api/feature_flag_user_lists.md b/doc/api/feature_flag_user_lists.md index eb54536a0fe..04cad8f2d1d 100644 --- a/doc/api/feature_flag_user_lists.md +++ b/doc/api/feature_flag_user_lists.md @@ -1,4 +1,4 @@ -# Feature Flag User Lists API **(PREMIUM)** +# Feature flag user lists API **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205409) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. @@ -63,7 +63,7 @@ POST /projects/:id/feature_flags_user_lists | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | | `name` | string | yes | The name of the feature flag. | -| `user_xids` | string | yes | A comma separated list of user ids. | +| `user_xids` | string | yes | A comma separated list of user IDs. | ```shell curl https://gitlab.example.com/api/v4/projects/1/feature_flags_user_lists \ @@ -122,6 +122,47 @@ Example response: } ``` +## Update a feature flag user list + +Updates a feature flag user list. + +```plaintext +PUT /projects/:id/feature_flags_user_lists/:iid +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `iid` | integer/string | yes | The internal ID of the project's feature flag user list. | +| `name` | string | no | The name of the feature flag. | +| `user_xids` | string | no | A comma separated list of user IDs. | + +```shell +curl https://gitlab.example.com/api/v4/projects/1/feature_flags_user_lists/1 \ + --header "PRIVATE-TOKEN: <your_access_token>" \ + --header "Content-type: application/json" \ + --request PUT \ + --data @- << EOF +{ + "user_xids": "user2,user3,user4" +} +EOF +``` + +Example response: + +```json +{ + "name": "my_user_list", + "user_xids": "user2,user3,user4", + "id": 1, + "iid": 1, + "project_id": 1, + "created_at": "2020-02-04T08:32:27.288Z", + "updated_at": "2020-02-05T09:33:17.179Z" +} +``` + ## Delete feature flag user list Deletes a feature flag user list. diff --git a/doc/api/settings.md b/doc/api/settings.md index 53166c5cf63..d86965d2817 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -364,7 +364,7 @@ are listed in the descriptions of the relevant settings. | `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider. | | `user_show_add_ssh_key_message` | boolean | no | When set to `false` disable the "You won't be able to pull or push project code via SSH" warning shown to users with no uploaded SSH key. | | `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | -| `web_ide_clientside_preview_enabled` | boolean | no | Client side evaluation (allow live previews of JavaScript projects in the Web IDE using CodeSandbox client side evaluation). | +| `web_ide_clientside_preview_enabled` | boolean | no | Live Preview (allow live previews of JavaScript projects in the Web IDE using CodeSandbox Live Preview). | | `snippet_size_limit` | integer | no | Max snippet content size in **bytes**. Default: 52428800 Bytes (50MB).| | `issues_create_limit` | integer | no | Max number of issue creation requests per minute per user. Default: 300. To disable throttling set to 0.| | `raw_blob_request_limit` | integer | no | Max number of requests per minute for each raw path. Default: 300. To disable throttling set to 0.| diff --git a/doc/ci/environments.md b/doc/ci/environments.md index e8707589f0c..31aa5bfadc3 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -925,7 +925,7 @@ with `review/` would have that particular variable. Some GitLab features can behave differently for each environment. For example, you can -[create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-environment-variables). +[create a secret variable to be injected only into a production environment](variables/README.md#limit-the-environment-scopes-of-environment-variables). In most cases, these features use the _environment specs_ mechanism, which offers an efficient way to implement scoping within each environment group. diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md index 92fb69286cf..4da62c95a69 100644 --- a/doc/ci/examples/test-scala-application.md +++ b/doc/ci/examples/test-scala-application.md @@ -74,5 +74,5 @@ in the `.gitlab-ci.yml` file with your application's name. ## Heroku API key You can look up your Heroku API key in your -[account](https://dashboard.heroku.com/account). Add a [protected variable](../variables/README.md#protected-environment-variables) with +[account](https://dashboard.heroku.com/account). Add a [protected variable](../variables/README.md#protect-a-custom-variable) with this value in **Project ➔ Variables** with key `HEROKU_API_KEY`. diff --git a/doc/ci/jenkins/index.md b/doc/ci/jenkins/index.md index 01bf4c605a1..e43f0e4131c 100644 --- a/doc/ci/jenkins/index.md +++ b/doc/ci/jenkins/index.md @@ -282,7 +282,7 @@ my_job: In GitLab, we use the [`variables` keyword](../yaml/README.md#variables) to define different variables at runtime. These can also be set up through the GitLab UI, under CI/CD settings. See also our [general documentation on variables](../variables/README.md), -including the section on [protected variables](../variables/README.md#protected-environment-variables) which can be used +including the section on [protected variables](../variables/README.md#protect-a-custom-variable) which can be used to limit access to certain variables to certain environments or runners: ```yaml diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 733dbc46370..d2632dfe719 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -74,7 +74,7 @@ You can also configure specific aspects of your pipelines through the GitLab UI. - [Pipeline settings](settings.md) for each project. - [Pipeline schedules](schedules.md). -- [Custom CI/CD variables](../variables/README.md#creating-a-custom-environment-variable). +- [Custom CI/CD variables](../variables/README.md#custom-environment-variables). ### View pipelines @@ -373,7 +373,7 @@ the pipeline view, *not* the play (**{play}**) button. This is useful when you want to alter the execution of a job that uses [custom environment variables](../variables/README.md#custom-environment-variables). Adding a variable name (key) and value here will override the value defined in -[the UI or `.gitlab-ci.yml`](../variables/README.md#creating-a-custom-environment-variable), +[the UI or `.gitlab-ci.yml`](../variables/README.md#custom-environment-variables), for a single run of the manual job.  diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index e21b62e93cf..dcfd863709e 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -27,7 +27,7 @@ variables: NOTE: **Note:** The `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` variables can't be set in the GitLab UI. -To set them, assign them to a variable [in the UI](../variables/README.md#via-the-ui), +To set them, assign them to a variable [in the UI](../variables/README.md#create-a-custom-variable-in-the-ui), and then assign that variable to the `MYSQL_DATABASE` and `MYSQL_ROOT_PASSWORD` variables in your `.gitlab-ci.yml`. diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md index cf34c28497e..2f92bd969ff 100644 --- a/doc/ci/services/postgres.md +++ b/doc/ci/services/postgres.md @@ -29,7 +29,7 @@ variables: NOTE: **Note:** The `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD` variables can't be set in the GitLab UI. To set them, assign them to a variable -[in the UI](../variables/README.md#via-the-ui), and then assign that +[in the UI](../variables/README.md#create-a-custom-variable-in-the-ui), and then assign that variable to the `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_HOST_AUTH_METHOD` variables in your `.gitlab-ci.yml`. diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index f300839e2d9..b12e7c559a1 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -4,149 +4,41 @@ type: reference # GitLab CI/CD environment variables -After a brief overview of the use of environment -variables, this document teaches you how to use GitLab CI/CD's -variables, presents the full reference for predefined variables, -and dives into more advanced applications. - -## Overview - -An environment variable is a dynamic-named value that can -affect the way running processes will behave on an operating +An environment variable is a dynamically-named value that can +affect the way running processes behave on an operating system. -They are part of the environment in which a process runs. +Environment variables are part of the environment in which a process runs. For example, a running process can query the value of the `TEMP` environment variable to discover a suitable location to store temporary files, or to define a `URL` for a database that can be reused in different scripts. -Variables are useful for customizing your jobs in GitLab -CI/CD's pipelines. Using variables means no hardcoded values. +Variables are useful for customizing your jobs in GitLab CI/CD. +When you use variables, you don't have to hard-code values. -### Predefined environment variables +## Predefined environment variables GitLab CI/CD has a [default set of predefined variables](predefined_variables.md) -which can be used without any specification needed. -You can call issues numbers, user names, branch names, +that you can use without any additional specification. +You can call issue numbers, user names, branch names, pipeline and commit IDs, and much more. -Predefined environment variables are the ones that GitLab -provides out of the box for the local environment of the Runner. - -GitLab reads the `.gitlab-ci.yml` file, sends the information -to the Runner (which runs the script commands), under which -the variables are exposed. - -For example, two jobs under the same pipeline can share the same -`CI_PIPELINE_ID` variable, but each one has its own `CI_JOB_ID` -variable. - -NOTE: **Note:** -Find here the full [**predefined variables reference table**](predefined_variables.md). - -### Custom environment variables - -When your use case requires a specific variable, you can -[set them up easily from the UI](#creating-a-custom-environment-variable) -or directly in the `.gitlab-ci.yml` file and reuse them as you wish. - -That can be very powerful as it can be used for scripting without -the need to specify the value itself. - -#### Types of variables - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/46806) in GitLab 11.11. - -There are two types of variables supported by GitLab: - -- [Variable type](#variable-type): The Runner will create an environment variable named the same as the - variable key and set its value to the variable value. -- [File type](#file-type): The Runner will write the variable value to a temporary file and set the - path to this file as the value of an environment variable, named the same as the variable key. - -##### Variable type - -Many tools (like [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) -and [kubectl](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable)) -provide the ability to customise configuration using files by either providing the -file path as a command line argument or an environment variable. In the past, the -common pattern was to read the value of a CI variable, save it in a file, and then -use the newly created file in your script: - -```shell -# Read certificate stored in $KUBE_CA_PEM variable and save it in a new file -echo "$KUBE_CA_PEM" > "$(pwd)/kube.ca.pem" -# Pass the newly created file to kubectl -kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$(pwd)/kube.ca.pem" -``` - -There are [some predefined variables](#custom-variables-validated-by-gitlab) of this type, which may be further validated. They will appear when you add or update a variable. - -##### File type - -The example above can now be simplified by creating a "File" type variable, and using -it directly. For example, let's say we have the following variables: - - - -We can then call them from `.gitlab-ci.yml` like this: - -```shell -kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM" -``` - -Variable types can be set via the [UI](#via-the-ui) or the [API](../../api/project_level_variables.md#create-variable), but not in `.gitlab-ci.yml`. - -#### Masked variables - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/13784) in GitLab 11.10 - -Variables can be created as masked variables. -This means that the value of the variable will be hidden in job logs, -though it must match certain requirements to do so: - -- The value must be in a single line. -- The value must only consist of characters from the Base64 alphabet (RFC4648). - - [In GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/63043) - and newer, `@` and `:` are also valid values. -- The value must be at least 8 characters long. -- The value must not use variables. - -If the value does not meet the requirements above, then the CI variable will fail to save. -In order to save, either alter the value to meet the masking requirements -or disable **Masked** for the variable. - -#### Custom variables validated by GitLab - -Some variables are listed in the UI so you can choose them more quickly. -GitLab validates the values of these variables to ensure they are in the correct format. - -| Variable | Allowed Values | Introduced in | -|-------------------------|----------------------------------------------------|---------------| -| `AWS_ACCESS_KEY_ID` | 20 characters: letters, digits | 12.10 | -| `AWS_DEFAULT_REGION` | Any | 12.10 | -| `AWS_SECRET_ACCESS_KEY` | 40 characters: letters, digits, special characters | 12.10 | +Predefined environment variables are provided by GitLab +for the local environment of the Runner. -NOTE: **Note:** -When you store credentials, there are security implications. If you are using AWS keys, -for example, follow their [best practices](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html). +GitLab reads the `.gitlab-ci.yml` file and sends the information +to the Runner, where the variables are exposed. The Runner then runs the script commands. -## Getting started +### Use predefined environment variables -To get started with environment variables in the scope of GitLab -CI/CD, let's go over a few examples. +You can choose one of the existing predefined variables +to be output by the Runner. -### Using predefined environment variables +This example shows how to output a job's stage by using the predefined variable `CI_JOB_STAGE`. -To get started, choose one of the existing -[predefined variables](predefined_variables.md) -to be output by the Runner. For example, let's say that you want -a given job you're running through your script to output the -stage that job is running for. In your `.gitlab-ci.yml` file, -call the variable from your script according to the [syntaxes](#syntax-of-environment-variables-in-job-scripts) available. To -output the job stage, use the predefined variable `CI_JOB_STAGE`: +In your `.gitlab-ci.yml` file, call the variable from your script. Ensure +you use the correct [syntax](#syntax-of-environment-variables-in-job-scripts). ```yaml test_variable: @@ -155,14 +47,14 @@ test_variable: - echo $CI_JOB_STAGE ``` -For this case, the Runner will output the `stage` for the +In this case, the Runner outputs the `stage` for the job `test_variable`, which is `test`:  As another example, let's say you're using your own GitLab -instance you want to know what domain your GitLab Pages are -served under. You can easily call it with the predefined +instance and you want to know what domain your GitLab Pages are +served under. You can call it by using the predefined variable `$CI_PAGES_DOMAIN` in your script: ```yaml @@ -176,47 +68,54 @@ For GitLab.com users, the output will be `gitlab.io`. For your private instance, the output will be whatever your sysadmin has defined. -### Creating a custom environment variable +## Custom environment variables -Assume you have something you want to repeat through your scripts -in GitLab CI/CD's configuration file. To keep this example simple, -let's say you want to output `HELLO WORLD` for a `TEST` variable. +When you need a specific custom environment variable, you can +[set it up in the UI](#create-a-custom-variable-in-the-ui), in [the API](../../api/project_level_variables.md), +or directly [in the `.gitlab-ci.yml` file](#create-a-custom-variable-in-gitlab-ciyml). -You can either set the variable directly in the `.gitlab-ci.yml` -file or through the UI. +The variables are used by the Runner any time the pipeline runs. +You can also [override variable values manually for a specific pipeline](../pipelines/index.md#specifying-variables-when-running-manual-jobs). -NOTE: **Note:** -It is possible to [specify variables when running manual jobs](../pipelines/index.md#specifying-variables-when-running-manual-jobs). +There are two types of variables: **Variable** and **File**. You cannot set types in +the `.gitlab-ci.yml` file, but you can set them in the UI and API. -#### Via `.gitlab-ci.yml` +### Create a custom variable in `.gitlab-ci.yml` -To create a new custom `env_var` variable via [`.gitlab-ci.yml`](../yaml/README.md#variables), define their variable/value pair under -`variables`: +To create a custom `env_var` variable in the [`.gitlab-ci.yml`](../yaml/README.md#variables) file, +define the variable/value pair under `variables`: ```yaml variables: TEST: "HELLO WORLD" ``` -For a deeper look into them, see [`.gitlab-ci.yml` defined variables](#gitlab-ciyml-defined-variables). +You can then call its value in your script: + +```yaml + script: + - echo "$TEST" +``` + +For more details, see [`.gitlab-ci.yml` defined variables](#gitlab-ciyml-defined-variables). -#### Via the UI +### Create a custom variable in the UI From within the UI, you can add or update custom environment variables: 1. Go to your project's **Settings > CI/CD** and expand the **Variables** section. -1. Click the **Add variable** button. In the **Add variable** modal, fill in the details: +1. Click the **Add Variable** button. In the **Add variable** modal, fill in the details: - **Key**: Must be one line, with no spaces, using only letters, numbers, `-` or `_`. - **Value**: No limitations. - **Type**: `File` or `Variable`. - **Environment scope**: `All`, or specific environments. - **Protect variable** (Optional): If selected, the variable will only be available in pipelines that run on protected branches or tags. - - **Mask variable** (Optional): If selected, the variable's **Value** will be masked in job logs. The variable will fail to save if the value does not meet the [masking requirements](#masked-variables). + - **Mask variable** (Optional): If selected, the variable's **Value** will be masked in job logs. The variable fails to save if the value does not meet the [masking requirements](#masked-variable-requirements). -After a variable is created, you can update any of the details by clicking on the **{pencil}** **Edit** button. +After a variable is created, you can update any of the details by clicking the **{pencil}** **Edit** button. -Once you've set the variables, call them from the `.gitlab-ci.yml` file: +After you set a variable, call it from the `.gitlab-ci.yml` file: ```yaml test_variable: @@ -232,7 +131,110 @@ The output will be:  -### Syntax of environment variables in job scripts +### Custom environment variables of type Variable + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/46806) in GitLab 11.11. + +For variables with the type **Variable**, the Runner creates an environment variable +that uses the key for the name and the value for the value. + +There are [some predefined variables](#custom-variables-validated-by-gitlab) of this type, +which may be further validated. They appear when you add or update a variable in the UI. + +### Custom environment variables of type File + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/46806) in GitLab 11.11. + +For variables with the type **File**, the Runner creates an environment variable that uses the key for the name. +For the value, the Runner writes the variable value to a temporary file and uses this path. + +You can use tools like [the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) +and [kubectl](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable) +to customize your configuration by using **File** type variables. + +In the past, a common pattern was to read the value of a CI variable, save it in a file, and then +use the newly created file in your script: + +```shell +# Read certificate stored in $KUBE_CA_PEM variable and save it in a new file +echo "$KUBE_CA_PEM" > "$(pwd)/kube.ca.pem" +# Pass the newly created file to kubectl +kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$(pwd)/kube.ca.pem" +``` + +Instead of this, you can use a **File** type variable. For example, if you have the following variables: + +- A variable of type **Variable**: `KUBE_URL` with the value `https://example.com`. +- A variable of type **File**: `KUBE_CA_PEM` with a certificate as the value. + +You can call them from `.gitlab-ci.yml`, like this: + +```shell +kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM" +``` + +### Mask a custom variable + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/13784) in GitLab 11.10 + +Variables can be masked so that the value of the variable will be hidden in job logs. + +To mask a variable: + +1. Go to **Settings > CI/CD**. +1. Expand the **Variables** section. +1. Next to the variable you want to protect, click **Edit**. +1. Select the **Mask variable** check box. +1. Click **Update variable**. + +#### Masked variable requirements + +The value of the variable must: + +- Be in a single line. +- Be at least 8 characters long. +- Not be a predefined or custom environment variable. +- Consist only of characters from the Base64 alphabet (RFC4648). + [In GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/63043) + and newer, `@` and `:` are also valid values. + +You can't mask variables that don't meet these requirements. + +### Protect a custom variable + +> Introduced in GitLab 9.3. + +Variables can be protected. When a variable is +protected, it is securely passed to pipelines running on +[protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md) only. The other pipelines do not get +the protected variable. + +To protect a variable: + +1. Go to **Settings > CI/CD**. +1. Expand the **Variables** section. +1. Next to the variable you want to protect, click **Edit**. +1. Select the **Protect variable** check box. +1. Click **Update variable**. + +The variable is available for all subsequent pipelines. + +### Custom variables validated by GitLab + +Some variables are listed in the UI so you can choose them more quickly. +GitLab validates the values of these variables to ensure they are in the correct format. + +| Variable | Allowed Values | Introduced in | +|-------------------------|----------------------------------------------------|---------------| +| `AWS_ACCESS_KEY_ID` | 20 characters: letters, digits | 12.10 | +| `AWS_DEFAULT_REGION` | Any | 12.10 | +| `AWS_SECRET_ACCESS_KEY` | 40 characters: letters, digits, special characters | 12.10 | + +NOTE: **Note:** +When you store credentials, there are security implications. If you are using AWS keys, +for example, follow their [best practices](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html). + +## Syntax of environment variables in job scripts All variables are set as environment variables in the build environment, and they are accessible with normal methods that are used to access such variables. @@ -329,14 +331,14 @@ export GITLAB_USER_EMAIL="user@example.com" export GITLAB_USER_ID="42" ``` -### `.gitlab-ci.yml` defined variables +## `.gitlab-ci.yml` defined variables NOTE: **Note:** This feature requires GitLab Runner 0.5.0 or higher and GitLab 7.14 or higher. -GitLab CI/CD allows you to add to `.gitlab-ci.yml` variables that are set in the -build environment. The variables are hence saved in the repository, and they -are meant to store non-sensitive project configuration. For example, `RAILS_ENV` or +You can add variables that are set in the build environment to `.gitlab-ci.yml`. +These variables are saved in the repository, and they +are meant to store non-sensitive project configuration, like `RAILS_ENV` or `DATABASE_URL`. For example, if you set the variable below globally (not inside a job), it will @@ -348,7 +350,7 @@ variables: ``` The YAML-defined variables are also set to all created -[service containers](../docker/using_docker_images.md), thus allowing to fine +[service containers](../docker/using_docker_images.md), so that you can fine tune them. Variables can be defined at a global level, but also at a job level. To turn off @@ -369,11 +371,11 @@ script: - 'eval $LS_CMD' # will execute 'ls -al $TMP_DIR' ``` -### Group-level environment variables +## Group-level environment variables > Introduced in GitLab 9.4. -GitLab CI/CD allows you to define per-project or per-group variables +You can define per-project or per-group variables that are set in the pipeline environment. Group-level variables are stored out of the repository (not in `.gitlab-ci.yml`) and are securely passed to GitLab Runner making them available during a pipeline run. It's the **recommended method** to @@ -400,8 +402,8 @@ variables, depending on where they are defined. The order of precedence for variables is (from highest to lowest): 1. [Trigger variables](../triggers/README.md#making-use-of-trigger-variables) or [scheduled pipeline variables](../pipelines/schedules.md#using-variables). -1. Project-level [variables](#creating-a-custom-environment-variable) or [protected variables](#protected-environment-variables). -1. Group-level [variables](#group-level-environment-variables) or [protected variables](#protected-environment-variables). +1. Project-level [variables](#custom-environment-variables) or [protected variables](#protect-a-custom-variable). +1. Group-level [variables](#group-level-environment-variables) or [protected variables](#protect-a-custom-variable). 1. YAML-defined [job-level variables](../yaml/README.md#variables). 1. YAML-defined [global variables](../yaml/README.md#variables). 1. [Deployment variables](#deployment-environment-variables). @@ -426,22 +428,7 @@ Click [here](where_variables_can_be_used.md) for a section that describes where ## Advanced use -### Protected environment variables - -> Introduced in GitLab 9.3. - -Variables can be protected. Whenever a variable is -protected, it would only be securely passed to pipelines running on the -[protected branches](../../user/project/protected_branches.md) or [protected tags](../../user/project/protected_tags.md). The other pipelines would not get any -protected variables. - -Protected variables can be added by going to your project's -**Settings > CI/CD**, then finding the section called -**Variables**, and check "Protected". - -Once you set them, they will be available for all subsequent pipelines. - -### Limiting environment scopes of environment variables +### Limit the environment scopes of environment variables You can limit the environment scope of a variable by [defining which environments](../environments.md) it can be available for. @@ -478,22 +465,23 @@ CAUTION: **Caution:** Variables with multiline values are not currently supported due to limitations with the current Auto DevOps scripting environment. -### Environment variables triggered manually +### Override a variable by manually running a pipeline > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/44059) in GitLab 10.8. -[Manually triggered pipelines](../pipelines/index.md#run-a-pipeline-manually) allow you to override the value of a current variable. +You can override the value of a current variable by +[running a pipeline manually](../pipelines/index.md#run-a-pipeline-manually). + +For instance, suppose you added a custom variable named `$TEST` +and you want to override it in a manual pipeline. -For instance, suppose you added a -[custom variable `$TEST`](#creating-a-custom-environment-variable) -as exemplified above and you want to override it in a manual pipeline. Navigate to your project's **CI/CD > Pipelines** and click **Run pipeline**. -Choose the branch you want to run the pipeline for, then add a new variable through the UI: +Choose the branch you want to run the pipeline for, then add a variable and its value in the UI:  -The Runner will override the value previously set and use the custom -value you set for this specific pipeline: +The Runner overrides the value previously set and uses the custom +value for this specific pipeline.  @@ -502,10 +490,10 @@ value you set for this specific pipeline: > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/README.md#onlyexcept-advanced) > - [Expanded](https://gitlab.com/gitlab-org/gitlab/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/README.md#rules) -Variable expressions can be used to limit what jobs are going to be created -within a pipeline after pushing changes to GitLab. +Use variable expressions to limit which jobs are created +within a pipeline after changes are pushed to GitLab. -In `.gitlab-ci.yml`, they work with both +In `.gitlab-ci.yml`, variable expressions work with both: - [`rules`](../yaml/README.md#rules), which is the recommended approach, and - [`only` and `except`](../yaml/README.md#onlyexcept-basic), which are candidates for deprecation. @@ -523,15 +511,15 @@ deploy: - $STAGING ``` -Each expression provided is going to be evaluated before creating a pipeline. +Each expression provided is evaluated before a pipeline is created. -If any of the conditions in `variables` evaluates to truth when using `only`, -a new job is going to be created. If any of the expressions evaluates to truth -when `except` is being used, a job is not going to be created. +If any of the conditions in `variables` evaluates to true when using `only`, +a new job is created. If any of the expressions evaluates to true +when `except` is being used, a job is not created. -This follows usual rules for [`only` / `except` policies](../yaml/README.md#onlyexcept-advanced). +This follows the usual rules for [`only` / `except` policies](../yaml/README.md#onlyexcept-advanced). -### Supported syntax +### Syntax of environment variable expressions Below you can find supported syntax reference: @@ -679,7 +667,7 @@ If a job isn't working as expected, this can make the problem difficult to investigate; in these cases, you can enable debug tracing in `.gitlab-ci.yml`. Available on GitLab Runner v1.7+, this feature enables the shell's execution log, resulting in a verbose job log listing all commands that were run, -variables that were set, etc. +variables that were set, and so on. Before enabling this, you should ensure jobs are visible to [team members only](../../user/permissions.md#project-features). You should diff --git a/doc/ci/variables/img/ci_job_stage_output_example.png b/doc/ci/variables/img/ci_job_stage_output_example.png Binary files differindex 056238d5693..e333da57121 100644 --- a/doc/ci/variables/img/ci_job_stage_output_example.png +++ b/doc/ci/variables/img/ci_job_stage_output_example.png diff --git a/doc/ci/variables/img/inherited_group_variables_v12_5.png b/doc/ci/variables/img/inherited_group_variables_v12_5.png Binary files differindex fd41859605f..a13ba711083 100644 --- a/doc/ci/variables/img/inherited_group_variables_v12_5.png +++ b/doc/ci/variables/img/inherited_group_variables_v12_5.png diff --git a/doc/ci/variables/img/override_value_via_manual_pipeline_output.png b/doc/ci/variables/img/override_value_via_manual_pipeline_output.png Binary files differindex 02369d57fb8..8a13bb3849e 100644 --- a/doc/ci/variables/img/override_value_via_manual_pipeline_output.png +++ b/doc/ci/variables/img/override_value_via_manual_pipeline_output.png diff --git a/doc/ci/variables/img/override_variable_manual_pipeline.png b/doc/ci/variables/img/override_variable_manual_pipeline.png Binary files differindex c77c5cb7764..de768105aec 100644 --- a/doc/ci/variables/img/override_variable_manual_pipeline.png +++ b/doc/ci/variables/img/override_variable_manual_pipeline.png diff --git a/doc/ci/variables/img/variable_types_usage_example.png b/doc/ci/variables/img/variable_types_usage_example.png Binary files differdeleted file mode 100644 index c2ae32fd048..00000000000 --- a/doc/ci/variables/img/variable_types_usage_example.png +++ /dev/null diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 1d1c8a76feb..1cf57fb9db2 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -897,7 +897,7 @@ In this example, if the first rule: `rules:if` differs slightly from `only:variables` by accepting only a single expression string, rather than an array of them. Any set of expressions to be evaluated should be conjoined into a single expression using `&&` or `||`, and use -the [variable matching syntax](../variables/README.md#supported-syntax). +the [variable matching syntax](../variables/README.md#syntax-of-environment-variable-expressions). For example: diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md index 483559672a7..eda9e1e21cc 100644 --- a/doc/development/dangerbot.md +++ b/doc/development/dangerbot.md @@ -145,7 +145,7 @@ at GitLab so far: fork. That way the danger comments will be made from CI using that API token instead. Making the variable - [masked](../ci/variables/README.md#masked-variables) will make sure + [masked](../ci/variables/README.md#mask-a-custom-variable) will make sure it doesn't show up in the job logs. The variable cannot be - [protected](../ci/variables/README.md#protected-environment-variables), + [protected](../ci/variables/README.md#protect-a-custom-variable), as it needs to be present for all feature branches. diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index c9fd1b75606..e924ed934d6 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -3,7 +3,8 @@ - **Write the code and the tests.**: As with any code, EE features should have good test coverage to prevent regressions. - **Write documentation.**: Add documentation to the `doc/` directory. Describe - the feature and include screenshots, if applicable. + the feature and include screenshots, if applicable. Indicate [what editions](documentation/styleguide.md#product-badges) + the feature applies to. - **Submit a MR to the `www-gitlab-com` project.**: Add the new feature to the [EE features list](https://about.gitlab.com/features/). diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index 37198499e7f..12ec9084b91 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -56,7 +56,7 @@ The author then adds a comment to this piece of code and adds a link to the issu - Track necessary events. See the [telemetry guide](../../telemetry/index.md) for details. - After the merge request is merged, use [`chatops`](../../ci/chatops/README.md) in the -[appropriate channel](../feature_flags/controls.md#where-to-run-commands) to start the experiment for 10% of the users. +[appropriate channel](../feature_flags/controls.md#communicate-the-change) to start the experiment for 10% of the users. The feature flag should have the name of the experiment with the `_experiment_percentage` suffix appended. For visibility, please also share any commands run against production in the `#s_growth` channel: diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index aa32285b27b..8ddcee0e531 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -16,32 +16,6 @@ run: /chatops run feature --help ``` -## Where to run commands - -To increase visibility, we recommend that GitLab team members run feature flag -related Chatops commands within certain Slack channels based on the environment -and related feature. For the [staging](https://staging.gitlab.com) -and [development](https://dev.gitlab.org) environments of GitLab.com, -the commands should run in a channel for the stage the feature is relevant too. - -For example, use the `#s_monitor` channel for features developed by the -Monitor stage, Health group. - -For all production environment Chatops commands, use the `#production` channel. - -As per the template, where a feature would have a (potentially) significant user -impact and the feature is being enabled instance wide prior to release, please copy -the Slack message and repost in the `#support_gitlab-com` channel for added visibility -and awareness, preferably with a link to the issue, MR, or docs. - -Regardless of the channel in which the Chatops command is ran, any feature flag change that affects GitLab.com will automatically be logged in an issue. - -The issue is created in the [gl-infra/feature-flag-log](https://gitlab.com/gitlab-com/gl-infra/feature-flag-log/issues?scope=all&utf8=%E2%9C%93&state=closed) project, and it will at minimum log the Slack handle of person enabling a feature flag, the time, and the name of the flag being changed. - -The issue is then also posted to GitLab Inc. internal [Grafana dashboard](https://dashboards.gitlab.net/) as an annotation marker to make the change even more visible. - -Changes to the issue format can be submitted in the [Chatops project](https://gitlab.com/gitlab-com/chatops). - ## Rolling out changes When the changes are deployed to the environments it is time to start @@ -67,19 +41,11 @@ If you get an error "Whoops! This action is not allowed. This incident will be reported." that means your Slack account is not allowed to change feature flags or you do not [have access](#access). -### Enabling feature for preproduction testing +### Enabling a feature for preproduction testing As a first step in a feature rollout, you should enable the feature on <https://staging.gitlab.com> and <https://dev.gitlab.org>. -For example, to enable a feature for 25% of all users, run the following in -Slack: - -```shell -/chatops run feature set new_navigation_bar 25 --dev -/chatops run feature set new_navigation_bar 25 --staging -``` - These two environments have different scopes. `dev.gitlab.org` is a production CE environment that has internal GitLab Inc. traffic and is used for some development and other related work. @@ -89,13 +55,65 @@ a (very) rough estimate of how your feature will look/behave on GitLab.com. Both of these instances are connected to Sentry so make sure you check the projects there for any exceptions while testing your feature after enabling the feature flag. -Once you are confident enough that these environments are in a good state with your -feature enabled, you can roll out the change to GitLab.com. +For these preproduction environments, the commands should be run in a +Slack channel for the stage the feature is relevant to. For example, use the +`#s_monitor` channel for features developed by the Monitor stage, Health +group. + +To enable a feature for 25% of all users, run the following in Slack: + +```shell +/chatops run feature set new_navigation_bar 25 --dev +/chatops run feature set new_navigation_bar 25 --staging +``` ### Enabling a feature for GitLab.com -Similar to above, to enable a feature for 25% of all users, run the following in -Slack: +When a feature has successfully been +[enabled on a preproduction](#enabling-a-feature-for-preproduction-testing) +environment and verified as safe and working, you can roll out the +change to GitLab.com (production). + +#### Communicate the change + +Some feature flag changes on GitLab.com should be communicated with +parts of the company. The developer responsible needs to determine +whether this is necessary and the appropriate level of communication. +This depends on the feature and what sort of impact it might have. + +As a guideline: + +- For simple features that are low-risk, and easily rolled back, then + just proceed to [enabling the feature in `#production`](#process). +- For features that will impact user experience consider notifying + `#support_gitlab-com` beforehand. +- For features with significant downstream effects (e.g.: turning on/off + Elasticsearch indexing) consider coordinating with `#production` + beforehand. + +#### Process + +Before toggling any feature flag, check that there are no ongoing +significant incidents on GitLab.com. You can do this by checking the +`#production` and `#incident-management` Slack channels, or looking for +[open incident issues](https://gitlab.com/gitlab-com/gl-infra/production/issues/?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=incident) +(although check the dates and times). + +We do not want to introduce changes during an incident, as it can make +diagnosis and resolution of the incident much harder to achieve, and +also will largely invalidate your rollout process as you will be unable +to assess whether the rollout was without problems or not. + +If there is any doubt, ask in `#production`. + +The following `/chatops` commands should be performed in the Slack +`#production` channel. + +When you begin to enable the feature, please link to the relevant +Feature Flag Rollout Issue within a Slack thread of the first `/chatops` +command you make so people can understand the change if they need to. + +To enable a feature for 25% of all users, run the following in Slack: ```shell /chatops run feature set new_navigation_bar 25 @@ -150,6 +168,23 @@ NOTE: **Note:** **Percentage of time** rollout is not a good idea if what you want is to make sure a feature is always on or off to the users. +### Feature flag change logging + +Any feature flag change that affects GitLab.com (production) will +automatically be logged in an issue. + +The issue is created in the +[gl-infra/feature-flag-log](https://gitlab.com/gitlab-com/gl-infra/feature-flag-log/issues?scope=all&utf8=%E2%9C%93&state=closed) +project, and it will at minimum log the Slack handle of person enabling +a feature flag, the time, and the name of the flag being changed. + +The issue is then also posted to GitLab's internal +[Grafana dashboard](https://dashboards.gitlab.net/) as an annotation +marker to make the change even more visible. + +Changes to the issue format can be submitted in the +[Chatops project](https://gitlab.com/gitlab-com/chatops). + ## Cleaning up Once the change is deemed stable, submit a new merge request to remove the diff --git a/doc/development/licensing.md b/doc/development/licensing.md index 06a71967d06..e1be1faa61b 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -42,66 +42,6 @@ For all of the above, please include `--why "Reason"` and `--who "My Name"` so t More detailed information on how the gem and its commands work is available in the [License Finder README](https://github.com/pivotal/LicenseFinder). -## Acceptable Licenses +## Additional information -Libraries with the following licenses are acceptable for use: - -- [MIT License](https://choosealicense.com/licenses/mit/) (the MIT Expat License specifically): The MIT License requires that the license itself is included with all copies of the source. It is a permissive (non-copyleft) license as defined by the Open Source Initiative. -- [GNU Lesser General Public License (GNU LGPL)](https://choosealicense.com/licenses/lgpl-3.0/) (version 2, version 3): GPL constraints regarding modification and redistribution under the same license are not required of projects using an LGPL library, only upon modification of the LGPL-licensed library itself. -- [Apache 2.0 License](https://choosealicense.com/licenses/apache-2.0/): A permissive license that also provides an express grant of patent rights from contributors to users. -- [Ruby 1.8 License](https://github.com/ruby/ruby/blob/ruby_1_8_6/COPYING): Dual-licensed under either itself or the GPLv2, defer to the Ruby License itself. Acceptable because of point 3b: "You may distribute the software in object code or binary form, provided that you do at least ONE of the following: b) accompany the distribution with the machine-readable source of the software." -- [Ruby 1.9 License](https://www.ruby-lang.org/en/about/license.txt): Dual-licensed under either itself or the BSD 2-Clause License, defer to BSD 2-Clause. -- [BSD 2-Clause License](https://opensource.org/licenses/BSD-2-Clause): A permissive (non-copyleft) license as defined by the Open Source Initiative. -- [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause) (also known as New BSD or Modified BSD): A permissive (non-copyleft) license as defined by the Open Source Initiative -- [ISC License](https://opensource.org/licenses/ISC) (also known as the OpenBSD License): A permissive (non-copyleft) license as defined by the Open Source Initiative. -- [Creative Commons Zero (CC0)](https://creativecommons.org/publicdomain/zero/1.0/): A public domain dedication, recommended as a way to disclaim copyright on your work to the maximum extent possible. -- [Unlicense](https://unlicense.org): Another public domain dedication. -- [OWFa 1.0](http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0): An open-source license and patent grant designed for specifications. -- [JSON License](https://www.json.org/license.html): Equivalent to the MIT license plus the statement, "The Software shall be used for Good, not Evil." - -## Unacceptable Licenses - -Libraries with the following licenses require legal approval for use: - -- [GNU GPL](https://choosealicense.com/licenses/gpl-3.0/) (version 1, [version 2](http://www.gnu.org/licenses/gpl-2.0.txt), [version 3](http://www.gnu.org/licenses/gpl-3.0.txt), or any future versions): GPL-licensed libraries cannot be linked to from non-GPL projects. -- [GNU AGPLv3](https://choosealicense.com/licenses/agpl-3.0/): AGPL-licensed libraries cannot be linked to from non-GPL projects. -- [Open Software License (OSL)](https://opensource.org/licenses/OSL-3.0): is a copyleft license. In addition, the FSF [recommend against its use](https://www.gnu.org/licenses/license-list.en.html#OSL). -- [WTFPL](https://wtfpl.net): is a public domain dedication [rejected by the OSI (3.2)](https://opensource.org/minutes20090304). Also has a strong language which is not in accordance with our diversity policy. - -## GPL Cooperation Commitment - -Before filing or continuing to prosecute any legal proceeding or claim (other than a Defensive Action) arising from termination of a Covered License, GitLab commits to extend to the person or entity (“you”) accused of violating the Covered License the following provisions regarding cure and reinstatement, taken from GPL version 3. As used here, the term ‘this License’ refers to the specific Covered License being enforced. - -However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. - -Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. - -GitLab intends this Commitment to be irrevocable, and binding and enforceable against GitLab and assignees of or successors to GitLab’s copyrights. - -GitLab may modify this Commitment by publishing a new edition on this page or a successor location. - -Definitions - -‘Covered License’ means the GNU General Public License, version 2 (GPLv2), the GNU Lesser General Public License, version 2.1 (LGPLv2.1), or the GNU Library General Public License, version 2 (LGPLv2), all as published by the Free Software Foundation. - -‘Defensive Action’ means a legal proceeding or claim that GitLab brings against you in response to a prior proceeding or claim initiated by you or your affiliate. - -GitLab means GitLab Inc. and its affiliates and subsidiaries. - -## Requesting Approval for Licenses or any other Intellectual Property - -Libraries that are not already approved and listed on the [Acceptable Licenses](#acceptable-licenses) list or that may be listed on the [Unacceptable Licenses](#unacceptable-licenses) list may be submitted to the legal team for review and use on a case-by-case basis. Please email `legal@gitlab.com` with the details of how the software will be used, whether or not it will be modified, and how it will be distributed (if at all). After a decision has been made, the original requestor is responsible for updating this document, if applicable. Not all approvals will be approved for universal use and may continue to remain on the Unacceptable License list. - -All inquiries relating to patents should be directed to the Legal team. - -## Notes - -Decisions regarding the GNU GPL licenses are based on information provided by [The GNU Project](http://www.gnu.org/licenses/gpl-faq.html#IfLibraryIsGPL), as well as [the Open Source Initiative](https://opensource.org/faq#linking-proprietary-code), which both state that linking GPL libraries makes the program itself GPL. - -If a gem uses a license which is not listed above, open an issue and ask. If a license is not included in the "acceptable" list, operate under the assumption that it is not acceptable. - -Keep in mind that each license has its own restrictions (typically defined in their body text). Please make sure to comply with those restrictions at all times whenever an external library is used. - -Dependencies which are only used in development or test environment are exempt from license requirements, as they're not distributed for use in production. - -**NOTE:** This document is **not** legal advice, nor is it comprehensive. It should not be taken as such. +Please see the [Open Source](https://about.gitlab.com/handbook/engineering/open-source/#using-open-source-libraries) page for more information on licensing. diff --git a/doc/push_rules/push_rules.md b/doc/push_rules/push_rules.md index f0d45efb1b0..15d09b31726 100644 --- a/doc/push_rules/push_rules.md +++ b/doc/push_rules/push_rules.md @@ -43,11 +43,18 @@ you want the branches to start with a certain name because you have different GitLab CI/CD jobs (`feature`, `hotfix`, `docker`, `android`, etc.) that rely on the branch name. -Your developers however, don't always remember that policy, so they push -various branches and CI pipelines do not work as expected. By restricting the -branch names globally in Push Rules, you can now sleep without the anxiety -of your developers' mistakes. Every branch that doesn't match your push rule -will get rejected. +Your developers, however, don't always remember that policy, so they might push to +various branches, and CI pipelines might not work as expected. By restricting the +branch names globally in Push Rules, such mistakes are prevented. +Any branch name that doesn't match your push rule will get rejected. + +Note that the name of your default branch is always allowed, regardless of the branch naming +regular expression (regex) specified. GitLab is configured this way +because merges typically have the default branch as their target. +If you have other target branches, include them in your regex. (See [Enabling push rules](#enabling-push-rules)). + +The default branch also defaults to being a [protected branch](../user/project/protected_branches.md), +which already limits users from pushing directly. ### Custom Push Rules **(CORE ONLY)** diff --git a/doc/raketasks/README.md b/doc/raketasks/README.md index 3e048b399f9..4b77d4952eb 100644 --- a/doc/raketasks/README.md +++ b/doc/raketasks/README.md @@ -37,4 +37,4 @@ The following are available Rake tasks: | [Uploads sanitize](../administration/raketasks/uploads/sanitize.md) | Remove EXIF data from images uploaded to earlier versions of GitLab. | | [User management](user_management.md) | Perform user management tasks. | | [Webhooks administration](web_hooks.md) | Maintain project Webhooks. | -| [X509 signatures](x509_signatures.md) | Update x509 commit signatures, useful if certificate store has changed. | +| [X.509 signatures](x509_signatures.md) | Update X.509 commit signatures, useful if certificate store has changed. | diff --git a/doc/raketasks/x509_signatures.md b/doc/raketasks/x509_signatures.md index ffc8f4f2a8f..e52584680f4 100644 --- a/doc/raketasks/x509_signatures.md +++ b/doc/raketasks/x509_signatures.md @@ -1,14 +1,14 @@ -# X509 signatures **(CORE ONLY)** +# X.509 signatures **(CORE ONLY)** -When [signing commits with x509](../user/project/repository/x509_signed_commits/index.md), +When [signing commits with X.509](../user/project/repository/x509_signed_commits/index.md), the trust anchor might change and the signatures stored within the database must be updated. -## Update all x509 signatures +## Update all X.509 signatures -This task loops through all X509 signed commits and updates their verification based on current +This task loops through all X.509 signed commits and updates their verification based on current certificate store. -To update all x509 signatures, run: +To update all X.509 signatures, run: **Omnibus Installation** diff --git a/doc/topics/airgap/index.md b/doc/topics/airgap/index.md index 29722a734c5..78af867c9d1 100644 --- a/doc/topics/airgap/index.md +++ b/doc/topics/airgap/index.md @@ -76,7 +76,7 @@ The next step is to tell the offline instance to use these resources instead of and so on. You can set these variables in the project's `.gitlab-ci.yml` files by using the bundle directly, or -in the GitLab UI at the project or group level. See the [GitLab CI/CD environment variables page](../../ci/variables/README.md#creating-a-custom-environment-variable) +in the GitLab UI at the project or group level. See the [GitLab CI/CD environment variables page](../../ci/variables/README.md#custom-environment-variables) for more information. #### Variables diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 8724c4ae292..06e4c17066c 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -146,7 +146,7 @@ to override the default chart values by setting `HELM_UPGRADE_EXTRA_ARGS` to `-- ## Custom Helm chart per environment You can specify the use of a custom Helm chart per environment by scoping the environment variable -to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables). +to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables). ## Customizing `.gitlab-ci.yml` diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 097cf58a420..4ed084fc01e 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -348,7 +348,7 @@ used by Auto DevOps currently defines 3 environment names: Those environments are tied to jobs using [Auto Deploy](stages.md#auto-deploy), so except for the environment scope, they must have a different deployment domain. You must define a separate `KUBE_INGRESS_BASE_DOMAIN` variable for each of the above -[based on the environment](../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables). +[based on the environment](../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables). The following table is an example of how to configure the three different clusters: diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 5a578e743eb..d3f3012e9b0 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -25,7 +25,7 @@ Access the default page for admin area settings by navigating to | [Terms of Service and Privacy Policy](terms.md) | Include a Terms of Service agreement and Privacy Policy that all users must accept. | | [External Authentication](external_authorization.md#configuration) | External Classification Policy Authorization | | [Web terminal](../../../administration/integration/terminal.md#limiting-websocket-connection-time) | Set max session time for web terminal. | -| [Web IDE](../../project/web_ide/index.md#enabling-client-side-evaluation) | Manage Web IDE Features. | +| [Web IDE](../../project/web_ide/index.md#enabling-live-preview) | Manage Web IDE Features. | ## Integrations diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index f9a45fadf6d..5a685678934 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -233,6 +233,7 @@ but commented out to help encourage others to add to it in the future. --> |protected_branches|counts|| |releases|counts|| |remote_mirrors|counts|| +|requirements_created|counts|| |snippets|counts|| |suggestions|counts|| |todos|counts|| diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index fea6c2fe31a..60d189c8b42 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -259,7 +259,7 @@ to pass a username and password. You can set it under your project's settings so that your credentials aren't exposed in `.gitlab-ci.yml`. If the username is `myuser` and the password is `verysecret` then you would -[set the following variable](../../ci/variables/README.md#via-the-ui) +[set the following variable](../../ci/variables/README.md#create-a-custom-variable-in-the-ui) under your project's settings: | Type | Key | Value | diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 270b1cc5eeb..51a2fdab1b9 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -354,7 +354,7 @@ Some analyzers can be customized with environment variables. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18193) in GitLab Ultimate 12.5. In addition to the aforementioned SAST configuration variables, -all [custom environment variables](../../../ci/variables/README.md#creating-a-custom-environment-variable) are propagated +all [custom environment variables](../../../ci/variables/README.md#custom-environment-variables) are propagated to the underlying SAST analyzer images if [the SAST vendored template](#configuration) is used. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 9cb4d495ced..54f0bebc6db 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -157,7 +157,7 @@ can be used for: - Downloading assets from a CDN - Any other commands that must run before the `git init` -To use this feature, define a [CI/CD variable](../../ci/variables/README.md#via-the-ui) called +To use this feature, define a [CI/CD variable](../../ci/variables/README.md#create-a-custom-variable-in-the-ui) called `CI_PRE_CLONE_SCRIPT` that contains a bash script. [This example](../../development/pipelines.md#pre-clone-step) diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 224836b20b5..11dfaaf9655 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -106,7 +106,7 @@ The domain should have a wildcard DNS configured to the Ingress IP address. When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments.md) similar to how the -[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables) +[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. While evaluating which environment matches the environment scope of a diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 00fe00cce6a..8dffb5c9df4 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -300,7 +300,7 @@ GitLab [isn't limited to the SAML providers listed above](#my-identity-provider- | SAML Request Binding | HTTP Redirect | GitLab (the service provider) redirects users to your Identity Provider with a base64 encoded `SAMLRequest` HTTP parameter. | | SAML Response Binding | HTTP POST | Your Identity Provider responds to users with an HTTP form including the `SAMLResponse`, which a user's browser submits back to GitLab. | | Sign SAML Response | Yes | We require this to prevent tampering. | -| X509 Certificate in response | Yes | This is used to sign the response and checked against the provided fingerprint. | +| X.509 Certificate in response | Yes | This is used to sign the response and checked against the provided fingerprint. | | Fingerprint Algorithm | SHA-1 | We need a SHA-1 hash of the certificate used to sign the SAML Response. | | Signature Algorithm | SHA-1/SHA-256/SHA-384/SHA-512 | Also known as the Digest Method, this can be specified in the SAML response. It determines how a response is signed. | | Encrypt SAML Assertion | No | TLS is used between your Identity Provider, the user's browser, and GitLab. | diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 74a58b93442..bb8cefd755d 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -182,7 +182,7 @@ you can either: When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments.md) similar to how the -[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables) work. +[environment-specific variables](../../../ci/variables/README.md#limit-the-environment-scopes-of-environment-variables) work. The default environment scope is `*`, which means all jobs, regardless of their environment, will use that cluster. Each scope can only be used by a single @@ -262,7 +262,7 @@ A Kubernetes cluster can be the destination for a deployment job. If the cluster from your jobs using tools such as `kubectl` or `helm`. - You don't use GitLab's cluster integration you can still deploy to your cluster. However, you will need configure Kubernetes tools yourself - using [environment variables](../../../ci/variables/README.md#creating-a-custom-environment-variable) + using [environment variables](../../../ci/variables/README.md#custom-environment-variables) before you can interact with the cluster from your jobs. ### Deployment variables diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 623833af894..279f08c2a72 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -134,7 +134,7 @@ the components outlined above and the pre-loaded demo runbook. 1. Navigate to **{settings}** **Settings >> CI/CD >> Variables** to create the variables in your project. -  +  1. Click **Save variables**. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 041a70067d4..4a4c536c80f 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -937,7 +937,7 @@ Prerequisites for embedding from a Grafana instance: You can set the visibility of the metrics dashboard to **Only Project Members** or **Everyone With Access**. When set to **Everyone with Access**, the metrics -dashboard, and all of the custom dashboard, YAML files, are visible to authenticated and non-authenticated users. +dashboard is visible to authenticated and non-authenticated users. ## Troubleshooting diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index c0ac76902dc..ad19e2aae75 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -2,17 +2,17 @@ type: concepts, howto --- -# Signing commits with x509 +# Signing commits with X.509 -[x509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key +[X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key certificates issued by a public or private Public Key Infrastructure (PKI). -Personal x509 certificates are used for authentication or signing purposes +Personal X.509 certificates are used for authentication or signing purposes such as SMIME, but Git also supports signing of commits and tags -with x509 certificates in a similar way as with [GPG](../gpg_signed_commits/index.md). -The main difference is the trust anchor which is the PKI for x509 certificates +with X.509 certificates in a similar way as with [GPG](../gpg_signed_commits/index.md). +The main difference is the trust anchor which is the PKI for X.509 certificates instead of a web of trust with GPG. -## How GitLab handles x509 +## How GitLab handles X.509 GitLab uses its own certificate store and therefore defines the trust chain. @@ -27,7 +27,7 @@ For a commit to be *verified* by GitLab: NOTE: **Note:** Certificate revocation lists are checked on a daily basis via background worker. -## Obtaining an x509 key pair +## Obtaining an X.509 key pair If your organization has Public Key Infrastructure (PKI), that PKI will provide an S/MIME key. @@ -37,9 +37,9 @@ own self-signed one, or purchase one. MozillaZine keeps a nice collection of [S/MIME-capable signing authorities](http://kb.mozillazine.org/Getting_an_SMIME_certificate) and some of them generate keys for free. -## Associating your x509 certificate with Git +## Associating your X.509 certificate with Git -To take advantage of X509 signing, you will need Git 2.19.0 or later. You can +To take advantage of X.509 signing, you will need Git 2.19.0 or later. You can check your Git version with: ```sh @@ -64,7 +64,7 @@ Install [smimesign](https://github.com/github/smimesign) by downloading the installer or via `brew install smimesign` on MacOS. Get the ID of your certificate with `smimesign --list-keys` and set your -signingkey `git config --global user.signingkey ID`, then configure x509: +signingkey `git config --global user.signingkey ID`, then configure X.509: ```sh git config --global gpg.x509.program smimesign @@ -73,7 +73,7 @@ git config --global gpg.format x509 ## Signing commits -After you have [associated your x509 certificate with Git](#associating-your-x509-certificate-with-git) you +After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you can start signing your commits: 1. Commit like you used to, the only difference is the addition of the `-S` flag: diff --git a/doc/user/project/web_ide/img/admin_clientside_evaluation.png b/doc/user/project/web_ide/img/admin_clientside_evaluation.png Binary files differdeleted file mode 100644 index a930490398b..00000000000 --- a/doc/user/project/web_ide/img/admin_clientside_evaluation.png +++ /dev/null diff --git a/doc/user/project/web_ide/img/admin_live_preview_v13_0.png b/doc/user/project/web_ide/img/admin_live_preview_v13_0.png Binary files differnew file mode 100644 index 00000000000..90129d240bc --- /dev/null +++ b/doc/user/project/web_ide/img/admin_live_preview_v13_0.png diff --git a/doc/user/project/web_ide/img/clientside_evaluation.png b/doc/user/project/web_ide/img/live_preview_v13_0.png Binary files differindex bd04d3d644b..bd04d3d644b 100644 --- a/doc/user/project/web_ide/img/clientside_evaluation.png +++ b/doc/user/project/web_ide/img/live_preview_v13_0.png diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index d383db2d62b..4aef3fce045 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -102,27 +102,28 @@ in the top of the sidebar to open a list of branches. You will need to commit or discard all your changes before switching to a different branch. -## Client Side Evaluation +## Live Preview -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19764) in [GitLab Core](https://about.gitlab.com/pricing/) 11.2. +> - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/issues/213853) from _Client Side Evaluation_ to _Live Preview_ in GitLab 13.0. You can use the Web IDE to preview JavaScript projects right in the browser. This feature uses CodeSandbox to compile and bundle the JavaScript used to preview the web application. - + Additionally, for public projects an **Open in CodeSandbox** button is available to transfer the contents of the project into a public CodeSandbox project to quickly share your project with others. -### Enabling Client Side Evaluation +### Enabling Live Preview -The Client Side Evaluation feature needs to be enabled in the GitLab instances -admin settings. Client Side Evaluation is enabled for all projects on +The Live Preview feature needs to be enabled in the GitLab instances +admin settings. Live Preview is enabled for all projects on GitLab.com - + Once you have done that, you can preview projects with a `package.json` file and a `main` entry point inside the Web IDE. An example `package.json` is shown diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 88b729272ec..fa3ad4536ef 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -126,7 +126,7 @@ found. The list is ordered alphabetically.  If you have many pages, not all will be listed in the sidebar. Click on -**More pages** to see all of them. +**View All Pages** to see all of them. ## Viewing the history of a wiki page @@ -189,7 +189,24 @@ instructions. On the project's Wiki page, there is a right side navigation that renders the full Wiki pages list by default, with hierarchy. -If the Wiki repository contains a `_sidebar` page, the file of this page replaces the default side navigation. -This custom file serves to render it's custom content, fully replacing the standard sidebar. +To customize the sidebar, you can create a file named `_sidebar` to fully replace the default navigation. + +CAUTION: **Warning:** +Unless you link the `_sidebar` file from your custom nav, to edit it you'll have to access it directly +from the browser's address bar by typing: `https://gitlab.com/<namespace>/<project_name>/-/wikis/_sidebar` (for self-managed GitLab instances, replace `gitlab.com` with your instance's URL). + +Example for `_sidebar` (using Markdown format): + +```markdown +### [Home](home) + +- [Hello World](hello) +- [Foo](foo) +- [Bar](bar) + +--- + +- [Sidebar](_sidebar) +``` Support for displaying a generated TOC with a custom side navigation is planned. |
