From 61729ab20ac7da2a7b53c00363752ab365d81181 Mon Sep 17 00:00:00 2001 From: lob Date: Mon, 17 Jun 2019 08:19:45 +0000 Subject: Change wording --- doc/user/project/description_templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 05ad15476ab..a8c5d4d95b5 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -65,7 +65,7 @@ changes you made after picking the template and return it to its initial status. > - Templates for merge requests were [introduced][ee-7478ece] in GitLab EE 6.9. The visibility of issues and/or merge requests should be set to either "Everyone -with access" or "Only team members" in your project's **Settings** otherwise the +with access" or "Only Project Members" in your project's **Settings** otherwise the template text areas won't show. This is the default behavior so in most cases you should be fine. -- cgit v1.2.1 From 74702f0e0e05bc346338fbd11b596fcbedfbaea6 Mon Sep 17 00:00:00 2001 From: Tiger Date: Wed, 12 Jun 2019 09:44:18 +1000 Subject: Enable project-level JIT resource creation Previously this behaviour was only available to group and instance-level clusters, as some project clusters relied on Kubernetes credentials being passed through to the runner instead of having their resources managed by GitLab (which is not available when using JIT). These clusters have been migrated to unmanaged, so resources can be created on demand for the remaining managed clusters. --- doc/user/project/clusters/index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 181b20dc710..1a2c9cbc838 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -518,9 +518,7 @@ service account of the cluster integration. ### Troubleshooting failed deployment jobs GitLab will create a namespace and service account specifically for your -deployment jobs. On project level clusters, this happens when the cluster -is created. On group level clusters, resources are created immediately -before the deployment job starts. +deployment jobs. This happens immediately before the deployment job starts. However, sometimes GitLab can not create them. In such instances, your job will fail with the message: -- cgit v1.2.1 From 030059ba9f8582a8f3622c5abd47a38c5d87d693 Mon Sep 17 00:00:00 2001 From: Per Lundberg Date: Tue, 18 Jun 2019 10:41:08 +0000 Subject: using_docker_images.md: fix config.json path --- doc/ci/docker/using_docker_images.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 29578efacbb..03c8b455482 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -478,7 +478,7 @@ To define which should be used, the GitLab Runner process reads the configuratio - A [variable](../variables/README.md#gitlab-cicd-environment-variables) in `.gitlab-ci.yml`. - A project's variables stored on the projects **Settings > CI/CD** page. - `DOCKER_AUTH_CONFIG` variable provided as environment variable in `config.toml` of the Runner. -- `config.json` file placed in `$HOME/docker` directory of the user running GitLab Runner process. +- `config.json` file placed in `$HOME/.docker` directory of the user running GitLab Runner process. If the `--user` flag is provided to run the GitLab Runner child processes as unprivileged user, the home directory of the main GitLab Runner process user will be used. -- cgit v1.2.1 From 09d7f0c0e0c6c7906078dbf1797b08e08d0e696c Mon Sep 17 00:00:00 2001 From: Mark Lapierre Date: Wed, 19 Jun 2019 00:22:23 +0000 Subject: Update docs on how to run E2E tests Make instructions on how to run the E2E tests against GDK more explicit and easier to find. --- doc/development/testing_guide/end_to_end/index.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'doc') diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index afd81ff00b2..527cd350633 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -126,6 +126,18 @@ See [Review Apps][review-apps] for more details about Review Apps. [helm-chart]: https://gitlab.com/charts/gitlab/ [cng]: https://gitlab.com/gitlab-org/build/CNG +## How do I run the tests? + +There are two main options for running the tests. If you simply want to run the +existing tests against a live GitLab instance or against a pre-built docker image +you can use the [GitLab QA orchestrator][gitlab-qa-readme]. See also [examples +of the test scenarios you can run via the orchestrator](https://gitlab.com/gitlab-org/gitlab-qa/blob/master/docs/what_tests_can_be_run.md#examples). + +On the other hand, if you would like to run against a local development GitLab +environment, you can use the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/). +Please refer to the instructions in the [QA README](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/README.md#how-can-i-use-it) +and the section below. + ## How do I write tests? In order to write new tests, you first need to learn more about GitLab QA -- cgit v1.2.1 From 22a6ac1869c7c72a03a14f4c9cfdba6db7bf9f9e Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 28 May 2019 09:59:17 -0400 Subject: Clean up the Sidekiq cluster docs More importantly: - Move the command line tips under a troubleshooting section - Add new section: "Ignore all GitHub import queues" - Add list of existing Sidekiq queues --- .../operations/extra_sidekiq_processes.md | 199 ++++++++++++++------- 1 file changed, 131 insertions(+), 68 deletions(-) (limited to 'doc') diff --git a/doc/administration/operations/extra_sidekiq_processes.md b/doc/administration/operations/extra_sidekiq_processes.md index 286b99aceb5..7297507f599 100644 --- a/doc/administration/operations/extra_sidekiq_processes.md +++ b/doc/administration/operations/extra_sidekiq_processes.md @@ -1,70 +1,132 @@ # Extra Sidekiq processes **[STARTER ONLY]** -GitLab Enterprise Edition allows one to start an extra set of Sidekiq processes +NOTE: **Note:** +The information in this page applies only to Omnibus GitLab. + +GitLab Starter allows one to start an extra set of Sidekiq processes besides the default one. These processes can be used to consume a dedicated set of queues. This can be used to ensure certain queues always have dedicated workers, no matter the number of jobs that need to be processed. -## Starting extra processes via Omnibus GitLab +## Available Sidekiq queues -To enable `sidekiq-cluster`, you must apply the `sidekiq_cluster['enable'] = true` -setting `/etc/gitlab/gitlab.rb`: +For a list of the existing Sidekiq queues, check the following files: -```ruby -sidekiq_cluster['enable'] = true -``` +- [Queues for both GitLab Community and Enterprise Editions](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/app/workers/all_queues.yml) +- [Queues for GitLab Enterprise Editions only](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/app/workers/all_queues.yml) -You will then specify how many additional processes to create via `sidekiq-cluster` -as well as which queues for them to handle. This is done via the -`sidekiq_cluster['queue_groups']` setting. This is an array whose items contain -which queues to process. Each item in the array will equate to one additional -sidekiq process. +Each entry in the above files represents a queue on which extra Sidekiq processes +can be started. -As an example, to make additional sidekiq processes that process the -`elastic_indexer` and `mailers` queues, you would apply the following: +## Starting extra processes -```ruby -sidekiq_cluster['queue_groups'] = [ - "elastic_indexer", - "mailers" -] -``` +To start extra Sidekiq processes, you must enable `sidekiq-cluster`: -To have an additional sidekiq process handle multiple queues, you simply put a -comma after the first queue name and then put the next queue name: +1. Edit `/etc/gitlab/gitlab.rb` and add: -```ruby -sidekiq_cluster['queue_groups'] = [ - "elastic_indexer,elastic_commit_indexer", - "mailers" -] -``` + ```ruby + sidekiq_cluster['enable'] = true + ``` -Keep in mind, all changes must be followed by reconfiguring your GitLab -application via `sudo gitlab-ctl reconfigure`. +1. You will then need to specify how many additional processes to create via `sidekiq-cluster` + and which queue they should handle via the `sidekiq_cluster['queue_groups']` + array setting. Each item in the array equates to one additional Sidekiq + process, and values in each item determine the queues it works on. -### Monitoring + For example, the following setting adds additional Sidekiq processes to two + queues, one to `elastic_indexer` and one to `mailers`: -Once the Sidekiq processes are added, you can visit the "Background Jobs" + ```ruby + sidekiq_cluster['queue_groups'] = [ + "elastic_indexer", + "mailers" + ] + ``` + + To have an additional Sidekiq process handle multiple queues, add multiple + queue names to its item delimited by commas. For example: + + ```ruby + sidekiq_cluster['queue_groups'] = [ + "elastic_indexer, elastic_commit_indexer", + "mailers" + ] + ``` + +1. Save the file and reconfigure GitLab for the changes to take effect: + + ```sh + sudo gitlab-ctl reconfigure + ``` + +Once the extra Sidekiq processes are added, you can visit the "Background Jobs" section under the admin area in GitLab (`/admin/background_jobs`). -![Extra sidekiq processes](img/sidekiq-cluster.png) +![Extra Sidekiq processes](img/sidekiq-cluster.png) -### All queues with exceptions +## Negating settings -To have the additional sidekiq processes work on every queue EXCEPT the ones +To have the additional Sidekiq processes work on every queue **except** the ones you list: +1. After you follow the steps for [starting extra processes](#starting-extra-processes), + edit `/etc/gitlab/gitlab.rb` and add: + + ```ruby + sidekiq_cluster['negate'] = true + ``` + +1. Save the file and reconfigure GitLab for the changes to take effect: + + ```sh + sudo gitlab-ctl reconfigure + ``` + +## Ignore all GitHub import queues + +When [importing from GitHub](../../user/project/import/github.md), Sidekiq might +use all of its resources to perform those operations. To set up a separate +`sidekiq-cluster` process to ignore all GitHub import-related queues: + 1. Edit `/etc/gitlab/gitlab.rb` and add: ```ruby + sidekiq_cluster['enable'] = true sidekiq_cluster['negate'] = true + sidekiq_cluster['queue_groups'] = [ + "github_import_advance_stage", + "github_importer:github_import_import_diff_note", + "github_importer:github_import_import_issue", + "github_importer:github_import_import_note", + "github_importer:github_import_import_lfs_object", + "github_importer:github_import_import_pull_request", + "github_importer:github_import_refresh_import_jid", + "github_importer:github_import_stage_finish_import", + "github_importer:github_import_stage_import_base_data", + "github_importer:github_import_stage_import_issues_and_diff_notes", + "github_importer:github_import_stage_import_notes", + "github_importer:github_import_stage_import_lfs_objects", + "github_importer:github_import_stage_import_pull_requests", + "github_importer:github_import_stage_import_repository" + ] ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Save the file and reconfigure GitLab for the changes to take effect: + ```sh + sudo gitlab-ctl reconfigure + ``` -### Limiting concurrency +## Number of threads + +Each process defined under `sidekiq_cluster` starts with a +number of threads that equals the number of queues, plus one spare thread. +For example, a process that handles the `process_commit` and `post_receive` +queues will use three threads in total. + +## Limiting concurrency + +To limit the concurrency of the Sidekiq processes: 1. Edit `/etc/gitlab/gitlab.rb` and add: @@ -72,11 +134,22 @@ you list: sidekiq_cluster['concurrency'] = 25 ``` -1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +1. Save the file and reconfigure GitLab for the changes to take effect: -Keep in mind, this normally would not exceed the number of CPU cores available. + ```sh + sudo gitlab-ctl reconfigure + ``` -### Modifying the check interval +For each queue group, the concurrency factor will be set to `min(number of queues, N)`. +Setting the value to 0 will disable the limit. Keep in mind this normally would +not exceed the number of CPU cores available. + +Each thread requires a Redis connection, so adding threads may +increase Redis latency and potentially cause client timeouts. See the [Sidekiq +documentation about Redis](https://github.com/mperham/sidekiq/wiki/Using-Redis) +for more details. + +## Modifying the check interval To modify the check interval for the additional Sidekiq processes: @@ -90,9 +163,14 @@ To modify the check interval for the additional Sidekiq processes: This tells the additional processes how often to check for enqueued jobs. -## Starting extra processes via command line +## Troubleshooting using the CLI -Starting extra Sidekiq processes can be done using the command +CAUTION: **Warning:** +It's recommended to use `/etc/gitlab/gitlab.rb` to configure the Sidekiq processes. +If you experience a problem, you should contact GitLab support. Use the command +line at your own risk. + +For debugging purposes, you can start extra Sidekiq processes by using the command `/opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster`. This command takes arguments using the following syntax: @@ -111,29 +189,29 @@ see the relevant section in the [Sidekiq style guide](../../development/sidekiq_style_guide.md#queue-namespaces). For example, say you want to start 2 extra processes: one to process the -"process_commit" queue, and one to process the "post_receive" queue. This can be +`process_commit` queue, and one to process the `post_receive` queue. This can be done as follows: ```bash /opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit post_receive ``` -If you instead want to start one process processing both queues you'd use the +If you instead want to start one process processing both queues, you'd use the following syntax: ```bash /opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit,post_receive ``` -If you want to have one Sidekiq process process the "process_commit" and -"post_receive" queues, and one process to process the "gitlab_shell" queue, +If you want to have one Sidekiq process dealing with the `process_commit` and +`post_receive` queues, and one process to process the `gitlab_shell` queue, you'd use the following: ```bash /opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit,post_receive gitlab_shell ``` -### Monitoring +### Monitoring the `sidekiq-cluster` command The `sidekiq-cluster` command will not terminate once it has started the desired amount of Sidekiq processes. Instead, the process will continue running and @@ -172,24 +250,24 @@ command and not the PID(s) of the started Sidekiq processes. The Rails environment can be set by passing the `--environment` flag to the `sidekiq-cluster` command, or by setting `RAILS_ENV` to a non-empty value. The -default value is "development". +default value can be found in `/opt/gitlab/etc/gitlab-rails/env/RAILS_ENV`. -### All queues with exceptions +### Using negation You're able to run all queues in `sidekiq_queues.yml` file on a single or multiple processes with exceptions using the `--negate` flag. For example, say you want to run a single process for all queues, -except "process_commit" and "post_receive". You can do so by executing: +except `process_commit` and `post_receive`: ```bash -sidekiq-cluster process_commit,post_receive --negate +/opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit,post_receive --negate ``` -For multiple processes of all queues (except "process_commit" and "post_receive"): +For multiple processes of all queues (except `process_commit` and `post_receive`): ```bash -sidekiq-cluster process_commit,post_receive process_commit,post_receive --negate +/opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit,post_receive process_commit,post_receive --negate ``` ### Limiting concurrency @@ -201,18 +279,3 @@ the `-m N` option. For example, this would cap the maximum number of threads to ```bash /opt/gitlab/embedded/service/gitlab-rails/ee/bin/sidekiq-cluster process_commit,post_receive -m 1 ``` - -For each queue group, the concurrency factor will be set to min(number of -queues, N). Setting the value to 0 will disable the limit. - -Note that each thread requires a Redis connection, so adding threads may -increase Redis latency and potentially cause client timeouts. See the [Sidekiq -documentation about Redis](https://github.com/mperham/sidekiq/wiki/Using-Redis) -for more details. - -## Number of threads - -Each process started using `sidekiq-cluster` (whether it be via command line or -via the gitlab.rb file) starts with a number of threads that equals the number -of queues, plus one spare thread. For example, a process that handles the -"process_commit" and "post_receive" queues will use 3 threads in total. -- cgit v1.2.1 From 8e5bc9e311b05c98956c6a0397a551dc3e14bf10 Mon Sep 17 00:00:00 2001 From: Tristan Williams <2390023-tristan@users.noreply.gitlab.com> Date: Wed, 19 Jun 2019 21:25:21 +0000 Subject: Correct group path instructions --- doc/user/group/index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/user/group/index.md b/doc/user/group/index.md index abd95eddf63..4fde45da6c4 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -268,9 +268,10 @@ be unique. To change your group path: -1. Navigate to your group's **Settings > General**. -1. Enter a new name under **Group path**. -1. Click **Save group**. +1. Navigate to your group's **Settings > General** page. +1. Expand the **Path, transfer, remove** section. +1. Enter a new name under **Change group path**. +1. Click **Change group path**. CAUTION: **Caution:** It is currently not possible to rename a namespace if it contains a -- cgit v1.2.1 From 3696fe630b6ebc209a9cc54eccbad7f313feaa65 Mon Sep 17 00:00:00 2001 From: Thong Kuah Date: Thu, 20 Jun 2019 11:22:28 +1200 Subject: Add how to migrate deployments for deploy boards --- doc/user/project/deploy_boards.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index b7f6a855cb6..53f78ba336a 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -86,7 +86,10 @@ To display the Deploy Boards for a specific [environment] you should: Kubernetes. NOTE: **Note:** - Matching based on the Kubernetes `app` label was removed in [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/14020) + Matching based on the Kubernetes `app` label was removed in [GitLab + 12.1](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/14020). + To migrate, please apply the required annotations (see above) and + re-deploy your application. ![Deploy Boards Kubernetes Label](img/deploy_boards_kubernetes_label.png) -- cgit v1.2.1 From 91cf0cb2d53b6f48560862fc121f897bb7331046 Mon Sep 17 00:00:00 2001 From: Fernando Date: Sun, 14 Apr 2019 11:05:28 -0500 Subject: Paginate license management and add license search First pass at license pagination * Paginate license management client side * Refactor license list into seperate component Add string filtering to license names * Add search input to query on license name Add add license button * Refactor add license button to be a slot Clean up styles and button state logic * Clean up alignment * Disable button when dorpdown is open Remove client side alphabetical sorting * Let the databse return order by date Refactor list to use row slot Further abstract pagination list compnent Finish refactor of paginated list * Refactor component into generic paginated list component * Add additional style tweaks + responsive classes Run prettier Update license_management_spec Run Prettier Add unit tests for paginated list component * Refactor template to be valid html (li in ul) * Add jest unit tests Add additional unit tests * Add unit tests around pagination and search states Add unit tests for filter props Pretty print, lint, and add changelog Update po files Regernate pot file Backport EE changes * Update paginated list component * Update specs and snapshot Add POT file Update default copy for pagianted list * update copy for empty and empty search result states Update pot file Backport changes from EE merge request * Paginaed list component and specs Backport EE changes Update paginated list snapshot Update license management docs and images Backport paginated-list component from EE Link to gitlab-ui artifacts job Match gitlab ui build to EE Update pot file Backport Paginated list changes Set gitlab-ui to temp artifact Add changelog --- .../img/license_management_add_license.png | Bin 0 -> 87049 bytes .../img/license_management_search.png | Bin 0 -> 104278 bytes .../img/license_management_settings.png | Bin 13300 -> 171592 bytes .../license_management/index.md | 16 ++++++++++++++++ 4 files changed, 16 insertions(+) create mode 100644 doc/user/application_security/license_management/img/license_management_add_license.png create mode 100644 doc/user/application_security/license_management/img/license_management_search.png (limited to 'doc') diff --git a/doc/user/application_security/license_management/img/license_management_add_license.png b/doc/user/application_security/license_management/img/license_management_add_license.png new file mode 100644 index 00000000000..1e1a698515b Binary files /dev/null and b/doc/user/application_security/license_management/img/license_management_add_license.png differ diff --git a/doc/user/application_security/license_management/img/license_management_search.png b/doc/user/application_security/license_management/img/license_management_search.png new file mode 100644 index 00000000000..7b6006cef9d Binary files /dev/null and b/doc/user/application_security/license_management/img/license_management_search.png differ diff --git a/doc/user/application_security/license_management/img/license_management_settings.png b/doc/user/application_security/license_management/img/license_management_settings.png index b5490e59074..1a2bfa78a03 100644 Binary files a/doc/user/application_security/license_management/img/license_management_settings.png and b/doc/user/application_security/license_management/img/license_management_settings.png differ diff --git a/doc/user/application_security/license_management/index.md b/doc/user/application_security/license_management/index.md index 7a583016586..957c4ede981 100644 --- a/doc/user/application_security/license_management/index.md +++ b/doc/user/application_security/license_management/index.md @@ -262,6 +262,8 @@ To approve or blacklist a license: navigate to the project's **Settings > CI/CD** and expand the **License Management** section. 1. Click the **Add a license** button. + + ![License Management Add License](img/license_management_add_license.png) 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. @@ -270,8 +272,22 @@ To approve or blacklist a license: 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. + ![License Management Settings](img/license_management_settings.png) +Searching for Licenses: + +1. Use the **Search** box to search for a specific license. + + ![License Management Search](img/license_management_search.png) + + + ## License Management report under pipelines > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5491) -- cgit v1.2.1 From e8078ed69f9954d66884078e270a24a42636969a Mon Sep 17 00:00:00 2001 From: DJ Mountney Date: Thu, 20 Jun 2019 08:40:44 +0000 Subject: Document the workaround for issues after registry restore Restoring the registry ends up using the wrong file permissions, breaking the registry. Document the workaround while we look at improvements. --- doc/raketasks/backup_restore.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'doc') diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 764916ca82d..c7aa22b11f8 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -936,5 +936,36 @@ A similar strategy can be employed for the remaining features - by removing the data that cannot be decrypted, GitLab can be brought back into working order, and the lost data can be manually replaced. +### Container Registry push failures after restoring from a backup + +If you use the [Container Registry](../user/project/container_registry.md), you +may see pushes to the registry fail after restoring your backup on an Omnibus +GitLab instance after restoring the registry data. + +These failures will mention permission issues in the registry logs, like: + +``` +level=error +msg="response completed with error" +err.code=unknown +err.detail="filesystem: mkdir /var/opt/gitlab/gitlab-rails/shared/registry/docker/registry/v2/repositories/...: permission denied" +err.message="unknown error" +``` + +This is caused by the restore being run as the unprivileged user `git` which was +unable to assign the correct ownership to the registry files during the restore +([issue 62759](https://gitlab.com/gitlab-org/gitlab-ce/issues/62759 "Incorrect permissions on registry filesystem after restore")). + +To get your registry working again: + +```bash +sudo chown -R registry:registry /var/opt/gitlab/gitlab-rails/shared/registry/docker +``` + +NOTE: **Note:** +If you have changed the default filesystem location for the registry, you will +want to run the chown against your custom location instead of +`/var/opt/gitlab/gitlab-rails/shared/registry/docker`. + [reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure [restart GitLab]: ../administration/restart_gitlab.md#installations-from-source -- cgit v1.2.1 From d18c101227878b6e451c241cfee5a12498a9067b Mon Sep 17 00:00:00 2001 From: Alexandru Croitor Date: Wed, 19 Jun 2019 17:10:52 +0300 Subject: Link issue statistics api endpoint in the docs Adds the missing link to issues_statistics api endpoint --- doc/api/README.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc') diff --git a/doc/api/README.md b/doc/api/README.md index 3a1064b787e..23c69deef23 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -35,6 +35,7 @@ The following API resources are available in the project context: | [Environments](environments.md) | `/projects/:id/environments` | | [Events](events.md) | `/projects/:id/events` (also available for users and standalone) | | [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | +| [Issues Statistics](issues_statistics.md) | `/projects/:id/issues_statistics` (also available for groups and standalone) | | [Issue boards](boards.md) | `/projects/:id/boards` | | [Issue links](issue_links.md) **[STARTER]** | `/projects/:id/issues/.../links` | | [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | @@ -92,6 +93,7 @@ The following API resources are available in the group context: | [Group-level variables](group_level_variables.md) | `/groups/:id/variables` | | [Group milestones](group_milestones.md) | `/groups/:id/milestones` | | [Issues](issues.md) | `/groups/:id/issues` (also available for projects and standalone) | +| [Issues Statistics](issues_statistics.md) | `/groups/:id/issues_statistics` (also available for projects and standalone) | | [Members](members.md) | `/groups/:id/members` (also available for projects) | | [Merge requests](merge_requests.md) | `/groups/:id/merge_requests` (also available for projects and standalone) | | [Notes](notes.md) (comments) | `/groups/:id/epics/.../notes` (also available for projects) | @@ -116,6 +118,7 @@ The following API resources are available outside of project and group contexts | [Geo Nodes](geo_nodes.md) **[PREMIUM ONLY]** | `/geo_nodes` | | [Import repository from GitHub](import.md) | `/import/github` | | [Issues](issues.md) | `/issues` (also available for groups and projects) | +| [Issues Statistics](issues_statistics.md) | `/issues_statistics` (also available for groups and projects) | | [Keys](keys.md) | `/keys` | | [License](license.md) **[CORE ONLY]** | `/license` | | [Markdown](markdown.md) | `/markdown` | -- cgit v1.2.1 From f26185a01ba0f85019826de174ac794f46568c9b Mon Sep 17 00:00:00 2001 From: Evan Read Date: Thu, 20 Jun 2019 09:15:39 +0000 Subject: Edit new Zoom call link content --- doc/user/project/issues/issue_data_and_actions.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index ac26b672d99..2103f331aa2 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -149,12 +149,19 @@ The plain text title and description of the issue fill the top center of the iss The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), allowing many formatting options. -##### 16.1 Zoom Call Links +##### Zoom call links -Including a link to a Zoom call in the description of an issue will result in a "Join Zoom meeting" button at the top of the issue, just under the header. To remove the button, edit the description and remove the Zoom call link. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/62966) in GitLab 12.0. + +Including a link to a [Zoom](https://zoom.us) call in the description of an issue +results in a **Join Zoom meeting** button at the top of the issue, just under the header. + +For example: ![Link Zoom Call in Issue](img/link_zoom_call_in_issue.png) +To remove the button, edit the description and remove the Zoom call link. + #### 17. Mentions You can mention a user or a group present in your GitLab instance with `@username` or -- cgit v1.2.1 From e04e2eb2c10e10f22cd2647b72e8da83643ceb6e Mon Sep 17 00:00:00 2001 From: Evan Read Date: Thu, 20 Jun 2019 09:20:05 +0000 Subject: Add version text and edit section --- doc/user/project/clusters/serverless/index.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 0ab6d8e112f..3be5bfeaddc 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -85,12 +85,22 @@ on a given project but not both. The current implementation makes use of a `serv ## Using an existing installation of Knative +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/58941) in GitLab 12.0. + NOTE: **Note:** -The "invocations" monitoring feature of GitLab serverless will not work when adding an existing installation of Knative. +The "invocations" monitoring feature of GitLab serverless will not work when +adding an existing installation of Knative. + +It is also possible to use GitLab Serverless with an existing Kubernetes +cluster which already has Knative installed. + +Simply: -It is also possible to use GitLab Serverless with an existing Kubernetes cluster which already has Knative installed. -Simply follow the steps to [add an existing Kubernetes cluster](../index.md#adding-an-existing-kubernetes-cluster) -and then follow the steps to deploy [functions](#deploying-functions) or [serverless applications](#deploying-serverless-applications) onto your cluster. +1. Follow the steps to + [add an existing Kubernetes cluster](../index.md#adding-an-existing-kubernetes-cluster). +1. Follow the steps to deploy [functions](#deploying-functions) + or [serverless applications](#deploying-serverless-applications) onto your + cluster. ## Deploying functions -- cgit v1.2.1 From a15e6206899e06ff8a868af49236cb9ab82c70c5 Mon Sep 17 00:00:00 2001 From: Alexandru Croitor Date: Wed, 19 Jun 2019 17:47:16 +0300 Subject: Add documentation on epic add/remove child relations quick actions --- doc/user/project/quick_actions.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 1d640966013..6c430ff7cd9 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -35,7 +35,7 @@ discussions, and descriptions: | `/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 | ✓ | ✓ | -| /copy_metadata #issue | !merge_request | Copy labels and milestone from other issue or merge request in the project | ✓ | ✓ | +| /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 | ✓ | ✓ | | /spend <time(1h 30m | -1h 5m)> <date(YYYY-MM-DD)> | Add or subtract spent time; optionally, specify the date that time was spent on | ✓ | ✓ | @@ -44,14 +44,14 @@ discussions, and descriptions: | `/unlock` | Unlock the discussion | ✓ | ✓ | | /due <in 2 days | this Friday | December 31st>| Set due date | ✓ | | | `/remove_due_date` | Remove due date | ✓ | | -| `/weight 0,1,2, ...` | Set weight **[STARTER]** | ✓ | | +| /weight <0 | 1 | 2 | ...> | Set weight **[STARTER]** | ✓ | | | `/clear_weight` | Clears weight **[STARTER]** | ✓ | | -| `/epic <&epic | group&epic | Epic URL>` | 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 | ✓ | | -| `/duplicate #issue` | Mark this issue as a duplicate of another issue | ✓ | -| `/move path/to/project` | Move this issue to another project | ✓ | | +| `/duplicate <#issue>` | Mark this issue as a duplicate of another issue | ✓ | +| `/move ` | Move this issue to another project | ✓ | | | `/target_branch ` | Set target branch | | ✓ | | `/wip` | Toggle the Work In Progress status | | ✓ | | `/approve` | Approve the merge request | | ✓ | @@ -85,3 +85,5 @@ The following quick actions are applicable for epics threads and description: | `/label ~label1 ~label2` | Add label(s) | | `/unlabel ~label1 ~label2` | Remove all or specific label(s) | | `/relabel ~label1 ~label2` | Replace label | +| /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)) | -- cgit v1.2.1 From d29ba165593e38d05b0133a87e2b040094a875d0 Mon Sep 17 00:00:00 2001 From: Jason Goodman Date: Thu, 20 Jun 2019 09:24:02 +0000 Subject: Update Docs for Container Registry API Delete Endpoints --- doc/api/container_registry.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'doc') diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 1f17af1f1e9..64ea15bca93 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -145,6 +145,9 @@ DELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_name curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects/5/registry/repositories/2/tags/v10.0.0" ``` +This action does not delete blobs. In order to delete them and recycle disk space, +[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests). + ## Delete repository tags in bulk Delete repository tags in bulk based on given criteria. @@ -174,6 +177,8 @@ This API call performs the following operations: These operations are executed asynchronously and it might take time to get executed. You can run this at most once an hour for a given container repository. +This action does not delete blobs. In order to delete them and recycle disk space, +[run the garbage collection](https://docs.gitlab.com/omnibus/maintenance/README.html#removing-unused-layers-not-referenced-by-manifests). NOTE: **Note:** Due to a [Docker Distribution deficiency](https://gitlab.com/gitlab-org/gitlab-ce/issues/21405), -- cgit v1.2.1 From c1ea40c4b943c44eed055a488979ddb39a5e5cca Mon Sep 17 00:00:00 2001 From: Mek Stittri Date: Thu, 20 Jun 2019 14:26:32 +0000 Subject: Improve bug severity definitions and consolidate guidance for clarity --- doc/development/contributing/issue_workflow.md | 52 +++++++++++++------------- 1 file changed, 26 insertions(+), 26 deletions(-) (limited to 'doc') diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 0396f7ebc45..3d36a7bf3b1 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -172,35 +172,35 @@ This label documents the planned timeline & urgency which is used to measure aga | ~P3 | Medium Priority | Within the next 3 releases (approx one quarter or 90 days) | | ~P4 | Low Priority | Anything outside the next 3 releases (more than one quarter or 120 days) | -If an issue seems to fall between two priority labels, assign it to the higher- -priority label. - ## Severity labels Severity labels help us clearly communicate the impact of a ~bug on users. - -| Label | Meaning | Impact on Functionality | Example | -|-------|-------------------|-------------------------------------------------------|---------| -| ~S1 | Blocker | Outage, broken feature with no workaround | Unable to create an issue. Data corruption/loss. Security breach. | -| ~S2 | Critical Severity | Broken Feature, workaround too complex & unacceptable | Can push commits, but only via the command line. | -| ~S3 | Major Severity | Broken Feature, workaround acceptable | Can create merge requests only from the Merge Requests page, not through the Issue. | -| ~S4 | Low Severity | Functionality inconvenience or cosmetic issue | Label colors are incorrect / not being displayed. | - -If an issue seems to fall between two severity labels, even taking the -[severity impact guidance](#severity-impact-guidance) into account, assign -it to the higher-severity label. - -### Severity impact guidance - -Severity levels can be applied further depending on the facet of the impact; e.g. Affected customers, GitLab.com availability, performance and etc. The below is a guideline. - -| Severity | Affected Customers/Users | GitLab.com Availability | Performance Degradation | -|----------|---------------------------------------------------------------------|----------------------------------------------------|------------------------------| -| ~S1 | >50% users affected (possible company extinction level event) | Significant impact on all of GitLab.com | | -| ~S2 | Many users or multiple paid customers affected (but not apocalyptic)| Significant impact on large portions of GitLab.com | Degradation is guaranteed to occur in the near future | -| ~S3 | A few users or a single paid customer affected | Limited impact on important portions of GitLab.com | Degradation is likely to occur in the near future | -| ~S4 | No paid users/customer affected, or expected to in the near future | Minor impact on GitLab.com | Degradation _may_ occur but it's not likely | - +There can be multiple facets of the impact. The below is a guideline. + +| Label | Meaning | Functionality | Affected Users | GitLab.com Availability | Performance Degradation | +|-------|-------------------|-------------------------------------------------------|----------------------------------|----------------------------------------------------|------------------------------| +| ~S1 | Blocker | Unusable feature with no workaround, user is blocked | Impacts 50% or more of users | Outage, Significant impact on all of GitLab.com | | +| ~S2 | Critical Severity | Broken Feature, workaround too complex & unacceptable | Impacts between 25%-50% of users | Significant impact on large portions of GitLab.com | Degradation is guaranteed to occur in the near future | +| ~S3 | Major Severity | Broken feature with an acceptable workaround | Impacts up to 25% of users | Limited impact on important portions of GitLab.com | Degradation is likely to occur in the near future | +| ~S4 | Low Severity | Functionality inconvenience or cosmetic issue | Impacts less than 5% of users | Minor impact on GitLab.com | Degradation _may_ occur but it's not likely | + +If a bug seems to fall between two severity labels, assign it to the higher-severity label. + +* Example(s) of ~S1 + * Data corruption/loss. + * Security breach. + * Unable to create an issue or merge request. + * Unable to add a comment or discussion to the issue or merge request. +* Example(s) of ~S2 + * Cannot submit changes through the web IDE but the commandline works. + * A status widget on the merge request page is not working but information can be seen in the test pipeline page. +* Example(s) of ~S3 + * Can create merge requests only from the Merge Requests list view, not from an Issue page. + * Status is not updated in real time and needs a page refresh. +* Example(s) of ~S4 + * Label colors are incorrect. + * UI elements are not fully aligned. + ## Label for community contributors Issues that are beneficial to our users, 'nice to haves', that we currently do -- cgit v1.2.1 From 3af348b6cf28ef1d9d3025f7012049132b57798c Mon Sep 17 00:00:00 2001 From: Oswaldo Ferreira Date: Tue, 21 May 2019 18:14:22 -0300 Subject: Automatically update MR merge-ref along merge status This couples the code that transitions the `MergeRequest#merge_status` and refs/merge-requests/:iid/merge ref update. In general, instead of directly telling `MergeToRefService` to update the merge ref, we should rely on `MergeabilityCheckService` to keep both the merge status and merge ref synced. Now, if the merge_status is `can_be_merged` it means the merge-ref is also updated to the latest. We've also updated the logic to be more systematic and less user-based. --- doc/api/merge_requests.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) (limited to 'doc') diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index dd7810c3403..7b58aa3100e 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -1191,33 +1191,29 @@ Parameters: } ``` -## Merge to default merge ref path +## Returns the up to date merge-ref HEAD commit Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge` -ref, of the target project repository. This ref will have the state the target branch would have if +ref, of the target project repository, if possible. This ref will have the state the target branch would have if a regular merge action was taken. -This is not a regular merge action given it doesn't change the merge request state in any manner. +This is not a regular merge action given it doesn't change the merge request target branch state in any manner. -This ref (`refs/merge-requests/:iid/merge`) is **always** overwritten when submitting -requests to this API, so none of its state is kept or used in the process. +This ref (`refs/merge-requests/:iid/merge`) isn't necessarily overwritten when submitting +requests to this API, though it'll make sure the ref has the latest possible state. -If the merge request has conflicts, is empty or already merged, -you'll get a `400` and a descriptive error message. If you don't have permissions to do so, -you'll get a `403`. +If the merge request has conflicts, is empty or already merged, you'll get a `400` and a descriptive error message. -It returns the HEAD commit of `refs/merge-requests/:iid/merge` in the response body in -case of `200`. +It returns the HEAD commit of `refs/merge-requests/:iid/merge` in the response body in case of `200`. ``` -PUT /projects/:id/merge_requests/:merge_request_iid/merge_to_ref +GET /projects/:id/merge_requests/:merge_request_iid/merge_ref ``` Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - Internal ID of MR -- `merge_commit_message` (optional) - Custom merge commit message ```json { -- cgit v1.2.1 From aa3c603ebdb08efece9aaa695755e95f633877af Mon Sep 17 00:00:00 2001 From: Stan Hu Date: Thu, 20 Jun 2019 22:12:35 +0000 Subject: Update Grafana and GitLab Monitor in component list This commit checks off two of the three components in the table that we added for the CEO Challenge in Contribute 2019: * Grafana: https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/3272 * GitLab Monitor: https://gitlab.com/charts/gitlab/merge_requests/787 --- doc/development/architecture.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/development/architecture.md b/doc/development/architecture.md index a43a40152db..d14a760f972 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -141,13 +141,13 @@ Component statuses are linked to configuration documentation for each component. | [Consul](#consul) | Database node discovery, failover | [⚙][consul-omnibus] | [❌][consul-charts] | [❌][consul-charts] | [✅](../user/gitlab_com/index.md#consul) | ❌ | ❌ | EE Only | | [GitLab self-monitoring: Prometheus](#prometheus) | Time-series database, metrics collection, and query service | [✅][prometheus-omnibus] | [✅][prometheus-charts] | [⚙][prometheus-charts] | [✅](../user/gitlab_com/index.md#prometheus) | ❌ | ❌ | CE & EE | | [GitLab self-monitoring: Alertmanager](#alertmanager) | Deduplicates, groups, and routes alerts from Prometheus | [⚙][alertmanager-omnibus] | [✅][alertmanager-charts] | [⚙][alertmanager-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE | -| [GitLab self-monitoring: Grafana](#grafana) | Metrics dashboard | [⚙][grafana-omnibus] | [⤓][grafana-charts] | [⤓][grafana-charts] | [✅](https://dashboards.gitlab.com/d/RZmbBr7mk/gitlab-triage?refresh=30s) | ❌ | ❌ | CE & EE | +| [GitLab self-monitoring: Grafana](#grafana) | Metrics dashboard | [✅][grafana-omnibus] | [⤓][grafana-charts] | [⤓][grafana-charts] | [✅](https://dashboards.gitlab.com/d/RZmbBr7mk/gitlab-triage?refresh=30s) | ❌ | ❌ | CE & EE | | [GitLab self-monitoring: Sentry](#sentry) | Track errors generated by the GitLab instance | [⤓][sentry-omnibus] | [❌][sentry-charts] | [❌][sentry-charts] | [✅](https://about.gitlab.com/handbook/support/workflows/services/gitlab_com/500_errors.html#searching-sentry) | [⤓][gitlab-yml] | [⤓][gitlab-yml] | CE & EE | | [GitLab self-monitoring: Jaeger](#jaeger) | View traces generated by the GitLab instance | [❌][jaeger-omnibus] | [❌][jaeger-charts] | [❌][jaeger-charts] | [❌](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/4104) | [⤓][jaeger-source] | [⚙][jaeger-gdk] | CE & EE | | [Redis Exporter](#redis-exporter) | Prometheus endpoint with Redis metrics | [✅][redis-exporter-omnibus] | [✅][redis-exporter-charts] | [✅][redis-exporter-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE | | [Postgres Exporter](#postgres-exporter) | Prometheus endpoint with PostgreSQL metrics | [✅][postgres-exporter-omnibus] | [✅][postgres-exporter-charts] | [✅][postgres-exporter-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE | | [PgBouncer Exporter](#pgbouncer-exporter) | Prometheus endpoint with PgBouncer metrics | [⚙][pgbouncer-exporter-omnibus] | [❌][pgbouncer-exporter-charts] | [❌][pgbouncer-exporter-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE | -| [GitLab Monitor](#gitlab-monitor) | Generates a variety of GitLab metrics | [✅][gitlab-monitor-omnibus] | [❌][gitab-monitor-charts] | [❌][gitab-monitor-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE | +| [GitLab Monitor](#gitlab-monitor) | Generates a variety of GitLab metrics | [✅][gitlab-monitor-omnibus] | [✅][gitab-monitor-charts] | [✅][gitab-monitor-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE | | [Node Exporter](#node-exporter) | Prometheus endpoint with system metrics | [✅][node-exporter-omnibus] | [❌][node-exporter-charts] | [❌][node-exporter-charts] | [✅](https://about.gitlab.com/handbook/engineering/monitoring/) | ❌ | ❌ | CE & EE | | [Mattermost](#mattermost) | Open-source Slack alternative | [⚙][mattermost-omnibus] | [⤓][mattermost-charts] | [⤓][mattermost-charts] | [⤓](../user/project/integrations/mattermost.md) | ❌ | ❌ | CE & EE | | [MinIO](#minio) | Object storage service | [⤓][minio-omnibus] | [✅][minio-charts] | [✅][minio-charts] | [✅](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/#storage-architecture) | ❌ | [⚙][minio-gdk] | CE & EE | @@ -681,7 +681,7 @@ We've also detailed [our architecture of GitLab.com](https://about.gitlab.com/ha [pgbouncer-exporter-omnibus]: ../administration/monitoring/prometheus/pgbouncer_exporter.md [pgbouncer-exporter-charts]: https://docs.gitlab.com/charts/installation/deployment.html#postgresql [gitlab-monitor-omnibus]: ../administration/monitoring/prometheus/gitlab_monitor_exporter.md -[gitab-monitor-charts]: https://gitlab.com/charts/gitlab/issues/319 +[gitab-monitor-charts]: https://docs.gitlab.com/charts/charts/gitlab/gitlab-monitor/index.html [node-exporter-omnibus]: ../administration/monitoring/prometheus/node_exporter.md [node-exporter-charts]: https://gitlab.com/charts/gitlab/issues/1332 [mattermost-omnibus]: https://docs.gitlab.com/omnibus/gitlab-mattermost/ -- cgit v1.2.1 From f53549ac9180a19f0583347fe61023e29bcede11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Cunha?= Date: Thu, 20 Jun 2019 22:40:25 +0000 Subject: Make deploy_boards doc clearer about its requirements --- doc/user/project/deploy_boards.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc') diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index b7f6a855cb6..2aef369c087 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -59,6 +59,8 @@ specific environment, there are lot of uses cases. To name a few: To display the Deploy Boards for a specific [environment] you should: +1. Have [defined an environment](../../ci/environments.md#defining-environments) with a deploy stage. + 1. Have a Kubernetes cluster up and running. NOTE: **Running on OpenShift:** -- cgit v1.2.1 From a87f0f3937261486960c55d1791c9c04dd6e4171 Mon Sep 17 00:00:00 2001 From: Tiger Watson Date: Fri, 21 Jun 2019 03:55:30 +0000 Subject: Remove project-level cluster credential fallback Project-level clusters that made use of this legacy behaviour have been migrated to unmanaged clusters, so we are now free to remove this fallback. --- doc/user/project/clusters/index.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'doc') diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index a4d4fb91f71..547a0c36108 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -532,6 +532,14 @@ This job failed because the necessary resources were not successfully created. To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#kuberneteslog). +NOTE: **NOTE:** +As of GitLab 12.1 we require [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) +tokens for all project level clusters unless you unselect the +[GitLab-managed cluster](#gitlab-managed-clusters) option. If you +want to manage namespaces and service accounts yourself and don't +want to provide a `cluster-admin` token to GitLab you must unselect this +option or you will get the above error. + Common reasons for failure include: - The token you gave GitLab did not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) -- cgit v1.2.1 From 81f78eb250bf3c99a6666d177673b78da7f6aa09 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Fri, 21 Jun 2019 10:31:35 +0000 Subject: Fixed formatting of notes bullet list --- doc/user/project/description_templates.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index a8c5d4d95b5..ca59fe3cc7d 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -58,6 +58,7 @@ changes you made after picking the template and return it to its initial status. ## Setting a default template for issues and merge requests **[STARTER]** > **Notes:** +> > - This feature was introduced before [description templates](#overview) and is > available in [GitLab Starter][products]. It can be enabled > in the project's settings. -- cgit v1.2.1 From b765b8e3b2fd4565cf48cd883c18d13893837364 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Fri, 21 Jun 2019 10:33:37 +0000 Subject: Add new troubleshooting step and refactor Geo replication docs --- .../geo/replication/troubleshooting.md | 108 +++++++++++++++------ 1 file changed, 76 insertions(+), 32 deletions(-) (limited to 'doc') diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index c5bdd36ba70..846afd8f5f4 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -1,15 +1,23 @@ # Geo Troubleshooting **[PREMIUM ONLY]** -NOTE: **Note:** -This list is an attempt to document all the moving parts that can go wrong. -We are working into getting all this steps verified automatically in a -rake task in the future. - Setting up Geo requires careful attention to details and sometimes it's easy to -miss a step. Here is a list of questions you should ask to try to detect -what you need to fix (all commands and path locations are for Omnibus installs): +miss a step. + +Here is a list of steps you should take to attempt to fix problem: + +- Perform [basic troubleshooting](#basic-troubleshooting). +- Fix any [replication errors](#fixing-replication-errors). +- Fix any [Foreign Data Wrapper](#fixing-foreign-data-wrapper-errors) errors. +- Fix any [common](#fixing-common-errors) errors. -## First check the health of the **secondary** node +## Basic troubleshooting + +Before attempting more advanced troubleshooting: + +- Check [the health of the **secondary** node](#check-the-health-of-the-secondary-node). +- Check [if PostgreSQL replication is working](#check-if-postgresql-replication-is-working). + +### Check the health of the **secondary** node Visit the **primary** node's **Admin Area > Geo** (`/admin/geo/nodes`) in your browser. We perform the following health checks on each **secondary** node @@ -23,10 +31,12 @@ to help identify if something is wrong: ![Geo health check](img/geo_node_healthcheck.png) -For information on how to resolve common errors reported from the UI, see [common errors](#common-errors). +For information on how to resolve common errors reported from the UI, see +[Fixing Common Errors](#fixing-common-errors). If the UI is not working, or you are unable to log in, you can run the Geo health check manually to get this information as well as a few more details. + This rake task can be run on an app node in the **primary** or **secondary** Geo nodes: @@ -36,7 +46,7 @@ sudo gitlab-rake gitlab:geo:check Example output: -``` +```text Checking Geo ... GitLab Geo is available ... yes @@ -68,7 +78,7 @@ sudo gitlab-rake geo:status Example output: -``` +```text http://secondary.example.com/ ----------------------------------------------------- GitLab Version: 11.10.4-ee @@ -89,16 +99,21 @@ http://secondary.example.com/ Last status report was: 2 minutes ago ``` -## Is Postgres replication working? +### Check if PostgreSQL replication is working + +To check if PostgreSQL replication is working, check if: + +- [Nodes are pointing to the correct database instance](#are-nodes-pointing-to-the-correct-database-instance). +- [Geo can detect the current node correctly](#can-geo-detect-the-current-node-correctly). -### Are my nodes pointing to the correct database instance? +#### Are nodes pointing to the correct database instance? You should make sure your **primary** Geo node points to the instance with writing permissions. Any **secondary** nodes should point only to read-only instances. -### Can Geo detect my current node correctly? +#### Can Geo detect the current node correctly? Geo uses the defined node from the **Admin Area > Geo** screen, and tries to match it with the value defined in the `/etc/gitlab/gitlab.rb` configuration file. @@ -112,29 +127,38 @@ sudo gitlab-rails runner "puts Gitlab::Geo.current_node.inspect" and expect something like: -``` +```ruby # ``` By running the command above, `primary` should be `true` when executed in the **primary** node, and `false` on any **secondary** node. -## How do I fix the message, "ERROR: replication slots can only be used if max_replication_slots > 0"? +## Fixing replication errors + +The following sections outline troubleshooting steps for fixing replication +errors. + +### Message: "ERROR: replication slots can only be used if max_replication_slots > 0"? This means that the `max_replication_slots` PostgreSQL variable needs to be set on the **primary** database. In GitLab 9.4, we have made this setting default to 1. You may need to increase this value if you have more -**secondary** nodes. Be sure to restart PostgreSQL for this to take +**secondary** nodes. + +Be sure to restart PostgreSQL for this to take effect. See the [PostgreSQL replication setup][database-pg-replication] guide for more details. -## How do I fix the message, "FATAL: could not start WAL streaming: ERROR: replication slot "geo_secondary_my_domain_com" does not exist"? +### Message: "FATAL: could not start WAL streaming: ERROR: replication slot "geo_secondary_my_domain_com" does not exist"? This occurs when PostgreSQL does not have a replication slot for the -**secondary** node by that name. You may want to rerun the [replication +**secondary** node by that name. + +You may want to rerun the [replication process](database.md) on the **secondary** node . -## How do I fix the message, "Command exceeded allowed execution time" when setting up replication? +### Message: "Command exceeded allowed execution time" when setting up replication? This may happen while [initiating the replication process][database-start-replication] on the **secondary** node, and indicates that your initial dataset is too large to be replicated in the default timeout (30 minutes). @@ -153,7 +177,7 @@ sudo gitlab-ctl \ This will give the initial replication up to six hours to complete, rather than the default thirty minutes. Adjust as required for your installation. -## How do I fix the message, "PANIC: could not write to file 'pg_xlog/xlogtemp.123': No space left on device" +### Message: "PANIC: could not write to file 'pg_xlog/xlogtemp.123': No space left on device" Determine if you have any unused replication slots in the **primary** database. This can cause large amounts of log data to build up in `pg_xlog`. Removing the unused slots can reduce the amount of space used in the `pg_xlog`. @@ -184,11 +208,12 @@ Slots where `active` is `f` are not active. SELECT pg_drop_replication_slot(''); ``` -## Very large repositories never successfully synchronize on the **secondary** node +### Very large repositories never successfully synchronize on the **secondary** node GitLab places a timeout on all repository clones, including project imports and Geo synchronization operations. If a fresh `git clone` of a repository on the primary takes more than a few minutes, you may be affected by this. + To increase the timeout, add the following line to `/etc/gitlab/gitlab.rb` on the **secondary** node: @@ -205,7 +230,7 @@ sudo gitlab-ctl reconfigure This will increase the timeout to three hours (10800 seconds). Choose a time long enough to accommodate a full clone of your largest repositories. -## How to reset Geo **secondary** node replication +### Reseting Geo **secondary** node replication If you get a **secondary** node in a broken state and want to reset the replication state, to start again from scratch, there are a few steps that can help you: @@ -289,12 +314,16 @@ to start again from scratch, there are a few steps that can help you: gitlab-ctl start ``` -## How do I fix a "Foreign Data Wrapper (FDW) is not configured" error? +## Fixing Foreign Data Wrapper errors + +This section documents ways to fix potential Foreign Data Wrapper errors. + +### "Foreign Data Wrapper (FDW) is not configured" error When setting up Geo, you might see this warning in the `gitlab-rake gitlab:geo:check` output: -``` +```text GitLab Geo tracking database Foreign Data Wrapper schema is up-to-date? ... foreign data wrapper is not configured ``` @@ -307,7 +336,7 @@ There are a few key points to remember: By default, the Geo secondary and tracking database are running on the same host on different ports. That is, 5432 and 5431 respectively. -### Checking configuration +#### Checking configuration NOTE: **Note:** The following steps are for Omnibus installs only. Using Geo with source-based installs was **deprecated** in GitLab 11.5. @@ -419,7 +448,7 @@ should see something like this: - `geo_postgresql['fdw_external_user']` - `geo_postgresql['fdw_external_password']` -### Manual reload of FDW schema +#### Manual reload of FDW schema If you're still unable to get FDW working, you may want to try a manual reload of the FDW schema. To manually reload the FDW schema: @@ -459,9 +488,25 @@ reload of the FDW schema. To manually reload the FDW schema: [database-start-replication]: database.md#step-3-initiate-the-replication-process [database-pg-replication]: database.md#postgresql-replication -## Common errors +### "Geo database has an outdated FDW remote schema" error + +GitLab can error with a `Geo database has an outdated FDW remote schema` message. + +For example: -This section documents common errors reported in the admin UI and how to fix them. +```text +Geo database has an outdated FDW remote schema. It contains 229 of 236 expected tables. Please refer to Geo Troubleshooting. +``` + +To resolve this, run the following command: + +```sh +sudo gitlab-rake geo:db:refresh_foreign_tables +``` + +## Fixing common errors + +This section documents common errors reported in the Admin UI and how to fix them. ### Geo database configuration file is missing @@ -470,7 +515,6 @@ GitLab cannot find or doesn't have permission to access the `database_geo.yml` c In an Omnibus GitLab installation, the file should be in `/var/opt/gitlab/gitlab-rails/etc`. If it doesn't exist or inadvertent changes have been made to it, run `sudo gitlab-ctl reconfigure` to restore it to its correct state. - If this path is mounted on a remote volume, please check your volume configuration and that it has correct permissions. ### Geo node has a database that is writable which is an indication it is not configured for replication with the primary node. @@ -503,7 +547,7 @@ Make sure you follow the [Geo database replication](database.md) instructions fo If you are using GitLab Omnibus installation, something might have failed during upgrade. You can: -- Run `sudo gitlab-ctl reconfigure`. +- Run `sudo gitlab-ctl reconfigure`. - Manually trigger the database migration by running: `sudo gitlab-rake geo:db:migrate` as root on the **secondary** node. ### Geo database is not configured to use Foreign Data Wrapper @@ -511,4 +555,4 @@ If you are using GitLab Omnibus installation, something might have failed during This error means the Geo Tracking Database doesn't have the FDW server and credentials configured. -See [How do I fix a "Foreign Data Wrapper (FDW) is not configured" error?](#how-do-i-fix-a-foreign-data-wrapper-fdw-is-not-configured-error). +See ["Foreign Data Wrapper (FDW) is not configured" error?](#foreign-data-wrapper-fdw-is-not-configured-error). -- cgit v1.2.1 From d41ed4bff3f23c33a56b9ddc27d2bd8ba468f834 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 21 Jun 2019 12:09:02 +0200 Subject: Clean up the web terminals docs - Clarify that they are available only for private Runners - Merge the two sections of file syncing into one --- doc/user/project/web_ide/index.md | 96 ++++++++++++++++++--------------------- 1 file changed, 43 insertions(+), 53 deletions(-) (limited to 'doc') diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index ef4eb45de66..b2bf85335c5 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -67,8 +67,8 @@ shows you a preview of the merge request diff if you commit your changes. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19279) in [GitLab Core][ce] 11.0. -You can use the Web IDE to quickly fix failing tests by opening -the branch or merge request in the Web IDE and opening the logs of the failed +You can use the Web IDE to quickly fix failing tests by opening +the branch or merge request in the Web IDE and opening the logs of the failed job. You can access the status of all jobs for the most recent pipeline and job traces for the current commit by clicking the **Pipelines** button in the top right. @@ -80,8 +80,8 @@ left. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19318) in [GitLab Core][ce] 11.0. -To switch between your authored and assigned merge requests, click the -dropdown in the top of the sidebar to open a list of merge requests. You will +To switch between your authored and assigned merge requests, click the +dropdown in the top of the sidebar to open a list of merge requests. You will need to commit or discard all your changes before switching to a different merge request. @@ -89,9 +89,9 @@ request. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20850) in [GitLab Core][ce] 11.2. -To switch between branches of the current project repository, click the dropdown -in the top of the sidebar to open a list of branches. -You will need to commit or discard all your changes before switching to a +To switch between branches of the current project repository, click the dropdown +in the top of the sidebar to open a list of branches. +You will need to commit or discard all your changes before switching to a different branch. ## Client Side Evaluation @@ -117,7 +117,7 @@ GitLab.com ![Admin Client Side Evaluation setting](img/admin_clientside_evaluation.png) Once you have done that, you can preview projects with a `package.json` file and -a `main` entry point inside the Web IDE. An example `package.json` is shown +a `main` entry point inside the Web IDE. An example `package.json` is shown below. ```json @@ -135,24 +135,20 @@ below. CAUTION: **Warning:** Interactive Web Terminals for the Web IDE is currently in **Beta**. +Shared Runners [do not yet support Interactive Web Terminals](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611), +so you would need to use your own private Runner(s) to make use of this feature. -[Interactive web terminals](../../../ci/interactive_web_terminal/index.md) -give the user access to a terminal to interact with the Runner directly from +[Interactive Web Terminals](../../../ci/interactive_web_terminal/index.md) +give the project [Maintainers](../../permissions.md#project-members-permissions) +user access to a terminal to interact with the Runner directly from GitLab, including through the Web IDE. -Only project [**maintainers**](../../permissions.md#project-members-permissions) -can run Interactive Web Terminals through the Web IDE. - -CAUTION: **Warning:** -GitLab.com [does not support Interactive Web Terminals yet](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611). -Shared Runners in private instances are not supported either. - ### Runner configuration Some things need to be configured in the runner for the interactive web terminal to work: -- The Runner needs to have +- The Runner needs to have [`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section). - If you are using a reverse proxy with your GitLab instance, web terminals need to be [enabled](../../../administration/integration/terminal.md#enabling-and-disabling-terminal-support). **[ULTIMATE ONLY]** @@ -204,7 +200,7 @@ the selected branch of the Web IDE. If there is no configuration file in a branch, an error message will be shown. -### Running Interactive Terminals in the Web IDE +### Running interactive terminals in the Web IDE If Interactive Terminals are available for the current user, the **Terminal** button will be visible in the right sidebar of the Web IDE. Click this button to open @@ -212,7 +208,7 @@ or close the terminal tab. Once open, the tab will show the **Start Web Terminal** button. This button may be disabled if the environment is not configured correctly. If so, a status -message will describe the issue. Here are some reasons why **Start Web Terminal** +message will describe the issue. Here are some reasons why **Start Web Terminal** may be disabled: - `.gitlab/.gitlab-webide.yml` does not exist or is set up incorrectly. @@ -231,45 +227,27 @@ While the terminal is running, it can be stopped by clicking **Stop Terminal**. This will disconnect the terminal and stop the runner's terminal job. From here, click **Restart Terminal** to start a new terminal session. -### File Syncing to Web Terminal +### File syncing to web terminal > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5276) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -File changes in the Web IDE can be synced to a running Web Terminal. +File changes in the Web IDE can be synced to a running web terminal. This enables users to test their code changes in a preconfigured terminal environment. NOTE: **Note:** Only file changes in the Web IDE are synced to the terminal. Changes made in the terminal are **not** synced to the Web IDE. +This feature is only available for Kubernetes Runners. -Once you have [configured the Web Terminal for File Syncing](#configuring-file-syncing), -then when the Web terminal is started, a **Terminal** status will be visible -in the status bar. - -![Web IDE Client Side Evaluation](img/terminal_status.png) - -Changes made to your files via the Web IDE will sync to the running terminal -when: - -- Ctrl + S (or Cmd + S on Mac) - is pressed while editing a file. -- Anything outside the file editor is clicked after editing a file. -- A file or folder is created, deleted, or renamed. - -### Configuring File Syncing - -NOTE: **Note:** -This feature is only available for Kubernetes runners. - -To enable file syncing to the Web Terminal, the `.gitlab/.gitlab-webide.yml` -file needs to have a `webide-file-sync` service configured. Here is an example +To enable file syncing to the web terminal, the `.gitlab/.gitlab-webide.yml` +file needs to have a `webide-file-sync` service configured. Here is an example configuration for a Node JS project which uses this service: ```yaml terminal: # This can be any image that has the necessary runtime environment for your project. - image: + image: name: node:10-alpine services: - name: registry.gitlab.com/gitlab-org/webide-file-sync:latest @@ -281,18 +259,30 @@ terminal: - number: 3000 ``` -> **Notes:** -> - For now, the `webide-file-sync` executable must start **after** the project -> directory is available. This is why we need to add `sleep 5` to the `command`. -> See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/issues/7) for -> more info. -> - `$CI_PROJECT_DIR` is a -> [predefined environment variable](../../../ci/variables/predefined_variables.md) -> for GitLab Runners. This is where your project's repository will be. +- The `webide-file-sync` executable must start **after** the project + directory is available. This is why we need to add `sleep 5` to the `command`. + See [this issue](https://gitlab.com/gitlab-org/webide-file-sync/issues/7) for + more info. +- `$CI_PROJECT_DIR` is a + [predefined environment variable](../../../ci/variables/predefined_variables.md) + for GitLab Runners. This is where your project's repository will be. + +Once you have configured the web terminal for file syncing, then when the web +terminal is started, a **Terminal** status will be visible in the status bar. + +![Web IDE Client Side Evaluation](img/terminal_status.png) + +Changes made to your files via the Web IDE will sync to the running terminal +when: + +- Ctrl + S (or Cmd + S on Mac) + is pressed while editing a file. +- Anything outside the file editor is clicked after editing a file. +- A file or folder is created, deleted, or renamed. ### Limitations -Interactive Terminals is in a beta phase and will continue to be improved upon in upcoming +Interactive Terminals is in a beta phase and will continue to be improved upon in upcoming releases. In the meantime, please note that the user is limited to having only one active terminal at a time. -- cgit v1.2.1 From 511e67e5ab820c85ac6edb2fa7b214cdcd4bf30c Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 21 Jun 2019 14:05:03 +0000 Subject: Mention Container Scanning NFS bug and how to fix it --- .../application_security/container_scanning/index.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'doc') diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index a24374dff1d..4a2fb1d7190 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -40,6 +40,9 @@ To enable Container Scanning in your pipeline, you need: [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html#running-privileged-containers-for-the-runners) executor running in privileged mode. If you're using the shared Runners on GitLab.com, this is enabled by default. +- Docker `18.09.03` or higher installed on the machine where the Runners are + running. If you're using the shared Runners on GitLab.com, this is already + the case. - To [build and push](../../../ci/docker/using_docker_build.md#container-registry-examples) your Docker image to your project's [Container Registry](../../project/container_registry.md). The name of the Docker image should match the following scheme: @@ -202,3 +205,20 @@ vulnerabilities in your groups and projects. Read more about the Once a vulnerability is found, you can interact with it. Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). + +## Troubleshooting + +### docker: Error response from daemon: failed to copy xattrs + +When the GitLab Runner uses the Docker executor and NFS is used +(e.g., `/var/lib/docker` is on an NFS mount), Container Scanning might fail with +an error like the following: + +``` +docker: Error response from daemon: failed to copy xattrs: failed to set xattr "security.selinux" on /path/to/file: operation not supported. +``` + +This is a result of a bug in Docker which is now [fixed](https://github.com/containerd/continuity/pull/138 "fs: add WithAllowXAttrErrors CopyOpt"). +To prevent the error, ensure the Docker version that the Runner is using is +`18.09.03` or higher. For more information, see +[issue #10241](https://gitlab.com/gitlab-org/gitlab-ee/issues/10241 "Investigate why Container Scanning is not working with NFS mounts"). -- cgit v1.2.1 From 10a612274420ef2e53f34517927378ad0ec43e1f Mon Sep 17 00:00:00 2001 From: Aric Buerer Date: Fri, 21 Jun 2019 15:55:57 +0000 Subject: Adding documentation for Prometheus Service Discovery Updating documentation to include Prometheus Service Discovery. Added monitoring node documentaiton as well as documentation for the individual service nodes. --- doc/administration/high_availability/README.md | 6 ++ doc/administration/high_availability/database.md | 23 +++++++- doc/administration/high_availability/gitaly.md | 25 ++++++++ doc/administration/high_availability/gitlab.md | 45 ++++++++++++++- .../high_availability/monitoring_node.md | 67 ++++++++++++++++++++++ doc/administration/high_availability/redis.md | 28 +++++++++ 6 files changed, 192 insertions(+), 2 deletions(-) create mode 100644 doc/administration/high_availability/monitoring_node.md (limited to 'doc') diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md index d9c80b1ec59..0c4f926c579 100644 --- a/doc/administration/high_availability/README.md +++ b/doc/administration/high_availability/README.md @@ -65,6 +65,7 @@ larger one. - 1 Redis node - 1 NFS/Gitaly storage server - 2 or more GitLab application nodes (Unicorn, Workhorse, Sidekiq) +- 1 Monitoring node (Prometheus, Grafana) #### Installation Instructions @@ -76,6 +77,7 @@ you can continue with the next step. 1. [Redis](redis.md#redis-in-a-scaled-environment) 1. [Gitaly](gitaly.md) (recommended) or [NFS](nfs.md) 1. [GitLab application nodes](gitlab.md) +1. [Monitoring node (Prometheus and Grafana)](monitoring_node.md) ### Full Scaling @@ -90,6 +92,7 @@ in size, indicating that there is contention or not enough resources. - 2 or more NFS/Gitaly storage servers - 2 or more Sidekiq nodes - 2 or more GitLab application nodes (Unicorn, Workhorse) +- 1 Monitoring node (Prometheus, Grafana) ## High Availability Architecture Examples @@ -133,6 +136,7 @@ the contention. - 3 Consul/Sentinel nodes - 2 or more GitLab application nodes (Unicorn, Workhorse, Sidekiq, PGBouncer) - 1 NFS/Gitaly server +- 1 Monitoring node (Prometheus, Grafana) ![Horizontal architecture diagram](img/horizontal.png) @@ -192,6 +196,7 @@ with the added complexity of many more nodes to configure, manage and monitor. - 2 or more API nodes (All requests to `/api`) - 2 or more Web nodes (All other web requests) - 2 or more NFS/Gitaly servers +- 1 Monitoring node (Prometheus, Grafana) ![Fully Distributed architecture diagram](img/fully-distributed.png) @@ -205,4 +210,5 @@ separately: 1. [NFS Client and Host setup](nfs_host_client_setup.md) 1. [Configure the GitLab application servers](gitlab.md) 1. [Configure the load balancers](load_balancer.md) +1. [Monitoring node (Prometheus and Grafana)](monitoring_node.md) diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index 2c051b660ee..4db53353218 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -82,7 +82,8 @@ deploy the bundled PostgreSQL. 1. Note the PostgreSQL node's IP address or hostname, port, and plain text password. These will be necessary when configuring the GitLab application servers later. - +1. [Enable monitoring](#enable-monitoring) + Advanced configuration options are supported and can be added if needed. @@ -399,6 +400,7 @@ check the [Troubleshooting section](#troubleshooting) before proceeding. ``` 1. [Reconfigure GitLab] for the changes to take effect. +1. [Enable Monitoring](#enable-monitoring) > Please note: > @@ -1086,6 +1088,25 @@ the previous section: the `gitlab` database user 1. [Reconfigure GitLab] for the changes to take effect +## Enable Monitoring + +> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0. + +If you enable Monitoring, it must be enabled on **all** database servers. + +1. Create/edit `/etc/gitlab/gitlab.rb` and add the following configuration: + + ```ruby + # Enable service discovery for Prometheus + consul['monitoring_service_discovery'] = true + + # Set the network addresses that the exporters will listen on + node_exporter['listen_address'] = '0.0.0.0:9100' + postgres_exporter['listen_address'] = '0.0.0.0:9187' + ``` + +1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. + ## Troubleshooting #### Consul and PostgreSQL changes not taking effect. diff --git a/doc/administration/high_availability/gitaly.md b/doc/administration/high_availability/gitaly.md index 1d8e6c999cb..90e5f71d835 100644 --- a/doc/administration/high_availability/gitaly.md +++ b/doc/administration/high_availability/gitaly.md @@ -19,3 +19,28 @@ Continue configuration of other components by going back to: - [Scaled Architectures](README.md#scalable-architecture-examples) - [High Availability Architectures](README.md#high-availability-architecture-examples) + +## Enable Monitoring + +> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0. + + 1. Create/edit `/etc/gitlab/gitlab.rb` and add the following configuration: + + ```ruby + # Enable service discovery for Prometheus + consul['enable'] = true + consul['monitoring_service_discovery'] = true + + # Replace placeholders + # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z + # with the addresses of the Consul server nodes + consul['configuration'] = { + retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z), + } + + # Set the network addresses that the exporters will listen on + node_exporter['listen_address'] = '0.0.0.0:9100' + gitaly['prometheus_listen_addr'] = "0.0.0.0:9236" + ``` + + 1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md index 7e3ff741071..0e655e49922 100644 --- a/doc/administration/high_availability/gitlab.md +++ b/doc/administration/high_availability/gitlab.md @@ -76,6 +76,8 @@ registry['gid'] = 9002 ``` +1. [Enable monitoring](#enable-monitoring) + > **Note:** To maintain uniformity of links across HA clusters, the `external_url` on the first application server as well as the additional application servers should point to the external url that users will use to access GitLab. @@ -88,7 +90,8 @@ [Nginx documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for more information. > - > **Note:** It is best to set the `uid` and `gid`s prior to the initial reconfigure of GitLab. Omnibus will not recursively `chown` directories if set after the initial reconfigure. + > **Note:** It is best to set the `uid` and `gid`s prior to the initial reconfigure + of GitLab. Omnibus will not recursively `chown` directories if set after the initial reconfigure. ## First GitLab application server @@ -129,6 +132,46 @@ need some extra configuration. 1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. +## Enable Monitoring + +> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0. + +If you enable Monitoring, it must be enabled on **all** GitLab servers. + +1. Create/edit `/etc/gitlab/gitlab.rb` and add the following configuration: + + ```ruby + # Enable service discovery for Prometheus + consul['enable'] = true + consul['monitoring_service_discovery'] = true + + # Replace placeholders + # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z + # with the addresses of the Consul server nodes + consul['configuration'] = { + retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z), + } + + # Set the network addresses that the exporters will listen on + node_exporter['listen_address'] = '0.0.0.0:9100' + gitlab_workhorse['prometheus_listen_addr'] = '0.0.0.0:9229' + sidekiq['listen_address'] = "0.0.0.0" + unicorn['listen'] = '0.0.0.0' + + # Add the monitoring node's IP address to the monitoring whitelist and allow it to scrape the NGINX metrics + # Replace placeholder + # monitoring.gitlab.example.com + # with the addresses gathered for the monitoring node + gitlab_rails['monitoring_whitelist'] = ['monitoring.gitlab.example.com'] + nginx['status']['options']['allow'] = ['monitoring.gitlab.example.com'] + ``` + +1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. + +> **Warning:** After changing `unicorn['listen']` in `gitlab.rb`, and running `sudo gitlab-ctl reconfigure`, + it can take an extended period of time for unicorn to complete reloading after receiving a `HUP`. + For more information, see the [issue](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/4401). + ## Troubleshooting - `mount: wrong fs type, bad option, bad superblock on` diff --git a/doc/administration/high_availability/monitoring_node.md b/doc/administration/high_availability/monitoring_node.md new file mode 100644 index 00000000000..d16bf7dc0f0 --- /dev/null +++ b/doc/administration/high_availability/monitoring_node.md @@ -0,0 +1,67 @@ +# Configuring a Monitoring node for Scaling and High Availability + +> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0. + +## Standalone Monitoring node using GitLab Omnibus + +The GitLab Omnibus package can be used to configure a standalone Monitoring node running Prometheus and Grafana. +The monitoring node is not highly available. See [Scaling and High Availability](README.md) +for an overview of GitLab scaling and high availability options. + +The steps below are the minimum necessary to configure a Monitoring node running Prometheus and Grafana with +Omnibus: + +1. SSH into the Monitoring node. +1. [Download/install](https://about.gitlab.com/installation) the Omnibus GitLab + package you want using **steps 1 and 2** from the GitLab downloads page. + - Do not complete any other steps on the download page. + +1. Edit `/etc/gitlab/gitlab.rb` and add the contents: + + ```ruby + external_url 'http://gitlab.example.com' + + # Enable Prometheus + prometheus['enable'] = true + prometheus['listen_address'] = '0.0.0.0:9090' + prometheus['monitor_kubernetes'] = false + + # Enable Grafana + grafana['enable'] = true + grafana['admin_password'] = 'toomanysecrets' + + # Enable service discovery for Prometheus + consul['enable'] = true + consul['monitoring_service_discovery'] = true + + # Replace placeholders + # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z + # with the addresses of the Consul server nodes + consul['configuration'] = { + retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z), + } + + # Disable all other services + gitlab_rails['auto_migrate'] = false + alertmanager['enable'] = false + gitaly['enable'] = false + gitlab_monitor['enable'] = false + gitlab_workhorse['enable'] = false + nginx['enable'] = true + postgres_exporter['enable'] = false + postgresql['enable'] = false + redis['enable'] = false + redis_exporter['enable'] = false + sidekiq['enable'] = false + unicorn['enable'] = false + node_exporter['enable'] = false + ``` + +1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. + +## Migrating to Service Discovery + +Once monitoring using Service Discovery is enabled with `consul['monitoring_service_discovery'] = true`, +ensure that `prometheus['scrape_configs']` is not set in `/etc/gitlab/gitlab.rb`. Setting both +`consul['monitoring_service_discovery'] = true` and `prometheus['scrape_configs']` in `/etc/gitlab/gitlab.rb` +will result in errors. diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index 1aaa709fc8f..f61a8834af3 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -74,6 +74,7 @@ Omnibus: 1. Note the Redis node's IP address or hostname, port, and Redis password. These will be necessary when configuring the GitLab application servers later. +1. [Enable Monitoring](#enable-monitoring) Advanced configuration options are supported and can be added if needed. @@ -749,6 +750,33 @@ gitlab_rails['redis_sentinels'] = [ [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect. +## Enable Monitoring + +> [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0. + + If you enable Monitoring, it must be enabled on **all** Redis servers. + + 1. Create/edit `/etc/gitlab/gitlab.rb` and add the following configuration: + + ```ruby + # Enable service discovery for Prometheus + consul['enable'] = true + consul['monitoring_service_discovery'] = true + + # Replace placeholders + # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z + # with the addresses of the Consul server nodes + consul['configuration'] = { + retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z), + } + + # Set the network addresses that the exporters will listen on + node_exporter['listen_address'] = '0.0.0.0:9100' + redis_exporter['listen_address'] = '0.0.0.0:9121' + ``` + + 1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. + ## Advanced configuration Omnibus GitLab configures some things behind the curtains to make the sysadmins' -- cgit v1.2.1 From a84a7233e33f967a51b7dd85413f46bd80370643 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 21 Jun 2019 18:04:29 +0200 Subject: Remove Gemnasium dead link from docs --- .../application_security/dependency_scanning/index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 34d4507210e..a4e5b19bdc7 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -346,7 +346,7 @@ the report JSON unless stated otherwise. Presence of optional fields depends on | `vulnerabilities[].scanner` | A node that describes the analyzer used to find this vulnerability. | | `vulnerabilities[].scanner.id` | Id of the scanner as a snake_case string. | | `vulnerabilities[].scanner.name` | Name of the scanner, for display purposes. | -| `vulnerabilities[].location` | A node that tells where the vulnerability is located. | +| `vulnerabilities[].location` | A node that tells where the vulnerability is located. | | `vulnerabilities[].location.file` | Path to the dependencies file (e.g., `yarn.lock`). Optional. | | `vulnerabilities[].location.dependency` | A node that describes the dependency of a project where the vulnerability is located. | | `vulnerabilities[].location.dependency.package` | A node that provides the information on the package where the vulnerability is located. | @@ -379,17 +379,17 @@ Once a vulnerability is found, you can interact with it. Read more on how to ## Dependency List -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10075) -in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10075) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. -An additional benefit of Dependency Scanning is the ability to get a list of your project's dependencies with their versions. +An additional benefit of Dependency Scanning is the ability to get a list of your +project's dependencies with their versions. This list can be generated only for +[languages and package managers](#supported-languages-and-package-managers) +supported by Gemnasium. -This list can be generated only for [languages and package managers](#supported-languages-and-package-managers) supported by [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general). - -To see the generated dependency list, navigate to the Dependency List page under your project's left sidebar menu **Project > Dependency List**. +To see the generated dependency list, navigate to your project's **Project > Dependency List**. ## Contributing to the vulnerability database You can search the [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project to find a vulnerability in the Gemnasium database. -You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). \ No newline at end of file +You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md). -- cgit v1.2.1 From be2bd9775247cd378e8d9557c6fdf6f47293fb7b Mon Sep 17 00:00:00 2001 From: Marcia Ramos Date: Mon, 24 Jun 2019 01:20:29 +0000 Subject: Docs: link to predefined env variables reference more evident --- doc/ci/variables/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index df455857dee..eccaab15e9b 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -27,8 +27,7 @@ CI/CD's pipelines. Using variables means no hardcoded values. ### Predefined environment variables -GitLab CI/CD has a default set of -[predefined variables](predefined_variables.md) +GitLab CI/CD has a [default set of predefined variables](predefined_variables.md) which can be used without any specification needed. You can call issues numbers, user names, branch names, pipeline and commit IDs, and much more. @@ -36,7 +35,7 @@ pipeline and commit IDs, and much more. Predefined environment variables are the ones that GitLab provides out of the box for the local environment of the Runner. -GitLab reads the .gitlab-ci.yml file, sends the information +GitLab reads the `.gitlab-ci.yml` file, sends the information to the Runner (which runs the script commands), under which the variables are exposed. @@ -44,6 +43,9 @@ For example, two jobs under the same pipeline can share the same `CI_PIPELINE_ID` variable, but each one has its own `CI_JOB_ID` variable. +NOTE: **Note:** +Find here the full [**predefined variables reference table**](predefined_variables.md). + ### Custom environment variables When your use case requires a specific variable, you can -- cgit v1.2.1 From 22cfb8588ce0752c11397eae158a935709fe533d Mon Sep 17 00:00:00 2001 From: Stan Hu Date: Sun, 23 Jun 2019 23:48:52 -0700 Subject: Remove requirement for personal access token in profiling Since https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23320, personal access tokens are no longer needed for profiling an endpoint since users are stubbed directly. --- doc/development/profiling.md | 4 ---- 1 file changed, 4 deletions(-) (limited to 'doc') diff --git a/doc/development/profiling.md b/doc/development/profiling.md index b2f3a105b23..795523b82aa 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -38,10 +38,6 @@ For routes that require authorization you will need to provide a user to Gitlab::Profiler.profile('/gitlab-org/gitlab-test', user: User.first) ``` -The user you provide will need to have a [personal access -token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html) in -the GitLab instance. - Passing a `logger:` keyword argument to `Gitlab::Profiler.profile` will send ActiveRecord and ActionController log output to that logger. Further options are documented with the method source. -- cgit v1.2.1 From 9ef27250a0812af77f162e0601bb2d9e6debd700 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Mon, 24 Jun 2019 08:26:39 +0000 Subject: Refactor and add version text to variable syntax --- doc/ci/variables/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index eccaab15e9b..c8c92002be2 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -482,7 +482,7 @@ Below you can find supported syntax reference: > Example: `$VARIABLE == "some value"` - > Example: `$VARIABLE != "some value"` _(added in 11.11)_ + > Example: `$VARIABLE != "some value"` (introduced in GitLab 11.11) You can use equality operator `==` or `!=` to compare a variable content to a string. We support both, double quotes and single quotes to define a string @@ -493,7 +493,7 @@ Below you can find supported syntax reference: > Example: `$VARIABLE == null` - > Example: `$VARIABLE != null` _(added in 11.11)_ + > Example: `$VARIABLE != null` (introduced in GitLab 11.11) It sometimes happens that you want to check whether a variable is defined or not. To do that, you can compare a variable to `null` keyword, like @@ -504,7 +504,7 @@ Below you can find supported syntax reference: > Example: `$VARIABLE == ""` - > Example: `$VARIABLE != ""` _(added in 11.11)_ + > Example: `$VARIABLE != ""` (introduced in GitLab 11.11) If you want to check whether a variable is defined, but is empty, you can simply compare it against an empty string, like `$VAR == ''` or non-empty @@ -514,7 +514,7 @@ Below you can find supported syntax reference: > Example: `$VARIABLE_1 == $VARIABLE_2` - > Example: `$VARIABLE_1 != $VARIABLE_2` _(added in 11.11)_ + > Example: `$VARIABLE_1 != $VARIABLE_2` (introduced in GitLab 11.11) It is possible to compare two variables. This is going to compare values of these variables. @@ -530,11 +530,11 @@ Below you can find supported syntax reference: `$STAGING` value needs to a string, with length higher than zero. Variable that contains only whitespace characters is not an empty variable. -1. Pattern matching _(added in 11.0)_ +1. Pattern matching (introduced in GitLab 11.0) > Example: `$VARIABLE =~ /^content.*/` - > Example: `$VARIABLE_1 !~ /^content.*/` _(added in 11.11)_ + > Example: `$VARIABLE_1 !~ /^content.*/` (introduced in GitLab 11.11) It is possible perform pattern matching against a variable and regular expression. Expression like this evaluates to truth if matches are found @@ -543,7 +543,7 @@ Below you can find supported syntax reference: Pattern matching is case-sensitive by default. Use `i` flag modifier, like `/pattern/i` to make a pattern case-insensitive. -1. Conjunction / Disjunction +1. Conjunction / Disjunction ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27925) in GitLab 12.0) > Example: `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"` -- cgit v1.2.1 From 60cd12a6d7d268b6f745c7208abe2273d8aa835f Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 7 Jun 2019 12:48:46 +0200 Subject: Document all the available options for Dependency Scanning Port all info from: - security-products/dependency-scanning/blob/master/docs/README.md - security-products/dependency-scanning/blob/master/docs/analyzers.md --- .../dependency_scanning/analyzers.md | 133 +++++++++++++++++++++ .../dependency_scanning/index.md | 54 +++++++-- 2 files changed, 174 insertions(+), 13 deletions(-) create mode 100644 doc/user/application_security/dependency_scanning/analyzers.md (limited to 'doc') diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md new file mode 100644 index 00000000000..937ded287e5 --- /dev/null +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -0,0 +1,133 @@ +# Dependency Scanning Analyzers **[ULTIMATE]** + +Dependency Scanning relies on underlying third party tools that are wrapped into +what we call "Analyzers". An analyzer is a +[dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers) +that wraps a particular tool to: + +- Expose its detection logic. +- Handle its execution. +- Convert its output to the common format. + +This is achieved by implementing the [common API](https://gitlab.com/gitlab-org/security-products/analyzers/common). + +Dependency Scanning supports the following official analyzers: + +- [`bundler-audit`](https://gitlab.com/gitlab-org/security-products/analyzers/bundler-audit) +- [`gemnasium`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) +- [`gemnasium-maven`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven) +- [`gemnasium-python`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python) +- [`retire.js`](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) + +The analyzers are published as Docker images that Dependency Scanning will use +to launch dedicated containers for each analysis. + +Dependency Scanning is pre-configured with a set of **default images** that are +maintained by GitLab, but users can also integrate their own **custom images**. + +## Official default analyzers + +Any custom change to the official analyzers can be achieved by using an +[environment variable in your `.gitlab-ci.yml`](index.md#customizing-the-dependency-scanning-settings). + +### Using a custom Docker mirror + +You can switch to a custom Docker registry that provides the official analyzer +images under a different prefix. For instance, the following instructs Dependency +Scanning to pull `my-docker-registry/gl-images/gemnasium` +instead of `registry.gitlab.com/gitlab-org/security-products/analyzers/gemnasium`. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_ANALYZER_IMAGE_PREFIX: my-docker-registry/gl-images +``` + +This configuration requires that your custom registry provides images for all +the official analyzers. + +### Selecting specific analyzers + +You can select the official analyzers you want to run. Here's how to enable +`bundler-audit` and `gemnasium` while disabling all the other default ones. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_DEFAULT_ANALYZERS: "bundler-audit,gemnasium" +``` + +`bundler-audit` runs first. When merging the reports, Dependency Scanning will +remove the duplicates and will keep the `bundler-audit` entries. + +### Disabling default analyzers + +Setting `DS_DEFAULT_ANALYZERS` to an empty string will disable all the official +default analyzers. In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_DEFAULT_ANALYZERS: "" +``` + +That's needed when one totally relies on [custom analyzers](#custom-analyzers). + +## Custom analyzers + +You can provide your own analyzers as a comma separated list of Docker images. +Here's how to add `analyzers/nugget` and `analyzers/perl` to the default images. +In `.gitlab-ci.yml` define: + +```yaml +include: + template: Dependency-Scanning.gitlab-ci.yml + +variables: + DS_ANALYZER_IMAGES: "my-docker-registry/analyzers/nugget,amy-docker-registry/nalyzers/perl" +``` + +The values must be the full path to the container registry images, +like what you would feed to the `docker pull` command. + +NOTE: **Note:** +This configuration doesn't benefit from the integrated detection step. Dependency +Scanning has to fetch and spawn each Docker image to establish whether the +custom analyzer can scan the source code. + +## Analyzers data + +The following table lists the data available for each official analyzer. + +| Property \ Tool | Gemnasium | bundler-audit | Retire.js | +|---------------------------------------|:------------------:|:------------------:|:------------------:| +| Severity | 𐄂 | ✓ | ✓ | +| Title | ✓ | ✓ | ✓ | +| File | ✓ | ⚠ | ✓ | +| Start line | 𐄂 | 𐄂 | 𐄂 | +| End line | 𐄂 | 𐄂 | 𐄂 | +| External ID (e.g., CVE) | ✓ | ✓ | ⚠ | +| URLs | ✓ | ✓ | ✓ | +| Internal doc/explanation | ✓ | 𐄂 | 𐄂 | +| Solution | ✓ | ✓ | 𐄂 | +| Confidence | 𐄂 | 𐄂 | 𐄂 | +| Affected item (e.g. class or package) | ✓ | ✓ | ✓ | +| Source code extract | 𐄂 | 𐄂 | 𐄂 | +| Internal ID | ✓ | 𐄂 | 𐄂 | +| Date | ✓ | 𐄂 | 𐄂 | +| Credits | ✓ | 𐄂 | 𐄂 | + +- ✓ => we have that data +- ⚠ => we have that data but it's partially reliable, or we need to extract that data from unstructured content +- 𐄂 => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. + +The values provided by these tools are heterogeneous so they are sometimes +normalized into common values (e.g., `severity`, `confidence`, etc). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index a4e5b19bdc7..dc86e66cb4f 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -54,9 +54,22 @@ The following languages and dependency managers are supported. | Java ([Maven](https://maven.apache.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | | PHP ([Composer](https://getcomposer.org/)) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium/general) | -Some scanners require to send a list of project dependencies to GitLab's central -servers to check for vulnerabilities. To learn more about this or to disable it, -refer to the [GitLab Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks). +## Remote checks + +While some tools pull a local database to check vulnerabilities, some others +like Gemnasium require sending data to GitLab central servers to analyze them: + +1. Gemnasium scans the dependencies of your project locally and sends a list of + packages to GitLab central servers. +1. The servers return the list of known vulnerabilities for all versions of + these packages. +1. The client picks up the relevant vulnerabilities by comparing with the versions + of the packages that are used by the project. + +The Gemnasium client does **NOT** send the exact package versions your project relies on. + +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 @@ -97,17 +110,10 @@ The report will be saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest Dependency Scanning artifact available. -Some security scanners require to send a list of project dependencies to GitLab -central servers to check for vulnerabilities. To learn more about this or to -disable it, check the -[GitLab Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#remote-checks). - #### Customizing the Dependency Scanning settings -The Dependency Scanning settings can be changed through environment variables by using the +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`. -These variables are documented in the -[Dependency Scanning tool documentation](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings). For example: @@ -116,7 +122,7 @@ include: template: Dependency-Scanning.gitlab-ci.yml variables: - DEP_SCAN_DISABLE_REMOTE_CHECKS: true + DS_DISABLE_REMOTE_CHECKS: true ``` Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline @@ -137,6 +143,24 @@ dependency_scanning: CI_DEBUG_TRACE: "true" ``` +#### Available variables + +Dependency Scanning can be [configured](#customizing-the-dependency-scanning-settings) +using environment variables. + +| Environment variable | Function | +|-------------------------------- |----------| +| `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_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). | +| `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, file or folder paths. Parent directories will also match patterns. | +| `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` @@ -171,7 +195,7 @@ dependency_scanning: dependency_scanning: gl-dependency-scanning-report.json ``` -You can supply many other [settings variables](https://gitlab.com/gitlab-org/security-products/dependency-scanning#settings) +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) @@ -388,6 +412,10 @@ supported by Gemnasium. To see the generated dependency list, navigate to your project's **Project > Dependency List**. +## Versioning and release process + +Please check the [Release Process documentation](https://gitlab.com/gitlab-org/security-products/release/blob/master/docs/release_process.md). + ## Contributing to the vulnerability database You can search the [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project -- cgit v1.2.1 From 28891a929d4c602d5d007f7a13ec1f2c435360c3 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Mon, 24 Jun 2019 08:47:38 +0000 Subject: Add to list of functionality --- doc/user/admin_area/settings/visibility_and_access_controls.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index a1229484388..63879935fd8 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -4,12 +4,15 @@ type: reference # Visibility and access controls -GitLab allows admins to: +GitLab allows administrators to: - Control access and visibility to GitLab resources including branches and projects. - Select from which hosting sites code can be imported into GitLab. - Select the protocols permitted to access GitLab. - Enable or disable repository mirroring. +- Prevent non-administrators from deleting projects + ([introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5615) in GitLab 12.0). + **[PREMIUM ONLY]** To access the visibility and access control options: -- cgit v1.2.1 From ec66f1b5ca20764abe21524792480755b614dbc7 Mon Sep 17 00:00:00 2001 From: Lee Tickett Date: Mon, 24 Jun 2019 12:18:40 +0000 Subject: Add name & search parameters to project environments API --- doc/api/environments.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/api/environments.md b/doc/api/environments.md index ebcdc546d08..44f86861ff7 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -11,9 +11,11 @@ GET /projects/:id/environments | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `name` | string | no | Return the environment with this name. Mutually exclusive with `search` | +| `search` | string | no | Return list of environments matching the search criteria. Mutually exclusive with `name` | ```bash -curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/projects/1/environments +curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/projects/1/environments?name=review%2Ffix-foo ``` Example response: -- cgit v1.2.1 From 942b38d5af047bfcbf10f42a4e553caf8d305bc2 Mon Sep 17 00:00:00 2001 From: Andreas Brandl Date: Mon, 24 Jun 2019 16:53:16 +0000 Subject: Require database reviews for migrations --- doc/development/code_review.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc') diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 29e2aa1a581..6123f9f845a 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -60,6 +60,8 @@ from teams other than your own. 1. If your merge request includes backend changes [^1], it must be **approved by a [backend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_backend)**. + 1. If your merge request includes database migrations or changes to expensive queries [^2], it must be + **approved by a [database maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_database)**. 1. If your merge request includes frontend changes [^1], it must be **approved by a [frontend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce_maintainers_frontend)**. 1. If your merge request includes UX changes [^1], it must be @@ -377,3 +379,4 @@ Largely based on the [thoughtbot code review guide]. [team]: https://about.gitlab.com/team/ [build handbook]: https://about.gitlab.com/handbook/build/handbook/build#how-to-work-with-build [^1]: Please note that specs other than JavaScript specs are considered backend code. +[^2]: We encourage you to seek guidance from a database maintainer if your merge request is potentially introducing expensive queries. It is most efficient to comment on the line of code in question with the SQL queries so they can give their advice. -- cgit v1.2.1 From b32f7d489136e3172967f1031d5ca58aacd26cab Mon Sep 17 00:00:00 2001 From: Lin Jen-Shin Date: Mon, 24 Jun 2019 17:24:25 +0000 Subject: Add doc for ServiceResponse --- doc/development/reusing_abstractions.md | 36 +++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'doc') diff --git a/doc/development/reusing_abstractions.md b/doc/development/reusing_abstractions.md index 01cedf734fb..59da02ed6fd 100644 --- a/doc/development/reusing_abstractions.md +++ b/doc/development/reusing_abstractions.md @@ -127,6 +127,42 @@ Everything in `lib/api`. Everything that resides in `app/services`. +#### ServiceResponse + +Service classes usually have an `execute` method, which can return a +`ServiceResponse`. You can use `ServiceResponse.success` and +`ServiceResponse.error` to return a response in `execute` method. + +In a successful case: + +``` ruby +response = ServiceResponse.success(message: 'Branch was deleted') + +response.success? # => true +response.error? # => false +response.status # => :success +response.message # => 'Branch was deleted' +``` + +In a failed case: + +``` ruby +response = ServiceResponse.error(message: 'Unsupported operation') + +response.success? # => false +response.error? # => true +response.status # => :error +response.message # => 'Unsupported operation' +``` + +An additional payload can also be attached: + +``` ruby +response = ServiceResponse.success(payload: { issue: issue }) + +response.payload[:issue] # => issue +``` + ### Finders Everything in `app/finders`, typically used for retrieving data from a database. -- cgit v1.2.1 From 90c27ea52ada6bc3f3a18bcf61f9c034c8cb65ba Mon Sep 17 00:00:00 2001 From: Tiger Date: Wed, 22 May 2019 13:55:15 -0500 Subject: Move terminal construction logic to Environment This enables terminals for group and project level clusters. Previously there was no way to determine which project (and therefore kubernetes namespace) to connect to, moving this logic onto Environment means the assoicated project can be used to look up the correct namespace. --- doc/user/group/clusters/index.md | 8 -------- 1 file changed, 8 deletions(-) (limited to 'doc') diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 26d764fa2cf..8d4ffd93f59 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -138,14 +138,6 @@ The result will then be: - The Staging cluster will be used for the `deploy to staging` job. - The Production cluster will be used for the `deploy to production` job. -## Unavailable features - -The following features are not currently available for group-level clusters: - -1. Terminals (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55487)). -1. Pod logs (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55488)). -1. Deployment boards (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55489)). - - - Roses are red [followed by two or more spaces] - Violets are blue +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#colors). - Sugar is sweet +It is possible to have color written in HEX, RGB or HSL format rendered with a color +indicator. - - -Roses are red -Violets are blue +Supported formats (named colors are not supported): -Sugar is sweet +- HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` `` +- RGB: `` `RGB[A](R, G, B[, A])` `` +- HSL: `` `HSL[A](H, S, L[, A])` `` -### Multiple underscores in words +Color written inside backticks will be followed by a color "chip": -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words +```markdown +`#F00` +`#F00A` +`#FF0000` +`#FF0000AA` +`RGB(0,255,0)` +`RGB(0%,100%,0%)` +`RGBA(0,255,0,0.3)` +`HSL(540,70%,50%)` +`HSLA(540,70%,50%,0.3)` +``` -It is not reasonable to italicize just _part_ of a word, especially when you're -dealing with code and names that often appear with multiple underscores. -Therefore, GFM ignores multiple underscores in words: +`#F00` +`#F00A` +`#FF0000` +`#FF0000AA` +`RGB(0,255,0)` +`RGB(0%,100%,0%)` +`RGBA(0,255,0,0.3)` +`HSL(540,70%,50%)` +`HSLA(540,70%,50%,0.3)` - perform_complicated_task +### Diagrams and flowcharts using Mermaid - do_this_and_do_that_and_another_thing +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15107) in +GitLab 10.3. -perform_complicated_task +It is possible to generate diagrams and flowcharts from text using [Mermaid](https://mermaidjs.github.io/). +Visit the official page for more details. -do_this_and_do_that_and_another_thing +In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block: -### URL auto-linking +~~~ +```mermaid +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` +~~~ -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#url-auto-linking +```mermaid +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` -GFM will autolink almost any URL you copy and paste into your text: +### Emoji - * https://www.google.com - * https://google.com/ - * ftp://ftp.us.debian.org/debian/ - * smb://foo/bar/baz - * irc://irc.freenode.net/gitlab - * http://localhost:3000 +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji). -* https://www.google.com -* https://google.com/ -* ftp://ftp.us.debian.org/debian/ -* smb://foo/bar/baz -* irc://irc.freenode.net/gitlab -* http://localhost:3000 +```md +Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: -### Multiline blockquote +:zap: You can use emoji anywhere GFM is supported. :v: -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote +You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. -On top of standard Markdown [blockquotes](#blockquotes), which require prepending `>` to quoted lines, -GFM supports multiline blockquotes fenced by >>>: +If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes. +Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: ``` ->>> -If you paste a message from somewhere else -that +Sometimes you want to around a bit and add some to your . Well we have a gift for you: -spans +You can use emoji anywhere GFM is supported. -multiple lines, +You can use it to point out a or warn about patches. And if someone improves your really code, send them some . People will you for that. -you can quote that without having to manually prepend `>` to every line! ->>> -``` +If you are new to this, don't be . You can easily join the emoji . All you need to do is to look up one of the supported codes. -
-

