diff options
Diffstat (limited to 'doc/user')
105 files changed, 1927 insertions, 2083 deletions
diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 9968b7349dc..7fbb4d84cfc 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -41,7 +41,7 @@ These settings can be found within: - The path `/admin/application_settings`. The first push of a new project, including LFS objects, will be checked for size -and **will** be rejected if the sum of their sizes exceeds the maximum allowed +and **will** be rejected if the sum of their sizes exceeds the maximum allowed repository size. **Note:** The repository size limit includes repository files and LFS, and does not include artifacts. diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index ebbb2472752..e56acac527f 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -94,7 +94,7 @@ a group in the **Usage Quotas** page available to the group page settings list.  -## Extra Shared Runners pipeline minutes quota **[FREE ONLY]** +## Extra Shared Runners pipeline minutes quota **(FREE ONLY)** If you're using GitLab.com, you can purchase additional CI minutes so your pipelines will not be blocked after you have used all your CI minutes from your @@ -164,3 +164,23 @@ questions that you know someone might ask. Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> + +## Required pipeline configuration **(PREMIUM ONLY)** + +GitLab administrators can force a pipeline configuration to run on every +pipeline. + +The configuration applies to all pipelines for a GitLab instance and is +sourced from: + +- The [instance template repository](instance_template_repository.md). +- GitLab-supplied configuration. + +To set required pipeline configuration: + +1. Go to **Admin area > Settings > CI/CD**. +1. Expand the **Required pipeline configuration** section. +1. Select the required configuration from the provided dropdown. +1. Click **Save changes**. + + diff --git a/doc/user/admin_area/settings/img/admin_required_pipeline.png b/doc/user/admin_area/settings/img/admin_required_pipeline.png Binary files differnew file mode 100644 index 00000000000..58488674d51 --- /dev/null +++ b/doc/user/admin_area/settings/img/admin_required_pipeline.png diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index cebf36c7ec1..d77e91156f8 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -4,8 +4,8 @@ type: reference # Sign-up restrictions -You can block email addresses of specific domains, or whitelist only some -specific domains via the **Application Settings** in the Admin area. +By implementing sign-up restrictions, you can blacklist or whitelist email addresses +belonging to specific domains. >**Note**: These restrictions are only applied during sign-up. An admin is able to add a user through the admin panel with a disallowed domain. Also @@ -24,17 +24,21 @@ domains list. > [Introduced][ce-5259] in GitLab 8.10. With this feature enabled, you can block email addresses of a specific domain -from creating an account on your GitLab server. This is particularly useful to -prevent spam. Disposable email addresses are usually used by malicious users to -create dummy accounts and spam issues. +from creating an account on your GitLab server. This is particularly useful to prevent spam. Disposable email addresses are usually used by malicious users to create dummy accounts and spam issues. ## Settings -This feature can be activated via the **Application Settings** in the Admin area, -and you have the option of entering the list manually, or uploading a file with -the list. +To access this feature: -Both whitelist and blacklist accept wildcards, so for example, you can use +1. Navigate to the **Settings > General** in the Admin area. +1. Expand the **Sign-up restrictions** section. + +For the: + +- Blacklist, you can enter the list manually, or upload a `.txt` file with it. +- Whitelist you must enter the list manually. + +Both the whitelist and blacklist accept wildcards. For example, you can use `*.company.com` to accept every `company.com` subdomain, or `*.io` to block all domains ending in `.io`. Domains should be separated by a whitespace, semicolon, comma, or a new line. diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 696446599c8..da75684a3fe 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -10,7 +10,7 @@ images (or more precisely the containers) for known vulnerabilities by using [Clair](https://github.com/coreos/clair) and [clair-scanner](https://github.com/arminc/clair-scanner), two open source tools for Vulnerability Static Analysis for containers. -You can take advantage of Container Scanning by either [including the CI job](#including-the-provided-template) in +You can take advantage of Container Scanning by either [including the CI job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using [Auto Container Scanning](../../../topics/autodevops/index.md#auto-container-scanning-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -55,32 +55,16 @@ To enable Container Scanning in your pipeline, you need: [predefined environment variables](../../../ci/variables/predefined_variables.md) document. -## Configuring Container Scanning +## Configuration -To enable Container Scanning in your project, define a job in your -`.gitlab-ci.yml` file that generates the -[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate). +For GitLab 11.9 and later, to enable Container Scanning, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) +that's provided as a part of your GitLab installation. +For GitLab versions earlier than 11.9, you can copy and use the job as defined +in that template. -This can be done in two ways: - -- For GitLab 11.9 and later, including the provided - `Container-Scanning.gitlab-ci.yml` template (recommended). -- Manually specifying the job definition. Not recommended unless using GitLab - 11.8 and earlier. - -### Including the provided template - -NOTE: **Note:** -The CI/CD Container Scanning template is supported on GitLab 11.9 and later versions. -For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). - -A CI/CD [Container Scanning template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml) -with the default Container Scanning job definition is provided as a part of your GitLab -installation that you can [include](../../../ci/yaml/README.md#includetemplate) -in your `.gitlab-ci.yml` file. - -To enable Container Scanning using the provided template, add the following to -your `.gitlab-ci.yml` file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -89,12 +73,12 @@ include: The included template will: -- Create a `container_scanning` job in your CI/CD pipeline. -- Pull the already built Docker image from your project's - [Container Registry](../../project/container_registry.md) (see [requirements](#requirements)) - and scan it for possible vulnerabilities. +1. Create a `container_scanning` job in your CI/CD pipeline. +1. Pull the already built Docker image from your project's + [Container Registry](../../project/container_registry.md) (see [requirements](#requirements)) + and scan it for possible vulnerabilities. -The report will be saved as a +The results will be saved as a [Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest Container Scanning @@ -106,95 +90,6 @@ If you want to whitelist some specific vulnerabilities, you can do so by definin them in a YAML file named `clair-whitelist.yml`. Read more in the [Clair documentation](https://github.com/arminc/clair-scanner/blob/master/README.md#example-whitelist-yaml-file). -### Manual job definition for GitLab 11.5 and later - -CAUTION: **Caution:** -The job definition shown below is supported on GitLab 11.5 and later versions. -However, if you're using GitLab 11.9+, it's recommended to use -[the provided Container Scanning template](#including-the-provided-template). - -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `container_scanning` -job can be added: - -```yaml -container_scanning: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - ## Define two new variables based on GitLab's CI/CD predefined variables - ## https://docs.gitlab.com/ee/ci/variables/README.html#predefined-environment-variables - CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG - CI_APPLICATION_TAG: $CI_COMMIT_SHA - CLAIR_LOCAL_SCAN_VERSION: v2.0.8_fe9b059d930314b54c78f75afe265955faf4fdc1 - allow_failure: true - services: - - docker:stable-dind - script: - - docker run -d --name db arminc/clair-db:latest - - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:${CLAIR_LOCAL_SCAN_VERSION} - - apk add -U wget ca-certificates - - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} - - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64 - - mv clair-scanner_linux_amd64 clair-scanner - - chmod +x clair-scanner - - touch clair-whitelist.yml - - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done - - retries=0 - - echo "Waiting for clair daemon to start" - - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done - - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true - artifacts: - reports: - container_scanning: gl-container-scanning-report.json -``` - -### Manual job definition for GitLab 11.4 and earlier (deprecated) - -CAUTION: **Deprecated:** -Before GitLab 11.5, the Container Scanning job and artifact had to be named specifically -to automatically extract report data and show it in the merge request widget. -While these old job definitions are still maintained, they have been deprecated -and may be removed in the next major release, GitLab 12.0. You are strongly -advised to update your current `.gitlab-ci.yml` configuration to reflect that change. - -For GitLab 11.4 and earlier, the Container Scanning job should look like: - -```yaml -container_scanning: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - ## Define two new variables based on GitLab's CI/CD predefined variables - ## https://docs.gitlab.com/ee/ci/variables/README.html#predefined-environment-variables - CI_APPLICATION_REPOSITORY: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG - CI_APPLICATION_TAG: $CI_COMMIT_SHA - CLAIR_LOCAL_SCAN_VERSION: v2.0.8_fe9b059d930314b54c78f75afe265955faf4fdc1 - allow_failure: true - services: - - docker:stable-dind - script: - - docker run -d --name db arminc/clair-db:latest - - docker run -p 6060:6060 --link db:postgres -d --name clair --restart on-failure arminc/clair-local-scan:${CLAIR_LOCAL_SCAN_VERSION} - - apk add -U wget ca-certificates - - docker pull ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} - - wget https://github.com/arminc/clair-scanner/releases/download/v8/clair-scanner_linux_amd64 - - mv clair-scanner_linux_amd64 clair-scanner - - chmod +x clair-scanner - - touch clair-whitelist.yml - - while( ! wget -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; done - - retries=0 - - echo "Waiting for clair daemon to start" - - while( ! wget -T 10 -q -O /dev/null http://docker:6060/v1/namespaces ) ; do sleep 1 ; echo -n "." ; if [ $retries -eq 10 ] ; then echo " Timeout, aborting." ; exit 1 ; fi ; retries=$(($retries+1)) ; done - - ./clair-scanner -c http://docker:6060 --ip $(hostname -i) -r gl-container-scanning-report.json -l clair.log -w clair-whitelist.yml ${CI_APPLICATION_REPOSITORY}:${CI_APPLICATION_TAG} || true - artifacts: - paths: [gl-container-scanning-report.json] -``` - -Alternatively, the job name could be `sast:container` -and the artifact name could be `gl-sast-container-report.json`. -These names have been deprecated with GitLab 11.0 -and may be removed in the next major release, GitLab 12.0. - ## Security Dashboard The Security Dashboard is a good place to get an overview of all the security diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 936703cce32..a0a917c5ebd 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -14,7 +14,7 @@ Dynamic Application Security Testing (DAST) comes into place. If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your running web application(s) for known vulnerabilities using Dynamic Application Security Testing (DAST). -You can take advantage of DAST by either [including the CI job](#configuring-dast) in +You can take advantage of DAST by either [including the CI job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using [Auto DAST](../../../topics/autodevops/index.md#auto-dast-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -51,30 +51,16 @@ applications while you are developing and testing your applications. To run a DAST job, you need GitLab Runner with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). -## Configuring DAST +## Configuration -To enable DAST in your project, define a job in your `.gitlab-ci.yml` file that generates the -[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate). +For GitLab 11.9 and later, to enable DAST, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`DAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml) +that's provided as a part of your GitLab installation. +For GitLab versions earlier than 11.9, you can copy and use the job as defined +in that template. -This can be done in two ways: - -- For GitLab 11.9 and later, including the provided `DAST.gitlab-ci.yml` template (recommended). -- Manually specifying the job definition. Not recommended unless using GitLab - 11.8 and earlier. - -### Including the provided template - -NOTE: **Note:** -The CI/CD DAST template is supported on GitLab 11.9 and later versions. -For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). - -A CI/CD [DAST template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/DAST.gitlab-ci.yml) -with the default DAST job definition is provided as a part of your GitLab -installation which you can [include](../../../ci/yaml/README.md#includetemplate) -in your `.gitlab-ci.yml` file. - -To enable DAST using the provided template, add the following to your `.gitlab-ci.yml` -file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -84,22 +70,22 @@ variables: DAST_WEBSITE: https://example.com ``` +There are two ways to define the URL to be scanned by DAST: + +- Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables). +- Add it in an `environment_url.txt` file at the root of your project. + The included template will create a `dast` job in your CI/CD pipeline and scan your project's source code for possible vulnerabilities. -The report will be saved as a +The results will be saved as a [DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate) that you can later download and analyze. Due to implementation limitations we always take the latest DAST artifact available. Behind the scenes, the [GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast) is used to run the tests on the specified URL and scan it for possible vulnerabilities. -There are two ways to define the URL to be scanned by DAST: - -- Set the `DAST_WEBSITE` [variable](../../../ci/yaml/README.md#variables). -- Add it in an `environment_url.txt` file at the root of your project. - -#### Authenticated scan +### Authenticated scan It's also possible to authenticate the user before performing the DAST checks: @@ -117,12 +103,12 @@ variables: DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between ``` -The report will be saved as a +The results will be saved as a [DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. -#### Full scan +### Full scan DAST can be configured to perform [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan), which includes both passive and active scanning against the same target website: @@ -135,7 +121,7 @@ variables: DAST_FULL_SCAN_ENABLED: "true" ``` -#### Customizing the DAST settings +### Customizing the DAST settings The DAST settings can be changed through environment variables by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. @@ -155,7 +141,7 @@ variables: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable will take precedence. -#### Overriding the DAST template +### Overriding the DAST template If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare a `dast` job after the @@ -176,79 +162,6 @@ As the DAST job belongs to a separate `dast` stage that runs after all [default stages](../../../ci/yaml/README.md#stages), don't forget to add `stage: dast` when you override the template job definition. -### Manual job definition for GitLab 11.5 and later - -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `dast` -job can be added: - -```yaml -dast: - image: registry.gitlab.com/gitlab-org/security-products/zaproxy - variables: - website: "https://example.com" - allow_failure: true - script: - - mkdir /zap/wrk/ - - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true - - cp /zap/wrk/gl-dast-report.json . - artifacts: - reports: - dast: gl-dast-report.json -``` - -Where the `website` variable holds the URL to run the tests against. - -For an authenticated scan, use the following definition: - -```yaml -dast: - image: registry.gitlab.com/gitlab-org/security-products/zaproxy - variables: - website: "https://example.com" - login_url: "https://example.com/sign-in" - username: "john.doe@example.com" - password: "john-doe-password" - allow_failure: true - script: - - mkdir /zap/wrk/ - - /zap/zap-baseline.py -J gl-dast-report.json -t $website - --auth-url $login_url - --auth-username $username - --auth-password $password || true - - cp /zap/wrk/gl-dast-report.json . - artifacts: - reports: - dast: gl-dast-report.json -``` - -See the [zaproxy documentation](https://gitlab.com/gitlab-org/security-products/zaproxy) -to learn more about the authentication settings. - -### Manual job definition for GitLab 11.4 and earlier (deprecated) - -CAUTION: **Caution:** -Before GitLab 11.5, DAST job and artifact had to be named specifically -to automatically extract report data and show it in the merge request widget. -While these old job definitions are still maintained they have been deprecated -and may be removed in next major release, GitLab 12.0. You are strongly advised -to update your current `.gitlab-ci.yml` configuration to reflect that change. - -For GitLab 11.4 and earlier, the job should look like: - -```yaml -dast: - image: registry.gitlab.com/gitlab-org/security-products/zaproxy - variables: - website: "https://example.com" - allow_failure: true - script: - - mkdir /zap/wrk/ - - /zap/zap-baseline.py -J gl-dast-report.json -t $website || true - - cp /zap/wrk/gl-dast-report.json . - artifacts: - paths: [gl-dast-report.json] -``` - ## Security Dashboard The Security Dashboard is a good place to get an overview of all the security diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 2fe8a6f9029..09bd306363c 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -8,7 +8,7 @@ in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your dependencies for known vulnerabilities using Dependency Scanning. -You can take advantage of Dependency Scanning by either [including the CI job](#including-the-provided-template) +You can take advantage of Dependency Scanning by either [including the CI job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using [Auto Dependency Scanning](../../../topics/autodevops/index.md#auto-dependency-scanning-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -74,31 +74,16 @@ The Gemnasium client does **NOT** send the exact package versions your project r You can disable the remote checks by [using](#customizing-the-dependency-scanning-settings) the `DS_DISABLE_REMOTE_CHECKS` environment variable and setting it to `true`. -## Configuring Dependency Scanning +## Configuration -To enable Dependency Scanning in your project, define a job in your `.gitlab-ci.yml` -file that generates the -[Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate). +For GitLab 11.9 and later, to enable Dependency Scanning, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) +that's provided as a part of your GitLab installation. +For GitLab versions earlier than 11.9, you can copy and use the job as defined +that template. -This can be done in two ways: - -- For GitLab 11.9 and later, including the provided `Dependency-Scanning.gitlab-ci.yml` template (recommended). -- Manually specifying the job definition. Not recommended unless using GitLab - 11.8 and earlier. - -### Including the provided template - -NOTE: **Note:** -The CI/CD Dependency Scanning template is supported on GitLab 11.9 and later versions. -For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). - -A CI/CD [Dependency Scanning template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) -with the default Dependency Scanning job definition is provided as a part of your GitLab -installation which you can [include](../../../ci/yaml/README.md#includetemplate) -in your `.gitlab-ci.yml` file. - -To enable Dependency Scanning using the provided template, add the following to -your `.gitlab-ci.yml` file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -108,12 +93,12 @@ include: The included template will create a `dependency_scanning` job in your CI/CD pipeline and scan your project's source code for possible vulnerabilities. -The report will be saved as a +The results will be saved as a [Dependency Scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest Dependency Scanning artifact available. -#### Customizing the Dependency Scanning settings +### Customizing the Dependency Scanning settings The Dependency Scanning settings can be changed through [environment variables](#available-variables) by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. @@ -131,7 +116,7 @@ variables: Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable will take precedence. -#### Overriding the Dependency Scanning template +### Overriding the Dependency Scanning template If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare a `dependency_scanning` job @@ -146,7 +131,7 @@ dependency_scanning: CI_DEBUG_TRACE: "true" ``` -#### Available variables +### Available variables Dependency Scanning can be [configured](#customizing-the-dependency-scanning-settings) using environment variables. @@ -156,6 +141,7 @@ using environment variables. | `DS_ANALYZER_IMAGES` | Comma separated list of custom images. The official default images are still enabled. Read more about [customizing analyzers](analyzers.md). | | `DS_ANALYZER_IMAGE_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). Read more about [customizing analyzers](analyzers.md). | | `DS_ANALYZER_IMAGE_TAG` | Override the Docker tag of the official default images. Read more about [customizing analyzers](analyzers.md). | +| `DS_PYTHON_VERSION` | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12296) in GitLab 12.1)| | `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | | `DS_DISABLE_REMOTE_CHECKS` | Do not send any data to GitLab. Used in the [Gemnasium analyzer](#remote-checks). | | `DS_PULL_ANALYZER_IMAGES` | Pull the images from the Docker registry (set to `0` to disable). | @@ -163,82 +149,8 @@ using environment variables. | `DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | | `DS_PULL_ANALYZER_IMAGE_TIMEOUT` | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | | `DS_RUN_ANALYZER_TIMEOUT` | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h`, or `2h45m`. | - -### Manual job definition for GitLab 11.5 and later - -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `dependency_scanning` -job can be added: - -```yaml -dependency_scanning: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} - - | - docker run \ - --env DS_ANALYZER_IMAGES \ - --env DS_ANALYZER_IMAGE_PREFIX \ - --env DS_ANALYZER_IMAGE_TAG \ - --env DS_DEFAULT_ANALYZERS \ - --env DEP_SCAN_DISABLE_REMOTE_CHECKS \ - --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \ - --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \ - --env DS_RUN_ANALYZER_TIMEOUT \ - --volume "$PWD:/code" \ - --volume /var/run/docker.sock:/var/run/docker.sock \ - "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code - dependencies: [] - artifacts: - reports: - dependency_scanning: gl-dependency-scanning-report.json -``` - -You can supply many other [settings variables](#available-variables) -via `docker run --env` to customize your job execution. - -### Manual job definition for GitLab 11.4 and earlier (deprecated) - -CAUTION: **Caution:** -Before GitLab 11.5, the Dependency Scanning job and artifact had to be named specifically -to automatically extract the report data and show it in the merge request widget. -While these old job definitions are still maintained, they have been deprecated -and may be removed in the next major release, GitLab 12.0. You are strongly advised -to update your current `.gitlab-ci.yml` configuration to reflect that change. - -For GitLab 11.4 and earlier, the job should look like: - -```yaml -dependency_scanning: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export DS_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} - - | - docker run \ - --env DS_ANALYZER_IMAGES \ - --env DS_ANALYZER_IMAGE_PREFIX \ - --env DS_ANALYZER_IMAGE_TAG \ - --env DS_DEFAULT_ANALYZERS \ - --env DS_EXCLUDED_PATHS \ - --env DEP_SCAN_DISABLE_REMOTE_CHECKS \ - --env DS_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \ - --env DS_PULL_ANALYZER_IMAGE_TIMEOUT \ - --env DS_RUN_ANALYZER_TIMEOUT \ - --volume "$PWD:/code" \ - --volume /var/run/docker.sock:/var/run/docker.sock \ - "registry.gitlab.com/gitlab-org/security-products/dependency-scanning:$DS_VERSION" /code - artifacts: - paths: [gl-dependency-scanning-report.json] -``` +| `PIP_INDEX_URL` | Base URL of Python Package Index (default https://pypi.org/simple). | +| `PIP_EXTRA_INDEX_URL` | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma separated. | ## Reports JSON format diff --git a/doc/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md index 8eb231f8359..b0eb753938b 100644 --- a/doc/user/application_security/license_management/index.md +++ b/doc/user/application_security/license_management/index.md @@ -8,7 +8,7 @@ in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. If you are using [GitLab CI/CD](../../../ci/README.md), you can search your project dependencies for their licenses using License Management. -You can take advantage of License Management by either [including the job](#configuring-license-management) +You can take advantage of License Management by either [including the job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using [Auto License Management](../../../topics/autodevops/index.md#auto-license-management-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -65,33 +65,16 @@ The following languages and package managers are supported. To run a License Management scanning job, you need GitLab Runner with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). -## Configuring License Management +## Configuration -To enable License Management in your project, define a job in your `.gitlab-ci.yml` -file that generates the [License Management report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate). +For GitLab 11.9 and later, to enable License Management, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml) +that's provided as a part of your GitLab installation. +For GitLab versions earlier than 11.9, you can copy and use the job as defined +that template. -This can be done in two ways: - -- For GitLab 11.9 and later, including the provided `License-Management.gitlab-ci.yml` template (recommended). -- Manually specifying the job definition. Not recommended unless using GitLab - 11.8 and earlier. - -The License Management settings can be changed through environment variables by using the -[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. These variables are documented in the [License Management documentation](https://gitlab.com/gitlab-org/security-products/license-management#settings). - -### Including the provided template - -NOTE: **Note:** -The CI/CD License Management template is supported on GitLab 11.9 and later versions. -For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). - -A CI/CD [License Management template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml) -with the default License Management job definition is provided as a part of your GitLab -installation which you can [include](../../../ci/yaml/README.md#includetemplate) -in your `.gitlab-ci.yml` file. - -To enable License Management using the provided template, add the following to -your `.gitlab-ci.yml` file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -101,14 +84,17 @@ include: The included template will create a `license_management` job in your CI/CD pipeline and scan your dependencies to find their licenses. -The report will be saved as a +The results will be saved as a [License Management report artifact](../../../ci/yaml/README.md#artifactsreportslicense_management-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest License Management artifact available. Behind the scenes, the [GitLab License Management Docker image](https://gitlab.com/gitlab-org/security-products/license-management) is used to detect the languages/frameworks and in turn analyzes the licenses. -#### Installing custom dependencies +The License Management settings can be changed through environment variables by using the +[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. These variables are documented in the [License Management documentation](https://gitlab.com/gitlab-org/security-products/license-management#settings). + +### Installing custom dependencies > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.4. @@ -136,7 +122,7 @@ variables: In this example, `my-custom-install-script.sh` is a shell script at the root directory of your project. -#### Overriding the template +### Overriding the template If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare a `license_management` job @@ -151,7 +137,7 @@ license_management: CI_DEBUG_TRACE: "true" ``` -#### Configuring Maven projects +### Configuring Maven projects The License Management tool provides a `MAVEN_CLI_OPTS` environment variable which can hold the command line arguments to pass to the `mvn install` command which is executed under the hood. @@ -192,67 +178,6 @@ license_management: LM_PYTHON_VERSION: 3 ``` -### Manual job definition for GitLab 11.5 and later - -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `license_management` -job can be added: - -```yaml -license_management: - image: - name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable" - entrypoint: [""] - stage: test - allow_failure: true - script: - - /run.sh analyze . - artifacts: - reports: - license_management: gl-license-management-report.json -``` - -If you want to install custom project dependencies via the `SETUP_CMD` variable: - -```yaml -license_management: - image: - name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable" - entrypoint: [""] - stage: test - variables: - SETUP_CMD: ./my-custom-install-script.sh - allow_failure: true - script: - - /run.sh analyze . - artifacts: - reports: - license_management: gl-license-management-report.json -``` - -### Manual job definition for GitLab 11.4 and earlier (deprecated) - -CAUTION: **Caution:** -Before GitLab 11.5, the License Management job and artifact had to be named specifically -to automatically extract the report data and show it in the merge request widget. -While these old job definitions are still maintained, they have been deprecated -and may be removed in the next major release, GitLab 12.0. You are strongly advised -to update your current `.gitlab-ci.yml` configuration to reflect that change. - -For GitLab 11.4 and earlier, the job should look like: - -```yaml -license_management: - image: - name: "registry.gitlab.com/gitlab-org/security-products/license-management:$CI_SERVER_VERSION_MAJOR-$CI_SERVER_VERSION_MINOR-stable" - entrypoint: [""] - stage: test - allow_failure: true - script: - - /run.sh analyze . - artifacts: - paths: [gl-license-management-report.json] -``` - ## Project policies for License Management > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5940) @@ -271,16 +196,15 @@ To approve or blacklist a license: 1. Click the **Add a license** button.  + 1. In the **License name** dropdown, either: - - Select one of the available licenses. You can search for licenses in the field - at the top of the list. - - Enter arbitrary text in the field at the top of the list. This will cause the text to be - added as a license name to the list. + - Select one of the available licenses. You can search for licenses in the field + at the top of the list. + - Enter arbitrary text in the field at the top of the list. This will cause the text to be + added as a license name to the list. 1. Select the **Approve** or **Blacklist** radio button to approve or blacklist respectively the selected license. - - To modify an existing license: 1. In the **License Management** list, click the **Approved/Declined** dropdown to change it to the desired status. @@ -293,8 +217,6 @@ Searching for Licenses:  - - ## License Management report under pipelines > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5491) diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 84b45cbe6e6..1f9fd9d4e18 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -13,7 +13,7 @@ to learn how to protect your organization. If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known vulnerabilities using Static Application Security Testing (SAST). -You can take advantage of SAST by either [including the CI job](#configuring-sast) in +You can take advantage of SAST by either [including the CI job](#configuration) in your existing `.gitlab-ci.yml` file or by implicitly using [Auto SAST](../../../topics/autodevops/index.md#auto-sast-ultimate) that is provided by [Auto DevOps](../../../topics/autodevops/index.md). @@ -73,30 +73,16 @@ The Java analyzers can also be used for variants like the [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html), [Grails](https://grails.org/) and the [Maven wrapper](https://github.com/takari/maven-wrapper). -## Configuring SAST +## Configuration -To enable SAST in your project, define a job in your `.gitlab-ci.yml` file that generates the -[SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast-ultimate). +For GitLab 11.9 and later, to enable SAST, you must +[include](../../../ci/yaml/README.md#includetemplate) the +[`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) +that's provided as a part of your GitLab installation. +For GitLab versions earlier than 11.9, you can copy and use the job as defined +that template. -This can be done in two ways: - -- For GitLab 11.9 and later, including the provided `SAST.gitlab-ci.yml` template (recommended). -- Manually specifying the job definition. Not recommended unless using GitLab - 11.8 and earlier. - -### Including the provided template - -NOTE: **Note:** -The CI/CD SAST template is supported on GitLab 11.9 and later versions. -For earlier versions, use the [manual job definition](#manual-job-definition-for-gitlab-115-and-later). - -A CI/CD [SAST template](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) -with the default SAST job definition is provided as a part of your GitLab -installation which you can [include](../../../ci/yaml/README.md#includetemplate) -in your `.gitlab-ci.yml` file. - -To enable SAST using the provided template, add the following to your `.gitlab-ci.yml` -file: +Add the following to your `.gitlab-ci.yml` file: ```yaml include: @@ -106,14 +92,14 @@ include: The included template will create a `sast` job in your CI/CD pipeline and scan your project's source code for possible vulnerabilities. -The report will be saved as a +The results will be saved as a [SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. Behind the scenes, the [GitLab SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) is used to detect the languages/frameworks and in turn runs the matching scan tools. -#### Customizing the SAST settings +### Customizing the SAST settings The SAST settings can be changed through environment variables by using the [`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`. @@ -134,7 +120,7 @@ variables: Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline configuration, the last mention of the variable will take precedence. -#### Overriding the SAST template +### Overriding the SAST template If you want to override the job definition (for example, change properties like `variables` or `dependencies`), you need to declare a `sast` job after the @@ -149,78 +135,6 @@ sast: CI_DEBUG_TRACE: "true" ``` -### Manual job definition for GitLab 11.5 and later - -For GitLab 11.5 and GitLab Runner 11.5 and later, the following `sast` -job can be added: - -```yaml -sast: - stage: test - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export SAST_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} - - | - docker run \ - --env SAST_ANALYZER_IMAGES \ - --env SAST_ANALYZER_IMAGE_PREFIX \ - --env SAST_ANALYZER_IMAGE_TAG \ - --env SAST_DEFAULT_ANALYZERS \ - --env SAST_EXCLUDED_PATHS \ - --env SAST_BANDIT_EXCLUDED_PATHS \ - --env SAST_BRAKEMAN_LEVEL \ - --env SAST_GOSEC_LEVEL \ - --env SAST_FLAWFINDER_LEVEL \ - --env SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT \ - --env SAST_PULL_ANALYZER_IMAGE_TIMEOUT \ - --env SAST_RUN_ANALYZER_TIMEOUT \ - --volume "$PWD:/code" \ - --volume /var/run/docker.sock:/var/run/docker.sock \ - "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code - dependencies: [] - artifacts: - reports: - sast: gl-sast-report.json -``` - -You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/sast#settings) -via `docker run --env` to customize your job execution. - -### Manual job definition for GitLab 11.4 and earlier (deprecated) - -CAUTION: **Deprecated:** -Before GitLab 11.5, the SAST job and artifact had to be named specifically -to automatically extract report data and show it in the merge request widget. -While these old job definitions are still maintained, they have been deprecated -and may be removed in the next major release, GitLab 12.0. You are strongly -advised to update your current `.gitlab-ci.yml` configuration to reflect that change. - -For GitLab 11.4 and earlier, the SAST job should look like: - -```yaml -sast: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export SAST_VERSION=${SP_VERSION:-$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/')} - - docker run - --env SAST_CONFIDENCE_LEVEL="${SAST_CONFIDENCE_LEVEL:-3}" - --volume "$PWD:/code" - --volume /var/run/docker.sock:/var/run/docker.sock - "registry.gitlab.com/gitlab-org/security-products/sast:$SAST_VERSION" /app/bin/run /code - artifacts: - paths: [gl-sast-report.json] -``` - ## Reports JSON format CAUTION: **Caution:** diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md index e4fd08a582c..1b1d126b726 100644 --- a/doc/user/award_emojis.md +++ b/doc/user/award_emojis.md @@ -7,7 +7,7 @@ When you're collaborating online, you get fewer opportunities for high-fives and thumbs-ups. Emoji can be awarded to [issues](project/issues/index.md), [merge requests](project/merge_requests/index.md), -[snippets](snippets.md), and anywhere you can have a discussion. +[snippets](snippets.md), and anywhere you can have a thread.  diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 2246ea8ed5a..6956086c382 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -251,6 +251,7 @@ The applications below can be uninstalled. | Application | GitLab version | Notes | | ----------- | -------------- | ----- | +| GitLab Runner | 12.2+ | Any running pipelines will be canceled. | | Ingress | 12.1+ | The associated load balancer and IP will be deleted and cannot be restored. Furthermore, it can only be uninstalled if JupyterHub is not installed. | | JupyterHub | 12.1+ | All data not committed to GitLab will be deleted and cannot be restored. | | Prometheus | 11.11+ | All data will be deleted and cannot be restored. | diff --git a/doc/user/discussions/img/automatically_resolve_outdated_discussions.png b/doc/user/discussions/img/automatically_resolve_outdated_discussions.png Binary files differindex ba129e7a618..d31216a7e2e 100644 --- a/doc/user/discussions/img/automatically_resolve_outdated_discussions.png +++ b/doc/user/discussions/img/automatically_resolve_outdated_discussions.png diff --git a/doc/user/discussions/img/btn_new_issue_for_all_discussions.png b/doc/user/discussions/img/btn_new_issue_for_all_discussions.png Binary files differdeleted file mode 100644 index 3306bf2e60e..00000000000 --- a/doc/user/discussions/img/btn_new_issue_for_all_discussions.png +++ /dev/null diff --git a/doc/user/discussions/img/btn_new_issue_for_all_threads.png b/doc/user/discussions/img/btn_new_issue_for_all_threads.png Binary files differnew file mode 100644 index 00000000000..f24c84a2348 --- /dev/null +++ b/doc/user/discussions/img/btn_new_issue_for_all_threads.png diff --git a/doc/user/discussions/img/commit_comment_mr_context.png b/doc/user/discussions/img/commit_comment_mr_context.png Binary files differindex b363e0035e8..7b87d6e44d7 100644 --- a/doc/user/discussions/img/commit_comment_mr_context.png +++ b/doc/user/discussions/img/commit_comment_mr_context.png diff --git a/doc/user/discussions/img/commit_comment_mr_discussions_tab.png b/doc/user/discussions/img/commit_comment_mr_discussions_tab.png Binary files differindex 2b06cdcc055..4798ff4b658 100644 --- a/doc/user/discussions/img/commit_comment_mr_discussions_tab.png +++ b/doc/user/discussions/img/commit_comment_mr_discussions_tab.png diff --git a/doc/user/discussions/img/discussion_comment.png b/doc/user/discussions/img/discussion_comment.png Binary files differindex 206ddebf54b..685c30e5004 100644 --- a/doc/user/discussions/img/discussion_comment.png +++ b/doc/user/discussions/img/discussion_comment.png diff --git a/doc/user/discussions/img/discussion_view.png b/doc/user/discussions/img/discussion_view.png Binary files differdeleted file mode 100644 index 3a2b766ed7e..00000000000 --- a/doc/user/discussions/img/discussion_view.png +++ /dev/null diff --git a/doc/user/discussions/img/image_resolved_discussion.png b/doc/user/discussions/img/image_resolved_discussion.png Binary files differindex ed00b5c77fe..9feded27c92 100644 --- a/doc/user/discussions/img/image_resolved_discussion.png +++ b/doc/user/discussions/img/image_resolved_discussion.png diff --git a/doc/user/discussions/img/merge_request_commits_tab.png b/doc/user/discussions/img/merge_request_commits_tab.png Binary files differindex 41a3648f390..065d4be61f0 100644 --- a/doc/user/discussions/img/merge_request_commits_tab.png +++ b/doc/user/discussions/img/merge_request_commits_tab.png diff --git a/doc/user/discussions/img/mr_review_resolve.png b/doc/user/discussions/img/mr_review_resolve.png Binary files differindex 34176f3fa8e..fc6299961a5 100644 --- a/doc/user/discussions/img/mr_review_resolve.png +++ b/doc/user/discussions/img/mr_review_resolve.png diff --git a/doc/user/discussions/img/mr_review_resolve2.png b/doc/user/discussions/img/mr_review_resolve2.png Binary files differindex e4adb5f2c2d..1794b682911 100644 --- a/doc/user/discussions/img/mr_review_resolve2.png +++ b/doc/user/discussions/img/mr_review_resolve2.png diff --git a/doc/user/discussions/img/mr_review_second_comment.png b/doc/user/discussions/img/mr_review_second_comment.png Binary files differindex 920ea05ad66..204cc840d9e 100644 --- a/doc/user/discussions/img/mr_review_second_comment.png +++ b/doc/user/discussions/img/mr_review_second_comment.png diff --git a/doc/user/discussions/img/mr_review_second_comment_added.png b/doc/user/discussions/img/mr_review_second_comment_added.png Binary files differindex 1fb54348547..aa15ca7fb98 100644 --- a/doc/user/discussions/img/mr_review_second_comment_added.png +++ b/doc/user/discussions/img/mr_review_second_comment_added.png diff --git a/doc/user/discussions/img/mr_review_start.png b/doc/user/discussions/img/mr_review_start.png Binary files differindex 38b44bda0d2..0f52bee7d89 100644 --- a/doc/user/discussions/img/mr_review_start.png +++ b/doc/user/discussions/img/mr_review_start.png diff --git a/doc/user/discussions/img/mr_review_unresolve.png b/doc/user/discussions/img/mr_review_unresolve.png Binary files differindex da895ceb89f..3441efc1572 100644 --- a/doc/user/discussions/img/mr_review_unresolve.png +++ b/doc/user/discussions/img/mr_review_unresolve.png diff --git a/doc/user/discussions/img/new_issue_for_thread.png b/doc/user/discussions/img/new_issue_for_thread.png Binary files differnew file mode 100644 index 00000000000..2264da0b5b5 --- /dev/null +++ b/doc/user/discussions/img/new_issue_for_thread.png diff --git a/doc/user/discussions/img/onion_skin_view.png b/doc/user/discussions/img/onion_skin_view.png Binary files differindex 91c3b396844..9bb4428184e 100644 --- a/doc/user/discussions/img/onion_skin_view.png +++ b/doc/user/discussions/img/onion_skin_view.png diff --git a/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png b/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png Binary files differnew file mode 100644 index 00000000000..9314e3a6490 --- /dev/null +++ b/doc/user/discussions/img/only_allow_merge_if_all_threads_are_resolved.png diff --git a/doc/user/discussions/img/pending_review_comment.png b/doc/user/discussions/img/pending_review_comment.png Binary files differindex 916ef5b7452..812e4ac966a 100644 --- a/doc/user/discussions/img/pending_review_comment.png +++ b/doc/user/discussions/img/pending_review_comment.png diff --git a/doc/user/discussions/img/preview_issue_for_thread.png b/doc/user/discussions/img/preview_issue_for_thread.png Binary files differnew file mode 100644 index 00000000000..1517902c61c --- /dev/null +++ b/doc/user/discussions/img/preview_issue_for_thread.png diff --git a/doc/user/discussions/img/preview_issue_for_threads.png b/doc/user/discussions/img/preview_issue_for_threads.png Binary files differnew file mode 100644 index 00000000000..8359ab3143c --- /dev/null +++ b/doc/user/discussions/img/preview_issue_for_threads.png diff --git a/doc/user/discussions/img/resolve_comment_button.png b/doc/user/discussions/img/resolve_comment_button.png Binary files differindex 7c19fac31a2..0319ec999fd 100644 --- a/doc/user/discussions/img/resolve_comment_button.png +++ b/doc/user/discussions/img/resolve_comment_button.png diff --git a/doc/user/discussions/img/resolve_thread_button.png b/doc/user/discussions/img/resolve_thread_button.png Binary files differnew file mode 100644 index 00000000000..873c302f570 --- /dev/null +++ b/doc/user/discussions/img/resolve_thread_button.png diff --git a/doc/user/discussions/img/resolve_thread_issue_notice.png b/doc/user/discussions/img/resolve_thread_issue_notice.png Binary files differnew file mode 100644 index 00000000000..c2a8fdebee7 --- /dev/null +++ b/doc/user/discussions/img/resolve_thread_issue_notice.png diff --git a/doc/user/discussions/img/resolve_thread_open_issue.png b/doc/user/discussions/img/resolve_thread_open_issue.png Binary files differnew file mode 100644 index 00000000000..be2a4365297 --- /dev/null +++ b/doc/user/discussions/img/resolve_thread_open_issue.png diff --git a/doc/user/discussions/img/review_comment_quickactions.png b/doc/user/discussions/img/review_comment_quickactions.png Binary files differindex bd9880c329a..df5c4dd0fcc 100644 --- a/doc/user/discussions/img/review_comment_quickactions.png +++ b/doc/user/discussions/img/review_comment_quickactions.png diff --git a/doc/user/discussions/img/review_preview.png b/doc/user/discussions/img/review_preview.png Binary files differindex 4bf53a81b9c..1b91506b477 100644 --- a/doc/user/discussions/img/review_preview.png +++ b/doc/user/discussions/img/review_preview.png diff --git a/doc/user/discussions/img/swipe_view.png b/doc/user/discussions/img/swipe_view.png Binary files differindex 82d6e52173c..287d52a0811 100644 --- a/doc/user/discussions/img/swipe_view.png +++ b/doc/user/discussions/img/swipe_view.png diff --git a/doc/user/discussions/img/thread_view.png b/doc/user/discussions/img/thread_view.png Binary files differnew file mode 100644 index 00000000000..8c1fd9d5acf --- /dev/null +++ b/doc/user/discussions/img/thread_view.png diff --git a/doc/user/discussions/img/threads_resolved.png b/doc/user/discussions/img/threads_resolved.png Binary files differnew file mode 100644 index 00000000000..6ac815cf874 --- /dev/null +++ b/doc/user/discussions/img/threads_resolved.png diff --git a/doc/user/discussions/img/two_up_view.png b/doc/user/discussions/img/two_up_view.png Binary files differindex d9e90708e87..062a96723dd 100644 --- a/doc/user/discussions/img/two_up_view.png +++ b/doc/user/discussions/img/two_up_view.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index c6bc580fb8f..3cb765c0463 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -1,4 +1,4 @@ -# Discussions +# Threads The ability to contribute conversationally is offered throughout GitLab. @@ -12,7 +12,7 @@ You can leave a comment in the following places: - commit diffs There are standard comments, and you also have the option to create a comment -in the form of a threaded discussion. A comment can also be [turned into a discussion](#start-a-discussion-by-replying-to-a-standard-comment) +in the form of a thread. A comment can also be [turned into a thread](#start-a-thread-by-replying-to-a-standard-comment) when it receives a reply. The comment area supports [Markdown] and [quick actions]. You can edit your own @@ -21,41 +21,39 @@ higher can also edit a comment made by someone else. You can also reply to a comment notification email to reply to the comment if [Reply by email] is configured for your GitLab instance. Replying to a standard comment -creates another standard comment. Replying to a discussion comment creates a reply in the -discussion thread. Email replies support [Markdown] and [quick actions], just as if you replied from the web. +creates another standard comment. Replying to a threaded comment creates a reply in the thread. Email replies support + [Markdown] and [quick actions], just as if you replied from the web. -## Resolvable comments and discussions +## Resolvable comments and threads > **Notes:** > > - The main feature was [introduced][ce-5022] in GitLab 8.11. -> - Resolvable discussions can be added only to merge request diffs. +> - Resolvable threads can be added only to merge request diffs. -Discussion resolution helps keep track of progress during planning or code review. +Thread resolution helps keep track of progress during planning or code review. -Every standard comment or discussion thread in merge requests, commits, commit diffs, and +Every standard comment or thread in merge requests, commits, commit diffs, and snippets is initially displayed as unresolved. They can then be individually resolved by anyone with at least Developer access to the project or by the author of the change being reviewed. -The need to resolve all standard comments or discussions prevents you from forgetting -to address feedback and lets you hide discussions that are no longer relevant. +The need to resolve all standard comments or threads prevents you from forgetting +to address feedback and lets you hide threads that are no longer relevant. -!["A discussion between two people on a piece of code"][discussion-view] + -### Commit discussions in the context of a merge request +### Commit threads in the context of a merge request > [Introduced][ce-31847] in GitLab 10.3. -For reviewers with commit-based workflow, it may be useful to add discussions to -specific commit diffs in the context of a merge request. These discussions will +For reviewers with commit-based workflow, it may be useful to add threads to +specific commit diffs in the context of a merge request. These threads will persist through a commit ID change when: - force-pushing after a rebase - amending a commit -This functionality is also demonstrated in the video [How to use Merge Request Commit Discussions](https://www.youtube.com/watch?v=TviJH6oRboo). - -To create a commit diff discussion: +To create a commit diff thread: 1. Navigate to the merge request **Commits** tab. A list of commits that constitute the merge request will be shown. @@ -67,141 +65,141 @@ To create a commit diff discussion:  -1. Any discussions created this way will be shown in the merge request's +1. Any threads created this way will be shown in the merge request's **Discussions** tab and are resolvable.  -Discussions created this way will only appear in the original merge request +Threads created this way will only appear in the original merge request and not when navigating to that commit under your project's **Repository > Commits** page. TIP: **Tip:** -When a link of a commit reference is found in a discussion inside a merge +When a link of a commit reference is found in a thread inside a merge request, it will be automatically converted to a link in the context of the current merge request. -### Jumping between unresolved discussions +### Jumping between unresolved threads When a merge request has a large number of comments it can be difficult to track -what remains unresolved. You can jump between unresolved discussions with the -Jump button next to the Reply field on a discussion. +what remains unresolved. You can jump between unresolved threads with the +Jump button next to the Reply field on a thread. -You can also jump to the first unresolved discussion from the button next to the -resolved discussions tracker. +You can also jump to the first unresolved thread from the button next to the +resolved threads tracker. -!["3/4 discussions resolved"][discussions-resolved] + -### Marking a comment or discussion as resolved +### Marking a comment or thread as resolved -You can mark a discussion as resolved by clicking the **Resolve discussion** -button at the bottom of the discussion. +You can mark a thread as resolved by clicking the **Resolve thread** +button at the bottom of the thread. -!["Resolve discussion" button][resolve-discussion-button] + Alternatively, you can mark each comment as resolved individually. -!["Resolve comment" button][resolve-comment-button] + -### Move all unresolved discussions in a merge request to an issue +### Move all unresolved threads in a merge request to an issue > [Introduced][ce-8266] in GitLab 9.1 -To continue all open discussions from a merge request in a new issue, click the -**Resolve all discussions in new issue** button. +To continue all open threads from a merge request in a new issue, click the +**Resolve all threads in new issue** button. - + -Alternatively, when your project only accepts merge requests [when all discussions -are resolved](#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved), +Alternatively, when your project only accepts merge requests [when all threads +are resolved](#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), there will be an **open an issue to resolve them later** link in the merge request widget. - + This will prepare an issue with its content referring to the merge request and -the unresolved discussions. +the unresolved threads. - + -Hitting **Submit issue** will cause all discussions to be marked as resolved and +Hitting **Submit issue** will cause all threads to be marked as resolved and add a note referring to the newly created issue. - + You can now proceed to merge the merge request from the UI. -### Moving a single discussion to a new issue +### Moving a single thread to a new issue > [Introduced][ce-8266] in GitLab 9.1 -To create a new issue for a single discussion, you can use the **Resolve this -discussion in a new issue** button. +To create a new issue for a single thread, you can use the **Resolve this +thread in a new issue** button. - + This will direct you to a new issue prefilled with the content of the -discussion, similar to the issues created for delegating multiple -discussions at once. Saving the issue will mark the discussion as resolved and -add a note to the merge request discussion referencing the new issue. +thread, similar to the issues created for delegating multiple +threads at once. Saving the issue will mark the thread as resolved and +add a note to the merge request thread referencing the new issue. - + -### Only allow merge requests to be merged if all discussions are resolved +### Only allow merge requests to be merged if all threads are resolved > [Introduced][ce-7125] in GitLab 8.14. -You can prevent merge requests from being merged until all discussions are +You can prevent merge requests from being merged until all threads are resolved. Navigate to your project's settings page, select the -**Only allow merge requests to be merged if all discussions are resolved** check +**Only allow merge requests to be merged if all threads are resolved** check box and hit **Save** for the changes to take effect. - + -From now on, you will not be able to merge from the UI until all discussions +From now on, you will not be able to merge from the UI until all threads are resolved. - + -### Automatically resolve merge request diff discussions when they become outdated +### Automatically resolve merge request diff threads when they become outdated > [Introduced][ce-14053] in GitLab 10.0. -You can automatically resolve merge request diff discussions on lines modified +You can automatically resolve merge request diff threads on lines modified with a new push. Navigate to your project's settings page, select the **Automatically resolve -merge request diffs discussions on lines changed with a push** check box and hit +merge request diffs threads on lines changed with a push** check box and hit **Save** for the changes to take effect. - + -From now on, any discussions on a diff will be resolved by default if a push -makes that diff section outdated. Discussions on lines that don't change and -top-level resolvable discussions are not automatically resolved. +From now on, any threads on a diff will be resolved by default if a push +makes that diff section outdated. Threads on lines that don't change and +top-level resolvable threads are not automatically resolved. -## Commit discussions +## Commit threads -You can add comments and discussion threads to a particular commit under your +You can add comments and threads to a particular commit under your project's **Repository > Commits**. CAUTION: **Attention:** -Discussions created this way will be lost if the commit ID changes after a +Threads created this way will be lost if the commit ID changes after a force push. ## Threaded discussions > [Introduced][ce-7527] in GitLab 9.1. -While resolvable discussions are only available to merge request diffs, -discussions can also be added without a diff. You can start a specific -discussion which will look like a thread, on issues, commits, snippets, and +While resolvable threads are only available to merge request diffs, +threads can also be added without a diff. You can start a specific +thread which will look like a thread, on issues, commits, snippets, and merge requests. To start a threaded discussion, click on the **Comment** button toggle dropdown, -select **Start discussion** and click **Start discussion** when you're ready to +select **Start thread** and click **Start thread** when you're ready to post the comment.  @@ -209,56 +207,57 @@ post the comment. This will post a comment with a single thread to allow you to discuss specific comments in greater detail. - + -## Image discussions +## Image threads > [Introduced][ce-14061] in GitLab 10.1. -Sometimes a discussion is revolved around an image. With image discussions, -you can easily target a specific coordinate of an image and start a discussion -around it. Image discussions are available in merge requests and commit detail views. +Sometimes a thread is revolved around an image. With image threads, +you can easily target a specific coordinate of an image and start a thread +around it. Image threads are available in merge requests and commit detail views. -To start an image discussion, hover your mouse over the image. Your mouse pointer +To start an image thread, hover your mouse over the image. Your mouse pointer should convert into an icon, indicating that the image is available for commenting. -Simply click anywhere on the image to create a new discussion. +Simply click anywhere on the image to create a new thread. - + After you click on the image, a comment form will be displayed that would be the start -of your discussion. Once you save your comment, you will see a new badge displayed on -top of your image. This badge represents your discussion. +of your thread. Once you save your comment, you will see a new badge displayed on +top of your image. This badge represents your thread. >**Note:** -This discussion badge is typically associated with a number that is only used as a visual -reference for each discussion. In the merge request discussion tab, -this badge will be indicated with a comment icon since each discussion will render a new +This thread badge is typically associated with a number that is only used as a visual +reference for each thread. In the merge request thread tab, +this badge will be indicated with a comment icon since each thread will render a new image section. -Image discussions also work on diffs that replace an existing image. In this diff view -mode, you can toggle the different view modes and still see the discussion point badges. +Image threads also work on diffs that replace an existing image. In this diff view +mode, you can toggle the different view modes and still see the thread point badges. | 2-up | Swipe | Onion Skin | | :-----------: | :----------: | :----------: | |  |  |  | -Image discussions also work well with resolvable discussions. Resolved discussions +Image threads also work well with resolvable threads. Resolved threads on diffs (not on the merge request discussion tab) will appear collapsed on page load and will have a corresponding badge counter to match the counter on the image. - + ## Lock discussions > [Introduced][ce-14531] in GitLab 10.1. -For large projects with many contributors, it may be useful to stop discussions +For large projects with many contributors, it may be useful to stop threads in issues or merge requests in these scenarios: -- The project maintainer has already resolved the discussion and it is not helpful - for continued feedback. The project maintainer has already directed new conversation +- The project maintainer has already resolved the thread and it is not helpful + for continued feedback. +- The project maintainer has already directed new conversation to newer issues or merge requests. -- The people participating in the discussion are trolling, abusive, or otherwise +- The people participating in the thread are trolling, abusive, or otherwise being unproductive. In these cases, a user with Developer permissions or higher in the project can lock (and unlock) @@ -300,7 +299,7 @@ in an MR and click on the **Start a review** button. Once a review is started, you will see any comments that are part of this review marked `Pending`. All comments that are part of a review show two buttons: -- **Submit review**: Submits all comments that are part of the review, making them visible to other users. +- **Finish review**: Submits all comments that are part of the review, making them visible to other users. - **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review.  @@ -317,20 +316,20 @@ This will add the comment to the review.  -### Resolving/Unresolving discussions +### Resolving/Unresolving threads -Review comments can also resolve/unresolve [resolvable discussions](#resolvable-comments-and-discussions). +Review comments can also resolve/unresolve [resolvable threads](#resolvable-comments-and-threads). When replying to a comment, you will see a checkbox that you can click in order to resolve or unresolve -the discussion once published. +the thread once published.  - -If a particular pending comment will resolve or unresolve the discussion, this will be shown on the pending +If a particular pending comment will resolve or unresolve the thread, this will be shown on the pending comment itself.  - + + ### Submitting a review @@ -356,7 +355,7 @@ Replying to this email will, consequentially, create a new comment on the associ > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/26723) in GitLab 11.5. For issues with many comments like activity notes and user comments, sometimes -finding useful information can be hard. There is a way to filter comments from single notes and discussions for merge requests and issues. +finding useful information can be hard. There is a way to filter comments from single notes and threads for merge requests and issues. From a merge request's **Discussion** tab, or from an epic/issue overview, find the filter's dropdown menu on the right side of the page, from which you can choose one of the following options: @@ -376,7 +375,7 @@ from any device you're logged into. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6. As a reviewer, you're able to suggest code changes with a simple -markdown syntax in Merge Request Diff discussions. Then, the +markdown syntax in Merge Request Diff threads. Then, the Merge Request author (or other users with appropriate [permission](../permissions.md)) is able to apply these suggestions with a click, which will generate a commit in @@ -399,7 +398,7 @@ the Merge Request authored by the user that applied them.  Once the author applies a suggestion, it will be marked with the **Applied** label, -the discussion will be automatically resolved, and GitLab will create a new commit +the thread will be automatically resolved, and GitLab will create a new commit with the message `Apply suggestion to <file-name>` and push the suggested change directly into the codebase in the merge request's branch. [Developer permission](../permissions.md) is required to do so. @@ -413,8 +412,8 @@ Custom commit messages will be introduced by > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/53310) in GitLab 11.10. Reviewers can also suggest changes to multiple lines with a single suggestion -within Merge Request diff discussions by adjusting the range offsets. The -offsets are relative to the position of the diff discussion, and specify the +within Merge Request diff threads by adjusting the range offsets. The +offsets are relative to the position of the diff thread, and specify the range to be replaced by the suggestion when it is applied.  @@ -430,25 +429,26 @@ Suggestions covering multiple lines are limited to 100 lines _above_ and 100 lines _below_ the commented diff line, allowing up to 200 changed lines per suggestion. -## Start a discussion by replying to a standard comment +## Start a thread by replying to a standard comment > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30299) in GitLab 11.9 -To reply to a standard (non-discussion) comment, you can use the **Reply to comment** button. +To reply to a standard (non-thread) comment, you can use the **Reply to comment** button.  -The **Reply to comment** button is only displayed if you have permissions to reply to an existing discussion, or start a discussion from a standard comment. +The **Reply to comment** button is only displayed if you have permissions to reply to an existing thread, or start a thread from a standard comment. Clicking on the **Reply to comment** button will bring the reply area into focus and you can type your reply.  -Replying to a non-discussion comment will convert the non-discussion comment to a -threaded discussion once the reply is submitted. This conversion is considered an edit +Replying to a non-thread comment will convert the non-thread comment to a +thread once the reply is submitted. This conversion is considered an edit to the original comment, so a note about when it was last edited will appear underneath it. -This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff discussions are not supported yet. +This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are +not supported yet. [ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022 [ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125 diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 601ffd4947b..4ab562b655f 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -205,12 +205,12 @@ You may also consult the [group permissions table][permissions]. These text fields also fully support [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). -## Comment, or start a discussion +## Comment, or start a thread Once you wrote your comment, you can either: - Click "Comment" and your comment will be published. -- Click "Start discussion": start a thread within that epic's thread to discuss specific points. +- Click "Start thread": start a thread within that epic's discussion to discuss specific points. ## Award emoji diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 2d408766db8..55c5a18db7d 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -27,23 +27,23 @@ The following identity providers are supported: - [Group SSO](index.md) needs to be configured. - The `scim_group` feature flag must be enabled: - Run the following commands in a Rails console: + Run the following commands in a Rails console: - ```sh - # Omnibus GitLab - gitlab-rails console + ```sh + # Omnibus GitLab + gitlab-rails console - # Installation from source - cd /home/git/gitlab - sudo -u git -H bin/rails console RAILS_ENV=production - ``` + # Installation from source + cd /home/git/gitlab + sudo -u git -H bin/rails console RAILS_ENV=production + ``` - To enable SCIM for a group named `group_name`: + To enable SCIM for a group named `group_name`: - ```ruby - group = Group.find_by_full_path('group_name') - Feature.enable(:group_scim, group) - ``` + ```ruby + group = Group.find_by_full_path('group_name') + Feature.enable(:group_scim, group) + ``` ### GitLab configuration @@ -85,26 +85,26 @@ You can then test the connection clicking on `Test Connection`. 1. Map the `userPricipalName` to `emails[type eq "work"].value` and `mailNickname` to `userName`. - Example configuration: + Example configuration: -  +  1. Click on **Show advanced options > Edit attribute list for AppName**. 1. Leave the `id` as the primary and only required field. - NOTE: **Note:** - `username` should neither be primary nor required as we don't support - that field on GitLab SCIM yet. + NOTE: **Note:** + `username` should neither be primary nor required as we don't support + that field on GitLab SCIM yet. -  +  1. Save all the screens and, in the **Provisioning** step, set the `Provisioning Status` to `ON`. - NOTE: **Note:** - You can control what is actually synced by selecting the `Scope`. For example, - `Sync only assigned users and groups` will only sync the users assigned to - the application (`Users and groups`), otherwise it will sync the whole Active Directory. + NOTE: **Note:** + You can control what is actually synced by selecting the `Scope`. For example, + `Sync only assigned users and groups` will only sync the users assigned to + the application (`Users and groups`), otherwise it will sync the whole Active Directory. Once enabled, the synchronization details and any errors will appear on the bottom of the **Provisioning** screen, together with a link to the audit logs. diff --git a/doc/user/index.md b/doc/user/index.md index 501d74c76d1..db2759727a5 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -124,12 +124,12 @@ merge requests, code snippets, and commits. When performing inline reviews to implementations to your codebase through merge requests you can -gather feedback through [resolvable discussions](discussions/index.md#resolvable-comments-and-discussions). +gather feedback through [resolvable threads](discussions/index.md#resolvable-comments-and-threads). ### GitLab Flavored Markdown (GFM) Read through the [GFM documentation](markdown.md) to learn how to apply -the best of GitLab Flavored Markdown in your discussions, comments, +the best of GitLab Flavored Markdown in your threads, comments, issues and merge requests descriptions, and everywhere else GMF is supported. @@ -148,7 +148,7 @@ requests you're assigned to. [Snippets](snippets.md) are code blocks that you want to store in GitLab, from which you have quick access to. You can also gather feedback on them through -[discussions](#discussions). +[Discussions](#Discussions). ## Integrations diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 0d3bbeff4e5..96e74125801 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -556,7 +556,7 @@ Inline `code` has `back-ticks around` it. Similarly, a whole block of code can be fenced with triple backticks ```` ``` ````, triple tildes (`~~~`), or indended 4 or more spaces to achieve a similar effect for -a larger body of code. test. +a larger body of code. ~~~ ``` @@ -586,9 +586,11 @@ def function(): print s ``` - Using 4 spaces - is like using - 3-backtick fences. +``` +Using 4 spaces +is like using +3-backtick fences. +``` ~~~ Tildes are OK too. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 1b279173d1c..619cf34b5c3 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -60,7 +60,7 @@ The following table depicts the various user permission levels in a project. | View confidential issues | (*2*) | ✓ | ✓ | ✓ | ✓ | | Assign issues | | ✓ | ✓ | ✓ | ✓ | | Label issues | | ✓ | ✓ | ✓ | ✓ | -| Lock issue discussions | | ✓ | ✓ | ✓ | ✓ | +| Lock issue threads | | ✓ | ✓ | ✓ | ✓ | | Manage issue tracker | | ✓ | ✓ | ✓ | ✓ | | Manage related issues **(STARTER)** | | ✓ | ✓ | ✓ | ✓ | | Create issue from vulnerability **(ULTIMATE)** | | ✓ | ✓ | ✓ | ✓ | @@ -81,7 +81,7 @@ The following table depicts the various user permission levels in a project. | Create new merge request | | | ✓ | ✓ | ✓ | | Assign merge requests | | | ✓ | ✓ | ✓ | | Label merge requests | | | ✓ | ✓ | ✓ | -| Lock merge request discussions | | | ✓ | ✓ | ✓ | +| Lock merge request threads | | | ✓ | ✓ | ✓ | | Manage/Accept merge requests | | | ✓ | ✓ | ✓ | | Create new environments | | | ✓ | ✓ | ✓ | | Stop environments | | | ✓ | ✓ | ✓ | diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index e3e8c9a0d6d..d3a634c7b9d 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -183,29 +183,29 @@ a new set of recovery codes with SSH: 1. You will then be prompted to confirm that you want to generate new codes. Continuing this process invalidates previously saved codes: - ```sh - Are you sure you want to generate new two-factor recovery codes? - Any existing recovery codes you saved will be invalidated. (yes/no) - - yes - - Your two-factor authentication recovery codes are: - - 119135e5a3ebce8e - 11f6v2a498810dcd - 3924c7ab2089c902 - e79a3398bfe4f224 - 34bd7b74adbc8861 - f061691d5107df1a - 169bf32a18e63e7f - b510e7422e81c947 - 20dbed24c5e74663 - df9d3b9403b9c9f0 - - During sign in, use one of the codes above when prompted for your - two-factor code. Then, visit your Profile Settings and add a new device - so you do not lose access to your account again. - ``` + ```sh + Are you sure you want to generate new two-factor recovery codes? + Any existing recovery codes you saved will be invalidated. (yes/no) + + yes + + Your two-factor authentication recovery codes are: + + 119135e5a3ebce8e + 11f6v2a498810dcd + 3924c7ab2089c902 + e79a3398bfe4f224 + 34bd7b74adbc8861 + f061691d5107df1a + 169bf32a18e63e7f + b510e7422e81c947 + 20dbed24c5e74663 + df9d3b9403b9c9f0 + + During sign in, use one of the codes above when prompted for your + two-factor code. Then, visit your Profile Settings and add a new device + so you do not lose access to your account again. + ``` 1. Go to the GitLab sign-in page and enter your username/email and password. When prompted for a two-factor code, enter one of the recovery codes obtained diff --git a/doc/user/project/autocomplete_characters.md b/doc/user/project/autocomplete_characters.md new file mode 100644 index 00000000000..9ebf7f821a1 --- /dev/null +++ b/doc/user/project/autocomplete_characters.md @@ -0,0 +1,48 @@ +# Autocomplete characters + +The autocomplete characters provide a quick way of entering field values into +Markdown fields. When you start typing a word in a Markdown field with one of +the following characters, GitLab progressively autocompletes against a set of +matching values. The string matching is not case sensitive. + +| Character | Autocompletes | +| :-------- | :------------ | +| `~` | Labels | +| `%` | Milestones | +| `@` | Users and groups | +| `#` | Issues | +| `!` | Merge requests | +| `&` | Epics | +| `$` | Snippets | +| `:` | Emoji | +| `/` | Quick Actions | + +Up to 5 of the most relevant matches are displayed in a popup list. When you +select an item from the list, the value is entered in the field. The more +characters you enter, the more precise the matches are. + +Autocomplete characters are useful when combined with [Quick Actions](quick_actions.md). + +## Example + +Assume your GitLab instance includes the following users: + +| Username | Name | +| :-------------- | :--- | +| alessandra | Rosy Grant | +| lawrence.white | Kelsey Kerluke | +| leanna | Rosemarie Rogahn | +| logan_gutkowski | Lee Wuckert | +| shelba | Josefine Haley | + +In an Issue comment, entering `@l` results in the following popup list +appearing. Note that user `shelba` is not included, because the list includes +only the 5 users most relevant to the Issue. + + + +If you continue to type, `@le`, the popup list changes to the following. The +popup now only includes users where `le` appears in their username, or a word in +their name. + + diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index ea09f9f1547..55a9fbabf98 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -40,97 +40,97 @@ then click **Add an existing Kubernetes cluster**. A few details from the EKS cluster will be required to connect it to GitLab: -1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to - authenticate to the EKS cluster. We will use the certificate created by default. - Open a shell and use `kubectl` to retrieve it: +1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to + authenticate to the EKS cluster. We will use the certificate created by default. + Open a shell and use `kubectl` to retrieve it: - - List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate with: + - List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + - Get the certificate with: - ```sh - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - -1. **Create admin token**: A `cluster-admin` token is required to install and - manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller - and creates limited service accounts for each application. To create the - token we will create an admin service account as follows: - - 2.1. Create a file called `eks-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: eks-admin - namespace: kube-system - ``` - - 2.2. Apply the service account to your cluster: - - ```bash - kubectl apply -f eks-admin-service-account.yaml + ```sh + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode ``` - Output: - - ```bash - serviceaccount "eks-admin" created - ``` - - 2.3. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: - - ```yaml - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: eks-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: eks-admin - namespace: kube-system - ``` - - 2.4. Apply the cluster role binding to your cluster: - - ```bash - kubectl apply -f eks-admin-cluster-role-binding.yaml - ``` - - Output: - - ```bash - clusterrolebinding "eks-admin" created - ``` - - 2.5. Retrieve the token for the `eks-admin` service account: - - ```bash - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: eks-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=eks-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` +1. **Create admin token**: A `cluster-admin` token is required to install and + manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller + and creates limited service accounts for each application. To create the + token we will create an admin service account as follows: + + 2.1. Create a file called `eks-admin-service-account.yaml` with contents: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: eks-admin + namespace: kube-system + ``` + + 2.2. Apply the service account to your cluster: + + ```bash + kubectl apply -f eks-admin-service-account.yaml + ``` + + Output: + + ```bash + serviceaccount "eks-admin" created + ``` + + 2.3. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: eks-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: eks-admin + namespace: kube-system + ``` + + 2.4. Apply the cluster role binding to your cluster: + + ```bash + kubectl apply -f eks-admin-cluster-role-binding.yaml + ``` + + Output: + + ```bash + clusterrolebinding "eks-admin" created + ``` + + 2.5. Retrieve the token for the `eks-admin` service account: + + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: eks-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=eks-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` 1. The API server endpoint is also required, so GitLab can connect to the cluster. This is displayed on the AWS EKS console, when viewing the EKS cluster details. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 56f8257fbe7..4c247691757 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -56,8 +56,8 @@ new Kubernetes cluster to your project: 1. Navigate to your project's **Operations > Kubernetes** page. - NOTE: **Note:** - You need Maintainer [permissions] and above to access the Kubernetes page. + NOTE: **Note:** + You need Maintainer [permissions] and above to access the Kubernetes page. 1. Click **Add Kubernetes cluster**. 1. Click **Create with Google Kubernetes Engine**. @@ -97,117 +97,119 @@ To add an existing Kubernetes cluster to your project: 1. Navigate to your project's **Operations > Kubernetes** page. - NOTE: **Note:** - You need Maintainer [permissions] and above to access the Kubernetes page. + NOTE: **Note:** + You need Maintainer [permissions] and above to access the Kubernetes page. 1. Click **Add Kubernetes cluster**. 1. Click **Add an existing Kubernetes cluster** and fill in the details: - - **Kubernetes cluster name** (required) - The name you wish to give the cluster. - - **Environment scope** (required) - The - [associated environment](#setting-the-environment-scope-premium) to this cluster. - - **API URL** (required) - - It's the URL that GitLab uses to access the Kubernetes API. Kubernetes - exposes several APIs, we want the "base" URL that is common to all of them, - e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. - - Get the API URL by running this command: - - ```sh - kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' - ``` - - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the EKS cluster. We will use the certificate created by default. - - List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate by running this command: - - ```sh - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - - **Token** - - GitLab authenticates against Kubernetes using service tokens, which are - scoped to a particular `namespace`. - **The token used should belong to a service account with - [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) - privileges.** To create this service account: - - 1. Create a file called `gitlab-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: gitlab-admin - namespace: kube-system - --- - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: gitlab-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: gitlab-admin - namespace: kube-system - ``` - - 1. Apply the service account and cluster role binding to your cluster: - - ```bash - kubectl apply -f gitlab-admin-service-account.yaml - ``` - - Output: - - ```bash - serviceaccount "gitlab-admin" created - clusterrolebinding "gitlab-admin" created - ``` - - 1. Retrieve the token for the `gitlab-admin` service account: - - ```bash - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: gitlab-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=gitlab-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - - NOTE: **Note:** - For GKE clusters, you will need the - `container.clusterRoleBindings.create` permission to create a cluster - role binding. You can follow the [Google Cloud - documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) - to grant access. - - - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information. - - - **Project namespace** (optional) - You don't have to fill it in; by leaving - it blank, GitLab will create one for you. Also: - - Each project should have a unique namespace. - - The project namespace is not necessarily the namespace of the secret, if - you're using a secret with broader permissions, like the secret from `default`. - - You should **not** use `default` as the project namespace. - - If you or someone created a secret specifically for the project, usually - with limited permissions, the secret's namespace and project namespace may - be the same. + - **Kubernetes cluster name** (required) - The name you wish to give the cluster. + - **Environment scope** (required) - The + [associated environment](#setting-the-environment-scope-premium) to this cluster. + - **API URL** (required) - + It's the URL that GitLab uses to access the Kubernetes API. Kubernetes + exposes several APIs, we want the "base" URL that is common to all of them, + e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. + + Get the API URL by running this command: + + ```sh + kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' + ``` + + - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the EKS cluster. We will use the certificate created by default. + - List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + - Get the certificate by running this command: + + ```sh + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + ``` + + - **Token** - + GitLab authenticates against Kubernetes using service tokens, which are + scoped to a particular `namespace`. + **The token used should belong to a service account with + [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) + privileges.** To create this service account: + + 1. Create a file called `gitlab-admin-service-account.yaml` with contents: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: gitlab-admin + namespace: kube-system + --- + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: gitlab-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: gitlab-admin + namespace: kube-system + ``` + + 1. Apply the service account and cluster role binding to your cluster: + + ```bash + kubectl apply -f gitlab-admin-service-account.yaml + ``` + + Output: + + ```bash + serviceaccount "gitlab-admin" created + clusterrolebinding "gitlab-admin" created + ``` + + 1. Retrieve the token for the `gitlab-admin` service account: + + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: gitlab-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=gitlab-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + + NOTE: **Note:** + For GKE clusters, you will need the + `container.clusterRoleBindings.create` permission to create a cluster + role binding. You can follow the [Google Cloud + documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) + to grant access. + + - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information. + + - **Project namespace** (optional) - You don't have to fill it in; by leaving + it blank, GitLab will create one for you. Also: + - Each project should have a unique namespace. + - The project namespace is not necessarily the namespace of the secret, if + you're using a secret with broader permissions, like the secret from `default`. + - You should **not** use `default` as the project namespace. + - If you or someone created a secret specifically for the project, usually + with limited permissions, the secret's namespace and project namespace may + be the same. 1. Finally, click the **Create Kubernetes cluster** button. diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index c67b12fb91a..c021d059d30 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -1,28 +1,27 @@ # Runbooks -Runbooks are a collection of documented procedures that explain how to -carry out a particular process, be it starting, stopping, debugging, +Runbooks are a collection of documented procedures that explain how to +carry out a particular process, be it starting, stopping, debugging, or troubleshooting a particular system. Using [Jupyter Notebooks](https://jupyter.org/) and the [Rubix library](https://github.com/Nurtch/rubix), users can get started writing their own executable runbooks. - ## Overview -Historically, runbooks took the form of a decision tree or a detailed -step-by-step guide depending on the condition or system. +Historically, runbooks took the form of a decision tree or a detailed +step-by-step guide depending on the condition or system. -Modern implementations have introduced the concept of an "executable -runbooks", where, along with a well-defined process, operators can execute +Modern implementations have introduced the concept of an "executable +runbooks", where, along with a well-defined process, operators can execute pre-written code blocks or database queries against a given environment. ## Executable Runbooks > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45912) in GitLab 11.4. -The JupyterHub app offered via GitLab’s Kubernetes integration now ships -with Nurtch’s Rubix library, providing a simple way to create DevOps +The JupyterHub app offered via GitLab’s Kubernetes integration now ships +with Nurtch’s Rubix library, providing a simple way to create DevOps runbooks. A sample runbook is provided, showcasing common operations. While Rubix makes it simple to create common Kubernetes and AWS workflows, you can also create them manually without Rubix. @@ -35,33 +34,33 @@ for an overview of how this is accomplished in GitLab!** To create an executable runbook, you will need: -1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. +1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab). -1. **Helm Tiller** - Helm is a package manager for Kubernetes and is required to install - all the other applications. It is installed in its own pod inside the cluster which +1. **Helm Tiller** - Helm is a package manager for Kubernetes and is required to install + all the other applications. It is installed in its own pod inside the cluster which can run the helm CLI in a safe environment. -1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based +1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications. -1. **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user service for managing notebooks across - a team. Jupyter Notebooks provide a web-based interactive programming environment +1. **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user service for managing notebooks across + a team. Jupyter Notebooks provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. ## Nurtch -Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). Rubix is -an open-source python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks. -Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified -down to a couple of lines of code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest) +Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). Rubix is +an open-source python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks. +Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified +down to a couple of lines of code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest) for more information. ## Configure an executable runbook with GitLab -Follow this step-by-step guide to configure an executable runbook in GitLab using +Follow this step-by-step guide to configure an executable runbook in GitLab using the components outlined above and the preloaded demo runbook. ### 1. Add a Kubernetes cluster -Follow the steps outlined in [Adding and creating a new GKE cluster via GitLab](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) +Follow the steps outlined in [Adding and creating a new GKE cluster via GitLab](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) to add a Kubernetes cluster to your project. ### 2. Install Helm Tiller, Ingress, and JupyterHub @@ -80,13 +79,13 @@ Once Ingress has been installed successfully, click the **Install** button next ### 3. Login to JupyterHub and start the server -Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click -**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This +Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click +**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This will redirect to GitLab in order to authorize JupyterHub to use your GitLab account. Click **Authorize**.  -Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server**. +Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server**. The server will take a couple of seconds to start. ### 4. Configure access @@ -103,7 +102,7 @@ Double-click the "Nurtch-DevOps-Demo.ipynb" runbook.  -The contents on the runbook will be displayed on the right side of the screen. Under the "Setup" section, you will find +The contents on the runbook will be displayed on the right side of the screen. Under the "Setup" section, you will find entries for both your `PRIVATE_TOKEN` and your `PROJECT_ID`. Enter both these values, conserving the single quotes as follows: ```sql @@ -111,7 +110,7 @@ PRIVATE_TOKEN = 'n671WNGecHugsdEDPsyo' PROJECT_ID = '1234567' ``` -Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your +Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your access token. In this example our variable name is `PRIVATE_TOKEN`. ```sql @@ -120,8 +119,8 @@ VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value ### 5. Configure an operation -For this example we'll use the "**Run SQL queries in Notebook**" section in the sample runbook to query -a postgres database. The first 4 lines of the section define the variables that are required for this query to function. +For this example we'll use the "**Run SQL queries in Notebook**" section in the sample runbook to query +a postgres database. The first 4 lines of the section define the variables that are required for this query to function. ```sql %env DB_USER={project.variables.get('DB_USER').value} @@ -134,10 +133,10 @@ Create the matching variables in your project's **Settings >> CI/CD >> Variables  -Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run*. The results will be +Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run*. The results will be displayed in-line as follows:  -You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the -[Nurtch Documentation](http://docs.nurtch.com/) for more information.
\ No newline at end of file +You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the +[Nurtch Documentation](http://docs.nurtch.com/) for more information. diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index a8473f76733..14ee6303bf9 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -24,34 +24,34 @@ To run Knative on Gitlab, you will need: 1. **Existing GitLab project:** You will need a GitLab project to associate all resources. The simplest way to get started: - - If you are planning on deploying functions, clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started. - - If you are planning on deploying a serverless application, clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. + - If you are planning on deploying functions, clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started. + - If you are planning on deploying a serverless application, clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. - The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab). - The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. + The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab). + The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. 1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install - Knative. + Knative. 1. **GitLab Runner:** A runner is required to run the CI jobs that will deploy serverless - applications or functions onto your cluster. You can install the GitLab Runner - onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. + applications or functions onto your cluster. You can install the GitLab Runner + onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. 1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an - external IP address or hostname for all the applications served by Knative. You will be prompted to enter a - wildcard domain where your applications will be served. Configure your DNS server to use the - external IP address or hostname for that domain. + external IP address or hostname for all the applications served by Knative. You will be prompted to enter a + wildcard domain where your applications will be served. Configure your DNS server to use the + external IP address or hostname for that domain. 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) - to build the application. We also use [gitlabktl](https://gitlab.com/gitlab-org/gitlabktl) - and [TriggerMesh CLI](https://github.com/triggermesh/tm) CLIs to simplify the - deployment of services and functions to Knative. + to build the application. We also use [gitlabktl](https://gitlab.com/gitlab-org/gitlabktl) + and [TriggerMesh CLI](https://github.com/triggermesh/tm) CLIs to simplify the + deployment of services and functions to Knative. 1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file - will contain the information for all the functions being hosted in the repository as well as a reference to the - runtime being used. + will contain the information for all the functions being hosted in the repository as well as a reference to the + runtime being used. 1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications): Knative requires a - `Dockerfile` in order to build your applications. It should be included at the root of your - project's repo and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions - using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). + `Dockerfile` in order to build your applications. It should be included at the root of your + project's repo and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions + using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). 1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application. - See [Installing Applications](../index.md#installing-applications) for more information. + See [Installing Applications](../index.md#installing-applications) for more information. ## Installing Knative via GitLab's Kubernetes integration @@ -60,9 +60,9 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22. 1. [Add a Kubernetes cluster](../index.md) and [install Helm](../index.md#installing-applications). 1. Once Helm has been successfully installed, scroll down to the Knative app section. Enter the domain to be used with - your application/functions (e.g. `example.com`) and click **Install**. + your application/functions (e.g. `example.com`) and click **Install**. -  +  1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../#manually-determining-the-external-endpoint). @@ -77,7 +77,7 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22. if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info` pointing the ip address or hostname of the ingress. -  +  NOTE: **Note:** You can deploy either [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) @@ -100,54 +100,54 @@ You must do the following: [add an existing Kubernetes cluster](../index.md#adding-an-existing-kubernetes-cluster). 1. Ensure GitLab can manage Knative: - - For a non-GitLab managed cluster, ensure that the service account for the token - provided can manage resources in the `serving.knative.dev` API group. - - For a GitLab managed cluster, if you added the cluster in [GitLab 12.1 or later](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30235), - then GitLab will already have the required access and you can proceed to the next step. - - Otherwise, you need to manually grant GitLab's service account the ability to manage - resources in the `serving.knative.dev` API group. Since every GitLab service account - has the `edit` cluster role, the simplest way to do this is with an - [aggregated ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles) - adding rules to the default `edit` cluster role: First, save the following YAML as - `knative-serving-only-role.yaml`: - - ```yaml - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: knative-serving-only-role - labels: - rbac.authorization.k8s.io/aggregate-to-edit: "true" - rules: - - apiGroups: - - serving.knative.dev - resources: - - configurations - - configurationgenerations - - routes - - revisions - - revisionuids - - autoscalers - - services - verbs: - - get - - list - - create - - update - - delete - - patch - - watch - ``` - - Then run the following command: - - ```bash - kubectl apply -f knative-serving-only-role.yaml - ``` - - If you would rather grant permissions on a per service account basis, you can do this - using a `Role` and `RoleBinding` specific to the service account and namespace. + - For a non-GitLab managed cluster, ensure that the service account for the token + provided can manage resources in the `serving.knative.dev` API group. + - For a GitLab managed cluster, if you added the cluster in [GitLab 12.1 or later](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30235), + then GitLab will already have the required access and you can proceed to the next step. + + Otherwise, you need to manually grant GitLab's service account the ability to manage + resources in the `serving.knative.dev` API group. Since every GitLab service account + has the `edit` cluster role, the simplest way to do this is with an + [aggregated ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles) + adding rules to the default `edit` cluster role: First, save the following YAML as + `knative-serving-only-role.yaml`: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: knative-serving-only-role + labels: + rbac.authorization.k8s.io/aggregate-to-edit: "true" + rules: + - apiGroups: + - serving.knative.dev + resources: + - configurations + - configurationgenerations + - routes + - revisions + - revisionuids + - autoscalers + - services + verbs: + - get + - list + - create + - update + - delete + - patch + - watch + ``` + + Then run the following command: + + ```bash + kubectl apply -f knative-serving-only-role.yaml + ``` + + If you would rather grant permissions on a per service account basis, you can do this + using a `Role` and `RoleBinding` specific to the service account and namespace. 1. Follow the steps to deploy [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) onto your @@ -157,9 +157,9 @@ You must do the following: > Introduced in GitLab 11.6. -Using functions is useful for dealing with independent -events without needing to maintain a complex unified infrastructure. This allows -you to focus on a single task that can be executed/scaled automatically and independently. +Using functions is useful for dealing with independent events without needing +to maintain a complex unified infrastructure. This allows you to focus on a +single task that can be executed/scaled automatically and independently. Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes) are offered: @@ -167,15 +167,21 @@ Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runt - node.js - Dockerfile -You can find and import all the files referenced in this doc in the **[functions example project](https://gitlab.com/knative-examples/functions)**. +`Dockerfile` presence is assumed when a runtime is not specified. -Follow these steps to deploy a function using the Node.js runtime to your Knative instance (you can skip these steps if you've cloned the example project): +You can find and import all the files referenced in this doc in the +**[functions example project](https://gitlab.com/knative-examples/functions)**. -1. Create a directory that will house the function. In this example we will create a directory called `echo` at the root of the project. +Follow these steps to deploy a function using the Node.js runtime to your +Knative instance (you can skip these steps if you've cloned the example +project): + +1. Create a directory that will house the function. In this example we will + create a directory called `echo` at the root of the project. 1. Create the file that will contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: - - Public, continue to the next step. - - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. + - Public, continue to the next step. + - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. 1. `.gitlab-ci.yml`: this defines a pipeline used to deploy your functions. It must be included at the root of your repository: @@ -193,16 +199,16 @@ Follow these steps to deploy a function using the Node.js runtime to your Knativ environment: production ``` - This `.gitlab-ci.yml` creates jobs that invoke some predefined commands to - build and deploy your functions to your cluster. + This `.gitlab-ci.yml` creates jobs that invoke some predefined commands to + build and deploy your functions to your cluster. - `Serverless.gitlab-ci.yml` is a template that allows customization. - You can either import it with `include` parameter and use `extends` to - customize your jobs, or you can inline the entire template by choosing it - from **Apply a template** dropdown when editing the `.gitlab-ci.yml` file through - the user interface. + `Serverless.gitlab-ci.yml` is a template that allows customization. + You can either import it with `include` parameter and use `extends` to + customize your jobs, or you can inline the entire template by choosing it + from **Apply a template** dropdown when editing the `.gitlab-ci.yml` file through + the user interface. -2. `serverless.yml`: this file contains the metadata for your functions, +1. `serverless.yml`: this file contains the metadata for your functions, such as name, runtime, and environment. It must be included at the root of your repository. @@ -248,21 +254,22 @@ Explanation of the fields used above: ### `functions` -In the `serverless.yml` example above, the function name is `echo` and the subsequent lines contain the function attributes. +In the `serverless.yml` example above, the function name is `echo` and the +subsequent lines contain the function attributes. | Parameter | Description | |-----------|-------------| | `handler` | The function's name. | | `source` | Directory with sources of a functions. | -| `runtime` | The runtime to be used to execute the function. | +| `runtime` (optional)| The runtime to be used to execute the function. When the runtime is not specified, we assume that `Dockerfile` is present in the function directory specified by `source`. | | `description` | A short description of the function. | | `environment` | Sets an environment variable for the specific function only. | -After the `gitlab-ci.yml` template has been added and the `serverless.yml` file has been -created, pushing a commit to your project will result in a -CI pipeline being executed which will deploy each function as a Knative service. -Once the deploy stage has finished, additional details for the function will -appear under **Operations > Serverless**. +After the `gitlab-ci.yml` template has been added and the `serverless.yml` file +has been created, pushing a commit to your project will result in a CI pipeline +being executed which will deploy each function as a Knative service. Once the +deploy stage has finished, additional details for the function will appear +under **Operations > Serverless**.  @@ -281,16 +288,17 @@ The sample function can now be triggered from any HTTP client using a simple `PO 1. Using curl (replace the URL on the last line with the URL of your application): - ```bash - curl \ - --header "Content-Type: application/json" \ - --request POST \ - --data '{"GitLab":"FaaS"}' \ - http://functions-echo.functions-1.functions.example.com/ - ``` - 2. Using a web-based tool (ie. postman, restlet, etc) + ```bash + curl \ + --header "Content-Type: application/json" \ + --request POST \ + --data '{"GitLab":"FaaS"}' \ + http://functions-echo.functions-1.functions.example.com/ + ``` + + 1. Using a web-based tool (ie. postman, restlet, etc) -  +  ## Deploying Serverless applications @@ -319,6 +327,8 @@ customize your jobs, or you can inline the entire template by choosing it from **Apply a template** dropdown when editing the `.gitlab-ci.yml` file through the user interface. +A `serverless.yml` file is not required when deploying serverless applications. + ### Deploy the application with Knative With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to @@ -392,259 +402,258 @@ The instructions below relate to installing and running Certbot on a Linux serve [`certbot-auto` wrapper script](https://certbot.eff.org/docs/install.html#certbot-auto). On the command line of your server, run the following commands: - ```sh - wget https://dl.eff.org/certbot-auto - sudo mv certbot-auto /usr/local/bin/certbot-auto - sudo chown root /usr/local/bin/certbot-auto - chmod 0755 /usr/local/bin/certbot-auto - /usr/local/bin/certbot-auto --help - ``` - - To check the integrity of the `certbot-auto` script, run: - - ```sh - wget -N https://dl.eff.org/certbot-auto.asc - gpg2 --keyserver ipv4.pool.sks-keyservers.net --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2 - gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc /usr/local/bin/certbot-auto - ``` - - The output of the last command should look something like: - - ```sh - gpg: Signature made Mon 10 Jun 2019 06:24:40 PM EDT - gpg: using RSA key A2CFB51FA275A7286234E7B24D17C995CD9775F2 - gpg: key 4D17C995CD9775F2 marked as ultimately trusted - gpg: checking the trustdb - gpg: marginals needed: 3 completes needed: 1 trust model: pgp - gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u - gpg: next trustdb check due at 2027-11-22 - gpg: Good signature from "Let's Encrypt Client Team <letsencrypt-client@eff.org>" [ultimate] - ``` + ```sh + wget https://dl.eff.org/certbot-auto + sudo mv certbot-auto /usr/local/bin/certbot-auto + sudo chown root /usr/local/bin/certbot-auto + chmod 0755 /usr/local/bin/certbot-auto + /usr/local/bin/certbot-auto --help + ``` + + To check the integrity of the `certbot-auto` script, run: + + ```sh + wget -N https://dl.eff.org/certbot-auto.asc + gpg2 --keyserver ipv4.pool.sks-keyservers.net --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2 + gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc /usr/local/bin/certbot-auto + ``` + + The output of the last command should look something like: + + ```sh + gpg: Signature made Mon 10 Jun 2019 06:24:40 PM EDT + gpg: using RSA key A2CFB51FA275A7286234E7B24D17C995CD9775F2 + gpg: key 4D17C995CD9775F2 marked as ultimately trusted + gpg: checking the trustdb + gpg: marginals needed: 3 completes needed: 1 trust model: pgp + gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u + gpg: next trustdb check due at 2027-11-22 + gpg: Good signature from "Let's Encrypt Client Team <letsencrypt-client@eff.org>" [ultimate] + ``` 1. Run the following command to use Certbot to request a certificate using DNS challenge during authorization: + ```sh + ./certbot-auto certonly --manual --preferred-challenges dns -d '*.<namespace>.example.com' + ``` + + Where `<namespace>` is the namespace created by GitLab for your serverless project (composed of `<projectname+id>`) and + `example.com` is the domain being used for your project. If you are unsure what the namespace of your project is, navigate + to the **Operations > Serverless** page of your project and inspect + the endpoint provided for your function/app. + +  + + In the above image, the namespace for the project is `node-function-11909507` and the domain is `knative.info`, thus + certificate request line would look like this: + + ```sh + ./certbot-auto certonly --manual --preferred-challenges dns -d '*.node-function-11909507.knative.info' + ``` - ```sh - ./certbot-auto certonly --manual --preferred-challenges dns -d '*.<namespace>.example.com' - ``` - - Where `<namespace>` is the namespace created by GitLab for your serverless project (composed of `<projectname+id>`) and - `example.com` is the domain being used for your project. If you are unsure what the namespace of your project is, navigate - to the **Operations > Serverless** page of your project and inspect - the endpoint provided for your function/app. - -  - - In the above image, the namespace for the project is `node-function-11909507` and the domain is `knative.info`, thus - certificate request line would look like this: - - ```sh - ./certbot-auto certonly --manual --preferred-challenges dns -d '*.node-function-11909507.knative.info' - ``` - - The Certbot tool walks you through the steps of validating that you own each domain that you specify by creating TXT records in those domains. - After this process is complete, the output should look something like this: - - ```sh - IMPORTANT NOTES: - - Congratulations! Your certificate and chain have been saved at: - /etc/letsencrypt/live/namespace.example.com/fullchain.pem - Your key file has been saved at: - /etc/letsencrypt/live/namespace.example/privkey.pem - Your cert will expire on 2019-09-19. To obtain a new or tweaked - version of this certificate in the future, simply run certbot-auto - again. To non-interactively renew *all* of your certificates, run - "certbot-auto renew" - -----BEGIN PRIVATE KEY----- - - Your account credentials have been saved in your Certbot - configuration directory at /etc/letsencrypt. You should make a - secure backup of this folder now. This configuration directory will - also contain certificates and private keys obtained by Certbot so - making regular backups of this folder is ideal. - ``` + The Certbot tool walks you through the steps of validating that you own each domain that you specify by creating TXT records in those domains. + After this process is complete, the output should look something like this: + + ```sh + IMPORTANT NOTES: + - Congratulations! Your certificate and chain have been saved at: + /etc/letsencrypt/live/namespace.example.com/fullchain.pem + Your key file has been saved at: + /etc/letsencrypt/live/namespace.example/privkey.pem + Your cert will expire on 2019-09-19. To obtain a new or tweaked + version of this certificate in the future, simply run certbot-auto + again. To non-interactively renew *all* of your certificates, run + "certbot-auto renew" + -----BEGIN PRIVATE KEY----- + - Your account credentials have been saved in your Certbot + configuration directory at /etc/letsencrypt. You should make a + secure backup of this folder now. This configuration directory will + also contain certificates and private keys obtained by Certbot so + making regular backups of this folder is ideal. + ``` 1. Create certificate and private key files. Using the contents of the files returned by Certbot, we'll create two files in order to create the Kubernetes secret: - Run the following command to see the contents of `fullchain.pem`: - - ```sh - sudo cat /etc/letsencrypt/live/node-function-11909507.knative.info/fullchain.pem - ``` - - Output should look like this: - - ```sh - -----BEGIN CERTIFICATE----- - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b4ag== - -----END CERTIFICATE----- - -----BEGIN CERTIFICATE----- - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - K2fcb195768c39e9a94cec2c2e30Qg== - -----END CERTIFICATE----- - ``` - - Create a file with the name `cert.pem` with the contents of the entire output. - - Once `cert.pem` is created, run the following command to see the contents of `privkey.pem`: - - ```sh - sudo cat /etc/letsencrypt/live/namespace.example/privkey.pem - ``` - - Output should look like this: - - ```sh - -----BEGIN PRIVATE KEY----- - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df - -----BEGIN CERTIFICATE----- - fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 - 4f294d1eaca42b8692017b4262== - -----END PRIVATE KEY----- - ``` - - Create a new file with the name `cert.pk` with the contents of the entire output. + Run the following command to see the contents of `fullchain.pem`: + + ```sh + sudo cat /etc/letsencrypt/live/node-function-11909507.knative.info/fullchain.pem + ``` + + Output should look like this: + + ```sh + -----BEGIN CERTIFICATE----- + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b4ag== + -----END CERTIFICATE----- + -----BEGIN CERTIFICATE----- + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + K2fcb195768c39e9a94cec2c2e30Qg== + -----END CERTIFICATE----- + ``` + + Create a file with the name `cert.pem` with the contents of the entire output. + + Once `cert.pem` is created, run the following command to see the contents of `privkey.pem`: + + ```sh + sudo cat /etc/letsencrypt/live/namespace.example/privkey.pem + ``` + + Output should look like this: + + ```sh + -----BEGIN PRIVATE KEY----- + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df + -----BEGIN CERTIFICATE----- + fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 + 4f294d1eaca42b8692017b4262== + -----END PRIVATE KEY----- + ``` + + Create a new file with the name `cert.pk` with the contents of the entire output. 1. Create a Kubernetes secret to hold your TLS certificate, `cert.pem`, and the private key `cert.pk`: - NOTE: **Note:** - Running `kubectl` commands on your cluster requires setting up access to the cluster first. - For clusters created on GKE, see - [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl). - For other platforms, [install `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/). - - ```sh - kubectl create --namespace istio-system secret tls istio-ingressgateway-certs \ - --key cert.pk \ - --cert cert.pem - ``` + NOTE: **Note:** + Running `kubectl` commands on your cluster requires setting up access to the cluster first. + For clusters created on GKE, see + [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl). + For other platforms, [install `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + + ```sh + kubectl create --namespace istio-system secret tls istio-ingressgateway-certs \ + --key cert.pk \ + --cert cert.pem + ``` - Where `cert.pem` and `cert.pk` are your certificate and private key files. Note that the `istio-ingressgateway-certs` secret name is required. + Where `cert.pem` and `cert.pk` are your certificate and private key files. Note that the `istio-ingressgateway-certs` secret name is required. 1. Configure Knative to use the new secret that you created for HTTPS connections. Run the - following command to open the Knative shared `gateway` in edit mode: - - ```sh - kubectl edit gateway knative-ingress-gateway --namespace knative-serving - ``` - - Update the gateway to include the following tls: section and configuration: - - ```sh - tls: - mode: SIMPLE - privateKey: /etc/istio/ingressgateway-certs/tls.key - serverCertificate: /etc/istio/ingressgateway-certs/tls.crt - ``` - - Example: - - ```sh - apiVersion: networking.istio.io/v1alpha3 - kind: Gateway - metadata: - # ... skipped ... - spec: - selector: - istio: ingressgateway - servers: - - hosts: - - "*" - port: - name: http - number: 80 - protocol: HTTP - - hosts: - - "*" - port: - name: https - number: 443 - protocol: HTTPS - tls: - mode: SIMPLE - privateKey: /etc/istio/ingressgateway-certs/tls.key - serverCertificate: /etc/istio/ingressgateway-certs/tls.crt - ``` - - After your changes are running on your Knative cluster, you can begin using the HTTPS protocol for secure access your deployed Knative services. - In the event a mistake is made during this process and you need to update the cert, you will need to edit the gateway `knative-ingress-gateway` - to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway will use the new certificates. + following command to open the Knative shared `gateway` in edit mode: + + ```sh + kubectl edit gateway knative-ingress-gateway --namespace knative-serving + ``` + + Update the gateway to include the following tls: section and configuration: + + ```sh + tls: + mode: SIMPLE + privateKey: /etc/istio/ingressgateway-certs/tls.key + serverCertificate: /etc/istio/ingressgateway-certs/tls.crt + ``` + + Example: + + ```sh + apiVersion: networking.istio.io/v1alpha3 + kind: Gateway + metadata: + # ... skipped ... + spec: + selector: + istio: ingressgateway + servers: + - hosts: + - "*" + port: + name: http + number: 80 + protocol: HTTP + - hosts: + - "*" + port: + name: https + number: 443 + protocol: HTTPS + tls: + mode: SIMPLE + privateKey: /etc/istio/ingressgateway-certs/tls.key + serverCertificate: /etc/istio/ingressgateway-certs/tls.crt + ``` + + After your changes are running on your Knative cluster, you can begin using the HTTPS protocol for secure access your deployed Knative services. + In the event a mistake is made during this process and you need to update the cert, you will need to edit the gateway `knative-ingress-gateway` + to switch back to `PASSTHROUGH` mode. Once corrections are made, edit the file again so the gateway will use the new certificates. diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index eac7fc6b195..9368c56004d 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -241,10 +241,10 @@ The following installation instructions assume you are running Ubuntu: Enter <kbd>CTRL</kbd>-<kbd>C</kbd> to quit. 1. Install the certificate from `~/.mitmproxy` to your system: - ```sh - sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt - sudo update-ca-certificates - ``` + ```sh + sudo cp ~/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy-ca-cert.crt + sudo update-ca-certificates + ``` If successful, the output should indicate that a certificate was added: diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index cb1faa771bc..0a83f2e894a 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -63,12 +63,12 @@ To display the Deploy Boards for a specific [environment] you should: 1. Have a Kubernetes cluster up and running. - NOTE: **Running on OpenShift:** - If you are using OpenShift, ensure that you're using the `Deployment` resource - instead of `DeploymentConfiguration`, otherwise the Deploy Boards won't render - correctly. For more information, read the - [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) - and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab-ee/issues/4584). + NOTE: **Running on OpenShift:** + If you are using OpenShift, ensure that you're using the `Deployment` resource + instead of `DeploymentConfiguration`, otherwise the Deploy Boards won't render + correctly. For more information, read the + [OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations) + and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab-ee/issues/4584). 1. [Configure GitLab Runner][runners] with the [Docker][docker-exec] or [Kubernetes][kube-exec] executor. @@ -93,7 +93,7 @@ To display the Deploy Boards for a specific [environment] you should: To migrate, please apply the required annotations (see above) and re-deploy your application. -  +  Once all of the above are set up and the pipeline has run at least once, navigate to the environments page under **Operations > Environments**. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index 72594733cd3..164d1dddff0 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -56,9 +56,9 @@ To download a repository using a Deploy Token, you just need to: 1. Take note of your `username` and `token`. 1. `git clone` the project using the Deploy Token: - ```sh - git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git - ``` + ```sh + git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git + ``` Replace `<username>` and `<deploy_token>` with the proper values. diff --git a/doc/user/project/img/autocomplete_characters_example1_v12_0.png b/doc/user/project/img/autocomplete_characters_example1_v12_0.png Binary files differnew file mode 100755 index 00000000000..9c6fa923b80 --- /dev/null +++ b/doc/user/project/img/autocomplete_characters_example1_v12_0.png diff --git a/doc/user/project/img/autocomplete_characters_example2_v12_0.png b/doc/user/project/img/autocomplete_characters_example2_v12_0.png Binary files differnew file mode 100755 index 00000000000..b2e8a782a0b --- /dev/null +++ b/doc/user/project/img/autocomplete_characters_example2_v12_0.png diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index d51a0c0ccca..e4eb1a9a392 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -24,9 +24,8 @@ Import your projects from Bitbucket Server to GitLab with minimal effort. 1. Currently GitLab doesn't allow comments on arbitrary lines of code, so any Bitbucket comments out of bounds will be inserted as comments in the merge request. -1. Bitbucket Server allows multiple levels of threading. GitLab - import will collapse this into one discussion and quote part of the original - comment. +1. Bitbucket Server allows multiple levels of threading. GitLab import + will collapse this into one thread and quote part of the original comment. 1. Declined pull requests have unreachable commits, which prevents the GitLab importer from generating a proper diff. These pull requests will show up as empty changes. diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 334be713aa5..9d7463416d8 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -34,7 +34,7 @@ This approach assumes all users from the self-hosted instance have already been If the users haven't been migrated yet, the user conducting the import will take the place of all references to the missing user(s). -If you need to migrate all data over, you can leverage our [api](../../../api/README.md) to migrate from self-hosted to GitLab.com. +If you need to migrate all data over, you can leverage our [api](../../../api/README.md) to migrate from self-hosted to GitLab.com. The order of assets to migrate from a self-hosted instance to GitLab is the following: 1. [Users](../../../api/users.md) @@ -54,5 +54,5 @@ perhaps from an old server to a new server for example, is to [back up the project](../../../raketasks/backup_restore.md), then restore it on the new server. -In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), +In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), refer to the instructions in [Migrating from self-hosted GitLab to GitLab.com](#migrating-from-self-hosted-gitlab-to-gitlabcom). diff --git a/doc/user/project/index.md b/doc/user/project/index.md index f332281fa82..7307c5b8991 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -52,6 +52,9 @@ When you create a project in GitLab, you'll have access to a large number of templates for issue and merge request description fields for your project - [Slash commands (quick actions)](quick_actions.md): Textual shortcuts for common actions on issues or merge requests +- [Autocomplete characters](autocomplete_characters.md): Autocomplete + references to users, groups, issues, merge requests, and other GitLab + elements. - [Web IDE](web_ide/index.md) **GitLab CI/CD:** @@ -221,7 +224,7 @@ There are numerous [APIs](../../api/README.md) to use with your projects: - [Badges](../../api/project_badges.md) - [Clusters](../../api/project_clusters.md) -- [Discussions](../../api/discussions.md) +- [Threads](../../api/discussions.md) - [General](../../api/projects.md) - [Import/export](../../api/project_import_export.md) - [Issue Board](../../api/boards.md) diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 23f1ce7a15a..7c7263704f9 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -17,6 +17,6 @@ Once you have configured and enabled Custom Issue Tracker Service you'll see a l ## Referencing issues -- Issues are referenced with `ANYTHING-<ID>`, where `ANYTHING` can be any string and `<ID>` is a number used in the target project of the custom integration (example `PROJECT-143`). +- Issues are referenced with `ANYTHING-<ID>`, where `ANYTHING` can be any string and `<ID>` is a number used in the target project of the custom integration (example `PROJECT-143`). - `ANYTHING` is a placeholder to differentiate against GitLab issues, which are referenced with `#<ID>`. You can use a project name or project key to replace it for example. -- So with the example above, `PROJECT-143` would refer to `https://customissuetracker.com/project-name/143`.
\ No newline at end of file +- So with the example above, `PROJECT-143` would refer to `https://customissuetracker.com/project-name/143`. diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 8e062ca627b..91de64be1fa 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -1,4 +1,4 @@ -# GitLab Slack application **[FREE ONLY]** +# GitLab Slack application **(FREE ONLY)** NOTE: **Note:** The GitLab Slack application is only configurable for GitLab.com. It will **not** diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 32991714973..5116cbfe9ac 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -13,46 +13,46 @@ access to your Jira projects. This is covered in the process below. 1. Log in to your Jira instance as an administrator and under **Jira Administration** go to **User Management** to create a new user. -  +  1. The next step is to create a new user (e.g., `gitlab`) who has write access to projects in Jira. Enter the user's name and a _valid_ e-mail address since Jira sends a verification e-mail to set up the password. _**Note:** Jira creates the username automatically by using the e-mail prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create - an HTTP basic authentication password. You can do this by visiting the user - profile, looking up the username, and setting a password._ + an HTTP basic authentication password. You can do this by visiting the user + profile, looking up the username, and setting a password._ -  +  1. Create a `gitlab-developers` group. (We will give this group write access to Jira projects in a later step). Go to the **Groups** tab on the left, and select **Add group**. -  +  - Give it a name and click **Add group**. + Give it a name and click **Add group**. 1. Add the `gitlab` user to the `gitlab-developers` group by clicking **Edit members**. The `gitlab-developers` group should be listed in the leftmost box as a selected group. Under **Add members to selected group(s)**, enter `gitlab`. -  - +  + Click **Add selected users** and `gitlab` should appear in the **Group member(s)** box. This membership is saved automatically. - -  + +  1. To give the newly-created group 'write' access, you need to create a **Permission Scheme**. To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**. Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**. - + 1. Once your permission scheme is created, you'll be taken back to the permissions scheme list. - Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, + Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers` from the dropdown. -  +  The Jira configuration is complete. Write down the new Jira username and its password as they will be needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index f63a2c2758b..67274e8d924 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -48,7 +48,7 @@ Click on the service links to see further configuration instructions and details | Pipelines emails | Email the pipeline status to a list of recipients | | [Slack Notifications](slack.md) | Send GitLab events (e.g. issue created) to Slack as notifications | | [Slack slash commands](slack_slash_commands.md) **(CORE ONLY)** | Use slash commands in Slack to control GitLab | -| [GitLab Slack application](gitlab_slack_application.md) **[FREE ONLY]** | Use Slack's official application | +| [GitLab Slack application](gitlab_slack_application.md) **(FREE ONLY)** | Use Slack's official application | | PivotalTracker | Project Management Software (Source Commits Endpoint) | | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 0d35d557c98..72f12972596 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -121,70 +121,93 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.htm To specify a variable in a query, enclose it in curly braces with a leading percent. For example: `%{ci_environment_slug}`. -### Defining Dashboards for Prometheus Metrics per Project +### Defining custom dashboards per project -All projects include a GitLab-defined system dashboard, which includes a few key metrics. Optionally, additional dashboards can also be defined by including configuration files in the project repository under `.gitlab/dashboards`. Configuration files nested under subdirectories will not be available in the UI. Each file should define the layout of the dashboard and the prometheus queries used to populate data. Dashboards can be selected from the dropdown in the UI. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/59974) in GitLab 12.1. -#### Relationship to Custom Metrics +By default, all projects include a GitLab-defined Prometheus dashboard, which +includes a few key metrics, but you can also define your own custom dashboards. -[Custom Metrics](#adding-additional-metrics-premium) are defined through the UI and, at this point, are unique from metrics defined in dashboard configuration files. Custom Metrics will appear on the system dashboard, as well as support alerting, whereas metrics defined in configuration files do not yet support alerts. +NOTE: **Note:** +The custom metrics as defined below do not support alerts, unlike +[additional metrics](#adding-additional-metrics-premium). -#### Dashboard Configuration +Dashboards have several components: -Dashboards have several components. A dashboard has many panel groups, which are comprised of panels, which support one or more metrics. The dashboard should be saved with the `.yml` extension. +- Panel groups, which comprise panels. +- Panels, which support one or more metrics. -Sample YML Configuration -``` -dashboard: 'Dashboard Title' -priority: 2 -panel_groups: - - group: 'Group Title' - panels: - - type: area-chart - title: "Chart Title" - y_label: "Y-Axis" - metrics: - - id: metric_of_ages - query_range: 'http_requests_total' - label: "Metric of Ages" - unit: "count" -``` +To configure a custom dashboard: + +1. Create a YAML file with the `.yml` extension under your repository's root + directory inside `.gitlab/dashboards/`. For example, create + `.gitlab/dashboards/prom_alerts.yml` with the following contents: + + ```yaml + dashboard: 'Dashboard Title' + panel_groups: + - group: 'Group Title' + panels: + - type: area-chart + title: "Chart Title" + y_label: "Y-Axis" + metrics: + - id: metric_of_ages + query_range: 'http_requests_total' + label: "Metric of Ages" + unit: "count" + ``` + + The above sample dashboard would display a single area chart. Each file should + define the layout of the dashboard and the Prometheus queries used to populate + data. + +1. Save the file, commit, and push to your repository. +1. Navigate to your project's **Operations > Metrics** and choose the custom + dashboard from the dropdown. -The above sample dashboard would display a single area chart. The following sections outline the details of expected properties. +NOTE: **Note:** +Configuration files nested under subdirectories of `.gitlab/dashboards` are not +supported and will not be available in the UI. -##### Dashboard Properties -| Property | Type | Required? | Meaning | +The following tables outline the details of expected properties. + +**Dashboard properties:** + +| Property | Type | Required | Description | | ------ | ------ | ------ | ------ | -| `dashboard` | string | required | Heading for the dashboard. Only one dashboard should be defined per file. | -| `priority` | number | optional, default to definition order | Order to appear in dashboard dropdown, higher priority should be higher in the dropdown. Numbers do not need to be consecutive. | -| `panel_groups` | array | required | The panel groups which should be on the dashboard. | +| `dashboard` | string | yes | Heading for the dashboard. Only one dashboard should be defined per file. | +| `panel_groups` | array | yes | The panel groups which should be on the dashboard. | + +**Panel group (`panel_groups`) properties:** -##### Panel Group Properties -| Property | Type | Required? | Meaning | +| Property | Type | Required | Description | | ------ | ------ | ------ | ------ | | `group` | string | required | Heading for the panel group. | -| `priority` | number | optional, defaults to order in file | Order to appear on the dashboard, higher priority will be higher on the page. Numbers do not need to be consecutive. | +| `priority` | number | optional, defaults to order in file | Order to appear on the dashboard. Higher number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | | `panels` | array | required | The panels which should be in the panel group. | -##### Panel Properties -| Property | Type | Required? | Meaning | +**Panel (`panels`) properties:** + +| Property | Type | Required | Description | | ------ | ------ | ------ | ------- | -| `type` | enum | optional, defaults to `area-chart` | Specifies the chart type to use. Only `area-chart` is currently supported. | -| `title` | string | required | Heading for the panel. | -| `y_label` | string | optional, but highly encouraged | Y-Axis label for the panel. | -| `weight` | number | optional, defaults to order in file | Order to appear within the grouping, higher priority will be higher on the page. Numbers do not need to be consecutive. | -| `metrics` | array | required | The metrics which should be displayed in the panel. | - -##### Metric Properties -| Property | Type | Required? | Meaning | +| `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use. Only `area-chart` is currently supported. | +| `title` | string | yes | Heading for the panel. | +| `y_label` | string | no, but highly encouraged | Y-Axis label for the panel. | +| `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | +| `metrics` | array | yes | The metrics which should be displayed in the panel. | + +**Metrics (`metrics`) properties:** + +| Property | Type | Required | Description | | ------ | ------ | ------ | ------ | -| `id` | string | optional | Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for [alerting](#setting-up-alerts-for-prometheus-metrics-ultimate) (support not yet enabled, see [relevant issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/60319)). | -| `unit` | string | required | Defines the unit of the query's return data. | -| `label` | string | optional, but highly encouraged | Defines the legend-label for the query. Should be unique within the panel's metrics. | -| `query` | string | required unless `query_range` is defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. | -| `query_range` | string | required unless `query` is defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. | +| `id` | string | no | Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for [alerting](#setting-up-alerts-for-prometheus-metrics-ultimate) (support not yet enabled, see [relevant issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/60319)). | +| `unit` | string | yes | Defines the unit of the query's return data. | +| `label` | string | no, but highly encouraged | Defines the legend-label for the query. Should be unique within the panel's metrics. | +| `query` | string | yes if `query_range` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. | +| `query_range` | string | yes if `query` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) will be utilized. | -### Setting up alerts for Prometheus metrics **[ULTIMATE]** +### Setting up alerts for Prometheus metrics **(ULTIMATE)** #### Managed Prometheus instances diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index 0d300d3c418..9e17edf7d36 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -13,15 +13,15 @@ integration services must be enabled. - Average Memory Usage (MB): - ``` - avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024 - ``` + ``` + avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024 + ``` - Average CPU Utilization (%): - ``` - avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name)) - ``` + ``` + avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name)) + ``` ## Configuring Prometheus to monitor for Kubernetes metrics @@ -48,12 +48,12 @@ These metrics expect the [Deployment](https://kubernetes.io/docs/concepts/worklo - Average Memory Usage (MB) - ``` - avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024 - ``` + ``` + avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024 + ``` - Average CPU Utilization (%) - ``` - avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name)) - ``` + ``` + avg(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (job)) without (job) / count(sum(rate(container_cpu_usage_seconds_total{container_name!="POD",pod_name=~"^%{ci_environment_slug}-canary-(.*)",namespace="%{kube_namespace}"}[15m])) by (pod_name)) + ``` diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index 93dc2a2e4ca..ec9eb7b62bb 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -47,7 +47,7 @@ display in both issues. The same is valid when mentioning issues in [merge reque ## From Merge Requests Mentioning issues in merge request comments works exactly the same way as -they do for [related issues](#from-related-issues). +they do for [related issues](#from-related-issues). When you mention an issue in a merge request description, it will simply [link the issue and merge request together](#from-related-issues). Additionally, diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 0b7a7af5927..d3f53c09fb3 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -48,7 +48,6 @@ Exported issues are always sorted by `Issue ID`. Data will be encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row will be the headers, which are listed in the following table along with a description of the values: - | Column | Description | |---------|-------------| | Issue ID | Issue `iid` | @@ -71,7 +70,6 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot | Time Estimate | [Time estimate](../../../workflow/time_tracking.md#estimates) in seconds | | Time Spent | [Time spent](../../../workflow/time_tracking.md#time-spent) in seconds | - ## Limitations As the issues will be sent as an email attachment, there is a limit on how much data can be exported. Currently this limit is 20MB to ensure successful delivery across a range of email providers. If this limit is reached we suggest narrowing the search before export, perhaps by exporting open and closed issues separately. diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 9c4d0de46d3..7b031f83cb1 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -116,13 +116,13 @@ issue boards or the issue list. #### 11. Lock issue -You can [lock the discussions](../../discussions/index.md#lock-discussions) in the issue, +You can [lock the threads](../../discussions/index.md#lock-discussions) in the issue, to prevent further comments from being added. #### 12. Participants -All the users involved in that issue. Either they participated in the [discussion](../../discussions/index.md), -or were mentioned in the description or discussions. +All the users involved in that issue. Either they participated in the [thread](../../discussions/index.md), +or were mentioned in the description or threads. #### 13. Notifications @@ -187,8 +187,8 @@ You can also click the `+` to add more related issues. #### 19. Related Merge Requests -Merge requests that were mentioned in that issue's description or in the issue discussion -thread are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here. +Merge requests that were mentioned in that issue's description or in the issue thread +are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here. Also, if the current issue was mentioned as related in another merge request, that merge request will be listed here. @@ -200,17 +200,17 @@ dropdown list of available [GitLab Flavored Markdown Emoji](../../markdown.md#em TIP: **Tip:** Posting "+1" as a comment in a thread spams all subscribed participants of that issue, -clutters the discussion threads, and is not recommended. Awarding an emoji is a way +clutters the threads, and is not recommended. Awarding an emoji is a way to let them know your reaction without spamming them. #### 21. Show all activity You can filter what is displayed in the issue history by clicking on **Show all activity** -and selecting either **Show comments only**, which only shows discussions and hides -updates to the issue, or **Show history only**, which hides discussions and only shows updates. +and selecting either **Show comments only**, which only shows threads and hides +updates to the issue, or **Show history only**, which hides threads and only shows updates. - You can mention a user or a group present in your GitLab instance with - `@username` or `@groupname` and they will be notified via To-Do items + `@username` or `@groupname` and they will be notified via To-Do items and email, unless they have [disabled all notifications](#13-notifications) in their profile settings. - Mentions for yourself (the current logged in user), will be highlighted @@ -242,15 +242,15 @@ filtered, as shown above. Collaborate in the issue by posting comments in its thread. This text field also fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). -#### 25. Submit Comment, start a discussion, or comment and close +#### 25. Submit Comment, start a thread, or comment and close Once you write a comment, you can: - Click **Comment** and your comment will be published. -- Choose **Start discussion** from the dropdown list and start a new [discussion thread](../../discussions/index.md#threaded-discussions) +- Choose **Start thread** from the dropdown list and start a new [thread](../../discussions/index.md#threaded-discussions) within that issue's main thread to discuss specific points. This invites other participants - to reply directly to your discussion, keeping related comments grouped together. + to reply directly to your thread, keeping related comments grouped together. - + You can also close the issue from here, so you don't need to scroll to the top of the issue page. diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index 2a490e3fd7f..e343fd45488 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -10,8 +10,6 @@ or import a new user to your project. To view, edit, add, and remove project's members, go to your project's **Settings > Members**. ---- - ## Add a user Right next to **People**, start typing the name or username of the user you @@ -19,22 +17,16 @@ want to add.  ---- - Select the user and the [permission level](../../permissions.md) that you'd like to give the user. Note that you can select more than one user.  ---- - Once done, hit **Add users to project** and they will be immediately added to your project with the permissions you gave them above.  ---- - From there on, you can either remove an existing user or change their access level to the project. @@ -47,8 +39,6 @@ In the dropdown menu, you can see only the projects you are Maintainer on.  ---- - Select the one you want and hit **Import project members**. A flash message notifying you that the import was successful will appear, and the new members are now in the project's members list. Notice that the permissions that they @@ -56,8 +46,6 @@ had on the project you imported from are retained.  ---- - ## Invite people using their e-mail address If a user you want to give access to doesn't have an account on your GitLab @@ -66,23 +54,17 @@ user search field.  ---- - As you can imagine, you can mix inviting multiple people and adding existing GitLab users to the project.  ---- - Once done, hit **Add users to project** and watch that there is a new member with the e-mail address we used above. From there on, you can resend the invitation, change their access level, or even delete them.  ---- - Once the user accepts the invitation, they will be prompted to create a new GitLab account using the same e-mail address the invitation was sent to. @@ -97,15 +79,11 @@ side of your screen.  ---- - Project owners & maintainers will be notified of your request and will be able to approve or decline it on the members page.  ---- - If you change your mind before your request is approved, just click the **Withdraw Access Request** button. diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index c299a8ecb96..f593046fa8b 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -18,7 +18,7 @@ It is as simple as the name implies: a _request_ to _merge_ one branch into anot With GitLab merge requests, you can: - Compare the changes between two [branches](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell#_git_branching) -- [Review and discuss](../../discussions/index.md#discussions) the proposed modifications inline +- [Review and discuss](../../discussions/index.md#threads) the proposed modifications inline - Live preview the changes when [Review Apps](../../../ci/review_apps/index.md) is configured for your project - Build, test, and deploy your code in a per-branch basis with built-in [GitLab CI/CD](../../../ci/README.md) - Prevent the merge request from being merged before it's ready with [WIP MRs](#work-in-progress-merge-requests) @@ -155,13 +155,13 @@ and remember to merge the request manually. [Learn more about merging when pipeline succeeds.](merge_when_pipeline_succeeds.md) -## Resolve discussion comments in merge requests reviews +## Resolve threads in merge requests reviews Keep track of the progress during a code review with resolving comments. Resolving comments prevents you from forgetting to address feedback and lets -you hide discussions that are no longer relevant. +you hide threads that are no longer relevant. -[Read more about resolving discussion comments in merge requests reviews.](../../discussions/index.md) +[Read more about resolving threads in merge requests reviews.](../../discussions/index.md) ## Commenting on any file line in merge requests @@ -192,7 +192,7 @@ commit when merging, to allow for a neater commit history. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/18008) in GitLab 11.6. As a reviewer, you can add suggestions to change the content in -merge request discussions, and users with appropriate [permission](../../permissions.md) +merge request threads, and users with appropriate [permission](../../permissions.md) can easily apply them to the codebase directly from the UI. Read through the documentation on [Suggest changes](../../discussions/index.md#suggest-changes) to learn more. diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 0f392676316..220795d6f15 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -162,7 +162,7 @@ the merge request is unblocked and can be merged. Note, that meeting the required number of approvals is a necessary, but not sufficient condition for unblocking a merge request from being merged. There are other conditions that may block it, such as merge conflicts, -[pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved) +[pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved) or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). ## Code Owners approvals **(PREMIUM)** diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 0dd60d84c42..50a4e514d49 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -36,7 +36,7 @@ changes to be reviewed. ## Only allow merge requests to be merged if the pipeline succeeds You can prevent merge requests from being merged if their pipeline did not succeed -or if there are discussions to be resolved. +or if there are threads to be resolved. Navigate to your project's settings page and expand the **Merge requests** section. In the **Merge checks** subsection, select the **Pipelines must succeed** check diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 142178ba241..ea59644fce6 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -5,7 +5,7 @@ type: reference, concepts # "Work In Progress" merge requests If a merge request is not yet ready to be merged, perhaps due to continued development -or open discussions, you can prevent it from being accepted before it's ready by flagging +or open threads, you can prevent it from being accepted before it's ready by flagging it as a **Work In Progress**. This will disable the "Merge" button, preventing it from being merged, and it will stay disabled until the "WIP" flag has been removed. @@ -19,7 +19,7 @@ There are several ways to flag a merge request as a Work In Progress: **Start the title with WIP:**, under the title box, when editing the merge request's description will have the same effect. - Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-and-merge-requests) - in a discussion comment in the merge request. This is a toggle, and can be repeated + in a comment in the merge request. This is a toggle, and can be repeated to change the status back. Note that any other text in the comment will be discarded. - Add "wip" or "WIP" to the start of a commit message targeting the merge request's source branch. This is not a toggle, and doing it again in another commit will have @@ -34,7 +34,7 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the **Remove the WIP: prefix from the title**, under the title box, when editing the merge request's description, will have the same effect. - Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-and-merge-requests) - in a discussion comment in the merge request. This is a toggle, and can be repeated + in a comment in the merge request. This is a toggle, and can be repeated to change the status back. Note that any other text in the comment will be discarded. - Click on the **Resolve WIP status** button near the bottom of the merge request description, next to the "Merge" button (see [image above](#work-in-progress-merge-requests)). diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index b0745b1e2c5..142462e1879 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -14,12 +14,12 @@ the start and end of your Agile sprint. Set the milestone title to the name of your Agile sprint, such as `November 2018 sprint`. Add an issue to your Agile sprint by associating -the milestone to the issue. +the milestone to the issue. ## Milestones as releases Milestones can be used as releases. -Set the milestone due date to represent the release date of your release. +Set the milestone due date to represent the release date of your release. (And leave the milestone start date blank.) Set the milestone title to the version of your release, such as `Version 9.4`. diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index d35a8568394..494dd539da7 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -6,8 +6,6 @@ GitLab 8.12 has a completely redesigned [job permissions] system. You can find all discussion and all our concerns when choosing the current approach in issue [#18994](https://gitlab.com/gitlab-org/gitlab-ce/issues/18994). ---- - Jobs permissions should be tightly integrated with the permissions of a user who is triggering a job. @@ -108,8 +106,6 @@ and to checkout project sources. It could also be used with the GitLab Container Registry for that project, allowing pulling and pushing Docker images from within the CI job. ---- - GitLab would create a special checkout URL like: ``` diff --git a/doc/user/project/packages/maven_repository.md b/doc/user/project/packages/maven_repository.md index 27c052fb2bc..c61402afb2c 100644 --- a/doc/user/project/packages/maven_repository.md +++ b/doc/user/project/packages/maven_repository.md @@ -198,7 +198,7 @@ domain name. NOTE: **Note:** For retrieving artifacts, you can use either the [URL encoded](../../../api/README.md#namespaced-path-encoding) path of the group -(e.g., `group%2Fsubgroup`) or the group's ID (e.g., `12`). +(e.g., `group%2Fsubgroup`) or the group's ID (e.g., `12`). ### Instance level Maven endpoint @@ -279,59 +279,59 @@ shows how to create a new package each time the `master` branch is updated: Add the server section with the same id you defined in your `pom.xml` file. For example, in our case it's `gitlab-maven`: - ```xml - <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"> - <servers> - <server> - <id>gitlab-maven</id> - <configuration> - <httpHeaders> - <property> - <name>Job-Token</name> - <value>${env.CI_JOB_TOKEN}</value> - </property> - </httpHeaders> - </configuration> - </server> - </servers> - </settings> - ``` + ```xml + <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"> + <servers> + <server> + <id>gitlab-maven</id> + <configuration> + <httpHeaders> + <property> + <name>Job-Token</name> + <value>${env.CI_JOB_TOKEN}</value> + </property> + </httpHeaders> + </configuration> + </server> + </servers> + </settings> + ``` 1. Make sure your `pom.xml` file includes the following: - ```xml - <repositories> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> - </repository> - </repositories> - <distributionManagement> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> - </repository> - <snapshotRepository> - <id>gitlab-maven</id> - <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> - </snapshotRepository> - </distributionManagement> - ``` - - TIP: **Tip:** - You can either let Maven utilize the CI environment variables or hardcode your project's ID. + ```xml + <repositories> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </repository> + </repositories> + <distributionManagement> + <repository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </repository> + <snapshotRepository> + <id>gitlab-maven</id> + <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> + </snapshotRepository> + </distributionManagement> + ``` + + TIP: **Tip:** + You can either let Maven utilize the CI environment variables or hardcode your project's ID. 1. Add a `deploy` job to your `.gitlab-ci.yml` file: - ```yaml - deploy: - image: maven:3.3.9-jdk-8 - script: - - 'mvn deploy -s ci_settings.xml' - only: - - master - ``` + ```yaml + deploy: + image: maven:3.3.9-jdk-8 + script: + - 'mvn deploy -s ci_settings.xml' + only: + - master + ``` 1. Push those files to your repository. diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md new file mode 100644 index 00000000000..3b80370d4a9 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -0,0 +1,95 @@ +--- +type: concepts +--- + +# DNS records overview + +_Read this document for a brief overview of DNS records in the scope +of GitLab Pages, for beginners in web development._ + +A Domain Name System (DNS) web service routes visitors to websites +by translating domain names (such as `www.example.com`) into the +numeric IP addresses (such as `192.0.2.1`) that computers use to +connect to each other. + +A DNS record is created to point a (sub)domain to a certain location, +which can be an IP address or another domain. In case you want to use +GitLab Pages with your own (sub)domain, you need to access your domain's +registrar control panel to add a DNS record pointing it back to your +GitLab Pages site. + +Note that **how to** add DNS records depends on which server your domain +is hosted on. Every control panel has its own place to do it. If you are +not an admin of your domain, and don't have access to your registrar, +you'll need to ask for the technical support of your hosting service +to do it for you. + +To help you out, we've gathered some instructions on how to do that +for the most popular hosting services: + +- [Amazon](http://docs.aws.amazon.com/gettingstarted/latest/swh/getting-started-configure-route53.html) +- [Bluehost](https://my.bluehost.com/cgi/help/559) +- [CloudFlare](https://support.cloudflare.com/hc/en-us/articles/200169096-How-do-I-add-A-records-) +- [cPanel](https://documentation.cpanel.net/display/ALD/Edit+DNS+Zone) +- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-) +- [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238) +- [Hostgator](http://support.hostgator.com/articles/changing-dns-records) +- [Inmotion hosting](https://my.bluehost.com/cgi/help/559) +- [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain) +- [Microsoft](https://msdn.microsoft.com/en-us/library/bb727018.aspx) + +If your hosting service is not listed above, you can just try to +search the web for `how to add dns record on <my hosting service>`. + +## `A` record + +A DNS A record maps a host to an IPv4 IP address. +It points a root domain as `example.com` to the host's IP address as +`192.192.192.192`. + +Example: + +- `example.com` => `A` => `192.192.192.192` + +## CNAME record + +CNAME records define an alias for canonical name for your server (one defined +by an A record). It points a subdomain to another domain. + +Example: + +- `www` => `CNAME` => `example.com` + +This way, visitors visiting `www.example.com` will be redirected to +`example.com`. + +## MX record + +MX records are used to define the mail exchanges that are used for the domain. +This helps email messages arrive at your mail server correctly. + +Example: + +- `MX` => `mail.example.com` + +Then you can register emails for `users@mail.example.com`. + +## TXT record + +A `TXT` record can associate arbitrary text with a host or other name. A common +use is for site verification. + +Example: + +- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"` + +This way, you can verify the ownership for that domain name. + +## All combined + +You can have one DNS record or more than one combined: + +- `example.com` => `A` => `192.192.192.192` +- `www` => `CNAME` => `example.com` +- `MX` => `mail.example.com` +- `example.com`=> TXT => `"google-site-verification=6P08Ow5E-8Q0m6vQ7FMAqAYIDprkVV8fUf_7hZ4Qvc8"`
\ No newline at end of file diff --git a/doc/user/project/pages/img/add_certificate_to_pages.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png Binary files differindex d92a981dc60..d92a981dc60 100644 --- a/doc/user/project/pages/img/add_certificate_to_pages.png +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png diff --git a/doc/user/project/pages/img/dns_add_new_a_record_example_updated_2018.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_add_new_a_record_example_updated_2018.png Binary files differindex 0150329d4b2..0150329d4b2 100644 --- a/doc/user/project/pages/img/dns_add_new_a_record_example_updated_2018.png +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_add_new_a_record_example_updated_2018.png diff --git a/doc/user/project/pages/img/dns_cname_record_example.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_cname_record_example.png Binary files differindex 43d1a838544..43d1a838544 100644 --- a/doc/user/project/pages/img/dns_cname_record_example.png +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/dns_cname_record_example.png diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png Binary files differnew file mode 100644 index 00000000000..b4dcdc9bb60 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/get_domain_verification_code_v12_0.png diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png Binary files differnew file mode 100644 index 00000000000..2e825e84d92 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/lets_encrypt_integration_v12_1.png diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png Binary files differnew file mode 100644 index 00000000000..db8f25bc6c3 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/retry_domain_verification_v12_0.png diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md new file mode 100644 index 00000000000..54ecc42d2b9 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -0,0 +1,277 @@ +--- +last_updated: 2019-07-04 +type: reference, howto +redirect_from: 'https://docs.gitlab.com/ee/user/project/pages/getting_started_part_three.html' +--- + +# Custom domains and SSL/TLS Certificates + +Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages. + +To use one or more custom domain names with your Pages site, you can: + +- Add a [custom **root domain** or a **subdomain**](#set-up-pages-with-a-custom-domain). +- Add [SSL/TLS certification](#adding-an-ssltls-certificate-to-pages). + +## Set up Pages with a custom domain + +To set up Pages with a custom domain name, read the requirements +and steps below. + +### Requirements + +- A GitLab Pages website up and running, served under the default Pages domain + (`*.gitlab.io`, for GitLab.com). +- A custom domain name `example.com` or subdomain `subdomain.example.com`. +- Access to your domain's server control panel to set up DNS records: + - A DNS A or CNAME record poiting your domain to GitLab Pages server. + - A DNS TXT record to verify your domain's ownership. + +### Steps + +Follow the steps below to add your custom domain to Pages. See also +this document for an [overview on DNS records](dns_concepts.md). + +#### 1. Add a custom domain to Pages + +Navigate to your project's **Setting > Pages** and click **+ New domain** +to add your custom domain to GitLab Pages. You can choose whether to: + +- Add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). +- Leave it blank (it can be added later). + +Click **Create New Domain**. + + + +#### 2. Get the verification code + +Once you have added a new domain to Pages, the verification code will be prompted to you. Copy the values from GitLab and paste them in your domain's control panel as a TXT record on the next step. + + + +#### 3. Set up DNS records for Pages + +Read this document for an [overview of DNS records for Pages](dns_concepts.md). +If you're familiar with the subject, follow the instructions below +according to the type of domain you want to use with your Pages site: + +- [For root domains](#for-root-domains), `example.com`. +- [For subdomains](#for-subdomains), `subdomain.example.com`. +- [For both](#for-both-root-and-subdomains). + +##### For root domains + +Root domains (`example.com`) require: + +- A [DNS A record](dns_concepts.md#a-record) pointing your domain to the Pages server. +- A [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership. + +| From | DNS Record | To | +| ---- | ---------- | -- | +| example.com | A | 35.185.44.232 | +| _gitlab-pages-verification-code.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | + +For projects on GitLab.com, this IP is `35.185.44.232`. +For projects living in other GitLab instances (CE or EE), please contact +your sysadmin asking for this information (which IP address is Pages +server running on your instance). + + + +CAUTION: **Caution:** +Note that if you use your root domain for your GitLab Pages website +**only**, and if your domain registrar supports this feature, you can +add a DNS apex `CNAME` record instead of an `A` record. The main +advantage of doing so is that when GitLab Pages IP on GitLab.com +changes for whatever reason, you don't need to update your `A` record. +There may be a few exceptions, but **this method is not recommended** +as it most likely won't work if you set an [`MX` record](dns_concepts.md#mx-record) for your root domain. + +##### For subdomains + +Subdomains (`subdomain.example.com`) require: + +- A DNS [CNAME record](dns_concepts.md#cname-record) record pointing your subdomain to the Pages server. +- A DNS [TXT record](dns_concepts.md#txt-record) to verify your domain's ownership. + +| From | DNS Record | To | +| ---- | ---------- | -- | +| subdomain.example.com | CNAME | namespace.gitlab.io | +| _gitlab-pages-verification-code.subdomain.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | + +Note that, whether it's a user or a project website, the `CNAME` +should point to your Pages domain (`namespace.gitlab.io`), +without any `/project-name`. + + + +##### For both root and subdomains + +There are a few cases where you need point both subdomain and root +domain to the same website, for instance, `example.com` and `www.example.com`. + +They require: + +- A DNS A record for the domain. +- A DNS CNAME record for the subdomain. +- A DNS TXT record for each. + +| From | DNS Record | To | +| ---- | ---------- | -- | +| example.com | A | 35.185.44.232 | +| _gitlab-pages-verification-code.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | +|---+---| +| www.example.com | CNAME | namespace.gitlab.io | +| _gitlab-pages-verification-code.www.example.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | + +If you're using CloudFlare, check +[Redirecting `www.domain.com` to `domain.com` with Cloudflare](#redirecting-wwwdomaincom-to-domaincom-with-cloudflare). + +> **Notes**: +> +> - **Do not** use a CNAME record if you want to point your + `domain.com` to your GitLab Pages site. Use an `A` record instead. +> - **Do not** add any special chars after the default Pages + domain. E.g., don't point `subdomain.domain.com` to + or `namespace.gitlab.io/`. Some domain hosting providers may request a trailling dot (`namespace.gitlab.io.`), though. +> - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017. +> - GitLab Pages IP on GitLab.com [has changed](https://about.gitlab.com/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains) + from `52.167.214.135` to `35.185.44.232` in 2018. + +#### 4. Verify the domain's ownership + +Once you have added all the DNS records: + +1. Go back at your project's **Settings > Pages**. +1. Locate your domain name and click **Details**. +1. Click the **Retry verification** button to activate your new domain. + + + +As soon as your domain becomes active, your website will be available +through your domain name. + +CAUTION: **Caution:** +Considering GitLab instances with domain verification enabled, +if the domain cannot be verified for 7 days, it will be removed +from the GitLab project. + +> **Notes:** +> +> - Domain verification is **required for GitLab.com users**; + for GitLab self-managed instances, your GitLab administrator has the option + to [disabled custom domain verification](../../../../administration/pages/index.md#custom-domain-verification). +> - [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes), + although it's usually a matter of minutes to complete. Until it does, verification + will fail and attempts to visit your domain will respond with a 404. +> - Once your domain has been verified, leave the verification record + in place: your domain will be periodically reverified, and may be + disabled if the record is removed. + +### Adding more domain aliases + +You can add more than one alias (custom domains and subdomains) to the same project. +An alias can be understood as having many doors leading to the same room. + +All the aliases you've set to your site will be listed on **Setting > Pages**. +From that page, you can view, add, and remove them. + +### Redirecting `www.domain.com` to `domain.com` with Cloudflare + +If you use Cloudflare, you can redirect `www` to `domain.com` +without adding both `www.domain.com` and `domain.com` to GitLab. + +To do so, you can use Cloudflare's page rules associated to a +CNAME record to redirect `www.domain.com` to `domain.com`. You +can use the following setup: + +1. In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232`. +1. In GitLab, add the domain to GitLab Pages and get the verification code. +1. In Cloudflare, create a DNS `TXT` record to verify your domain. +1. In GitLab, verify your domain. +1. In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com`. +1. In Cloudflare, add a Page Rule pointing `www.domain,com` to `domain.com`: + - Navigate to your domain's dashboard and click **Page Rules** + on the top nav. + - Click **Create Page Rule**. + - Enter the domain `www.domain.com` and click **+ Add a Setting**. + - From the dropdown menu, choose **Forwarding URL**, then select the + status code **301 - Permanent Redirect**. + - Enter the destination URL `https://domain.com`. + +## Adding an SSL/TLS certificate to Pages + +Read this document for an [overview on SSL/TLS certification](ssl_tls_concepts.md). + +To secure your custom domain with GitLab Pages you can opt by: + +- Using the [Let's Encrypt integration with GitLab Pages](lets_encrypt_integration.md), + which automatically obtains and renews SSL certificates + for your Pages domains. +- Manually adding SSL/TLS certificates to GitLab Pages websites + by following the steps below. + +### Requirements + +- A GitLab Pages website up and running accessible via a custom domain. +- **A PEM certificate**: it is the certificate generated by the CA, + which needs to be added to the field **Certificate (PEM)**. +- **An [intermediate certificate](https://en.wikipedia.org/wiki/Intermediate_certificate_authority)**: (aka "root certificate"), it is + the part of the encryption keychain that identifies the CA. + Usually it's combined with the PEM certificate, but there are + some cases in which you need to add them manually. + [CloudFlare certs](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) + are one of these cases. +- **A private key**, it's an encrypted key which validates + your PEM against your domain. + +### Steps + +- To add the certificate at the time you add a new domain, go to your + project's **Settings > Pages > New Domain**, add the domain name and the certificate. +- To add the certificate to a domain previously added, go to your + project's **Settings > Pages**, locate your domain name, click **Details** and **Edit** to add the certificate. + + + +1. Add the PEM certificate to its corresponding field. +1. If your certificate is missing its intermediate, copy + and paste the root certificate (usually available from your CA website) + and paste it in the [same field as your PEM certificate](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/), + just jumping a line between them. +1. Copy your private key and paste it in the last field. + +NOTE: **Note:** +**Do not** open certificates or encryption keys in +regular text editors. Always use code editors (such as +Sublime Text, Atom, Dreamweaver, Brackets, etc). + +## Force HTTPS for GitLab Pages websites + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28857) in GitLab 10.7. + +To make your website's visitors even more secure, you can choose to +force HTTPS for GitLab Pages. By doing so, all attempts to visit your +website via HTTP will be automatically redirected to HTTPS via 301. + +It works with both GitLab's default domain and with your custom +domain (as long as you've set a valid certificate for it). + +To enable this setting: + +1. Navigate to your project's **Settings > Pages**. +1. Tick the checkbox **Force HTTPS (requires valid certificates)**. + + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md new file mode 100644 index 00000000000..7675a5dd9d4 --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md @@ -0,0 +1,68 @@ +--- +type: reference +description: "Automatic Let's Encrypt SSL certificates for GitLab Pages." +--- + +# GitLab Pages integration with Let's Encrypt + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28996) in GitLab 12.1. + +The GitLab Pages integration with Let's Encrypt (LE) allows you +to use LE certificates for your Pages website with custom domains +without the hassle of having to issue and update them yourself; +GitLab does it for you, out-of-the-box. + +[Let's Encrypt](https://letsencrypt.org) is a free, automated, and +open source Certificate Authority. + +## Requirements + +Before you can enable automatic provisioning of a SSL certificate for your domain, make sure you have: + +- Created a [project](../getting_started_part_two.md) in GitLab + containing your website's source code. +- Acquired a domain (`example.com`) and added a [DNS entry](index.md) + pointing it to your Pages website. +- [Added your domain to your Pages project](index.md#1-add-a-custom-domain-to-pages) + and verified your ownership. +- Have your website up and running, accessible through your custom domain. + +NOTE: **Note:** +GitLab's Let's Encrypt integration is enabled and available on GitLab.com. +For **self-managed** GitLab instances, make sure your administrator has +[enabled it](../../../../administration/pages/index.md#lets-encrypt-integration). + +## Enabling Let's Encrypt integration for your custom domain + +Once you've met the requirements, to enable Let's Encrypt integration: + +1. Navigate to your project's **Settings > Pages**. +1. Find your domain and click **Details**. +1. Click **Edit** in the top-right corner. +1. Enable Let's Encrypt integration by switching **Automatic certificate management using Let's Encrypt**: + +  + +1. Click **Save changes**. + +Once enabled, GitLab will obtain a LE certificate and add it to the +associated Pages domain. It will be also renewed automatically by GitLab. + +> **Notes:** +> +> - Issuing the certificate and updating Pages configuration +> **can take up to an hour**. +> - If you already have SSL certificate in domain settings it +> will continue to work until it will be replaced by Let's Encrypt's certificate. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md new file mode 100644 index 00000000000..2470e78819f --- /dev/null +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/ssl_tls_concepts.md @@ -0,0 +1,75 @@ +--- +type: concepts +--- + +# SSL/TLS Certificates + +_Read this document for a brief overview of SSL/TLS certificates in +the scope of GitLab Pages, for beginners in web development._ + +Every GitLab Pages project on GitLab.com will be available under +HTTPS for the default Pages domain (`*.gitlab.io`). Once you set +up your Pages project with your custom (sub)domain, if you want +it secured by HTTPS, you will have to issue a certificate for that +(sub)domain and install it on your project. + +NOTE: **Note:** +Certificates are NOT required to add to your custom +(sub)domain on your GitLab Pages project, though they are +highly recommendable. + +Let's start with an introduction to the importance of HTTPS. + +## Why should I care about HTTPS? + +This might be your first question. If our sites are hosted by GitLab Pages, +they are static, hence we are not dealing with server-side scripts +nor credit card transactions, then why do we need secure connections? + +Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" +security measure, necessary just for big companies, like banks and shoppings sites +with financial transactions. +Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): + +> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ + +Therefore, the reason why certificates are so important is that they encrypt +the connection between the **client** (you, me, your visitors) +and the **server** (where you site lives), through a keychain of +authentications and validations. + +How about taking Josh's advice and protecting our sites too? We will be +well supported, and we'll contribute to a safer internet. + +## Organizations supporting HTTPS + +There is a huge movement in favor of securing all the web. W3C fully +[supports the cause](https://w3ctag.github.io/web-https/) and explains very well +the reasons for that. Richard Barnes, a writer for Mozilla Security Blog, +suggested that [Firefox would deprecate HTTP](https://blog.mozilla.org/security/2015/04/30/deprecating-non-secure-http/), +and would no longer accept unsecured connections. Recently, Mozilla published a +[communication](https://blog.mozilla.org/security/2016/03/29/march-2016-ca-communication/) +reiterating the importance of HTTPS. + +## Issuing Certificates + +GitLab Pages accepts certificates provided in the [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) format, issued by +[Certificate Authorities (CAs)](https://en.wikipedia.org/wiki/Certificate_authority) or as +[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://securingtomorrow.mcafee.com/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) +for public websites for security reasons and to ensure that browsers trust your site's certificate. + +There are various kinds of certificates, each one +with a certain security level. A static personal website will +not require the same security level as an online banking web app, +for instance. + +There are some certificate authorities that +offer free certificates, aiming to make the internet more secure +to everyone. The most popular is [Let's Encrypt](https://letsencrypt.org/), +which issues certificates trusted by most of browsers, it's open +source, and free to use. See our tutorial on [how to secure your GitLab Pages website with Let's Encrypt](../lets_encrypt_for_gitlab_pages.md). + +Similarly popular are [certificates issued by CloudFlare](https://www.cloudflare.com/ssl/), +which also offers a [free CDN service](https://blog.cloudflare.com/cloudflares-free-cdn-and-you/). +Their certs are valid up to 15 years. See the tutorial on +[how to add a CloudFlare Certificate to your GitLab Pages website](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/). diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index bc9a11504cd..9bc9fe97fd3 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -1,314 +1 @@ ---- -last_updated: 2019-06-25 -type: concepts, reference, howto ---- - -# GitLab Pages custom domains and SSL/TLS Certificates - -Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages. - -These steps assume you've already [set your site up](getting_started_part_two.md) and it's served under the default Pages domain `namespace.gitlab.io`, or `namespace.gitlab.io/project-name`. - -## Adding your custom domain to GitLab Pages - -To use one or more custom domain with your Pages site, there are two things -you should consider first, which we'll cover in this guide: - -1. Either if you're adding a **root domain** or a **subdomain**, for which - you'll need to set up [DNS records](#dns-records) -1. Whether you want to add an [SSL/TLS certificate](#ssltls-certificates) or not - -To finish the association, you need to [add your domain to your project's Pages settings](#add-your-custom-domain-to-gitlab-pages-settings). - -Let's start from the beginning with [DNS records](#dns-records). -If you already know how they work and want to skip the introduction to DNS, -you may be interested in skipping it until the [TL;DR](#tldr) section below. - -### DNS Records - -A Domain Name System (DNS) web service routes visitors to websites -by translating domain names (such as `www.example.com`) into the -numeric IP addresses (such as `192.0.2.1`) that computers use to -connect to each other. - -A DNS record is created to point a (sub)domain to a certain location, -which can be an IP address or another domain. In case you want to use -GitLab Pages with your own (sub)domain, you need to access your domain's -registrar control panel to add a DNS record pointing it back to your -GitLab Pages site. - -Note that **how to** add DNS records depends on which server your domain -is hosted on. Every control panel has its own place to do it. If you are -not an admin of your domain, and don't have access to your registrar, -you'll need to ask for the technical support of your hosting service -to do it for you. - -To help you out, we've gathered some instructions on how to do that -for the most popular hosting services: - -- [Amazon](http://docs.aws.amazon.com/gettingstarted/latest/swh/getting-started-configure-route53.html) -- [Bluehost](https://my.bluehost.com/cgi/help/559) -- [CloudFlare](https://support.cloudflare.com/hc/en-us/articles/200169096-How-do-I-add-A-records-) -- [cPanel](https://documentation.cpanel.net/display/ALD/Edit+DNS+Zone) -- [DreamHost](https://help.dreamhost.com/hc/en-us/articles/215414867-How-do-I-add-custom-DNS-records-) -- [Go Daddy](https://www.godaddy.com/help/add-an-a-record-19238) -- [Hostgator](http://support.hostgator.com/articles/changing-dns-records) -- [Inmotion hosting](https://my.bluehost.com/cgi/help/559) -- [Media Temple](https://mediatemple.net/community/products/dv/204403794/how-can-i-change-the-dns-records-for-my-domain) -- [Microsoft](https://msdn.microsoft.com/en-us/library/bb727018.aspx) - -If your hosting service is not listed above, you can just try to -search the web for `how to add dns record on <my hosting service>`. - -#### DNS A record - -In case you want to point a root domain (`example.com`) to your -GitLab Pages site, deployed to `namespace.gitlab.io`, you need to -log into your domain's admin control panel and add a DNS `A` record -pointing your domain to Pages' server IP address. For projects on -GitLab.com, this IP is `35.185.44.232`. For projects living in -other GitLab instances (CE or EE), please contact your sysadmin -asking for this information (which IP address is Pages server -running on your instance). - -**Practical Example:** - - - -CAUTION: **Caution:** -Note that if you use your root domain for your GitLab Pages website -**only**, and if your domain registrar supports this feature, you can -add a DNS apex `CNAME` record instead of an `A` record. The main -advantage of doing so is that when GitLab Pages IP on GitLab.com -changes for whatever reason, you don't need to update your `A` record. -There may be a few exceptions, but **this method is not recommended** -as it most likely won't work if you set an `MX` record for your root domain. - -#### DNS CNAME record - -In case you want to point a subdomain (`hello-world.example.com`) -to your GitLab Pages site initially deployed to `namespace.gitlab.io`, -you need to log into your domain's admin control panel and add a DNS -`CNAME` record pointing your subdomain to your website URL -(`namespace.gitlab.io`) address. - -Note that, whether it's a user or a project website, the `CNAME` -should point to your Pages domain (`namespace.gitlab.io`), -without any `/project-name`. - -**Practical Example:** - - - -#### DNS TXT record - -Unless your GitLab administrator has [disabled custom domain verification](../../../administration/pages/index.md#custom-domain-verification), -you'll have to prove that you own the domain by creating a `TXT` record -containing a verification code. The code will be displayed after you -[add your custom domain to GitLab Pages settings](#add-your-custom-domain-to-gitlab-pages-settings). - -If using a [DNS A record](#dns-a-record), you can place the TXT record directly -under the domain. If using a [DNS CNAME record](#dns-cname-record), the two record types won't -co-exist, so you need to place the TXT record in a special subdomain of its own. - -If the domain cannot be verified for 7 days, it will be removed from the GitLab project. - -#### TL;DR - -For root domains (`domain.com`), set a DNS `A` record and verify your -domain's ownership with a TXT record: - -| From | DNS Record | To | -| ---- | ---------- | -- | -| domain.com | A | 35.185.44.232 | -| domain.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | - -For subdomains (`subdomain.domain.com`), set a DNS `CNAME` record and -verify your domain's ownership with a TXT record: - -| From | DNS Record | To | -| ---- | ---------- | -- | -| subdomain.domain.com | CNAME | namespace.gitlab.io | -| _gitlab-pages-verification-code.subdomain.domain.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | - -> **Notes**: -> -> - **Do not** use a CNAME record if you want to point your - `domain.com` to your GitLab Pages site. Use an `A` record instead. -> - **Do not** add any special chars after the default Pages - domain. E.g., **do not** point your `subdomain.domain.com` to - `namespace.gitlab.io.` or `namespace.gitlab.io/`. -> - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017. -> - GitLab Pages IP on GitLab.com [has been changed](https://about.gitlab.com/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains) - from `52.167.214.135` to `35.185.44.232` in 2018. - -### Add your custom domain to GitLab Pages settings - -Once you've set the DNS record, you'll need navigate to your project's -**Setting > Pages** and click **+ New domain** to add your custom domain to -GitLab Pages. You can choose whether to add an [SSL/TLS certificate](#ssltls-certificates) -to make your website accessible under HTTPS or leave it blank. If you don't add a certificate, -your site will be accessible only via HTTP: - - - -Once you have added a new domain, you will need to **verify your ownership** -(unless the GitLab administrator has disabled this feature). A verification code -will be shown to you; add it as a [DNS TXT record](#dns-txt-record), then press -the "Verify ownership" button to activate your new domain: - - - -Once your domain has been verified, leave the verification record in place - -your domain will be periodically reverified, and may be disabled if the record -is removed. - -You can add more than one alias (custom domains and subdomains) to the same project. -An alias can be understood as having many doors leading to the same room. - -All the aliases you've set to your site will be listed on **Setting > Pages**. -From that page, you can view, add, and remove them. - -Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes), -although it's usually a matter of minutes to complete. Until it does, verification -will fail and attempts to visit your domain will respond with a 404. - -### Redirecting `www.domain.com` to `domain.com` with Cloudflare - -If you use Cloudflare, you can redirect `www` to `domain.com` without the need of adding both -`www.domain.com` and `domain.com` to GitLab. This happens due to a [Cloudflare feature that creates -a 301 redirect as a "page rule"](https://gitlab.com/gitlab-org/gitlab-ce/issues/48848#note_87314849) for redirecting `www.domain.com` to `domain.com`. In this case, -you can use the following setup: - -- In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232` -- In GitLab, add the domain to GitLab Pages -- In Cloudflare, create a DNS `TXT` record to verify your domain -- In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com` - -## SSL/TLS Certificates - -Every GitLab Pages project on GitLab.com will be available under -HTTPS for the default Pages domain (`*.gitlab.io`). Once you set -up your Pages project with your custom (sub)domain, if you want -it secured by HTTPS, you will have to issue a certificate for that -(sub)domain and install it on your project. - ->**Note:** -Certificates are NOT required to add to your custom -(sub)domain on your GitLab Pages project, though they are -highly recommendable. - -Let's start with an introduction to the importance of HTTPS. -Alternatively, jump ahead to [adding certificates to your project](#adding-certificates-to-pages). - -### Why should I care about HTTPS? - -This might be your first question. If our sites are hosted by GitLab Pages, -they are static, hence we are not dealing with server-side scripts -nor credit card transactions, then why do we need secure connections? - -Back in the 1990s, where HTTPS came out, [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security#SSL_1.0.2C_2.0_and_3.0) was considered a "special" -security measure, necessary just for big companies, like banks and shoppings sites -with financial transactions. -Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): - -> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ - -Therefore, the reason why certificates are so important is that they encrypt -the connection between the **client** (you, me, your visitors) -and the **server** (where you site lives), through a keychain of -authentications and validations. - -How about taking Josh's advice and protecting our sites too? We will be -well supported, and we'll contribute to a safer internet. - -### Organizations supporting HTTPS - -There is a huge movement in favor of securing all the web. W3C fully -[supports the cause](https://w3ctag.github.io/web-https/) and explains very well -the reasons for that. Richard Barnes, a writer for Mozilla Security Blog, -suggested that [Firefox would deprecate HTTP](https://blog.mozilla.org/security/2015/04/30/deprecating-non-secure-http/), -and would no longer accept unsecured connections. Recently, Mozilla published a -[communication](https://blog.mozilla.org/security/2016/03/29/march-2016-ca-communication/) -reiterating the importance of HTTPS. - -## Issuing Certificates - -GitLab Pages accepts certificates provided in the [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) format, issued by -[Certificate Authorities (CAs)](https://en.wikipedia.org/wiki/Certificate_authority) or as -[self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate). Note that [self-signed certificates are typically not used](https://securingtomorrow.mcafee.com/other-blogs/mcafee-labs/self-signed-certificates-secure-so-why-ban/) -for public websites for security reasons and to ensure that browsers trust your site's certificate. - -There are various kinds of certificates, each one -with a certain security level. A static personal website will -not require the same security level as an online banking web app, -for instance. - -There are some certificate authorities that -offer free certificates, aiming to make the internet more secure -to everyone. The most popular is [Let's Encrypt](https://letsencrypt.org/), -which issues certificates trusted by most of browsers, it's open -source, and free to use. See our tutorial on [how to secure your GitLab Pages website with Let's Encrypt](lets_encrypt_for_gitlab_pages.md). - -Similarly popular are [certificates issued by CloudFlare](https://www.cloudflare.com/ssl/), -which also offers a [free CDN service](https://blog.cloudflare.com/cloudflares-free-cdn-and-you/). -Their certs are valid up to 15 years. See the tutorial on -[how to add a CloudFlare Certificate to your GitLab Pages website](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/). - -### Adding certificates to Pages - -Regardless the CA you choose, the steps to add your certificate to -your Pages project are the same. - -#### Requirements - -1. A PEM certificate -1. An intermediate certificate -1. A private key - - - -These fields are found under your **Project**'s **Settings** > **Pages** > **New Domain**. - -#### Certificate types - -- A PEM certificate is the certificate generated by the CA, - which needs to be added to the field **Certificate (PEM)**. -- An [intermediate certificate](https://en.wikipedia.org/wiki/Intermediate_certificate_authority) (aka "root certificate") is - the part of the encryption keychain that identifies the CA. - Usually it's combined with the PEM certificate, but there are - some cases in which you need to add them manually. - [CloudFlare certs](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) - are one of these cases. -- A private key is an encrypted key which validates - your PEM against your domain. - -#### Add the certificate to your project - -Once you've met the requirements: - -- Your PEM certificate needs to be added to the first field. -- If your certificate is missing its intermediate, copy - and paste the root certificate (usually available from your CA website) - and paste it in the [same field as your PEM certificate](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/), - just jumping a line between them. -- Copy your private key and paste it in the last field. - -NOTE: **Note:** -**Do not** open certificates or encryption keys in -regular text editors. Always use code editors (such as -Sublime Text, Atom, Dreamweaver, Brackets, etc). - -## Force HTTPS for GitLab Pages websites - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28857) in GitLab 10.7. - -To make your website's visitors even more secure, you can choose to -force HTTPS for GitLab Pages. By doing so, all attempts to visit your -website via HTTP will be automatically redirected to HTTPS via 301. - -It works with both GitLab's default domain and with your custom -domain (as long as you've set a valid certificate for it). - -To enable this setting, navigate to your project's **Settings > Pages** -and tick the checkbox **Force HTTPS (requires valid certificates)**. +This document was moved to [another location](custom_domains_ssl_tls_certification/index.md). diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index fe92d19567d..743c360f075 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -22,7 +22,7 @@ Optional Features: 1. **Optional**: an SSL/TLS certificate so your custom domain is accessible under HTTPS. -The optional settings, custom domain, DNS records, and SSL/TLS certificates, are described in [Part 3](getting_started_part_three.md)). +The optional settings, custom domain, DNS records, and SSL/TLS certificates, are described in [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md)). ## Project @@ -169,4 +169,4 @@ baseurl: "" ## Custom Domains GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. -See [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md) for more information. +See [GitLab Pages custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) for more information. diff --git a/doc/user/project/pages/img/pages_project_templates_11-8.png b/doc/user/project/pages/img/pages_project_templates_v11_8.png Binary files differindex a645d28260b..a645d28260b 100644 --- a/doc/user/project/pages/img/pages_project_templates_11-8.png +++ b/doc/user/project/pages/img/pages_project_templates_v11_8.png diff --git a/doc/user/project/pages/img/verify_your_domain.png b/doc/user/project/pages/img/verify_your_domain.png Binary files differdeleted file mode 100644 index d870f9e6505..00000000000 --- a/doc/user/project/pages/img/verify_your_domain.png +++ /dev/null diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 64b1e259292..25944b029d7 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -101,7 +101,7 @@ To get started with GitLab Pages, you can either: 1. Select **Create from Template**. 1. Choose one of the templates starting with **Pages**: -  +  1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your @@ -115,8 +115,8 @@ will run a new pipeline to publish your changes to the server. _Advanced options:_ -- [Use a custom domain](getting_started_part_three.md#adding-your-custom-domain-to-gitlab-pages) -- Apply [SSL/TLS certification](getting_started_part_three.md#ssltls-certificates) to your custom domain +- [Use a custom domain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain) +- Apply [SSL/TLS certification](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages) to your custom domain ## Availability @@ -142,9 +142,9 @@ To learn more about configuration options for GitLab Pages, read the following: | [GitLab CI/CD for GitLab Pages](getting_started_part_four.md) | Understand how to create your own `.gitlab-ci.yml` for your site. | | [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI's configuration options, Access Control, custom 404 pages, limitations, FAQ. | |---+---| -| [Custom domains and SSL/TLS Certificates](getting_started_part_three.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. | +| [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. | +| [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates automatically obtained and renewed by GitLab. | | [CloudFlare certificates](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) | Secure your Pages site with CloudFlare certificates. | -| [Let's Encrypt certificates](lets_encrypt_for_gitlab_pages.md) | Secure your Pages site with Let's Encrypt certificates. | |---+---| | [Static vs dynamic websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | A conceptual overview on static versus dynamic sites. | | [Modern static site generators](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) | A conceptual overview on SSGs. | diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index 91a660c0f7a..1338c7e58f5 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,10 +1,15 @@ --- -description: "How to secure GitLab Pages websites with Let's Encrypt." +description: "How to secure GitLab Pages websites with Let's Encrypt (manual process, deprecated)." type: howto -last_updated: 2019-06-04 +last_updated: 2019-07-15 --- -# Let's Encrypt for GitLab Pages +# Let's Encrypt for GitLab Pages (manual process, deprecated) + +CAUTION: **Warning:** +This method is still valid but was **deprecated** in favor of the +[Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) +introduced in GitLab 12.1. If you have a GitLab Pages website served under your own domain, you might want to secure it with a SSL/TSL certificate. @@ -18,9 +23,9 @@ To follow along with this tutorial, we assume you already have: - Created a [project](getting_started_part_two.md) in GitLab which contains your website's source code. -- Acquired a domain (`example.com`) and added a [DNS entry](getting_started_part_three.md#dns-records) +- Acquired a domain (`example.com`) and added a [DNS entry](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain) pointing it to your Pages website. -- [Added your domain to your Pages project](getting_started_part_three.md#add-your-custom-domain-to-gitlab-pages-settings) +- [Added your domain to your Pages project](custom_domains_ssl_tls_certification/index.md#steps) and verified your ownership. - Cloned your project into your computer. - Your website up and running, served under HTTP protocol at `http://example.com`. @@ -36,111 +41,111 @@ operating systems the steps might be slightly different. Follow the [CertBot instructions](https://certbot.eff.org/) according to your OS. 1. On your computer, open a terminal and navigate to your repository's - root directory: + root directory: - ```bash - cd path/to/dir - ``` + ```bash + cd path/to/dir + ``` 1. Install CertBot (the tool Let's Encrypt uses to issue certificates): - ```bash - brew install certbot - ``` + ```bash + brew install certbot + ``` 1. Request a certificate for your domain (`example.com`) and - provide an email account (`your@email.com`) to receive notifications: + provide an email account (`your@email.com`) to receive notifications: - ```bash - sudo certbot certonly -a manual -d example.com --email your@email.com - ``` + ```bash + sudo certbot certonly -a manual -d example.com --email your@email.com + ``` - Alternatively, you can register without adding an e-mail account, - but you won't be notified about the certificate expiration's date: + Alternatively, you can register without adding an e-mail account, + but you won't be notified about the certificate expiration's date: - ```bash - sudo certbot certonly -a manual -d example.com --register-unsafely-without-email - ``` + ```bash + sudo certbot certonly -a manual -d example.com --register-unsafely-without-email + ``` - TIP: **Tip:** - Read through CertBot's documentation on their - [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). + TIP: **Tip:** + Read through CertBot's documentation on their + [command line options](https://certbot.eff.org/docs/using.html#certbot-command-line-options). 1. You'll be prompted with a message to agree with their terms. - Press `A` to agree and `Y` to let they log your IP. + Press `A` to agree and `Y` to let they log your IP. - CertBot will then prompt you with the following message: + CertBot will then prompt you with the following message: - ```bash - Create a file containing just this data: + ```bash + Create a file containing just this data: - Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb + Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb - And make it available on your web server at this URL: + And make it available on your web server at this URL: - http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP + http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP - Press Enter to Continue - ``` + Press Enter to Continue + ``` 1. **Do not press Enter yet.** Let's Encrypt will need to verify your - domain ownership before issuing the certificate. To do so, create 3 - consecutive directories under your website's root: - `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/` - and add to the last folder an `index.html` file containing the content - referred on the previous prompt message: - - ```bash - Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb - ``` - - Note that this file needs to be accessed under - `http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP` - to allow Let's Encrypt to verify the ownership of your domain, - therefore, it needs to be part of the website content under the - repo's [`public`](index.md#how-it-works) folder. + domain ownership before issuing the certificate. To do so, create 3 + consecutive directories under your website's root: + `/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP/` + and add to the last folder an `index.html` file containing the content + referred on the previous prompt message: + + ```bash + Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP.HUGNKk82jlsmOOfphlt8Jy69iuglsn095nxOMH9j3Yb + ``` + + Note that this file needs to be accessed under + `http://example.com/.well-known/acme-challenge/Rxnv6WKo95hsuLVX3osmT6LgmzsJKSaK9htlPToohOP` + to allow Let's Encrypt to verify the ownership of your domain, + therefore, it needs to be part of the website content under the + repo's [`public`](index.md#how-it-works) folder. 1. Add, commit, and push the file into your repo in GitLab. Once the pipeline - passes, press **Enter** on your terminal to continue issuing your - certificate. CertBot will then prompt you with the following message: - - ```bash - Waiting for verification... - Cleaning up challenges - - IMPORTANT NOTES: - - Congratulations! Your certificate and chain have been saved at: - /etc/letsencrypt/live/example.com/fullchain.pem - Your key file has been saved at: - /etc/letsencrypt/live/example.com/privkey.pem - Your cert will expire on 2019-03-12. To obtain a new or tweaked - version of this certificate in the future, simply run certbot - again. To non-interactively renew *all* of your certificates, run - "certbot renew" - - If you like Certbot, please consider supporting our work by: - - Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate - Donating to EFF: https://eff.org/donate-le - ``` + passes, press **Enter** on your terminal to continue issuing your + certificate. CertBot will then prompt you with the following message: + + ```bash + Waiting for verification... + Cleaning up challenges + + IMPORTANT NOTES: + - Congratulations! Your certificate and chain have been saved at: + /etc/letsencrypt/live/example.com/fullchain.pem + Your key file has been saved at: + /etc/letsencrypt/live/example.com/privkey.pem + Your cert will expire on 2019-03-12. To obtain a new or tweaked + version of this certificate in the future, simply run certbot + again. To non-interactively renew *all* of your certificates, run + "certbot renew" + - If you like Certbot, please consider supporting our work by: + + Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate + Donating to EFF: https://eff.org/donate-le + ``` ## Add your certificate to GitLab Pages Now that your certificate has been issued, let's add it to your Pages site: 1. Back at GitLab, navigate to your project's **Settings > Pages**, - find your domain and click **Details** and **Edit** to add your certificate. + find your domain and click **Details** and **Edit** to add your certificate. 1. From your terminal, copy and paste the certificate into the first field - **Certificate (PEM)**: + **Certificate (PEM)**: - ```bash - sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy - ``` + ```bash + sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy + ``` 1. Copy and paste the private key into the second field **Key (PEM)**: - ```bash - sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy - ``` + ```bash + sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy + ``` 1. Click **Save changes** to apply them to your website. 1. Wait a few minutes for the configuration changes to take effect. diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index 1966b136e9d..2411744c874 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -67,8 +67,6 @@ artifacts in case you changed your mind and want to keep them.  ---- - The archive browser shows the name and the actual file size of each file in the archive. If your artifacts contained directories, then you are also able to browse inside them. @@ -80,8 +78,6 @@ one HTML file that you can view directly online when  ---- - ## Downloading artifacts If you need to download the whole archive, there are buttons in various places @@ -90,22 +86,22 @@ inside GitLab that make that possible. 1. While on the pipelines page, you can see the download icon for each job's artifacts archive in the right corner: -  +  1. While on the **Jobs** page, you can see the download icon for each job's artifacts archive in the right corner: -  +  1. While inside a specific job, you are presented with a download button along with the one that browses the archive: -  +  1. And finally, when browsing an archive you can see the download button at the top right corner: -  +  ## Downloading the latest artifacts diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index 24e15a37a40..df82daa3da3 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -25,10 +25,10 @@ in `.gitlab-ci.yml`. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/28919) in GitLab 12.0. NOTE: **Note**: -As of GitLab 12.0, newly created projects will automatically have a default +As of GitLab 12.0, newly created projects will automatically have a default `git depth` value of `50`. -It is possible to limit the number of changes that GitLab CI/CD will fetch when cloning +It is possible to limit the number of changes that GitLab CI/CD will fetch when cloning a repository. Setting a limit to `git depth` can speed up Pipelines execution. Maximum allowed value is `1000`. @@ -89,6 +89,22 @@ in the jobs table. A few examples of known coverage tools for a variety of languages can be found in the pipelines settings page. +### Removing color codes + +Some test coverage tools output with ANSI color codes that won't be +parsed correctly by the regular expression and will cause coverage +parsing to fail. + +If your coverage tool doesn't provide an option to disable color +codes in the output, you can pipe the output of the coverage tool through a +small one line script that will strip the color codes off. + +For example: + +```bash +lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g' +``` + ## Visibility of pipelines Access to pipelines and job details (including output of logs and artifacts) diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 8b8aa51b6dd..948ac91a886 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -34,19 +34,19 @@ discussions, and descriptions: | `/remove_milestone` | Remove milestone | ✓ | ✓ | | `/label ~label1 ~label2` | Add label(s). Label names can also start without ~ but mixed syntax is not supported. | ✓ | ✓ | | `/unlabel ~label1 ~label2` | Remove all or specific label(s)| ✓ | ✓ | -| `/relabel ~label1 ~label2` | Replace label | ✓ | ✓ | -| <code>/copy_metadata <#issue | !merge_request></code> | Copy labels and milestone from other issue or merge request in the project | ✓ | ✓ | -| <code>/estimate <1w 3d 2h 14m></code> | Set time estimate | ✓ | ✓ | +| `/relabel ~label1 ~label2` | Replace existing label(s) with those specified | ✓ | ✓ | +| `/copy_metadata <#issue | !merge_request>` | Copy labels and milestone from other issue or merge request in the project | ✓ | ✓ | +| `/estimate <1w 3d 2h 14m>` | Set time estimate | ✓ | ✓ | | `/remove_estimate` | Remove time estimate | ✓ | ✓ | -| <code>/spend <time(1h 30m | -1h 5m)> <date(YYYY-MM-DD)></code> | Add or subtract spent time; optionally, specify the date that time was spent on | ✓ | ✓ | +| `/spend <time(1h 30m | -1h 5m)> <date(YYYY-MM-DD)>` | Add or subtract spent time; optionally, specify the date that time was spent on | ✓ | ✓ | | `/remove_time_spent` | Remove time spent | ✓ | ✓ | -| `/lock` | Lock the discussion | ✓ | ✓ | -| `/unlock` | Unlock the discussion | ✓ | ✓ | -| <code>/due <in 2 days | this Friday | December 31st></code>| Set due date | ✓ | | +| `/lock` | Lock the thread | ✓ | ✓ | +| `/unlock` | Unlock the thread | ✓ | ✓ | +| `/due <in 2 days | this Friday | December 31st>`| Set due date | ✓ | | | `/remove_due_date` | Remove due date | ✓ | | -| <code>/weight <0 | 1 | 2 | ...></code> | Set weight **(STARTER)** | ✓ | | +| `/weight <0 | 1 | 2 | ...>` | Set weight **(STARTER)** | ✓ | | | `/clear_weight` | Clears weight **(STARTER)** | ✓ | | -| <code>/epic <&epic | group&epic | Epic URL></code> | Add to epic **(ULTIMATE)** | ✓ | | +| `/epic <&epic | group&epic | Epic URL>` | Add to epic **(ULTIMATE)** | ✓ | | | `/remove_epic` | Removes from epic **(ULTIMATE)** | ✓ | | | `/promote` | Promote issue to epic **(ULTIMATE)** | ✓ | | | `/confidential` | Make confidential | ✓ | | @@ -85,8 +85,8 @@ The following quick actions are applicable for epics threads and description: | `/award :emoji:` | Toggle emoji award | | `/label ~label1 ~label2` | Add label(s) | | `/unlabel ~label1 ~label2` | Remove all or specific label(s) | -| `/relabel ~label1 ~label2` | Replace label | -| <code>/child_epic <&epic | group&epic | Epic URL></code> | Adds child epic to epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) | -| <code>/remove_child_epic <&epic | group&epic | Epic URL></code> | Removes child epic from epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) | -| <code>/parent_epic <&epic | group&epic | Epic URL></code> | Sets parent epic to epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) | -| <code>/remove_parent_epic | Removes parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) | +| `/relabel ~label1 ~label2` | Replace existing label(s) with those specified | +| `/child_epic <&epic | group&epic | Epic URL>` | Adds child epic to epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) | +| `/remove_child_epic <&epic | group&epic | Epic URL>` | Removes child epic from epic ([introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-ee/issues/7330)) | +| `/parent_epic <&epic | group&epic | Epic URL>` | Sets parent epic to epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) | +| `/remove_parent_epic` | Removes parent epic from epic ([introduced in GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/issues/10556)) | diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index cf0a986887e..3b0a045ef9c 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -45,94 +45,95 @@ started: 1. Generate the private/public key pair with the following command, which will spawn a series of questions: - ```sh - gpg --full-gen-key - ``` + ```sh + gpg --full-gen-key + ``` - NOTE: **Note:** - In some cases like Gpg4win on Windows and other macOS versions, the command - here may be `gpg --gen-key`. + NOTE: **Note:** + In some cases like Gpg4win on Windows and other macOS versions, the command + here may be `gpg --gen-key`. 1. The first question is which algorithm can be used. Select the kind you want or press <kbd>Enter</kbd> to choose the default (RSA and RSA): - ``` - Please select what kind of key you want: - (1) RSA and RSA (default) - (2) DSA and Elgamal - (3) DSA (sign only) - (4) RSA (sign only) - Your selection? 1 - ``` + ``` + Please select what kind of key you want: + (1) RSA and RSA (default) + (2) DSA and Elgamal + (3) DSA (sign only) + (4) RSA (sign only) + Your selection? 1 + ``` 1. The next question is key length. We recommend to choose the highest value which is `4096`: - ``` - RSA keys may be between 1024 and 4096 bits long. - What keysize do you want? (2048) 4096 - Requested keysize is 4096 bits - ``` + ``` + RSA keys may be between 1024 and 4096 bits long. + What keysize do you want? (2048) 4096 + Requested keysize is 4096 bits + ``` + 1. Next, you need to specify the validity period of your key. This is something subjective, and you can use the default value which is to never expire: - ``` - Please specify how long the key should be valid. - 0 = key does not expire - <n> = key expires in n days - <n>w = key expires in n weeks - <n>m = key expires in n months - <n>y = key expires in n years - Key is valid for? (0) 0 - Key does not expire at all - ``` + ``` + Please specify how long the key should be valid. + 0 = key does not expire + <n> = key expires in n days + <n>w = key expires in n weeks + <n>m = key expires in n months + <n>y = key expires in n years + Key is valid for? (0) 0 + Key does not expire at all + ``` 1. Confirm that the answers you gave were correct by typing `y`: - ``` - Is this correct? (y/N) y - ``` + ``` + Is this correct? (y/N) y + ``` 1. Enter you real name, the email address to be associated with this key (should match a verified email address you use in GitLab) and an optional comment (press <kbd>Enter</kbd> to skip): - ``` - GnuPG needs to construct a user ID to identify your key. + ``` + GnuPG needs to construct a user ID to identify your key. - Real name: Mr. Robot - Email address: <your_email> - Comment: - You selected this USER-ID: - "Mr. Robot <your_email>" + Real name: Mr. Robot + Email address: <your_email> + Comment: + You selected this USER-ID: + "Mr. Robot <your_email>" - Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O - ``` + Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O + ``` 1. Pick a strong password when asked and type it twice to confirm. 1. Use the following command to list the private GPG key you just created: - ``` - gpg --list-secret-keys --keyid-format LONG <your_email> - ``` + ``` + gpg --list-secret-keys --keyid-format LONG <your_email> + ``` - Replace `<your_email>` with the email address you entered above. + Replace `<your_email>` with the email address you entered above. 1. Copy the GPG key ID that starts with `sec`. In the following example, that's `30F2B65B9246B6CA`: - ``` - sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] - D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA - uid [ultimate] Mr. Robot <your_email> - ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] - ``` + ``` + sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] + D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA + uid [ultimate] Mr. Robot <your_email> + ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] + ``` 1. Export the public key of that ID (replace your key ID from the previous step): - ``` - gpg --armor --export 30F2B65B9246B6CA - ``` + ``` + gpg --armor --export 30F2B65B9246B6CA + ``` 1. Finally, copy the public key and [add it in your profile settings](#adding-a-gpg-key-to-your-account) @@ -146,17 +147,17 @@ You can add a GPG key in your profile's settings: 1. On the upper right corner, click on your avatar and go to your **Settings**. -  +  1. Navigate to the **GPG keys** tab and paste your _public_ key in the 'Key' box. -  +  1. Finally, click on **Add key** to add it to GitLab. You will be able to see its fingerprint, the corresponding email address and creation date. -  +  ## Associating your GPG key with Git @@ -166,29 +167,29 @@ key to use. 1. Use the following command to list the private GPG key you just created: - ```sh - gpg --list-secret-keys --keyid-format LONG <your_email> - ``` + ```sh + gpg --list-secret-keys --keyid-format LONG <your_email> + ``` - Replace `<your_email>` with the email address you entered above. + Replace `<your_email>` with the email address you entered above. 1. Copy the GPG key ID that starts with `sec`. In the following example, that's `30F2B65B9246B6CA`: - ``` - sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] - D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA - uid [ultimate] Mr. Robot <your_email> - ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] - ``` + ``` + sec rsa4096/30F2B65B9246B6CA 2017-08-18 [SC] + D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA + uid [ultimate] Mr. Robot <your_email> + ssb rsa4096/B7ABC0813E4028C0 2017-08-18 [E] + ``` 1. Tell Git to use that key to sign the commits: - ```sh - git config --global user.signingkey 30F2B65B9246B6CA - ``` + ```sh + git config --global user.signingkey 30F2B65B9246B6CA + ``` - Replace `30F2B65B9246B6CA` with your GPG key ID. + Replace `30F2B65B9246B6CA` with your GPG key ID. 1. (Optional) If Git is using `gpg` and you get errors like `secret key not available` or `gpg: signing failed: secret key not available`, run the following command to @@ -206,9 +207,9 @@ commits: 1. Commit like you used to, the only difference is the addition of the `-S` flag: - ``` - git commit -S -m "My commit msg" - ``` + ``` + git commit -S -m "My commit msg" + ``` 1. Enter the passphrase of your GPG key when asked. 1. Push to GitLab and check that your commits [are verified](#verifying-commits). @@ -227,13 +228,13 @@ git config --global commit.gpgsign true "Verified" or "Unverified", depending on the verification status of the GPG signature. -  +  1. By clicking on the GPG badge, details of the signature are displayed. -  +  -  +  ## Revoking a GPG key diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index 7765a3d7438..7c711bc0b3b 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -54,50 +54,50 @@ removed from the repository. 1. Navigate to your repository: - ``` - cd my_repository/ - ``` + ``` + cd my_repository/ + ``` 1. Change to the branch you want to remove the big file from: - ``` - git checkout master - ``` + ``` + git checkout master + ``` 1. Create a commit removing the large file from the branch, if it still exists: - ``` - git rm path/to/big_file.mpg - git commit -m 'Remove unneeded large file' - ``` + ``` + git rm path/to/big_file.mpg + git commit -m 'Remove unneeded large file' + ``` 1. Rewrite history: - ``` - bfg --delete-files path/to/big_file.mpg - ``` + ``` + bfg --delete-files path/to/big_file.mpg + ``` - An object map file will be written to `object-id-map.old-new.txt`. Keep it - around - you'll need it for the final step! + An object map file will be written to `object-id-map.old-new.txt`. Keep it + around - you'll need it for the final step! 1. Force-push the changes to GitLab: - ``` - git push --force-with-lease origin master - ``` + ``` + git push --force-with-lease origin master + ``` - If this step fails, someone has changed the `master` branch while you were - rewriting history. You could restore the branch and re-run BFG to preserve - their changes, or use `git push --force` to overwrite their changes. + If this step fails, someone has changed the `master` branch while you were + rewriting history. You could restore the branch and re-run BFG to preserve + their changes, or use `git push --force` to overwrite their changes. 1. Navigate to **Project > Settings > Repository > Repository Cleanup**: -  +  - Upload the `object-id-map.old-new.txt` file and press **Start cleanup**. - This will remove any internal git references to the old commits, and run - `git gc` against the repository. You will receive an email once it has - completed. + Upload the `object-id-map.old-new.txt` file and press **Start cleanup**. + This will remove any internal git references to the old commits, and run + `git gc` against the repository. You will receive an email once it has + completed. NOTE: **Note:** This process will remove some copies of the rewritten commits from GitLab's @@ -110,32 +110,32 @@ purposes! 1. Navigate to your repository: - ``` - cd my_repository/ - ``` + ``` + cd my_repository/ + ``` 1. Change to the branch you want to remove the big file from: - ``` - git checkout master - ``` + ``` + git checkout master + ``` 1. Use `filter-branch` to remove the big file: - ``` - git filter-branch --force --tree-filter 'rm -f path/to/big_file.mpg' HEAD - ``` + ``` + git filter-branch --force --tree-filter 'rm -f path/to/big_file.mpg' HEAD + ``` 1. Instruct Git to purge the unwanted data: - ``` - git reflog expire --expire=now --all && git gc --prune=now --aggressive - ``` + ``` + git reflog expire --expire=now --all && git gc --prune=now --aggressive + ``` 1. Lastly, force push to the repository: - ``` - git push --force origin master - ``` + ``` + git push --force origin master + ``` Your repository should now be below the size limit. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 253e5374f52..0116f0fe7ca 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -13,8 +13,6 @@ Choose **New file** from the dropdown.  ---- - Enter a file name in the **File name** box. Then, add file content in the editor area. Add a descriptive commit message and choose a branch. The branch field will default to the branch you were viewing in the file browser. If you enter @@ -59,8 +57,6 @@ selector. Choose **Upload file** from the dropdown.  ---- - Once the upload dialog pops up there are two ways to upload your file. Either drag and drop a file on the pop up or use the **click to upload** link. A file preview will appear once you have selected a file to upload. @@ -80,8 +76,6 @@ Choose **New directory** from the dropdown.  ---- - In the new directory dialog enter a directory name, a commit message and choose the target branch. Click **Create directory** to finish. @@ -129,8 +123,6 @@ choose **New branch** from the dropdown.  ---- - Enter a new **Branch name**. Optionally, change the **Create from** field to choose which branch, tag or commit SHA this new branch will originate from. This field will autocomplete if you start typing an existing branch or tag. @@ -139,8 +131,6 @@ branch.  ---- - You can now make changes to any files, as needed. When you're ready to merge the changes back to master you can use the widget at the top of the screen. This widget only appears for a period of time after you create the branch or @@ -156,8 +146,6 @@ SHA. From a project's files page, choose **New tag** from the dropdown.  ---- - Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you would like to create this new tag. You can optionally add a message and release notes. The release notes section supports markdown format and you can diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index f899120f0c2..645b9bffcc1 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -53,36 +53,35 @@ Service Desk is enabled on GitLab.com. If you're a [Silver subscriber](https://about.gitlab.com/gitlab-com/), you can skip the step 1 below; you only need to enable it per project. -1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. This must - support [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing). -2. Navigate to your project's **Settings** and scroll down to the **Service Desk** - section. -3. If you have the correct access and an Premium license, - you will see an option to set up Service Desk: +1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. This must + support [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing). +1. Navigate to your project's **Settings** and scroll down to the **Service Desk** + section. +1. If you have the correct access and an Premium license, + you will see an option to set up Service Desk: -  +  -4. Checking that box will enable Service Desk for the project, and show a - unique email address to email issues to the project. These issues will be - [confidential](issues/confidential_issues.md), so they will only be visible to project members. +1. Checking that box will enable Service Desk for the project, and show a + unique email address to email issues to the project. These issues will be + [confidential](issues/confidential_issues.md), so they will only be visible to project members. - **Warning**: this email address can be used by anyone to create an issue on - this project, whether or not they have access to your GitLab instance. - We recommend **putting this behind an alias** so that it can be changed if - needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab instance to add spam - checking to this service. Unblocked email spam would result in many spam - issues being created, and may disrupt your GitLab service. + **Warning**: this email address can be used by anyone to create an issue on + this project, whether or not they have access to your GitLab instance. + We recommend **putting this behind an alias** so that it can be changed if + needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab instance to add spam + checking to this service. Unblocked email spam would result in many spam + issues being created, and may disrupt your GitLab service. -  +  - _In GitLab 11.7, we updated the format of the generated email address. - However the older format is still supported, allowing existing aliases - or contacts to continue working._ + _In GitLab 11.7, we updated the format of the generated email address. + However the older format is still supported, allowing existing aliases + or contacts to continue working._ +1. Service Desk is now enabled for this project! You should be able to access it from your project's navigation **Issue submenu**: -5. Service Desk is now enabled for this project! You should be able to access it from your project's navigation **Issue submenu**: - -  +  ## Using Service Desk diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 98bcc7cc09f..7241df613eb 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -2,33 +2,33 @@ >**Notes:** > -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/3050) in GitLab 8.9. -> - Importing will not be possible if the import instance version differs from -> that of the exporter. -> - For GitLab admins, please read through -> [Project import/export administration](../../../administration/raketasks/project_import_export.md). -> - For existing installations, the project import option has to be enabled in -> application settings (`/admin/application_settings`) under 'Import sources'. -> Ask your administrator if you don't see the **GitLab export** button when -> creating a new project. -> - Starting with GitLab 10.0, administrators can disable the project export option -> on the GitLab instance in application settings (`/admin/application_settings`) -> under 'Visibility and Access Controls'. -> - You can find some useful raketasks if you are an administrator in the -> [import_export](../../../administration/raketasks/project_import_export.md) raketask. -> - The exports are stored in a temporary [shared directory](../../../development/shared_files.md) -> and are deleted every 24 hours by a specific worker. -> - Group members will get exported as project members, as long as the user has -> maintainer or admin access to the group where the exported project lives. An admin -> in the import side is required to map the users, based on email or username. -> Otherwise, a supplementary comment is left to mention the original author and -> the MRs, notes or issues will be owned by the importer. -> - Project members with owner access will get imported as maintainers. -> - Control project Import/Export with the [API](../../../api/project_import_export.md). -> - If an imported project contains merge requests originated from forks, -> then new branches associated with such merge requests will be created -> within a project during the import/export. Thus, the number of branches -> in the exported project could be bigger than in the original project. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/3050) in GitLab 8.9. +> - Importing will not be possible if the import instance version differs from +> that of the exporter. +> - For GitLab admins, please read through +> [Project import/export administration](../../../administration/raketasks/project_import_export.md). +> - For existing installations, the project import option has to be enabled in +> application settings (`/admin/application_settings`) under 'Import sources'. +> Ask your administrator if you don't see the **GitLab export** button when +> creating a new project. +> - Starting with GitLab 10.0, administrators can disable the project export option +> on the GitLab instance in application settings (`/admin/application_settings`) +> under 'Visibility and Access Controls'. +> - You can find some useful raketasks if you are an administrator in the +> [import_export](../../../administration/raketasks/project_import_export.md) raketask. +> - The exports are stored in a temporary [shared directory](../../../development/shared_files.md) +> and are deleted every 24 hours by a specific worker. +> - Group members will get exported as project members, as long as the user has +> maintainer or admin access to the group where the exported project lives. An admin +> in the import side is required to map the users, based on email or username. +> Otherwise, a supplementary comment is left to mention the original author and +> the MRs, notes or issues will be owned by the importer. +> - Project members with owner access will get imported as maintainers. +> - Control project Import/Export with the [API](../../../api/project_import_export.md). +> - If an imported project contains merge requests originated from forks, +> then new branches associated with such merge requests will be created +> within a project during the import/export. Thus, the number of branches +> in the exported project could be bigger than in the original project. Existing projects running on any GitLab instance or GitLab.com can be exported with all their related data and be moved into a new GitLab instance. @@ -79,7 +79,7 @@ The following items will NOT be exported: - Awards NOTE: **Note:** -For more details on the specific data persisted in a project export, see the +For more details on the specific data persisted in a project export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/lib/gitlab/import_export/import_export.yml) file. ## Exporting a project and its data @@ -90,29 +90,29 @@ For more details on the specific data persisted in a project export, see the 1. Scroll down to find the **Export project** button: -  +  1. Once the export is generated, you should receive an e-mail with a link to download the file: -  +  1. Alternatively, you can come back to the project settings and download the file from there, or generate a new export. Once the file available, the page should show the **Download export** button: -  +  ## Importing the project -1. The GitLab project import feature is the first import option when creating a +1. The GitLab project import feature is the first import option when creating a new project. Click on **GitLab export**: -  +  1. Enter your project name and URL. Then select the file you exported previously: -  +  1. Click on **Import project** to begin importing. Your newly imported project page will appear soon. diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 06b431decad..17ec9ecb5d1 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -44,7 +44,7 @@ Set up your project's merge request settings: - Merge request [description templates](../description_templates.md#description-templates). - Enable [merge request approvals](../merge_requests/merge_request_approvals.md). **(STARTER)** - Enable [merge only of pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). -- Enable [merge only when all discussions are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved). +- Enable [merge only when all discussions are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved).  @@ -96,7 +96,7 @@ To rename a repository: 1. Hit **Rename project**. Remember that this can have unintended side effects since everyone with the -old URL will not be able to push or pull. Read more about what happens with the +old URL will not be able to push or pull. Read more about what happens with the [redirects when renaming repositories](../index.md#redirects-when-changing-repository-paths). #### Transferring an existing project into another namespace diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 3d92508ad04..9bf400e7dff 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -295,6 +295,5 @@ active terminal at a time. connect to the runner. Please try to stop and restart the terminal. If the problem persists, double check your runner configuration. - [ce]: https://about.gitlab.com/pricing/ [ee]: https://about.gitlab.com/pricing/ |