If you paste a message from somewhere else

-

that

-

spans

-

multiple lines,

-

you can quote that without having to manually prepend > to every line!

-
+Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. -### Code and syntax highlighting +> **Note:** The emoji example above uses hard-coded images for this documentation. The emoji, +when rendered within GitLab, may appear different depending on the OS and browser used. -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting +Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. -_GitLab uses the [Rouge Ruby library][rouge] for syntax highlighting. For a -list of supported languages visit the Rouge website._ +NOTE: **Note:** On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) +to get full native emoji support. Ubuntu 18.04 (like many modern Linux distros) has +this font installed by default. -Blocks of code are either fenced by lines with three back-ticks ```, -or are indented with four spaces. Only the fenced code blocks support syntax -highlighting: +### Front matter -``` -Inline `code` has `back-ticks around` it. -``` +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23331) + in GitLab 11.6. -Inline `code` has `back-ticks around` it. +Front matter is metadata included at the beginning of a markdown document, preceding +its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/), +[Hugo](https://gohugo.io/content-management/front-matter/), and many other applications. -Example: +When you view a Markdown file rendered by GitLab, any front matter is displayed as-is, +in a box at the top of the document, before the rendered HTML content. To view an example, +you can toggle between the source and rendered version of a [GitLab documentation file](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/README.md). - ```javascript - var s = "JavaScript syntax highlighting"; - alert(s); - ``` +In GitLab, front matter is only used in Markdown files and wiki pages, not the other +places where Markdown formatting is supported. It must be at the very top of the document, +and must be between delimiters, as explained below. - ```python - def function(): - #indenting works just fine in the fenced code block - s = "Python syntax highlighting" - print s - ``` +The following delimeters are supported: - ```ruby - require 'redcarpet' - markdown = Redcarpet.new("Hello World!") - puts markdown.to_html - ``` +- YAML (`---`): - ``` - No language indicated, so no syntax highlighting. - s = "There is no highlighting for this." - But let's throw in a tag. - ``` + ~~~yaml + --- + title: About Front Matter + example: + language: yaml + --- + ~~~ -becomes: +- TOML (`+++`): -```javascript -var s = "JavaScript syntax highlighting"; -alert(s); -``` + ~~~toml + +++ + title = "About Front Matter" + [example] + language = "toml" + +++ + ~~~ -```python -def function(): - #indenting works just fine in the fenced code block - s = "Python syntax highlighting" - print s -``` +- JSON (`;;;`): -```ruby -require 'redcarpet' -markdown = Redcarpet.new("Hello World!") -puts markdown.to_html -``` + ~~~json + ;;; + { + "title": "About Front Matter" + "example": { + "language": "json" + } + } + ;;; + ~~~ -``` -No language indicated, so no syntax highlighting. -s = "There is no highlighting for this." -But let's throw in a tag. +Other languages are supported by adding a specifier to any of the existing +delimiters. For example: + +```php +---php +$title = "About Front Matter"; +$example = array( + 'language' => "php", +); +--- ``` ### Inline diff -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff). -With inline diffs tags you can display {+ additions +} or [- deletions -]. +With inline diff tags you can display {+ additions +} or [- deletions -]. -The wrapping tags can be either curly braces or square brackets. +The wrapping tags can be either curly braces or square brackets: -Examples: - -``` -- {+ additions +} -- [+ additions +] -- {- deletions -} -- [- deletions -] +```markdown +- {+ addition 1 +} +- [+ addition 2 +] +- {- deletion 3 -} +- [- deletion 4 -] ``` -becomes: +- {+ addition 1 +} +- [+ addition 2 +] +- {- deletion 3 -} +- [- deletion 4 -] -![inline diffs tags rendered](img/markdown_inline_diffs_tags_rendered.png) +--- -However the wrapping tags cannot be mixed as such: +However the wrapping tags cannot be mixed: -``` -- {+ additions +] -- [+ additions +} -- {- deletions -] -- [- deletions -} +```markdown +- {+ addition +] +- [+ addition +} +- {- deletion -] +- [- deletion -} ``` -### Emoji +### Math -```md -Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#math). -:zap: You can use emoji anywhere GFM is supported. :v: +It is possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/Khan/KaTeX). -You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. +Math written between dollar signs `$` will be rendered inline with the text. Math written +inside a [code block](#code-spans-and-blocks) with the language declared as `math`, will be rendered +on a separate line: -If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes. +~~~ +This math is inline $`a^2+b^2=c^2`$. -Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: - -Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. - -On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. +This is on a separate line -Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +```math +a^2+b^2=c^2 ``` +~~~ -Sometimes you want to around a bit and add some to your . Well we have a gift for you: - -You can use emoji anywhere GFM is supported. - -You can use it to point out a or warn about patches. And if someone improves your really code, send them some . People will you for that. +This math is inline $`a^2+b^2=c^2`$. -If you are new to this, don't be . You can easily join the emoji . All you need to do is to look up one of the supported codes. - -Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. +This is on a separate line -Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. +```math +a^2+b^2=c^2 +``` -On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. +_Be advised that KaTeX only supports a [subset](https://katex.org/docs/supported.html) of LaTeX._ -Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +NOTE: **Note:** This also works for the asciidoctor `:stem: latexmath`. For details see +the [asciidoctor user manual](http://asciidoctor.org/docs/user-manual/#activating-stem-support). ### Special GitLab references -GFM recognizes special references. +GFM recognizes special GitLab related references. For example, you can easily reference +an issue, a commit, a team member or even the whole team within a project. GFM will turn +that reference into a link so you can navigate between them easily. -You can easily reference e.g. an issue, a commit, a team member or even the whole team within a project. - -GFM will turn that reference into a link so you can navigate between them easily. +Additionally, GFM recognizes certain cross-project references, and also has a shorthand +version to reference other projects from the same namespace. GFM will recognize the following: -| input | references | -|:---------------------------|:--------------------------------| -| `@user_name` | specific user | -| `@group_name` | specific group | -| `@all` | entire team | -| `namespace/project>` | project | -| `#12345` | issue | -| `!123` | merge request | -| `$123` | snippet | -| `&123` | epic **[ULTIMATE]** | -| `~123` | label by ID | -| `~bug` | one-word label by name | -| `~"feature request"` | multi-word label by name | -| `%123` | project milestone by ID | -| `%v1.23` | one-word milestone by name | -| `%"release candidate"` | multi-word milestone by name | -| `9ba12248` | specific commit | -| `9ba12248...b19a04f5` | commit range comparison | -| `[README](doc/README)` | repository file references | -| `[README](doc/README#L13)` | repository file line references | - -GFM also recognizes certain cross-project references: - -| input | references | -|:----------------------------------------|:------------------------| -| `namespace/project#123` | issue | -| `namespace/project!123` | merge request | -| `namespace/project%123` | project milestone | -| `namespace/project$123` | snippet | -| `namespace/project@9ba12248` | specific commit | -| `group1/subgroup&123` | epic **[ULTIMATE]** | -| `namespace/project@9ba12248...b19a04f5` | commit range comparison | -| `namespace/project~"Some label"` | issues with given label | - -It also has a shorthand version to reference other projects from the same namespace: - -| input | references | -|:------------------------------|:------------------------| -| `project#123` | issue | -| `project!123` | merge request | -| `project%123` | project milestone | -| `project$123` | snippet | -| `project@9ba12248` | specific commit | -| `project@9ba12248...b19a04f5` | commit range comparison | -| `project~"Some label"` | issues with given label | +| references | input | cross-project reference | shortcut within same namespace | +| :------------------------------ | :------------------------- | :-------------------------------------- | :----------------------------- | +| specific user | `@user_name` | | | +| specific group | `@group_name` | | | +| entire team | `@all` | | | +| project | `namespace/project>` | | | +| issue | ``#123`` | `namespace/project#123` | `project#123` | +| merge request | `!123` | `namespace/project!123` | `project!123` | +| snippet | `$123` | `namespace/project$123` | `project$123` | +| epic **[ULTIMATE]** | `&123` | `group1/subgroup&123` | | +| label by ID | `~123` | `namespace/project~123` | `project~123` | +| one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | +| multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | +| project milestone by ID | `%123` | `namespace/project%123` | `project%123` | +| one-word milestone by name | `%v1.23` | `namespace/project%v1.23` | `project%v1.23` | +| multi-word milestone by name | `%"release candidate"` | `namespace/project%"release candidate"` | `project%"release candidate"` | +| specific commit | `9ba12248` | `namespace/project@9ba12248` | `project@9ba12248` | +| commit range comparison | `9ba12248...b19a04f5` | `namespace/project@9ba12248...b19a04f5` | `project@9ba12248...b19a04f5` | +| repository file references | `[README](doc/README)` | | | +| repository file line references | `[README](doc/README#L13)` | | | ### Task lists -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists). -You can add task lists to issues, merge requests and comments. To create a task list, add a specially-formatted Markdown list, like so: +You can add task lists anywhere markdown is supported, but you can only "click" to +toggle the boxes if they are in issues, merge requests, or comments. In other places +you must edit the markdown manually to change the status by adding or removing the `x`. -``` +To create a task list, add a specially-formatted Markdown list. You can use either +unordered or ordered lists: + +```markdown - [x] Completed task - [ ] Incomplete task - - [ ] Sub-task 1 - - [x] Sub-task 2 - - [ ] Sub-task 3 + - [ ] Sub-task 1 + - [x] Sub-task 2 + - [ ] Sub-task 3 +1. [x] Completed task +1. [ ] Incomplete task + 1. [ ] Sub-task 1 + 1. [x] Sub-task 2 ``` -![alt unordered-check-list-render-gfm](img/unordered_check_list_render_gfm.png) - -Tasks formatted as ordered lists are supported as well: - -``` +- [x] Completed task +- [ ] Incomplete task + - [ ] Sub-task 1 + - [x] Sub-task 2 + - [ ] Sub-task 3 1. [x] Completed task 1. [ ] Incomplete task - 1. [ ] Sub-task 1 - 1. [x] Sub-task 2 -``` + 1. [ ] Sub-task 1 + 1. [x] Sub-task 2 -![alt task-list-ordered-render-gfm](img/task_list_ordered_render_gfm.png) +### Wiki-specific Markdown -Task lists can only be created in descriptions, not in titles. Task item state can be managed by editing the description's Markdown or by toggling the rendered check boxes. +The following examples show how links inside wikis behave. -### Videos +#### Wiki - Direct page link -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#videos +A link which just includes the slug for a page will point to that page, +_at the base level of the wiki_. -Image tags with a video extension are automatically converted to a video player. +This snippet would link to a `documentation` page at the root of your wiki: -The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`. +```markdown +[Link to Documentation](documentation) +``` - Here's a sample video: +#### Wiki - Direct file link - ![Sample Video](img/markdown_video.mp4) +Links with a file extension point to that file, _relative to the current page_. -Here's a sample video: +If the snippet below was placed on a page at `/documentation/related`, +it would link to `/documentation/file.md`: -
- -

Sample Video

-
+```markdown +[Link to File](file.md) +``` -### Math +#### Wiki - Hierarchical link -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#math +A link can be constructed relative to the current wiki page using `./`, +`../`, etc. -It is possible to have math written with the LaTeX syntax rendered using [KaTeX][katex]. +If this snippet was placed on a page at `/documentation/main`, +it would link to `/documentation/related`: -Math written inside ```$``$``` will be rendered inline with the text. +```markdown +[Link to Related Page](./related) +``` -Math written inside triple back quotes, with the language declared as `math`, will be rendered on a separate line. +If this snippet was placed on a page at `/documentation/related/content`, +it would link to `/documentation/main`: -Example: +```markdown +[Link to Related Page](../main) +``` - This math is inline $`a^2+b^2=c^2`$. +If this snippet was placed on a page at `/documentation/main`, +it would link to `/documentation/related.md`: - This is on a separate line - ```math - a^2+b^2=c^2 - ``` +```markdown +[Link to Related Page](./related.md) +``` -Becomes: +If this snippet was placed on a page at `/documentation/related/content`, +it would link to `/documentation/main.md`: -This math is inline ![alt text](img/math_inline_sup_render_gfm.png). +```markdown +[Link to Related Page](../main.md) +``` -This is on a separate line +#### Wiki - Root link - +A link starting with a `/` is relative to the wiki root. -_Be advised that KaTeX only supports a [subset][katex-subset] of LaTeX._ +This snippet links to `/documentation`: ->**Note:** -This also works for the asciidoctor `:stem: latexmath`. For details see the [asciidoctor user manual][asciidoctor-manual]. +```markdown +[Link to Related Page](/documentation) +``` -### Colors +This snippet links to `/miscellaneous.md`: -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#colors +```markdown +[Link to Related Page](/miscellaneous.md) +``` -It is possible to have color written in HEX, RGB or HSL format rendered with a color indicator. +## Standard markdown and extensions in GitLab -Color written inside backticks will be followed by a color "chip". +All standard markdown formatting should work as expected within GitLab. Some standard +functionality is extended with additional features, without affecting the standard usage. +If a functionality is extended, the new option will be listed as a sub-section. -Examples: +### Blockquotes - `#F00` - `#F00A` - `#FF0000` - `#FF0000AA` - `RGB(0,255,0)` - `RGB(0%,100%,0%)` - `RGBA(0,255,0,0.7)` - `HSL(540,70%,50%)` - `HSLA(540,70%,50%,0.7)` +Blockquotes are an easy way to highlight information, such as a side-note. It is generated +by starting the lines of the blockquote with `>`: -Becomes: +```markdown +> Blockquotes are very handy to emulate reply text. +> This line is part of the same quote. -![alt color-inline-colorchip-render-gfm](img/color_inline_colorchip_render_gfm.png) +Quote break. -#### Supported formats: +> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. +``` -* HEX: `` `#RGB[A]` `` or `` `#RRGGBB[AA]` `` -* RGB: `` `RGB[A](R, G, B[, A])` `` -* HSL: `` `HSL[A](H, S, L[, A])` `` +> Blockquotes are very handy to emulate reply text. +> This line is part of the same quote. -### Mermaid +Quote break. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15107) in -GitLab 10.3. -> -> If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#mermaid +> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. -It is possible to generate diagrams and flowcharts from text using [Mermaid](https://mermaidjs.github.io/). +#### Multiline blockquote -In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block. +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote). -Example: +GFM extends the standard markdown standard by also supporting multiline blockquotes +fenced by `>>>`: - ```mermaid - graph TD; - A-->B; - A-->C; - B-->D; - C-->D; - ``` +``` +>>> +If you paste a message from somewhere else -Becomes: +that spans multiple lines, -```mermaid -graph TD; - A-->B; - A-->C; - B-->D; - C-->D; +you can quote that without having to manually prepend `>` to every line! +>>> ``` -For details see the [Mermaid official page](https://mermaidjs.github.io/). +>>> +If you paste a message from somewhere else -### Front matter +that spans multiple lines, -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/23331) - in GitLab 11.6. - -Front matter is metadata included at the beginning of a markdown document, preceding -its content. This data can be used by static site generators such as [Jekyll](https://jekyllrb.com/docs/front-matter/) and [Hugo](https://gohugo.io/content-management/front-matter/), -and many other applications. +you can quote that without having to manually prepend `>` to every line! +>>> -In GitLab, front matter is only used in Markdown files and wiki pages, not the other places where Markdown formatting is supported. -When you view a Markdown file rendered by GitLab, any front matter is displayed as-is, in a box at the top of the document, before the rendered HTML content. -To view an example, you can toggle between the source and rendered version of a [GitLab documentation file](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/README.md). +### Code spans and blocks -The following delimeters are supported: +You can easily highlight anything that should be viewed as code and not simple text. -- YAML (`---`): +Simple inline code is easily highlighted with single backticks `` ` ``: - ``` - --- - title: About Front Matter - example: - language: yaml - --- - ``` +```markdown +Inline `code` has `back-ticks around` it. +``` -- TOML (`+++`): +Inline `code` has `back-ticks around` it. - ``` - +++ - title = "About Front Matter" - [example] - language = "toml" - +++ - ``` +--- -- JSON (`;;;`): +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. - ``` - ;;; - { - "title": "About Front Matter" - "example": { - "language": "json" - } - } - ;;; - ``` +~~~ +``` +def function(): + #indenting works just fine in the fenced code block + s = "Python code" + print s +``` -Other languages are supported by adding a specifier to any of the existing -delimiters. For example: + Using 4 spaces + is like using + 3-backtick fences. +~~~ ``` ----php -$title = "About Front Matter"; -$example = array( - 'language' => "php", -); ---- +~~~ +Tildes are OK too. +~~~ ``` -## Standard Markdown - -### Headers +The three examples above render as: ``` -# H1 -## H2 -### H3 -#### H4 -##### H5 -###### H6 +def function(): + #indenting works just fine in the fenced code block + s = "Python code" + print s +``` -Alternatively, for H1 and H2, an underline-ish style: + Using 4 spaces + is like using + 3-backtick fences. -Alt-H1 -====== +~~~ +Tildes are OK too. +~~~ -Alt-H2 ------- -``` +#### Colored code and syntax highlighting -#### Header IDs and links +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#colored-code-and-syntax-highlighting). -All Markdown-rendered headers automatically get IDs, which can be linked to, except in comments. +GitLab uses the [Rouge Ruby library](http://rouge.jneen.net/) for more colorful syntax +highlighting in code blocks. For a list of supported languages visit the +[Rouge project wiki](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers). +Syntax highlighting is only supported in code blocks, it is not possible to highlight +code when it is inline. -On hover, a link to those IDs becomes visible to make it easier to copy the link to the header to use it somewhere else. +Blocks of code are fenced by lines with three back-ticks ```` ``` ```` or three tildes `~~~`, and have +the language identified at the end of the first fence: -The IDs are generated from the content of the header according to the following rules: +~~~ +```javascript +var s = "JavaScript syntax highlighting"; +alert(s); +``` -1. All text is converted to lowercase. -1. All non-word text (e.g., punctuation, HTML) is removed. -1. All spaces are converted to hyphens. -1. Two or more hyphens in a row are converted to one. -1. If a header with the same ID has already been generated, a unique - incrementing number is appended, starting at 1. +```python +def function(): + #indenting works just fine in the fenced code block + s = "Python syntax highlighting" + print s +``` -For example: +```ruby +require 'redcarpet' +markdown = Redcarpet.new("Hello World!") +puts markdown.to_html +``` ``` -# This header has spaces in it -## This header has a :thumbsup: in it -# This header has Unicode in it: 한글 -## This header has spaces in it -### This header has spaces in it -## This header has 3.5 in it (and parentheses) +No language indicated, so no syntax highlighting. +s = "There is no highlighting for this." +But let's throw in a tag. ``` +~~~ -Would generate the following link IDs: +The four examples above render as: -1. `this-header-has-spaces-in-it` -1. `this-header-has-a-in-it` -1. `this-header-has-unicode-in-it-한글` -1. `this-header-has-spaces-in-it-1` -1. `this-header-has-spaces-in-it-2` -1. `this-header-has-3-5-in-it-and-parentheses` +```javascript +var s = "JavaScript syntax highlighting"; +alert(s); +``` -Note that the Emoji processing happens before the header IDs are generated, so the Emoji is converted to an image which then gets removed from the ID. +```python +def function(): + #indenting works just fine in the fenced code block + s = "Python syntax highlighting" + print s +``` + +```ruby +require 'redcarpet' +markdown = Redcarpet.new("Hello World!") +puts markdown.to_html +``` + +``` +No language indicated, so no syntax highlighting. +s = "There is no highlighting for this." +But let's throw in a tag. +``` ### Emphasis +There are multiple ways to emphasize text in markdown. You can italicize, bold, strikethrough, +as well as combine these emphasis styles together. + Examples: -``` +```markdown Emphasis, aka italics, with *asterisks* or _underscores_. -Strong emphasis, aka bold, with **asterisks** or __underscores__. +Strong emphasis, aka bold, with double **asterisks** or __underscores__. Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` -Becomes: - Emphasis, aka italics, with *asterisks* or _underscores_. -Strong emphasis, aka bold, with **asterisks** or __underscores__. +Strong emphasis, aka bold, with double **asterisks** or __underscores__. Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ -### Lists +NOTE: **Note:** Strikethrough is not part of the core Markdown standard, but is part of GFM. -Examples: +#### Multiple underscores in words and mid-word emphasis -``` -1. First ordered list item -2. Another item - * Unordered sub-list. -1. Actual numbers don't matter, just that it's a number - 1. Ordered sub-list -4. And another item. +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words). -* Unordered list can use asterisks -- Or minuses -+ Or pluses +It is not usually useful to italicize just _part_ of a word, especially when you're +dealing with code and names that often appear with multiple underscores. As a result, +GFM extends the standard markdown standard by ignoring multiple underlines in words, +to allow better rendering of markdown documents discussing code: + +```md +perform_complicated_task + +do_this_and_do_that_and_another_thing + +but_emphasis is_desired _here_ ``` -Becomes: +perform_complicated_task + +do_this_and_do_that_and_another_thing -1. First ordered list item -2. Another item - * Unordered sub-list. -1. Actual numbers don't matter, just that it's a number - 1. Ordered sub-list -4. And another item. +but_emphasis is_desired _here_ -* Unordered list can use asterisks -- Or minuses -+ Or pluses +--- -If a list item contains multiple paragraphs, -each subsequent paragraph should be indented to the same level as the start of the list item text +If you wish to emphasize only a part of a word, it can still be done with asterisks: -Example: +```md +perform*complicated*task + +do*this*and*do*that*and*another thing +``` + +perform*complicated*task + +do*this*and*do*that*and*another thing + +### Footnotes +Footnotes add a link to a note rendered at the end of a markdown file: + +```markdown +You can add footnotes to your text as follows.[^1] + +[^1]: This is my awesome footnote (later in file). ``` -1. First ordered list item - Second paragraph of first item. +You can add footnotes to your text as follows.[^1] -2. Another item +[^1]: This is my awesome footnote (later in file). + +### Headers + +```markdown +# H1 +## H2 +### H3 +#### H4 +##### H5 +###### H6 + +Alternatively, for H1 and H2, an underline-ish style: + +Alt-H1 +====== + +Alt-H2 +------ ``` -Becomes: +#### Header IDs and links -1. First ordered list item +GFM extends the standard markdown standard so that all Markdown-rendered headers automatically +get IDs, which can be linked to, except in comments. - Paragraph of first item. +On hover, a link to those IDs becomes visible to make it easier to copy the link to +the header to use it somewhere else. -2. Another item +The IDs are generated from the content of the header according to the following rules: -If the paragraph of the first item is not indented with the proper number of spaces, -the paragraph will appear outside the list, instead of properly indented under the list item. +1. All text is converted to lowercase. +1. All non-word text (e.g., punctuation, HTML) is removed. +1. All spaces are converted to hyphens. +1. Two or more hyphens in a row are converted to one. +1. If a header with the same ID has already been generated, a unique + incrementing number is appended, starting at 1. Example: ``` -1. First ordered list item - - Paragraph of first item. - -2. Another item +# This header has spaces in it +## This header has a :thumbsup: in it +# This header has Unicode in it: 한글 +## This header has spaces in it +### This header has spaces in it +## This header has 3.5 in it (and parentheses) ``` -Becomes: - -1. First ordered list item +Would generate the following link IDs: - Paragraph of first item. +1. `this-header-has-spaces-in-it` +1. `this-header-has-a-in-it` +1. `this-header-has-unicode-in-it-한글` +1. `this-header-has-spaces-in-it-1` +1. `this-header-has-spaces-in-it-2` +1. `this-header-has-3-5-in-it-and-parentheses` -2. Another item +Note that the Emoji processing happens before the header IDs are generated, so the +Emoji is converted to an image which is then removed from the ID. -### Links +### Horizontal Rule -There are two ways to create links, inline-style and reference-style. +It's very simple to create a horizontal rule, by using three or more hyphens, asterisks, +or underscores: ```markdown -[I'm an inline-style link](https://www.google.com) -[I'm a link to a repository file in the same directory](index.md) -[I am an absolute reference within the repository](/doc/user/index.md) -[I'm a relative link to the Milestones page](../README.md) +Three or more hyphens, -[I link to a section on a different markdown page, using a header ID](index.md#overview) -[I link to a different section on the same page, using the header ID](#header-ids-and-links) +--- -[I'm a reference-style link][Arbitrary case-insensitive reference text] -[You can use numbers for reference-style link definitions][1] -Or leave it empty and use the [link text itself][] +asterisks, -Some text to show that the reference links can follow later. +*** -[arbitrary case-insensitive reference text]: https://www.mozilla.org -[1]: http://slashdot.org -[link text itself]: https://www.reddit.com +or underscores + +___ ``` ->**Note:** -Relative links do not allow referencing project files in a wiki page or wiki -page in a project file. The reason for this is that, in GitLab, wiki is always -a separate Git repository. For example, `[I'm a reference-style link](style)` -will point the link to `wikis/style` when the link is inside of a wiki markdown file. +Three or more hyphens, + +--- + +asterisks, + +*** + +or underscores + +___ ### Images Examples: - Here's our logo (hover to see the title text): - - Inline-style: - ![alt text](img/markdown_logo.png) +```markdown +Inline-style (hover to see title text): - Reference-style: - ![alt text1][logo] +![alt text](img/markdown_logo.png "Title Text") - [logo]: img/markdown_logo.png +Reference-style (hover to see title text): -Becomes: +![alt text1][logo] -Here's our logo: +[logo]: img/markdown_logo.png "Title Text" +``` -Inline-style: +Inline-style (hover to see title text): -![alt text](img/markdown_logo.png) +![alt text](img/markdown_logo.png "Title Text") -Reference-style: +Reference-style (hover to see title text): ![alt text][logo] -[logo]: img/markdown_logo.png +[logo]: img/markdown_logo.png "Title Text" -### Blockquotes +#### Videos -Examples: +> If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#videos). -``` -> Blockquotes are very handy in email to emulate reply text. -> This line is part of the same quote. +Image tags that link to files with a video extension are automatically converted to +a video player. The valid video extensions are `.mp4`, `.m4v`, `.mov`, `.webm`, and `.ogv`: -Quote break. +```md +Here's a sample video: -> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. +![Sample Video](img/markdown_video.mp4) ``` -Becomes: - -> Blockquotes are very handy in email to emulate reply text. -> This line is part of the same quote. - -Quote break. +Here's a sample video: -> This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. +![Sample Video](img/markdown_video.mp4) ### Inline HTML -You can also use raw HTML in your Markdown, and it'll mostly work pretty well. +> To see the markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-html). -See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/SanitizationFilter#WHITELIST-constant) class for the list of allowed HTML tags and attributes. In addition to the default `SanitizationFilter` whitelist, GitLab allows `span`, `abbr`, `details` and `summary` elements. +You can also use raw HTML in your Markdown, and it'll usually work pretty well. -Examples: +See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/SanitizationFilter#WHITELIST-constant) +class for the list of allowed HTML tags and attributes. In addition to the default +`SanitizationFilter` whitelist, GitLab allows `span`, `abbr`, `details` and `summary` elements. -``` +```html
Definition list
Is something people use sometimes.
Markdown in HTML
-
Does *not* work **very** well. Use HTML tags.
+
Does *not* work **very** well. HTML tags will always work.
``` -Becomes: -
Definition list
Is something people use sometimes.
Markdown in HTML
-
Does *not* work **very** well. Use HTML tags.
+
Does *not* work **very** well. HTML tags will always work.
+
+ +--- + +It is still possible to use markdown inside HTML tags, but only if the lines containing markdown +are separated into their own lines: + +```html +
+
Markdown in HTML
+
Does *not* work **very** well. HTML tags will always work.
+ +
Markdown in HTML
+
+ + Does *not* work **very** well. HTML tags will always work. + +
+
+``` + + + +
+
Markdown in HTML
+
Does *not* work **very** well. HTML tags will always work.
+ +
Markdown in HTML
+
+ + Does not work very well. HTML tags will always work. + +
#### Details and Summary -Content can be collapsed using HTML's [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) and [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) tags. This is especially useful for collapsing long logs so they take up less screen space. +> To see the markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#details-and-summary). + +Content can be collapsed using HTML's [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) +and [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary) +tags. This is especially useful for collapsing long logs so they take up less screen space. + +```html +

+

+Click me to collapse/fold. + +These details will remain hidden until expanded. + +
PASTE LOGS HERE
+ +
+

+```

@@ -847,7 +963,10 @@ These details will remain hidden until expanded.

-**Note:** Markdown inside these tags is supported, as long as you have a blank line after the `` tag and before the `
` tag, as shown in the example. +--- + +Markdown inside these tags is supported as well, as long as you have a blank line +after the `` tag and before the `
` tag, as shown in the example: ```html
@@ -860,232 +979,304 @@ These details _will_ remain **hidden** until expanded.
``` -### Horizontal Rule + -Examples: +
+Click me to collapse/fold. -``` -Three or more... +These details will remain hidden until expanded. ---- + PASTE LOGS HERE + +
-Hyphens +### Line Breaks -*** +A line break will be inserted (a new paragraph will start) if the previous text is +ended with two newlines, i.e. you hit Enter twice in a row. If you only +use one newline (hit Enter once), the next sentence will be part of the +same paragraph. This is useful if you want to keep long lines from wrapping, and keep +them easily editable: -Asterisks +```markdown +Here's a line for us to start with. -___ +This longer line is separated from the one above by two newlines, so it will be a *separate paragraph*. -Underscores +This line is also a separate paragraph, but... +These lines are only separated by single newlines, +so they *do not break* and just follow the previous lines +in the *same paragraph*. ``` -Becomes: - -Three or more... +Here's a line for us to start with. ---- +This longer line is separated from the one above by two newlines, so it will be a *separate paragraph*. -Hyphens +This line is also a separate paragraph, but... +These lines are only separated by single newlines, +so they *do not break* and just follow the previous lines +in the *same paragraph*. -*** +#### Newlines -Asterisks +GFM adheres to the markdown specification in how [paragraphs and line breaks are handled](https://spec.commonmark.org/current/). -___ +A paragraph is simply one or more consecutive lines of text, separated by one or +more blank lines (i.e. two newlines at the end of the first paragraph), as [explained above](#line-breaks). -Underscores +If you need more control over line-breaks or soft returns, you can add a single line-break +by ending a line with a backslash, or two or more spaces. Two newlines in a row will create a new +paragraph, with a blank line in between: -### Line Breaks +```markdown +First paragraph. +Another line in the same paragraph. +A third line in the same paragraph, but this time ending with two spaces.{space}{space} +A new line directly under the first paragraph. + +Second paragraph. +Another line, this time ending with a backslash.\ +A new line due to the previous backslash. +``` -A good way to learn how line breaks work is to experiment and discover -- hit Enter once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want. The "Preview" tab is your friend. + + -Here are some things to try out: +First paragraph. +Another line in the same paragraph. +A third line in the same paragraph, but this time ending with two spaces. +A new line directly under the first paragraph. -Examples: + + -``` -Here's a line for us to start with. +Second paragraph. +Another line, this time ending with a backslash. +A new line due to the previous backslash. -This line is separated from the one above by two newlines, so it will be a *separate paragraph*. +### Links -This line is also a separate paragraph, but... -This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*. +There are two ways to create links, inline-style and reference-style: -This line is also a separate paragraph, and... -This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*) +```md +- This is an [inline-style link](https://www.google.com) +- This is a [link to a repository file in the same directory](index.md) +- This is an [absolute reference within the repository](/doc/user/index.md) +- This is a [relative link to a readme one directory higher](../README.md) +- This is a [link that also has title text](https://www.google.com "This link takes you to Google!") -spaces. -``` +Using header ID anchors: -Becomes: +- This links to [a section on a different markdown page, using a "#" and the header ID](index.md#overview) +- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) -Here's a line for us to start with. +Using references: -This line is separated from the one above by two newlines, so it will be a *separate paragraph*. +- This is a [reference-style link, see below][Arbitrary case-insensitive reference text] +- You can [use numbers for reference-style link definitions, see below][1] +- Or leave it empty and use the [link text itself][], see below. -This line is also a separate paragraph, but... -This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*. +Some text to show that the reference links can follow later. -This line is also a separate paragraph, and... -This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*) +[arbitrary case-insensitive reference text]: https://www.mozilla.org +[1]: http://slashdot.org +[link text itself]: https://www.reddit.com +``` -spaces. +- This is an [inline-style link](https://www.google.com) +- This is a [link to a repository file in the same directory](index.md) +- This is an [absolute reference within the repository](/doc/user/index.md) +- This is a [relative link to a readme one directory higher](../README.md) +- This is a [link that also has title text](https://www.google.com "This link takes you to Google!") -### Tables +Using header ID anchors: -Tables aren't part of the core Markdown spec, but they are part of GFM. +- This links to [a section on a different markdown page, using a "#" and the header ID](index.md#overview) +- This links to [a different section on the same page, using a "#" and the header ID](#header-ids-and-links) -Example: +Using references: -``` -| header 1 | header 2 | -| -------- | -------- | -| cell 1 | cell 2 | -| cell 3 | cell 4 | -``` +- This is a [reference-style link, see below][Arbitrary case-insensitive reference text] +- You can [use numbers for reference-style link definitions, see below][1] +- Or leave it empty and use the [link text itself][], see below. -Becomes: +Some text to show that the reference links can follow later. -| header 1 | header 2 | -| -------- | -------- | -| cell 1 | cell 2 | -| cell 3 | cell 4 | +[arbitrary case-insensitive reference text]: https://www.mozilla.org +[1]: http://slashdot.org +[link text itself]: https://www.reddit.com -**Note:** The row of dashes between the table header and body must have at least three dashes in each column. +NOTE: **Note:** Relative links do not allow the referencing of project files in a wiki +page, or a wiki page in a project file. The reason for this is that a wiki is always +in a separate Git repository in GitLab. For example, `[I'm a reference-style link](style)` +will point the link to `wikis/style` only when the link is inside of a wiki markdown file. -By including colons in the header row, you can align the text within that column. +#### URL auto-linking -Example: +GFM will autolink almost any URL you put into your text: -``` -| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | -| :----------- | :------: | ------------: | :----------- | :------: | ------------: | -| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | -| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | +```markdown +* https://www.google.com +* https://google.com/ +* ftp://ftp.us.debian.org/debian/ +* smb://foo/bar/baz +* irc://irc.freenode.net/gitlab +* http://localhost:3000 ``` -Becomes: +* https://www.google.com +* https://google.com/ +* ftp://ftp.us.debian.org/debian/ +* smb://foo/bar/baz +* irc://irc.freenode.net/gitlab +* http://localhost:3000 -| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | -| :----------- | :------: | ------------: | :----------- | :------: | ------------: | -| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | -| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | +### Lists -### Footnotes +Ordered and unordered lists can be easily created. Add the number you want the list +to start with, like `1. ` (with a space) at the start of each line for ordered lists. +After the first number, it does not matter what number you use, ordered lists will be +numbered automatically by vertical order, so repeating `1. ` for all items in the +same list is common. If you start with a number other than `1. `, it will use that as the first +number, and count up from there. -Example: +Add a `* `, `- ` or `+ ` (with a space) at the start of each line for unordered lists, but +you should not use a mix of them. +Examples: + +```md +1. First ordered list item +2. Another item + * Unordered sub-list. +1. Actual numbers don't matter, just that it's a number + 1. Ordered sub-list + 1. Next ordered sub-list item +4. And another item. + +* Unordered lists can use asterisks +- Or minuses ++ Or pluses ``` -You can add footnotes to your text as follows.[^2] -[^2]: This is my awesome footnote. -``` -Becomes: +1. First ordered list item +2. Another item + * Unordered sub-list. +1. Actual numbers don't matter, just that it's a number + 1. Ordered sub-list + 1. Next ordered sub-list item +4. And another item. + +* Unordered lists can use asterisks +- Or minuses ++ Or pluses -You can add footnotes to your text as follows.[^2] +--- -### Superscripts / Subscripts +If a list item contains multiple paragraphs, each subsequent paragraph should be indented +to the same level as the start of the list item text. -CommonMark and GFM currently do not support the superscript syntax ( `x^2` ) that Redcarpet does. You can use the standard HTML syntax for superscripts and subscripts. +Example: -``` -The formula for water is H2O -while the equation for the theory of relativity is E = mc2. -``` +```markdown +1. First ordered list item -The formula for water is H2O while the equation for the theory of relativity is E = mc2. + Second paragraph of first item. -## Wiki-specific Markdown +2. Another item +``` -The following examples show how links inside wikis behave. +1. First ordered list item -### Wiki - Direct page link + Second paragraph of first item. -A link which just includes the slug for a page will point to that page, -_at the base level of the wiki_. +2. Another item -This snippet would link to a `documentation` page at the root of your wiki: +--- -```markdown -[Link to Documentation](documentation) -``` +If the paragraph of the first item is not indented with the proper number of spaces, +the paragraph will appear outside the list, instead of properly indented under the list item. -### Wiki - Direct file link +Example: -Links with a file extension point to that file, _relative to the current page_. +``` +1. First ordered list item -If this snippet was placed on a page at `/documentation/related`, -it would link to `/documentation/file.md`: + Paragraph of first item. -```markdown -[Link to File](file.md) +2. Another item ``` -### Wiki - Hierarchical link +1. First ordered list item -A link can be constructed relative to the current wiki page using `./`, -`../`, etc. + Paragraph of first item. -- If this snippet was placed on a page at `/documentation/main`, - it would link to `/documentation/related`: +2. Another item + +### Superscripts / Subscripts - ```markdown - [Link to Related Page](related) - ``` +CommonMark and GFM currently do not support the superscript syntax ( `x^2` ) that +Redcarpet does. You can use the standard HTML syntax for superscripts and subscripts: -- If this snippet was placed on a page at `/documentation/related/content`, - it would link to `/documentation/main`: +```html +The formula for water is H2O +while the equation for the theory of relativity is E = mc2. +``` - ```markdown - [Link to Related Page](../main) - ``` +The formula for water is H2O +while the equation for the theory of relativity is E = mc2. -- If this snippet was placed on a page at `/documentation/main`, - it would link to `/documentation/related.md`: +### Tables - ```markdown - [Link to Related Page](related.md) - ``` +Tables aren't part of the core Markdown spec, but they are part of GFM. -- If this snippet was placed on a page at `/documentation/related/content`, - it would link to `/documentation/main.md`: +1. The first line contains the headers, separated by "pipes" (`|`). +1. The second line separates the headers from the cells, and must contain three or more dashes. +1. The third, and any following lines, contain the cell values. + - You **can't** have cells separated over many lines in the markdown, they must be kept to single lines, + but they can be very long. You can also include HTML `
` tags to force newlines if needed. + - The cell sizes **don't** have to match each other. They are flexible, but must be separated + by pipes (`|`). + - You **can** have blank cells. - ```markdown - [Link to Related Page](../main.md) - ``` +Example: -### Wiki - Root link +```markdown +| header 1 | header 2 | header 3 | +| --- | ------ |----------| +| cell 1 | cell 2 | cell 3 | +| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It will eventually wrap the text when the cell is too large for the display size. | +| cell 7 | | cell
9 | +``` -A link starting with a `/` is relative to the wiki root. +| header 1 | header 2 | header 3 | +| --- | ------ |---------:| +| cell 1 | cell 2 | cell 3 | +| cell 4 | cell 5 is longer | cell 6 is much longer than the others, but that's ok. It will eventually wrap the text when the cell is too large for the display size. | +| cell 7 | | cell
9 | -- This snippet links to `/documentation`: +Additionally, you can choose the alignment of text within columns by adding colons (`:`) +to the sides of the "dash" lines in the second row. This will affect every cell in the column. - ```markdown - [Link to Related Page](/documentation) - ``` +> Note that the headers are always right aligned [within GitLab itself itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#tables). -- This snippet links to `/miscellaneous.md`: +```markdown +| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | +| :--- | :---: | ---: | :----------- | :------: | ------------: | +| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | +| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | +``` - ```markdown - [Link to Related Page](/miscellaneous.md) - ``` +| Left Aligned | Centered | Right Aligned | Left Aligned | Centered | Right Aligned | +| :--- | :---: | ---: | :----------- | :------: | ------------: | +| Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 5 | Cell 6 | +| Cell 7 | Cell 8 | Cell 9 | Cell 10 | Cell 11 | Cell 12 | ## References - This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). -- The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown. -- The detailed specification for CommonMark can be found in the [CommonMark Spec][commonmark-spec] +- The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) + at Daring Fireball is an excellent resource for a detailed explanation of standard markdown. +- The detailed specification for CommonMark can be found in the [CommonMark Spec](https://spec.commonmark.org/current/) - The [CommonMark Dingus](http://try.commonmark.org) is a handy tool for testing CommonMark syntax. - -[^1]: This link will be broken if you see this document from the Help page or docs.gitlab.com -[^2]: This is my awesome footnote. - -[markdown.md]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md -[rouge]: http://rouge.jneen.net/ "Rouge website" -[redcarpet]: https://github.com/vmg/redcarpet "Redcarpet website" -[katex]: https://github.com/Khan/KaTeX "KaTeX website" -[katex-subset]: https://katex.org/docs/supported.html "Macros supported by KaTeX" -[asciidoctor-manual]: http://asciidoctor.org/docs/user-manual/#activating-stem-support "Asciidoctor user manual" -[commonmarker]: https://github.com/gjtorikian/commonmarker -[commonmark-spec]: https://spec.commonmark.org/current/ diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index be4215b1934..2bf8d4dfe7b 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -18,7 +18,7 @@ Adjust your project's name, description, avatar, [default branch](../repository/ ![general project settings](img/general_settings.png) -The project description also partially supports [standard markdown](../../markdown.md#standard-markdown). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. +The project description also partially supports [standard markdown](../../markdown.md#standard-markdown-and-extensions-in-gitlab). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. ### Sharing and permissions -- cgit v1.2.1 From 5abf50cdd24fea4a42dedf5a468781f9051f32c2 Mon Sep 17 00:00:00 2001 From: Daniel Gruesso Date: Thu, 27 Jun 2019 01:11:22 +0000 Subject: Add zero downtime upgrade detail for production_replicas --- doc/topics/autodevops/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 702245b22a0..41d12128e51 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -723,7 +723,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | From Gitlab 11.11, this variable can be used to set a username to connect to the helm repository. Defaults to no credentials. (Also set AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD) | | `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD` | From Gitlab 11.11, this variable can be used to set a password to connect to the helm repository. Defaults to no credentials. (Also set AUTO_DEVOPS_CHART_REPOSITORY_USERNAME) | | `REPLICAS` | The number of replicas to deploy; defaults to 1. | -| `PRODUCTION_REPLICAS` | The number of replicas to deploy in the production environment. This takes precedence over `REPLICAS`; defaults to 1. | +| `PRODUCTION_REPLICAS` | The number of replicas to deploy in the production environment. Takes precedence over `REPLICAS` and defaults to 1. For zero downtime upgrades, set to 2 or greater. | | `CANARY_REPLICAS` | The number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md); defaults to 1 | | `CANARY_PRODUCTION_REPLICAS` | The number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. This takes precedence over `CANARY_REPLICAS`; defaults to 1 | | `ADDITIONAL_HOSTS` | Fully qualified domain names specified as a comma-separated list that are added to the ingress hosts. | -- cgit v1.2.1 From ee1838851b08d8f19d39ac2c602c42292feb226f Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Thu, 27 Jun 2019 01:41:05 +0000 Subject: Fix broken link in markdown doc --- doc/user/markdown.md | 2 -- 1 file changed, 2 deletions(-) (limited to 'doc') diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 186fd7178d3..16df6d93277 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1062,7 +1062,6 @@ There are two ways to create links, inline-style and reference-style: ```md - This is an [inline-style link](https://www.google.com) - This is a [link to a repository file in the same directory](index.md) -- This is an [absolute reference within the repository](/doc/user/index.md) - This is a [relative link to a readme one directory higher](../README.md) - This is a [link that also has title text](https://www.google.com "This link takes you to Google!") @@ -1086,7 +1085,6 @@ Some text to show that the reference links can follow later. - This is an [inline-style link](https://www.google.com) - This is a [link to a repository file in the same directory](index.md) -- This is an [absolute reference within the repository](/doc/user/index.md) - This is a [relative link to a readme one directory higher](../README.md) - This is a [link that also has title text](https://www.google.com "This link takes you to Google!") -- cgit v1.2.1 From 4c9e068224a18ef47a2c80e3f150fc35b667fc75 Mon Sep 17 00:00:00 2001 From: Russell Dickenson Date: Thu, 27 Jun 2019 03:32:19 +0000 Subject: Clarified supported operating systems --- doc/install/requirements.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 92122fca7dd..68c1bcbc801 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -9,7 +9,7 @@ as the hardware requirements that are needed to install and use GitLab. ## Operating Systems -### Supported Unix distributions +### Supported Linux distributions - Ubuntu - Debian @@ -21,7 +21,7 @@ as the hardware requirements that are needed to install and use GitLab. For the installations options, see [the main installation page](README.md). -### Unsupported Unix distributions +### Unsupported Linux distributions and Unix-like operating systems - Arch Linux - Fedora @@ -29,13 +29,13 @@ For the installations options, see [the main installation page](README.md). - Gentoo - macOS -On the above unsupported distributions is still possible to install GitLab yourself. +Installation of GitLab on these operating systems is possible, but not supported. Please see the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/installation/) for more information. -### Non-Unix operating systems such as Windows +### Microsoft Windows -GitLab is developed for Unix operating systems. -It does **not** run on Windows, and we have no plans to support it in the near future. For the latest development status view this [issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/46567). +GitLab is developed for Linux-based operating systems. +It does **not** run on Microsoft Windows, and we have no plans to support it in the near future. For the latest development status view this [issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/46567). Please consider using a virtual machine to run GitLab. ## Ruby versions -- cgit v1.2.1