diff options
Diffstat (limited to 'doc')
67 files changed, 1276 insertions, 325 deletions
diff --git a/doc/README.md b/doc/README.md index 1a0359f9e2a..f87ff925e94 100644 --- a/doc/README.md +++ b/doc/README.md @@ -336,7 +336,7 @@ Viewing [Container Scanning reports](https://docs.gitlab.com/ee/user/project/mer There are two ways to use GitLab: - [GitLab self-managed](#gitlab-self-managed): Install, administer, and maintain your own GitLab instance. -- [GitLab.com](#gitlab-com): GitLab's SaaS offering. You don't need to install anything to use GitLab.com, +- [GitLab.com](#gitlabcom): GitLab's SaaS offering. You don't need to install anything to use GitLab.com, you only need to [sign up](https://gitlab.com/users/sign_in) and start using GitLab straight away. The following sections outline tiers and features within GitLab self-managed and GitLab.com. diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index 341a00009e5..11b2adeeeb8 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -5,6 +5,13 @@ description: "Set and configure Git protocol v2" # Configuring Git Protocol v2 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/46555) in GitLab 11.4. +> [Temporarily disabled](https://gitlab.com/gitlab-org/gitlab-ce/issues/55769) in GitLab 11.5.8, 11.6.6, 11.7.1, and 11.8+ + +NOTE: **Note:** +Git protocol v2 support has been [temporarily disabled](https://gitlab.com/gitlab-org/gitlab-ce/issues/55769), +as a feature used to hide certain internal references does not function when it +is enabled, and this has a security impact. Once this problem has been resolved, +protocol v2 support will be re-enabled. Git protocol v2 improves the v1 wire protocol in several ways and is enabled by default in GitLab for HTTP requests. In order to enable SSH, diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index abef7a6cd33..0795d3dad40 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -52,10 +52,10 @@ is used. ### Network architecture - gitlab-rails shards repositories into "repository storages" -- gitlab-rails/config/gitlab.yml contains a map from storage names to +- `gitlab-rails/config/gitlab.yml` contains a map from storage names to (Gitaly address, Gitaly token) pairs - the `storage name` -\> `(Gitaly address, Gitaly token)` map in - gitlab.yml is the single source of truth for the Gitaly network + `gitlab.yml` is the single source of truth for the Gitaly network topology - a (Gitaly address, Gitaly token) corresponds to a Gitaly server - a Gitaly server hosts one or more storages @@ -65,7 +65,7 @@ is used. gitlab-shell, and Gitaly itself - special case: a Gitaly server must be able to make RPC calls **to itself** via its own (Gitaly address, Gitaly token) pair as - specified in gitlab-rails/config/gitlab.yml + specified in `gitlab-rails/config/gitlab.yml` - Gitaly servers must not be exposed to the public internet Gitaly network traffic is unencrypted so you should use a firewall to @@ -125,7 +125,7 @@ Omnibus installations: ```ruby # /etc/gitlab/gitlab.rb -# Avoid running unnecessary services on the gitaly server +# Avoid running unnecessary services on the Gitaly server postgresql['enable'] = false redis['enable'] = false nginx['enable'] = false @@ -153,7 +153,7 @@ gitaly['storage'] = [ { 'name' => 'storage1', 'path' => '/mnt/gitlab/storage1/repositories' }, ] -# To use tls for gitaly you need to add +# To use TLS for Gitaly you need to add gitaly['tls_listen_addr'] = "0.0.0.0:9999" gitaly['certificate_path'] = "path/to/cert.pem" gitaly['key_path'] = "path/to/key.pem" @@ -239,11 +239,11 @@ repository from your GitLab server over HTTP. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22602) in GitLab 11.7. Gitaly supports TLS credentials for GRPC authentication. To be able to communicate -with a gitaly instance that listens for secure connections you will need to use `tls://` url +with a Gitaly instance that listens for secure connections you will need to use `tls://` url scheme in the `gitaly_address` of the corresponding storage entry in the gitlab configuration. The admin needs to bring their own certificate as we do not provide that automatically. -The certificate to be used needs to be installed on all gitaly nodes and on all client nodes that communicate with it following procedures described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates) +The certificate to be used needs to be installed on all Gitaly nodes and on all client nodes that communicate with it following procedures described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates) ### Example TLS configuration @@ -261,7 +261,7 @@ git_data_dirs({ gitlab_rails['gitaly_token'] = 'abc123secret' ``` -#### On gitaly server nodes: +#### On Gitaly server nodes: ```ruby gitaly['tls_listen_addr'] = "0.0.0.0:9999" @@ -289,7 +289,7 @@ gitlab: token: 'abc123secret' ``` -#### On gitaly server nodes: +#### On Gitaly server nodes: ```toml # /home/git/gitaly/config.toml diff --git a/doc/administration/index.md b/doc/administration/index.md index 0b673d61139..12fec2753bf 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -48,6 +48,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Third party offers](../user/admin_area/settings/third_party_offers.md) - [Compliance](compliance.md): A collection of features from across the application that you may configure to help ensure that your GitLab instance and DevOps workflow meet compliance standards. - [Diff limits](../user/admin_area/diff_limits.md): Configure the diff rendering size limits of branch comparison pages. +- [Merge request diffs](merge_request_diffs.md): Configure the diffs shown on merge requests - [Broadcast Messages](../user/admin_area/broadcast_messages.md): Send messages to GitLab users through the UI. #### Customizing GitLab's appearance @@ -64,6 +65,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Backup and restore](../raketasks/backup_restore.md): Backup and restore your GitLab instance. - [Operations](operations/index.md): Keeping GitLab up and running (clean up Redis sessions, moving repositories, Sidekiq MemoryKiller, Unicorn). - [Restart GitLab](restart_gitlab.md): Learn how to restart GitLab and its components. +- [Invalidate markdown cache](invalidate_markdown_cache.md): Invalidate any cached markdown. #### Updating GitLab diff --git a/doc/administration/invalidate_markdown_cache.md b/doc/administration/invalidate_markdown_cache.md new file mode 100644 index 00000000000..ad64cb077c1 --- /dev/null +++ b/doc/administration/invalidate_markdown_cache.md @@ -0,0 +1,16 @@ +# Invalidate Markdown Cache + +For performance reasons, GitLab caches the HTML version of markdown text +(e.g. issue and merge request descriptions, comments). It's possible +that these cached versions become outdated, for example +when the `external_url` configuration option is changed - causing links +in the cached text to refer to the old URL. + +To avoid this problem, the administrator can invalidate the existing cache by +increasing the `local_markdown_version` setting in application settings. This can +be done by [changing the application settings through +the API](../api/settings.md#change-application-settings): + +```bash +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/application/settings?local_markdown_version=<increased_number> +``` diff --git a/doc/administration/merge_request_diffs.md b/doc/administration/merge_request_diffs.md new file mode 100644 index 00000000000..94620c3d3a0 --- /dev/null +++ b/doc/administration/merge_request_diffs.md @@ -0,0 +1,154 @@ +# Merge request diffs administration + +> **Notes:** +> - External merge request diffs introduced in GitLab 11.8 + +Merge request diffs are size-limited copies of diffs associated with merge +requests. When viewing a merge request, diffs are sourced from these copies +wherever possible as a performance optimization. + +By default, merge request diffs are stored in the database, in a table named +`merge_request_diff_files`. Larger installations may find this table grows too +large, in which case, switching to external storage is recommended. + +### Using external storage + +Merge request diffs can be stored on disk, or in object storage. In general, it +is better to store the diffs in the database than on disk. + +To enable external storage of merge request diffs: + +--- + +**In Omnibus installations:** + +1. Edit `/etc/gitlab/gitlab.rb` and add the following line: + + ```ruby + gitlab_rails['external_diffs_enabled'] = true + ``` + +1. _The external diffs will be stored in in + `/var/opt/gitlab/gitlab-rails/shared/external-diffs`._ To change the path, + for example to `/mnt/storage/external-diffs`, edit `/etc/gitlab/gitlab.rb` + and add the following line: + + ```ruby + gitlab_rails['external_diffs_storage_path'] = "/mnt/storage/external-diffs" + ``` + +1. Save the file and [reconfigure GitLab][] for the changes to take effect. + +--- + +**In installations from source:** + +1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following + lines: + + ```yaml + external_diffs: + enabled: true + ``` + +1. _The external diffs will be stored in + `/home/git/gitlab/shared/external-diffs`._ To change the path, for example + to `/mnt/storage/external-diffs`, edit `/home/git/gitlab/config/gitlab.yml` + and add or amend the following lines: + + ```yaml + external_diffs: + enabled: true + storage_path: /mnt/storage/external-diffs + ``` + +1. Save the file and [restart GitLab][] for the changes to take effect. + +### Using object storage + +Instead of storing the external diffs on disk, we recommended you use an object +store like AWS S3 instead. This configuration relies on valid AWS credentials to +be configured already. + +### Object Storage Settings + +For source installations, these settings are nested under `external_diffs:` and +then `object_store:`. On omnibus installs, they are prefixed by +`external_diffs_object_store_`. + +| Setting | Description | Default | +|---------|-------------|---------| +| `enabled` | Enable/disable object storage | `false` | +| `remote_directory` | The bucket name where external diffs will be stored| | +| `direct_upload` | Set to true to enable direct upload of external diffs without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | `false` | +| `background_upload` | Set to false to disable automatic upload. Option may be removed once upload is direct to S3 | `true` | +| `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` | +| `connection` | Various connection options described below | | + +#### S3 compatible connection settings + +The connection settings match those provided by [Fog](https://github.com/fog), and are as follows: + +| Setting | Description | Default | +|---------|-------------|---------| +| `provider` | Always `AWS` for compatible hosts | AWS | +| `aws_access_key_id` | AWS credentials, or compatible | | +| `aws_secret_access_key` | AWS credentials, or compatible | | +| `aws_signature_version` | AWS signature version to use. 2 or 4 are valid options. Digital Ocean Spaces and other providers may need 2. | 4 | +| `region` | AWS region | us-east-1 | +| `host` | S3 compatible host for when not using AWS, e.g. `localhost` or `storage.example.com` | s3.amazonaws.com | +| `endpoint` | Can be used when configuring an S3 compatible service such as [Minio](https://www.minio.io), by entering a URL such as `http://127.0.0.1:9000` | (optional) | +| `path_style` | Set to true to use `host/bucket_name/object` style paths instead of `bucket_name.host/object`. Leave as false for AWS S3 | false | +| `use_iam_profile` | Set to true to use IAM profile instead of access keys | false + +**In Omnibus installations:** + +1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with + the values you want: + + ```ruby + gitlab_rails['external_diffs_enabled'] = true + gitlab_rails['external_diffs_object_store_enabled'] = true + gitlab_rails['external_diffs_object_store_remote_directory'] = "external-diffs" + gitlab_rails['external_diffs_object_store_connection'] = { + 'provider' => 'AWS', + 'region' => 'eu-central-1', + 'aws_access_key_id' => 'AWS_ACCESS_KEY_ID', + 'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY' + } + ``` + + NOTE: if you are using AWS IAM profiles, be sure to omit the + AWS access key and secret access key/value pairs. For example: + + ```ruby + gitlab_rails['external_diffs_object_store_connection'] = { + 'provider' => 'AWS', + 'region' => 'eu-central-1', + 'use_iam_profile' => true + } + ``` + +1. Save the file and [reconfigure GitLab][] for the changes to take effect. + +--- + +**In installations from source:** + +1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following + lines: + + ```yaml + external_diffs: + enabled: true + object_store: + enabled: true + remote_directory: "external-diffs" # The bucket name + connection: + provider: AWS # Only AWS supported at the moment + aws_access_key_id: AWS_ACCESS_KEY_ID + aws_secret_access_key: AWS_SECRET_ACCESS_KEY + region: eu-central-1 + ``` + +1. Save the file and [restart GitLab][] for the changes to take effect. diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index c9a2778b3a4..6ea0ac0d495 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -48,6 +48,8 @@ The following metrics are available: | upload_file_does_not_exist | Counter | 10.7 in EE, 11.5 in CE | Number of times an upload record could not find its file | | failed_login_captcha_total | Gauge | 11.0 | Counter of failed CAPTCHA attempts during login | | successful_login_captcha_total | Gauge | 11.0 | Counter of successful CAPTCHA attempts during login | +| unicorn_active_connections | Gauge | 11.0 | The number of active Unicorn connections (workers) | +| unicorn_queued_connections | Gauge | 11.0 | The number of queued Unicorn connections | ### Ruby metrics diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md index 0397452e650..c0c242733a2 100644 --- a/doc/administration/operations/filesystem_benchmarking.md +++ b/doc/administration/operations/filesystem_benchmarking.md @@ -7,13 +7,72 @@ systems. Normally when talking about filesystem performance the biggest concern is with Network Filesystems (NFS). However, even some local disks can have slow -IO. The information on this page can be used for either scenario. +I/O. The information on this page can be used for either scenario. -## Write Performance +## Executing benchmarks -The following one-line command is a quick benchmark for filesystem write +### Benchmarking with `fio` + +We recommend using +[fio](https://fio.readthedocs.io/en/latest/fio_doc.html) to test I/O +performance. This test should be run both on the NFS server and on the +application nodes that talk to the NFS server. + +To install: + +- On Ubuntu: `apt install fio`. +- On `yum`-managed environments: `yum install fio`. + +Then run the following: + +```sh +fio --randrepeat=1 --ioengine=libaio --direct=1 --gtod_reduce=1 --name=test --filename=/path/to/git-data/testfile --bs=4k --iodepth=64 --size=4G --readwrite=randrw --rwmixread=75 +``` + +This will create a 4GB file in `/path/to/git-data/testfile`. It performs +4KB reads and writes using a 75%/25% split within the file, with 64 +operations running at a time. Be sure to delete the file after the test +completes. + +The output will vary depending on what version of `fio` installed. The following +is an example output from `fio` v2.2.10 on a networked solid-state drive (SSD): + +``` +test: (g=0): rw=randrw, bs=4K-4K/4K-4K/4K-4K, ioengine=libaio, iodepth=64 + fio-2.2.10 + Starting 1 process + test: Laying out IO file(s) (1 file(s) / 1024MB) + Jobs: 1 (f=1): [m(1)] [100.0% done] [131.4MB/44868KB/0KB /s] [33.7K/11.3K/0 iops] [eta 00m:00s] + test: (groupid=0, jobs=1): err= 0: pid=10287: Sat Feb 2 17:40:10 2019 + read : io=784996KB, bw=133662KB/s, iops=33415, runt= 5873msec + write: io=263580KB, bw=44880KB/s, iops=11219, runt= 5873msec + cpu : usr=6.56%, sys=23.11%, ctx=266267, majf=0, minf=8 + IO depths : 1=0.1%, 2=0.1%, 4=0.1%, 8=0.1%, 16=0.1%, 32=0.1%, >=64=100.0% + submit : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0% + complete : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.1%, >=64=0.0% + issued : total=r=196249/w=65895/d=0, short=r=0/w=0/d=0, drop=r=0/w=0/d=0 + latency : target=0, window=0, percentile=100.00%, depth=64 + + Run status group 0 (all jobs): + READ: io=784996KB, aggrb=133661KB/s, minb=133661KB/s, maxb=133661KB/s, mint=5873msec, maxt=5873msec + WRITE: io=263580KB, aggrb=44879KB/s, minb=44879KB/s, maxb=44879KB/s, mint=5873msec, maxt=5873msec +``` + +Notice the `iops` values in this output. In this example, the SSD +performed 33,415 read operations per second and 11,219 write operations +per second. A spinning disk might yield 2,000 and 700 read and write +operations per second. + +### Simple benchmarking + +NOTE: **Note:** This test is naive but may be useful if `fio` is not +available on the system. It's possible to receive good results on this +test but still have poor performance due to read speed and various other +factors. + +The following one-line commands provide a quick benchmark for filesystem write and read performance. This will write 1,000 small files to the directory in which it is -executed. +executed, and then read the same 1,000 files. 1. Change into the root of the appropriate [repository storage path](../repository_storage_paths.md). @@ -27,13 +86,18 @@ executed. ```sh time for i in {0..1000}; do echo 'test' > "test${i}.txt"; done ``` +1. To benchmark read performance, run the command: + + ```sh + time for i in {0..1000}; do cat "test${i}.txt" > /dev/null; done + ``` 1. Remove the test files: ```sh cd ../; rm -rf test ``` -The output of the `time for ...` command will look similar to the following. The +The output of the `time for ...` commands will look similar to the following. The important metric is the `real` time. ```sh @@ -42,12 +106,13 @@ $ time for i in {0..1000}; do echo 'test' > "test${i}.txt"; done real 0m0.116s user 0m0.025s sys 0m0.091s + +$ time for i in {0..1000}; do cat "test${i}.txt" > /dev/null; done + +real 0m3.118s +user 0m1.267s +sys 0m1.663s ``` From experience with multiple customers, this task should take under 10 -seconds to indicate good filesystem performance. - -NOTE: **Note:** -This test is naive and only evaluates write performance. It's possible to -receive good results on this test but still have poor performance due to read -speed and various other factors.
\ No newline at end of file +seconds to indicate good filesystem performance. diff --git a/doc/api/README.md b/doc/api/README.md index 0bf29a3fc49..3b43d195390 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -29,6 +29,7 @@ The following API resources are available: - [Group access requests](access_requests.md) - [Group badges](group_badges.md) - [Group issue boards](group_boards.md) + - [Group labels](group_labels.md) - [Group-level variables](group_level_variables.md) - [Group members](members.md) - [Group milestones](group_milestones.md) diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index fe370682308..357d9916ade 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.md @@ -1,18 +1,25 @@ # Broadcast Messages API -> **Note:** This feature was introduced in GitLab 8.12. +> Introduced in GitLab 8.12. -The broadcast message API is only accessible to administrators. All requests by -guests will respond with `401 Unauthorized`, and all requests by normal users -will respond with `403 Forbidden`. +Broadcast messages API operates on [broadcast messages](../user/admin_area/broadcast_messages.md). + +The broadcast message API is only accessible to administrators. All requests by: + +- Guests will result in `401 Unauthorized`. +- Regular users will result in `403 Forbidden`. ## Get all broadcast messages -``` +List all broadcast messages. + +```text GET /broadcast_messages ``` -```bash +Example request: + +```sh curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages ``` @@ -34,15 +41,21 @@ Example response: ## Get a specific broadcast message -``` +Get a specific broadcast message. + +```text GET /broadcast_messages/:id ``` -| Attribute | Type | Required | Description | -| ----------- | -------- | -------- | ------------------------- | -| `id` | integer | yes | Broadcast message ID | +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:-------------------------------------| +| `id` | integer | yes | ID of broadcast message to retrieve. | + +Example request: -```bash +```sh curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1 ``` @@ -62,19 +75,25 @@ Example response: ## Create a broadcast message -``` +Create a new broadcast message. + +```text POST /broadcast_messages ``` -| Attribute | Type | Required | Description | -| ----------- | -------- | -------- | ---------------------------------------------------- | -| `message` | string | yes | Message to display | -| `starts_at` | datetime | no | Starting time (defaults to current time) | -| `ends_at` | datetime | no | Ending time (defaults to one hour from current time) | -| `color` | string | no | Background color hex code | -| `font` | string | no | Foreground color hex code | +Parameters: -```bash +| Attribute | Type | Required | Description | +|:------------|:---------|:---------|:------------------------------------------------------| +| `message` | string | yes | Message to display. | +| `starts_at` | datetime | no | Starting time (defaults to current time). | +| `ends_at` | datetime | no | Ending time (defaults to one hour from current time). | +| `color` | string | no | Background color hex code. | +| `font` | string | no | Foreground color hex code. | + +Example request: + +```sh curl --data "message=Deploy in progress&color=#cecece" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages ``` @@ -94,20 +113,26 @@ Example response: ## Update a broadcast message -``` +Update an existing broadcast message. + +```text PUT /broadcast_messages/:id ``` -| Attribute | Type | Required | Description | -| ----------- | -------- | -------- | ------------------------- | -| `id` | integer | yes | Broadcast message ID | -| `message` | string | no | Message to display | -| `starts_at` | datetime | no | Starting time | -| `ends_at` | datetime | no | Ending time | -| `color` | string | no | Background color hex code | -| `font` | string | no | Foreground color hex code | +Parameters: + +| Attribute | Type | Required | Description | +|:------------|:---------|:---------|:-----------------------------------| +| `id` | integer | yes | ID of broadcast message to update. | +| `message` | string | no | Message to display. | +| `starts_at` | datetime | no | Starting time. | +| `ends_at` | datetime | no | Ending time. | +| `color` | string | no | Background color hex code. | +| `font` | string | no | Foreground color hex code. | -```bash +Example request: + +```sh curl --request PUT --data "message=Update message&color=#000" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1 ``` @@ -127,14 +152,20 @@ Example response: ## Delete a broadcast message -``` +Delete a broadcast message. + +```sh DELETE /broadcast_messages/:id ``` -| Attribute | Type | Required | Description | -| ----------- | -------- | -------- | ------------------------- | -| `id` | integer | yes | Broadcast message ID | +Parameters: + +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:-----------------------------------| +| `id` | integer | yes | ID of broadcast message to delete. | + +Example request: -```bash +```sh curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/broadcast_messages/1 ``` diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md new file mode 100644 index 00000000000..c36d34b4af1 --- /dev/null +++ b/doc/api/group_labels.md @@ -0,0 +1,201 @@ +# Group Label API + +>**Note:** This feature was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21368) in GitLab 11.8. + +This API supports managing of [group labels](../user/project/labels.md#project-labels-and-group-labels). It allows to list, create, update, and delete group labels. Furthermore, users can subscribe and unsubscribe to and from group labels. + +## List group labels + +Get all labels for a given group. + +``` +GET /groups/:id/labels +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels +``` + +Example response: + +```json +[ + { + "id": 7, + "name": "bug", + "color": "#FF0000", + "description": null, + "open_issues_count": 0, + "closed_issues_count": 0, + "open_merge_requests_count": 0, + "subscribed": false + }, + { + "id": 4, + "name": "feature", + "color": "#228B22", + "description": null, + "open_issues_count": 0, + "closed_issues_count": 0, + "open_merge_requests_count": 0, + "subscribed": false + } +] +``` + +## Create a new group label + +Create a new group label for a given group. + +``` +POST /groups/:id/labels +``` + +| Attribute | Type | Required | Description | +| ------------- | ------- | -------- | ---------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `name` | string | yes | The name of the label | +| `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | +| `description` | string | no | The description of the label | + +```bash +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "Feature Proposal", "color": "#FFA500", "description": "Describes new ideas" }' https://gitlab.example.com/api/v4/groups/5/labels +``` + +Example response: + +```json +{ + "id": 9, + "name": "Feature Proposal", + "color": "#FFA500", + "description": "Describes new ideas", + "open_issues_count": 0, + "closed_issues_count": 0, + "open_merge_requests_count": 0, + "subscribed": false +} +``` + +## Update a group label + +Updates an existing group label. At least one parameter is required, to update the group label. + +``` +PUT /groups/:id/labels +``` + +| Attribute | Type | Required | Description | +| ------------- | ------- | -------- | ---------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `name` | string | yes | The name of the label | +| `new_name` | string | no | The new name of the label | +| `color` | string | no | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | +| `description` | string | no | The description of the label | + +```bash +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "Feature Proposal", "new_name": "Feature Idea" }' https://gitlab.example.com/api/v4/groups/5/labels +``` + +Example response: + +```json +{ + "id": 9, + "name": "Feature Idea", + "color": "#FFA500", + "description": "Describes new ideas", + "open_issues_count": 0, + "closed_issues_count": 0, + "open_merge_requests_count": 0, + "subscribed": false +} +``` + +## Delete a group label + +Deletes a group label with a given name. + +``` +DELETE /groups/:id/labels +``` + +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | --------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `name` | string | yes | The name of the label | + +```bash +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels?name=bug +``` + +## Subscribe to a group label + +Subscribes the authenticated user to a group label to receive notifications. If +the user is already subscribed to the label, the status code `304` is returned. + +``` +POST /groups/:id/labels/:label_id/subscribe +``` + +| Attribute | Type | Required | Description | +| ---------- | ----------------- | -------- | ------------------------------------ | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `label_id` | integer or string | yes | The ID or title of a group's label | + +```bash +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels/9/subscribe +``` + +Example response: + +```json +{ + "id": 9, + "name": "Feature Idea", + "color": "#FFA500", + "description": "Describes new ideas", + "open_issues_count": 0, + "closed_issues_count": 0, + "open_merge_requests_count": 0, + "subscribed": true +} +``` + +## Unsubscribe from a group label + +Unsubscribes the authenticated user from a group label to not receive +notifications from it. If the user is not subscribed to the label, the status +code `304` is returned. + +``` +POST /groups/:id/labels/:label_id/unsubscribe +``` + +| Attribute | Type | Required | Description | +| ---------- | ----------------- | -------- | ------------------------------------ | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `label_id` | integer or string | yes | The ID or title of a group's label | + +```bash +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels/9/unsubscribe +``` + +Example response: + +```json +{ + "id": 9, + "name": "Feature Idea", + "color": "#FFA500", + "description": "Describes new ideas", + "open_issues_count": 0, + "closed_issues_count": 0, + "open_merge_requests_count": 0, + "subscribed": false +} +``` diff --git a/doc/api/issues.md b/doc/api/issues.md index 6d8683601f6..ed3165d95df 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -31,6 +31,7 @@ GET /issues?iids[]=42&iids[]=43 GET /issues?author_id=5 GET /issues?assignee_id=5 GET /issues?my_reaction_emoji=star +GET /issues?search=foo&in=title ``` | Attribute | Type | Required | Description | @@ -46,6 +47,7 @@ GET /issues?my_reaction_emoji=star | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search issues against their `title` and `description` | +| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | | `created_after` | datetime | no | Return issues created on or after the given time | | `created_before` | datetime | no | Return issues created on or before the given time | | `updated_after` | datetime | no | Return issues updated on or after the given time | diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index c9b271eada3..d58cd45538d 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -24,6 +24,7 @@ GET /merge_requests?labels=bug,reproduced GET /merge_requests?author_id=5 GET /merge_requests?my_reaction_emoji=star GET /merge_requests?scope=assigned_to_me +GET /merge_requests?search=foo&in=title ``` Parameters: @@ -47,6 +48,7 @@ Parameters: | `source_branch` | string | no | Return merge requests with the given source branch | | `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | +| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | | `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | ```json @@ -182,6 +184,7 @@ Parameters: | `source_branch` | string | no | Return merge requests with the given source branch | | `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | +| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | ```json [ @@ -991,6 +994,8 @@ 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 +- `squash_commit_message` (optional) - Custom squash commit message +- `squash` (optional) - if `true` the commits will be squashed into a single commit on merge - `should_remove_source_branch` (optional) - if `true` removes the source branch - `merge_when_pipeline_succeeds` (optional) - if `true` the MR is merged when the pipeline succeeds - `sha` (optional) - if present, then this SHA must match the HEAD of the source branch, otherwise the merge will fail diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 034b9172ffa..8efb98fe1fc 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -76,7 +76,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer | yes | The ID of the project owned by the authenticated user | -| `cluster_id` | integer | yes | The ID of the cluster | +| `cluster_id` | integer | yes | The ID of the cluster | Example request: @@ -157,12 +157,12 @@ Parameters: | --------- | ---- | -------- | ----------- | | `id` | integer | yes | The ID of the project owned by the authenticated user | | `name` | String | yes | The name of the cluster | -| `enabled` | Boolean | no | Determines if cluster is active or not, defaults to true | -| `platform_kubernetes_attributes[api_url]` | String | yes | The URL to access the Kubernetes API | +| `enabled` | Boolean | no | Determines if cluster is active or not, defaults to true | +| `platform_kubernetes_attributes[api_url]` | String | yes | The URL to access the Kubernetes API | | `platform_kubernetes_attributes[token]` | String | yes | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | -| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | -| `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | +| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | +| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | +| `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | Example request: @@ -246,11 +246,11 @@ Parameters: | --------- | ---- | -------- | ----------- | | `id` | integer | yes | The ID of the project owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | -| `name` | String | no | The name of the cluster | -| `platform_kubernetes_attributes[api_url]` | String | no | The URL to access the Kubernetes API | -| `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes | -| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | -| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | +| `name` | String | no | The name of the cluster | +| `platform_kubernetes_attributes[api_url]` | String | no | The URL to access the Kubernetes API | +| `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes | +| `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | +| `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | NOTE: **Note:** `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added diff --git a/doc/api/projects.md b/doc/api/projects.md index 1296b435792..3c0c956ddc2 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -54,6 +54,7 @@ GET /projects | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | | `with_issues_enabled` | boolean | no | Limit by enabled issues feature | | `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature | +| `with_programming_language` | string | no | Limit by projects which use the given programming language | | `wiki_checksum_failed` | boolean | no | Limit projects where the wiki checksum calculation has failed _([Introduced][ee-6137] in [GitLab Premium][eep] 11.2)_ | | `repository_checksum_failed` | boolean | no | Limit projects where the repository checksum calculation has failed _([Introduced][ee-6137] in [GitLab Premium][eep] 11.2)_ | | `min_access_level` | integer | no | Limit by current user minimal [access level](members.md) | @@ -279,6 +280,7 @@ GET /users/:user_id/projects | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | | `with_issues_enabled` | boolean | no | Limit by enabled issues feature | | `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature | +| `with_programming_language` | string | no | Limit by projects which use the given programming language | | `min_access_level` | integer | no | Limit by current user minimal [access level](members.md) | ```json diff --git a/doc/api/settings.md b/doc/api/settings.md index c329e3cdf24..2e0a2a09133 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -57,11 +57,13 @@ Example response: "dsa_key_restriction": 0, "ecdsa_key_restriction": 0, "ed25519_key_restriction": 0, + "first_day_of_week": 0, "enforce_terms": true, "terms": "Hello world!", "performance_bar_allowed_group_id": 42, "instance_statistics_visibility_private": false, - "user_show_add_ssh_key_message": true + "user_show_add_ssh_key_message": true, + "local_markdown_version": 0 } ``` @@ -113,11 +115,13 @@ Example response: "dsa_key_restriction": 0, "ecdsa_key_restriction": 0, "ed25519_key_restriction": 0, + "first_day_of_week": 0, "enforce_terms": true, "terms": "Hello world!", "performance_bar_allowed_group_id": 42, "instance_statistics_visibility_private": false, - "user_show_add_ssh_key_message": true + "user_show_add_ssh_key_message": true, + "local_markdown_version": 0 } ``` @@ -157,6 +161,7 @@ are listed in the descriptions of the relevant settings. | `email_author_in_body` | boolean | no | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. | | `enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. | | `enforce_terms` | boolean | no | (**If enabled, requires:** `terms`) Enforce application ToS to all users. | +| `first_day_of_week` | integer | no | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday and `1` for Monday. | | `gitaly_timeout_default` | integer | no | Default Gitaly timeout, in seconds. This timeout is not enforced for git fetch/push operations or Sidekiq jobs. Set to `0` to disable timeouts. | | `gitaly_timeout_fast` | integer | no | Gitaly fast operation timeout, in seconds. Some Gitaly operations are expected to be fast. If they exceed this threshold, there may be a problem with a storage shard and 'failing fast' can help maintain the stability of the GitLab instance. Set to `0` to disable timeouts. | | `gitaly_timeout_medium` | integer | no | Medium Gitaly timeout, in seconds. This should be a value between the Fast and the Default timeout. Set to `0` to disable timeouts. | @@ -235,3 +240,4 @@ are listed in the descriptions of the relevant settings. | `user_oauth_applications` | boolean | no | Allow users to register any application to use GitLab as an OAuth provider. | | `user_show_add_ssh_key_message` | boolean | no | When set to `false` disable the "You won't be able to pull or push project code via SSH" warning shown to users with no uploaded SSH key. | | `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | +| `local_markdown_version` | integer | no | Increase this value when any cached markdown should be invalidated. | diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 2cbd041d132..f90447e124e 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -1,43 +1,100 @@ # Snippets API -> [Introduced][ce-6373] in GitLab 8.15. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6373) in GitLab 8.15. + +Snippets API operates on [snippets](../user/snippets.md). ## Snippet visibility level Snippets in GitLab can be either private, internal, or public. You can set it with the `visibility` field in the snippet. -Constants for snippet visibility levels are: +Valid values for snippet visibility levels are: -| Visibility | Description | -| ---------- | ----------- | -| `private` | The snippet is visible only to the snippet creator | -| `internal` | The snippet is visible for any logged in user | -| `public` | The snippet can be accessed without any authentication | +| Visibility | Description | +|:-----------|:----------------------------------------------------| +| `private` | Snippet is visible only to the snippet creator. | +| `internal` | Snippet is visible for any logged in user. | +| `public` | Snippet can be accessed without any authentication. | -## List snippets +## List all snippets for a user -Get a list of current user's snippets. +Get a list of the current user's snippets. -``` +```text GET /snippets ``` -## Single snippet +Example request: -Get a single snippet. +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets +``` + +Example response: +```json +[ + { + "id": 42, + "title": "Voluptatem iure ut qui aut et consequatur quaerat.", + "file_name": "mclaughlin.rb", + "description": null, + "visibility": "internal", + "author": { + "id": 22, + "name": "User 0", + "username": "user0", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon", + "web_url": "http://localhost:3000/user0" + }, + "updated_at": "2018-09-18T01:12:26.383Z", + "created_at": "2018-09-18T01:12:26.383Z", + "project_id": null, + "web_url": "http://localhost:3000/snippets/42", + "raw_url": "http://localhost:3000/snippets/42/raw" + }, + { + "id": 41, + "title": "Ut praesentium non et atque.", + "file_name": "ondrickaemard.rb", + "description": null, + "visibility": "internal", + "author": { + "id": 22, + "name": "User 0", + "username": "user0", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon", + "web_url": "http://localhost:3000/user0" + }, + "updated_at": "2018-09-18T01:12:26.360Z", + "created_at": "2018-09-18T01:12:26.360Z", + "project_id": null, + "web_url": "http://localhost:3000/snippets/41", + "raw_url": "http://localhost:3000/snippets/41/raw" + } +] ``` + +## Get a single snippet + +Get a single snippet. + +```text GET /snippets/:id ``` Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | Integer | yes | The ID of a snippet | +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:---------------------------| +| `id` | integer | yes | ID of snippet to retrieve. | + +Example request: -```bash +```sh curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1 ``` @@ -69,46 +126,52 @@ Example response: Get a single snippet's raw contents. -``` +```text GET /snippets/:id/raw ``` Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | Integer | yes | The ID of a snippet | +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:---------------------------| +| `id` | integer | yes | ID of snippet to retrieve. | -```bash +Example request: + +```sh curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1/raw ``` Example response: -``` +```text Hello World snippet ``` ## Create new snippet -Creates a new snippet. The user must have permission to create new snippets. +Create a new snippet. -``` +NOTE: **Note:** +The user must have permission to create new snippets. + +```text POST /snippets ``` Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `title` | String | yes | The title of a snippet | -| `file_name` | String | yes | The name of a snippet file | -| `content` | String | yes | The content of a snippet | -| `description` | String | no | The description of a snippet | -| `visibility` | String | no | The snippet's visibility | +| Attribute | Type | Required | Description | +|:--------------|:-------|:---------|:---------------------------------------------------| +| `title` | string | yes | Title of a snippet. | +| `file_name` | string | yes | Name of a snippet file. | +| `content` | string | yes | Content of a snippet. | +| `description` | string | no | Description of a snippet. | +| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level). | +Example request: -```bash +```sh curl --request POST \ --data '{"title": "This is a snippet", "content": "Hello world", "description": "Hello World snippet", "file_name": "test.txt", "visibility": "internal" }' \ --header 'Content-Type: application/json' \ @@ -142,25 +205,29 @@ Example response: ## Update snippet -Updates an existing snippet. The user must have permission to change an existing snippet. +Update an existing snippet. -``` +NOTE: **Note:** +The user must have permission to change an existing snippet. + +```text PUT /snippets/:id ``` Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | Integer | yes | The ID of a snippet | -| `title` | String | no | The title of a snippet | -| `file_name` | String | no | The name of a snippet file | -| `description` | String | no | The description of a snippet | -| `content` | String | no | The content of a snippet | -| `visibility` | String | no | The snippet's visibility | +| Attribute | Type | Required | Description | +|:--------------|:--------|:---------|:---------------------------------------------------| +| `id` | integer | yes | ID of snippet to update. | +| `title` | string | no | Title of a snippet. | +| `file_name` | string | no | Name of a snippet file. | +| `description` | string | no | Description of a snippet. | +| `content` | string | no | Content of a snippet. | +| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level). | +Example request: -```bash +```sh curl --request PUT \ --data '{"title": "foo", "content": "bar"}' \ --header 'Content-Type: application/json' \ @@ -194,38 +261,49 @@ Example response: ## Delete snippet -Deletes an existing snippet. +Delete an existing snippet. -``` +```text DELETE /snippets/:id ``` Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | Integer | yes | The ID of a snippet | +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:-------------------------| +| `id` | integer | yes | ID of snippet to delete. | +Example request: -``` +```sh curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippets/1" ``` -upon successful delete a `204 No content` HTTP code shall be expected, with no data, -but if the snippet is non-existent, a `404 Not Found` will be returned. +The following are possible return codes: -## Explore all public snippets +| Code | Description | +|:------|:--------------------------------------------| +| `204` | Delete was successful. No data is returned. | +| `404` | The snippet wasn't found. | -``` +## List all public snippets + +List all public snippets. + +```text GET /snippets/public ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `per_page` | Integer | no | number of snippets to return per page | -| `page` | Integer | no | the page to retrieve | +Parameters: + +| Attribute | Type | Required | Description | +|:-----------|:--------|:---------|:---------------------------------------| +| `per_page` | integer | no | Number of snippets to return per page. | +| `page` | integer | no | Page to retrieve. | -```bash +Example request: + +```sh curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/public?per_page=2&page=1 ``` @@ -273,21 +351,22 @@ Example response: ## Get user agent details -> **Notes:** -> [Introduced][ce-29508] in GitLab 9.4. - +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12655) in GitLab 9.4. -Available only for admins. +NOTE: **Note:** +Available only for administrators. -``` +```text GET /snippets/:id/user_agent_detail ``` -| Attribute | Type | Required | Description | -|-------------|---------|----------|--------------------------------------| -| `id` | Integer | yes | The ID of a snippet | +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:---------------| +| `id` | integer | yes | ID of snippet. | -```bash +Example request: + +```sh curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1/user_agent_detail ``` @@ -300,6 +379,3 @@ Example response: "akismet_submitted": false } ``` - -[ce-6373]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6373 -[ce-29508]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12655 diff --git a/doc/api/users.md b/doc/api/users.md index 6000b9b900f..fd8778abb17 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -1212,6 +1212,7 @@ The activities that update the timestamp are: - Git HTTP/SSH activities (such as clone, push) - User logging in into GitLab + - User visiting pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/54947) in GitLab 11.8) By default, it shows the activity for all users in the last 6 months, but this can be amended by using the `from` parameter. diff --git a/doc/ci/examples/browser_performance.md b/doc/ci/examples/browser_performance.md index 7c3b3a65675..b47038011de 100644 --- a/doc/ci/examples/browser_performance.md +++ b/doc/ci/examples/browser_performance.md @@ -41,7 +41,7 @@ The above example will create a `performance` job in your CI/CD pipeline and wil Sitespeed.io against the webpage you defined in `URL` to gather key metrics. The [GitLab plugin](https://gitlab.com/gitlab-org/gl-performance) for Sitespeed.io is downloaded in order to save the report as a -[Performance report artifact](https://docs.gitlab.com/ee//ci/yaml/README.html#artifactsreportsperformance) +[Performance report artifact](../yaml/README.md#artifactsreportsperformance-premium) that you can later download and analyze. Due to implementation limitations we always take the latest Performance artifact available. diff --git a/doc/ci/examples/code_quality.md b/doc/ci/examples/code_quality.md index ae000b9d30d..3e7d6e7e3f7 100644 --- a/doc/ci/examples/code_quality.md +++ b/doc/ci/examples/code_quality.md @@ -36,7 +36,7 @@ code_quality: The above example will create a `code_quality` job in your CI/CD pipeline which will scan your source code for code quality issues. The report will be saved as a -[Code Quality report artifact](../../ci/yaml/README.md#artifactsreportscodequality) +[Code Quality report artifact](../yaml/README.md#artifactsreportscodequality-starter) that you can later download and analyze. Due to implementation limitations we always take the latest Code Quality artifact available. diff --git a/doc/ci/examples/container_scanning.md b/doc/ci/examples/container_scanning.md index 31c3df81fef..e8e9c73d1b2 100644 --- a/doc/ci/examples/container_scanning.md +++ b/doc/ci/examples/container_scanning.md @@ -51,7 +51,7 @@ The above example will create a `container_scanning` job in your CI/CD pipeline, the image from the [Container Registry](../../user/project/container_registry.md) (whose name is defined from the two `CI_APPLICATION_` variables) and scan it for possible vulnerabilities. The report will be saved as a -[Container Scanning report artifact](https://docs.gitlab.com/ee//ci/yaml/README.html#artifactsreportscontainer_scanning) +[Container Scanning report artifact](../yaml/README.md#artifactsreportscontainer_scanning-ultimate) that you can later download and analyze. Due to implementation limitations we always take the latest Container Scanning artifact available. diff --git a/doc/ci/examples/dast.md b/doc/ci/examples/dast.md index 0ca89eb6700..ab0ca13d2cf 100644 --- a/doc/ci/examples/dast.md +++ b/doc/ci/examples/dast.md @@ -40,7 +40,7 @@ dast: The above example will create a `dast` job in your CI/CD pipeline which will run the tests on the URL defined in the `website` variable (change it to use your own) and scan it for possible vulnerabilities. The report will be saved as a -[DAST report artifact](https://docs.gitlab.com/ee//ci/yaml/README.html#artifactsreportsdast) +[DAST report artifact](../yaml/README.md#artifactsreportsdast-ultimate) that you can later download and analyze. Due to implementation limitations we always take the latest DAST artifact available. diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md index 0cf9daed22f..2a4160f62b0 100644 --- a/doc/ci/interactive_web_terminal/index.md +++ b/doc/ci/interactive_web_terminal/index.md @@ -1,4 +1,4 @@ -# Interactive Web Terminals **[CORE ONLY]** +# Interactive Web Terminals > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/50144) in GitLab 11.3. @@ -9,10 +9,11 @@ is deployed, some [security precautions](../../administration/integration/termin taken to protect the users. NOTE: **Note:** -GitLab.com does not support interactive web terminal at the moment – neither -using shared GitLab.com runners nor your own runners. Please follow -[this issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611) for -progress. +[Shared runners on GitLab.com](../quick_start/README.md#shared-runners) do not +provide an interactive web terminal. Follow [this +issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/52611) for progress on +adding support. For groups and projects hosted on GitLab.com, interactive web +terminals are available when using your own group or project runner. ## Configuration diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index d2a00b9218d..c41f3b7e82d 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -3,7 +3,7 @@ > Introduced in GitLab 8.8. NOTE: **Note:** -If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository), +If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository-starter), you may need to enable pipeline triggering in your project's **Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 1ec8a8c89c9..9684cb6ed98 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -127,7 +127,7 @@ Now if you go to the **Pipelines** page you will see that the pipeline is pending. NOTE: **Note:** -If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository), +If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository-starter), you may need to enable pipeline triggering in your project's **Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 8b3a7b63e62..f4d7b9ad194 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -60,7 +60,7 @@ To get a better understanding of Review Apps, review documentation on how enviro 1. Learn about [environments](../environments.md) and their role in the development workflow. 1. Learn about [CI variables](../variables/README.md) and how they can be used in your CI jobs. 1. Explore the [`environment` syntax](../yaml/README.md#environment) as defined in `.gitlab-ci.yml`. This will become a primary reference. -1. Additionally, find out about [manual actions](../environments.md#manual-actions) and how you can use them to deploy to critical environments like production with the push of a button. +1. Additionally, find out about [manual actions](../environments.md#manually-deploying-to-environments) and how you can use them to deploy to critical environments like production with the push of a button. 1. Follow the [example tutorials](#examples). These will guide you through setting up infrastructure and using Review Apps. ### Configuring dynamic environments diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 45667caf65d..7498617ed2c 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -65,12 +65,12 @@ future GitLab releases.** | **CI_COMMIT_TITLE** | 10.8 | all | The title of the commit - the full first line of the message | | **CI_CONFIG_PATH** | 9.4 | 0.5 | The path to CI config file. Defaults to `.gitlab-ci.yml` | | **CI_DEBUG_TRACE** | all | 1.7 | Whether [debug tracing](#debug-tracing) is enabled | -| **CI_DEPLOY_PASSWORD** | 10.8 | all | Authentication password of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.| +| **CI_DEPLOY_PASSWORD** | 10.8 | all | Authentication password of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.| | **CI_DEPLOY_USER** | 10.8 | all | Authentication username of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.| | **CI_DISPOSABLE_ENVIRONMENT** | all | 10.1 | Marks that the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). If the environment is disposable, it is set to true, otherwise it is not defined at all. | -| **CI_ENVIRONMENT_NAME** | 8.15 | all | The name of the environment for this job | -| **CI_ENVIRONMENT_SLUG** | 8.15 | all | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. | -| **CI_ENVIRONMENT_URL** | 9.3 | all | The URL of the environment for this job | +| **CI_ENVIRONMENT_NAME** | 8.15 | all | The name of the environment for this job. Only present if [`environment:name`](../yaml/README.md#environmentname) is set. | +| **CI_ENVIRONMENT_SLUG** | 8.15 | all | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. Only present if [`environment:name`](../yaml/README.md#environmentname) is set. | +| **CI_ENVIRONMENT_URL** | 9.3 | all | The URL of the environment for this job. Only present if [`environment:url`](../yaml/README.md#environmenturl) is set. | | **CI_JOB_ID** | 9.0 | all | The unique id of the current job that GitLab CI uses internally | | **CI_JOB_MANUAL** | 8.12 | all | The flag to indicate that job was manually started | | **CI_JOB_NAME** | 9.0 | 0.5 | The name of the job as defined in `.gitlab-ci.yml` | @@ -98,7 +98,7 @@ future GitLab releases.** | **CI_PIPELINE_SOURCE** | 10.0 | all | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `trigger`, `schedule`, `api`, and `pipeline`. For pipelines created before GitLab 9.5, this will show as `unknown` | | **CI_PIPELINE_TRIGGERED** | all | all | The flag to indicate that job was [triggered] | | **CI_PIPELINE_URL** | 11.1 | 0.5 | Pipeline details URL | -| **CI_PROJECT_DIR** | all | all | The full path where the repository is cloned and where the job is run | +| **CI_PROJECT_DIR** | all | all | The full path where the repository is cloned and where the job is run. If the GitLab Runner `builds_dir` parameter is set, this variable is set relative to the value of `builds_dir`. For more information, see [Advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) for GitLab Runner. | | **CI_PROJECT_ID** | all | all | The unique id of the current project that GitLab CI uses internally | | **CI_PROJECT_NAME** | 8.10 | 0.5 | The project name that is currently being built (actually it is project folder name) | | **CI_PROJECT_NAMESPACE** | 8.10 | 0.5 | The project namespace (username or groupname) that is currently being built | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 4c39b14b1d0..984878b6c9b 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -11,7 +11,7 @@ If you want a quick introduction to GitLab CI, follow our [quick start guide](../quick_start/README.md). NOTE: **Note:** -If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository), +If you have a [mirrored repository where GitLab pulls from](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository-starter), you may need to enable pipeline triggering in your project's **Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**. @@ -776,7 +776,7 @@ In the above example we set up the `review_app` job to deploy to the `review` environment, and we also defined a new `stop_review_app` job under `on_stop`. Once the `review_app` job is successfully finished, it will trigger the `stop_review_app` job based on what is defined under `when`. In this case we -set it up to `manual` so it will need a [manual action](#manual-actions) via +set it up to `manual` so it will need a [manual action](#whenmanual) via GitLab's web interface in order to run. The `stop_review_app` job is **required** to have the following keywords defined: diff --git a/doc/development/README.md b/doc/development/README.md index 05715274a81..d5829e31343 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -123,3 +123,7 @@ description: 'Learn how to contribute to GitLab.' ## Compliance - [Licensing](licensing.md) for ensuring license compliance + +## Go guides + +- [Go Guidelines](go_guide/index.md) diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 24feb1378a1..c5344139ab4 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -20,7 +20,7 @@ All labels, their meaning and priority are defined on the If you come across an issue that has none of these, and you're allowed to set labels, you can _always_ add the team and type, and often also the subject. -[milestones-page]: https://gitlab.com/gitlab-org/gitlab-ce/milestones +[milestones-page]: https://gitlab.com/groups/gitlab-org/-/milestones ## Type labels diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 9bef0635e3f..19b6181c9a2 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -86,6 +86,9 @@ request is as follows: guidelines](../merge_request_performance_guidelines.md). 1. For tests that use Capybara or PhantomJS, see this [article on how to write reliable asynchronous tests](https://robots.thoughtbot.com/write-reliable-asynchronous-integration-tests-with-capybara). +1. If your merge request introduces changes that require additional steps when + installing GitLab from source, add them to `doc/install/installation.md` in + the same merge request. Please keep the change in a single MR **as small as possible**. If you want to contribute a large feature think very hard what the minimum viable change is. diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 6f1ba5d62a5..0eedef5e14f 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -21,6 +21,7 @@ of _prohibited this user from being saved due to the following errors:_ the text should be _sorry, we could not create your account because:_ 1. Code should be written in [US English][us-english] +1. [Go](../go_guide/index.md) This is also the style used by linting tools such as [RuboCop](https://github.com/bbatsov/rubocop) and [Hound CI](https://houndci.com). diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 828f9bfeec6..aac98c6ee7f 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -27,7 +27,7 @@ The source of the documentation is maintained in the following repository locati | Project | Path | | --- | --- | | [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-ce/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc) | -| [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab-ce/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc) | +| [GitLab Enterprise Edition](https://gitlab.com/gitlab-org/gitlab-ee/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc) | | [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/) | [`/docs`](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) | | [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/) | [`/doc`](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc) | @@ -78,7 +78,7 @@ you can immediately tell that you are navigating to user-related documentation about project features; specifically about merge requests. Our site's paths match those of our repository, so the clear structure also makes documentation easier to update. -While the documentation is home to a variety of content types, we do not organize by content type. +While the documentation is home to a variety of content types, we do not organize by content type. For example, do not create groupings of similar media types (e.g. indexes of all articles, videos, etc.). Similarly, we do not use glossaries or FAQs. Such grouping of content by type makes it difficult to browse for the information you need and difficult to maintain up-to-date content. @@ -498,7 +498,7 @@ If you want to know the in-depth details, here's what's really happening: The following GitLab features are used among others: -- [Manual actions](../../ci/yaml/README.md#manual-actions) +- [Manual actions](../../ci/yaml/README.md#whenmanual) - [Multi project pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html) - [Review Apps](../../ci/review_apps/index.md) - [Artifacts](../../ci/yaml/README.md#artifacts) diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 790b1bf951b..e0985922443 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -839,6 +839,20 @@ For example there can be an `app/assets/javascripts/protected_branches/protected_branches_bundle.js` and an EE counterpart `ee/app/assets/javascripts/protected_branches/protected_branches_bundle.js`. +The corresponding import statement would then look like this: + +```javascript +// app/assets/javascripts/protected_branches/protected_branches_bundle.js +import bundle from '~/protected_branches/protected_branches_bundle.js'; + +// ee/app/assets/javascripts/protected_branches/protected_branches_bundle.js +// (only works in EE) +import bundle from 'ee/protected_branches/protected_branches_bundle.js'; + +// in CE: app/assets/javascripts/protected_branches/protected_branches_bundle.js +// in EE: ee/app/assets/javascripts/protected_branches/protected_branches_bundle.js +import bundle from 'ee_else_ce/protected_branches/protected_branches_bundle.js'; +``` See the frontend guide [performance section](./fe_guide/performance.md) for information on managing page-specific javascript within EE. diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index b90dc90e424..597812c8c49 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -18,6 +18,7 @@ There are many places where file uploading is used, according to contexts: - Issues/MR/Notes Legacy Markdown attachments - CI Artifacts (archive, metadata, trace) - LFS Objects + - Merge request diffs ## Disk storage @@ -37,6 +38,7 @@ they are still not 100% standardized. You can see them below: | Issues/MR/Notes Legacy Markdown attachments | no | uploads/-/system/note/attachment/:id/:filename | `AttachmentUploader` | Note | | CI Artifacts (CE) | yes | shared/artifacts/:disk_hash[0..1]/:disk_hash[2..3]/:disk_hash/:year_:month_:date/:job_id/:job_artifact_id (:disk_hash is SHA256 digest of project_id) | `JobArtifactUploader` | Ci::JobArtifact | | LFS Objects (CE) | yes | shared/lfs-objects/:hex/:hex/:object_hash | `LfsObjectUploader` | LfsObject | +| External merge request diffs | yes | shared/external-diffs/merge_request_diffs/mr-:parent_id/diff-:id | `ExternalDiffUploader` | MergeRequestDiff | CI Artifacts and LFS Objects behave differently in CE and EE. In CE they inherit the `GitlabUploader` while in EE they inherit the `ObjectStorage` and store files in and S3 API compatible object store. diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md new file mode 100644 index 00000000000..cdc806a2d31 --- /dev/null +++ b/doc/development/go_guide/index.md @@ -0,0 +1,216 @@ +# Go standards and style guidelines + +This document describes various guidelines and best practices for GitLab +projects using the [Go language](https://golang.org). + +## Overview + +GitLab is built on top of [Ruby on Rails](https://rubyonrails.org/), but we're +also using Go for projects where it makes sense. Go is a very powerful +language, with many advantages, and is best suited for projects with a lot of +IO (disk/network access), HTTP requests, parallel processing, etc. Since we +have both Ruby on Rails and Go at GitLab, we should evaluate carefully which of +the two is best for the job. + +This page aims to define and organize our Go guidelines, based on our various +experiences. Several projects were started with different standards and they +can still have specifics. They will be described in their respective +`README.md` or `PROCESS.md` files. + +## Code Review + +We follow the common principles of +[Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments). + +Reviewers and maintainers should pay attention to: + +- `defer` functions: ensure the presence when needed, and after `err` check. +- Inject dependencies as parameters. +- Void structs when marshalling to JSON (generates `null` instead of `[]`). + +### Security + +Security is our top priority at GitLab. During code reviews, we must take care +of possible security breaches in our code: + +- XSS when using text/template +- CSRF Protection using Gorilla +- Use a Go version without known vulnerabilities +- Don't leak secret tokens +- SQL injections + +Remember to run +[SAST](https://docs.gitlab.com/ee/user/project/merge_requests/sast.html) +**[ULTIMATE]** on your project (or at least the [gosec +analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/gosec)), +and to follow our [Security +requirements](../code_review.md#security-requirements). + +Web servers can take advantages of middlewares like [Secure](https://github.com/unrolled/secure). + +### Finding a reviewer + +Many of our projects are too small to have full-time maintainers. That's why we +have a shared pool of Go reviewers at GitLab. To find a reviewer, use the +[Engineering Projects](https://about.gitlab.com/handbook/engineering/projects/) +page in the handbook. "GitLab Community Edition (CE)" and "GitLab Community +Edition (EE)" both have a "Go" section with its list of reviewers. + +To add yourself to this list, add the following to your profile in the +[team.yml](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/team.yml) +file and ask your manager to review and merge. + +```yaml +projects: + gitlab-ee: reviewer go + gitlab-ce: reviewer go +``` + +## Code style and format + +- Avoid global variables, even in packages. By doing so you will introduce side + effects if the package is included multiple times. +- Use `go fmt` before committing ([Gofmt](https://golang.org/cmd/gofmt/) is a + tool that automatically formats Go source code). + +### Automatic linting + +All Go projects should include these GitLab CI/CD jobs: + +```yaml +go lint: + image: golang:1.11 + script: + - go get -u golang.org/x/lint/golint + - golint -set_exit_status +``` + +Once [recursive includes](https://gitlab.com/gitlab-org/gitlab-ce/issues/56836) +become available, you will be able to share job templates like this +[analyzer](https://gitlab.com/gitlab-org/security-products/ci-templates/raw/master/includes-dev/analyzer.yml). + +## Dependencies + +Dependencies should be kept to the minimum. The introduction of a new +dependency should be argued in the merge request, as per our [Approval +Guidelines](../code_review.html#approval-guidelines). Both [License +Management](https://docs.gitlab.com/ee/user/project/merge_requests/license_management.html) +**[ULTIMATE]** and [Dependency +Scanning](https://docs.gitlab.com/ee/user/project/merge_requests/dependency_scanning.html) +**[ULTIMATE]** should be activated on all projects to ensure new dependencies +security status and license compatibility. + +### Modules + +Since Go 1.11, a standard dependency system is available behind the name [Go +Modules](https://github.com/golang/go/wiki/Modules). It provides a way to +define and lock dependencies for reproducible builds. It should be used +whenever possible. + +There was a [bug on modules +checksums](https://github.com/golang/go/issues/29278) in Go < v1.11.4, so make +sure to use at least this version to avoid `checksum mismatch` errors. + +### ORM + +We don't use object-relational mapping libraries (ORMs) at GitLab (except +[ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html) in +Ruby on Rails). Projects can be structured with services to avoid them. +[PQ](https://github.com/lib/pq) should be enough to interact with PostgreSQL +databases. + +### Migrations + +In the rare event of managing a hosted database, it's necessary to use a +migration system like ActiveRecord is providing. A simple library like +[Journey](https://github.com/db-journey/journey), designed to be used in +`postgres` containers, can be deployed as long-running pods. New versions will +deploy a new pod, migrating the data automatically. + +## Testing + +We should not use any specific library or framework for testing, as the +[standard library](https://golang.org/pkg/) provides already everything to get +started. For example, some external dependencies might be worth considering in +case we decide to use a specific library or framework: + +- [Testify](https://github.com/stretchr/testify) +- [httpexpect](https://github.com/gavv/httpexpect) + +Use [subtests](https://blog.golang.org/subtests) whenever possible to improve +code readability and test output. + +### Benchmarks + +Programs handling a lot of IO or complex operations should always include +[benchmarks](https://golang.org/pkg/testing/#hdr-Benchmarks), to ensure +performance consistency over time. + +## CLIs + +Every Go program is launched from the command line. +[cli](https://github.com/urfave/cli) is a convenient package to create command +line apps. It should be used whether the project is a daemon or a simple cli +tool. Flags can be mapped to [environment +variables](https://github.com/urfave/cli#values-from-the-environment) directly, +which documents and centralizes at the same time all the possible command line +interactions with the program. Don't use `os.GetEnv`, it hides variables deep +in the code. + +## Daemons + +### Logging + +The usage of a logging library is strongly recommended for daemons. Even though +there is a `log` package in the standard library, we generally use +[logrus](https://github.com/sirupsen/logrus). Its plugin ("hooks") system +makes it a powerful logging library, with the ability to add notifiers and +formatters at the logger level directly. + +### Tracing and Correlation + +[LabKit](https://gitlab.com/gitlab-org/labkit) is a place to keep common +libraries for Go services. Currently it's vendored into two projects: +Workhorse and Gitaly, and it exports two main (but related) pieces of +functionality: + +- [`gitlab.com/gitlab-org/labkit/correlation`](https://gitlab.com/gitlab-org/labkit/tree/master/correlation): + for propagating and extracting correlation ids between services. +- [`gitlab.com/gitlab-org/labkit/tracing`](https://gitlab.com/gitlab-org/labkit/tree/master/tracing): + for instrumenting Go libraries for distributed tracing. + +This gives us a thin abstraction over underlying implementations that is +consistent across Workhorse, Gitaly, and, in future, other Go servers. For +example, in the case of `gitlab.com/gitlab-org/labkit/tracing` we can switch +from using Opentracing directly to using Zipkin or Gokit's own tracing wrapper +without changes to the application code, while still keeping the same +consistent configuration mechanism (i.e. the `GITLAB_TRACING` environment +variable). + +### Context + +Since daemons are long-running applications, they should have mechanisms to +manage cancellations, and avoid unnecessary resources consumption (which could +lead to DDOS vulnerabilities). [Go +Context](https://github.com/golang/go/wiki/CodeReviewComments#contexts) should +be used in functions that can block and passed as the first parameter. + +## Dockerfiles + +Every project should have a `Dockerfile` at the root of their repository, to +build and run the project. Since Go program are static binaries, they should +not require any external dependency, and shells in the final image are useless. +We encourage [Multistage +builds](https://docs.docker.com/develop/develop-images/multistage-build/): + +- They let the user build the project with the right Go version and + dependencies. +- They generate a small, self-contained image, derived from `Scratch`. + +Generated docker images should have the program at their `Entrypoint` to create +portable commands. That way, anyone can run the image, and without parameters +it will display its help message (if `cli` has been used). + +--- + +[Return to Development documentation](../README.md). diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 00db58a45a2..223585ebb55 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -231,11 +231,11 @@ This makes use of [`Intl.DateTimeFormat`]. - In Ruby/HAML, we have two ways of adding format to dates and times: 1. **Through the `l` helper**, i.e. `l(active_session.created_at, format: :short)`. We have some predefined formats for -[dates](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L54) and [times](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L261). + [dates](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L54) and [times](https://gitlab.com/gitlab-org/gitlab-ce/blob/v11.7.0/config/locales/en.yml#L261). If you need to add a new format, because other parts of the code could benefit from it, you'll need to add it to [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) file. - 2. **Through `strftime`**, i.e. `milestone.start_date.strftime('%b %-d')`. We use `strftime` in case none of the formats - defined on [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) matches the date/time + 1. **Through `strftime`**, i.e. `milestone.start_date.strftime('%b %-d')`. We use `strftime` in case none of the formats + defined on [en.yml](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/locales/en.yml) matches the date/time specifications we need, and if there is no need to add it as a new format because is very particular (i.e. it's only used in a single view). ## Best practices diff --git a/doc/development/i18n/index.md b/doc/development/i18n/index.md index c44690a4c5d..5e4923341af 100644 --- a/doc/development/i18n/index.md +++ b/doc/development/i18n/index.md @@ -51,4 +51,4 @@ able to proofread and instructions on becoming a proofreader yourself. Translations are typically included in the next major or minor release. -See [Merging translations from Crowdin](merging_translations.md) +See [Merging translations from Crowdin](merging_translations.md). diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md index d172aa6da21..2fa7558d30b 100644 --- a/doc/development/i18n/merging_translations.md +++ b/doc/development/i18n/merging_translations.md @@ -4,7 +4,7 @@ Crowdin automatically syncs the `gitlab.pot` file presenting newly added translations to the community of translators. At the same time, it creates a merge request to merge all newly added -& approved translations. Find the [merge reqeust created by +& approved translations. Find the [merge request created by `gitlab-crowdin-bot`](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&author_username=gitlab-crowdin-bot) to see new and merged merge requests. They are created in EE and need to be ported to CE manually. diff --git a/doc/development/sql.md b/doc/development/sql.md index 06005a0a6f8..47519d39e74 100644 --- a/doc/development/sql.md +++ b/doc/development/sql.md @@ -256,32 +256,12 @@ violation, for example. Using transactions does not solve this problem. -The following pattern should be used to avoid the problem: +To solve this we've added the `ApplicationRecord.safe_find_or_create_by`. -```ruby -Project.transaction do - begin - User.find_or_create_by(username: "foo") - rescue ActiveRecord::RecordNotUnique - retry - end -end -``` - -If the above block is run inside a transaction and hits the race -condition, the transaction is aborted and we cannot simply retry (any -further queries inside the aborted transaction are going to fail). We -can employ [nested transactions](http://api.rubyonrails.org/classes/ActiveRecord/Transactions/ClassMethods.html#module-ActiveRecord::Transactions::ClassMethods-label-Nested+transactions) -here to only rollback the "inner transaction". Note that `requires_new: true` is required here. +This method can be used just as you would the normal +`find_or_create_by` but it wraps the call in a *new* transaction and +retries if it were to fail because of an +`ActiveRecord::RecordNotUnique` error. -```ruby -Project.transaction do - begin - User.transaction(requires_new: true) do - User.find_or_create_by(username: "foo") - end - rescue ActiveRecord::RecordNotUnique - retry - end -end -``` +To be able to use this method, make sure the model you want to use +this on inherits from `ApplicationRecord`. diff --git a/doc/install/installation.md b/doc/install/installation.md index 1f65e3415d1..a8064ae046e 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -139,8 +139,8 @@ Then select 'Internet Site' and press enter to confirm the hostname. The Ruby interpreter is required to run GitLab. -**Note:** The current supported Ruby (MRI) version is 2.3.x. GitLab 9.0 dropped -support for Ruby 2.1.x. +**Note:** The current supported Ruby (MRI) version is 2.5.x. GitLab 11.6 + dropped support for Ruby 2.4.x. The use of Ruby version managers such as [RVM], [rbenv] or [chruby] with GitLab in production, frequently leads to hard to diagnose problems. For example, @@ -345,11 +345,15 @@ cd /home/git ```sh # Clone GitLab repository -sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 11-7-stable gitlab +sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b X-Y-stable gitlab ``` +Make sure to replace `X-Y-stable` with the stable branch that matches the +version you want to install. For example, if you want to install 11.8 you would +use the branch name `11-8-stable`. + CAUTION: **Caution:** -You can change `11-7-stable` to `master` if you want the *bleeding edge* version, but never install `master` on a production server! +You can change `X-Y-stable` to `master` if you want the *bleeding edge* version, but never install `master` on a production server! ### Configure It @@ -691,6 +695,11 @@ sudo nginx -t You should receive `syntax is okay` and `test is successful` messages. If you receive errors check your `gitlab` or `gitlab-ssl` Nginx config file for typos, etc. as indicated in the error message given. +NOTE: **Note:** +Verify that the installed version is greater than 1.12.1 by running `nginx -v`. If it's lower, you may receive the error below: +`nginx: [emerg] unknown "start$temp=[filtered]$rest" variable +nginx: configuration file /etc/nginx/nginx.conf test failed` + ### Restart ```sh diff --git a/doc/integration/bitbucket.md b/doc/integration/bitbucket.md index a69db1d1a6e..68ec8c4b5c2 100644 --- a/doc/integration/bitbucket.md +++ b/doc/integration/bitbucket.md @@ -43,9 +43,13 @@ you to use. | :--- | :---------- | | **Name** | This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. | | **Application description** | Fill this in if you wish. | - | **Callback URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com`. | + | **Callback URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com/users/auth`. | | **URL** | The URL to your GitLab installation, e.g., `https://gitlab.example.com`. | + NOTE: Be sure to append `/users/auth` to the end of the callback URL + to prevent a [OAuth2 convert + redirect](http://tetraph.com/covert_redirect/) vulnerability. + NOTE: Starting in GitLab 8.15, you MUST specify a callback URL, or you will see an "Invalid redirect_uri" message. For more details, see [the Bitbucket documentation](https://confluence.atlassian.com/bitbucket/oauth-faq-338365710.html). diff --git a/doc/integration/github.md b/doc/integration/github.md index b8156b2b593..eca9aa16499 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -21,9 +21,13 @@ To get the credentials (a pair of Client ID and Client Secret), you must registe - Application name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. - Homepage URL: the URL to your GitLab installation. e.g., `https://gitlab.company.com` - Application description: Fill this in if you wish. - - Authorization callback URL: `http(s)://${YOUR_DOMAIN}`. Please make sure the port is included if your GitLab instance is not configured on default port. + - Authorization callback URL: `http(s)://${YOUR_DOMAIN}/users/auth`. Please make sure the port is included if your GitLab instance is not configured on default port.  + NOTE: Be sure to append `/users/auth` to the end of the callback URL + to prevent a [OAuth2 convert + redirect](http://tetraph.com/covert_redirect/) vulnerability. + 1. Select **Register application**. 1. You should now see a pair of **Client ID** and **Client Secret** near the top right of the page (see screenshot). diff --git a/doc/ssh/README.md b/doc/ssh/README.md index 09a97fcea07..1b53be15b44 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -19,7 +19,7 @@ comes pre-installed on GNU/Linux and macOS, but not on Windows. Depending on your Windows version, there are different methods to work with SSH keys. -### Installing the SSH client for Windows 10 +### Windows 10: Windows Subsystem for Linux Starting with Windows 10, you can [install the Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10) @@ -27,10 +27,10 @@ where you can run Linux distributions directly on Windows, without the overhead of a virtual machine. Once installed and set up, you'll have the Git and SSH clients at your disposal. -### Installing the SSH client for Windows 8.1 and Windows 7 +### Windows 10, 8.1, and 7: Git for Windows The easiest way to install Git and the SSH client on Windows 8.1 and Windows 7 -is [Git for Windows](https://gitforwindows.org). It provides a BASH +is [Git for Windows](https://gitforwindows.org). It provides a Bash emulation (Git Bash) used for running Git from the command line and the `ssh-keygen` command that is useful to create SSH keys as you'll learn below. @@ -114,7 +114,8 @@ To create a new SSH key pair: and want to tell which is which. It is optional. 1. Next, you will be prompted to input a file path to save your SSH key pair to. - If you don't already have an SSH key pair, use the suggested path by pressing + If you don't already have an SSH key pair and aren't generating a [deploy key](#deploy-keys), + use the suggested path by pressing <kbd>Enter</kbd>. Using the suggested path will normally allow your SSH client to automatically use the SSH key pair with no additional configuration. @@ -128,7 +129,7 @@ To create a new SSH key pair: <kbd>Enter</kbd> twice. If, in any case, you want to add or change the password of your SSH key pair, - you can use the `-p`flag: + you can use the `-p` flag: ``` ssh-keygen -p -o -f <keyname> @@ -258,7 +259,8 @@ Integration (CI) server. By using deploy keys, you don't have to set up a dummy user account. If you are a project maintainer or owner, you can add a deploy key in the -project settings under the section 'Repository'. Specify a title for the new +project's **Settings > Repository** page by expanding the +**Deploy Keys** section. Specify a title for the new deploy key and paste a public SSH key. After this, the machine that uses the corresponding private SSH key has read-only or read-write (if enabled) access to the project. @@ -300,8 +302,8 @@ of broader usage for something like "Anywhere you need to give read access to your repository". Once a GitLab administrator adds the Global Deployment key, project maintainers -and owners can add it in project's **Settings > Repository** section by expanding the -**Deploy Key** section and clicking **Enable** next to the appropriate key listed +and owners can add it in project's **Settings > Repository** page by expanding the +**Deploy Keys** section and clicking **Enable** next to the appropriate key listed under **Public deploy keys available to any project**. NOTE: **Note:** diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 325de50cab0..463bdd59282 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -126,14 +126,22 @@ Auto Deploy, and Auto Monitoring will be silently skipped. ## Auto DevOps base domain +NOTE: **Note** +`AUTO_DEVOPS_DOMAIN` environment variable is deprecated and +[is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959) in GitLab 12.0. + The Auto DevOps base domain is required if you want to make use of [Auto Review Apps](#auto-review-apps) and [Auto Deploy](#auto-deploy). It can be defined -in three places: +in any of the following places: -- either under the project's CI/CD settings while [enabling Auto DevOps](#enabling-auto-devops) +- either under the cluster's settings, whether for [projects](../../user/project/clusters/index.md#base-domain) or [groups](../../user/group/clusters/index.md#base-domain) - or in instance-wide settings in the **admin area > Settings** under the "Continuous Integration and Delivery" section -- or at the project as a variable: `AUTO_DEVOPS_DOMAIN` (required if you want to use [multiple clusters](#using-multiple-kubernetes-clusters)) -- or at the group level as a variable: `AUTO_DEVOPS_DOMAIN` +- or at the project level as a variable: `KUBE_INGRESS_BASE_DOMAIN` +- or at the group level as a variable: `KUBE_INGRESS_BASE_DOMAIN`. + +NOTE: **Note** +The Auto DevOps base domain variable (`KUBE_INGRESS_BASE_DOMAIN`) follows the same order of precedence +as other environment [variables](../../ci/variables/README.md#priority-of-variables). A wildcard DNS A record matching the base domain(s) is required, for example, given a base domain of `example.com`, you'd need a DNS entry like: @@ -170,13 +178,13 @@ In the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab-ce/blob/maste Those environments are tied to jobs that use [Auto Deploy](#auto-deploy), so except for the environment scope, they would also need to have a different domain they would be deployed to. This is why you need to define a separate -`AUTO_DEVOPS_DOMAIN` variable for all the above +`KUBE_INGRESS_BASE_DOMAIN` variable for all the above [based on the environment](../../ci/variables/README.md#limiting-environment-scopes-of-variables). The following table is an example of how the three different clusters would be configured. -| Cluster name | Cluster environment scope | `AUTO_DEVOPS_DOMAIN` variable value | Variable environment scope | Notes | +| Cluster name | Cluster environment scope | `KUBE_INGRESS_BASE_DOMAIN` variable value | Variable environment scope | Notes | | ------------ | -------------- | ----------------------------- | ------------- | ------ | | review | `review/*` | `review.example.com` | `review/*` | The review cluster which will run all [Review Apps](../../ci/review_apps/index.md). `*` is a wildcard, which means it will be used by every environment name starting with `review/`. | | staging | `staging` | `staging.example.com` | `staging` | (Optional) The staging cluster which will run the deployments of the staging environments. You need to [enable it first](#deploy-policy-for-staging-and-production-environments). | @@ -190,14 +198,11 @@ To add a different cluster for each environment:  1. After the clusters are created, navigate to each one and install Helm Tiller - and Ingress. + and Ingress. Wait for the Ingress IP address to be assigned. 1. Make sure you have [configured your DNS](#auto-devops-base-domain) with the specified Auto DevOps domains. -1. Navigate to your project's **Settings > CI/CD > Environment variables** and add - the `AUTO_DEVOPS_DOMAIN` variables with their respective environment - scope. - -  +1. Navigate to each cluster's page, through **Operations > Kubernetes**, + and add the domain based on its Ingress IP address. Now that all is configured, you can test your setup by creating a merge request and verifying that your app is deployed as a review app in the Kubernetes @@ -205,10 +210,9 @@ cluster with the `review/*` environment scope. Similarly, you can check the other environments. NOTE: **Note:** -Auto DevOps is not supported for a group with multiple clusters, as it -is not possible to set `AUTO_DEVOPS_DOMAIN` per environment on the group -level. This will be resolved in the future with the [following issue]( -https://gitlab.com/gitlab-org/gitlab-ce/issues/52363). +From GitLab 11.8, `KUBE_INGRESS_BASE_DOMAIN` replaces `AUTO_DEVOPS_DOMAIN`. +`AUTO_DEVOPS_DOMAIN` [is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959) +in GitLab 12.0. ## Enabling/Disabling Auto DevOps @@ -681,7 +685,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | **Variable** | **Description** | | ------------ | --------------- | -| `AUTO_DEVOPS_DOMAIN` | The [Auto DevOps domain](#auto-devops-domain); by default set automatically by the [Auto DevOps setting](#enabling-auto-devops). | +| `AUTO_DEVOPS_DOMAIN` | The [Auto DevOps domain](#auto-devops-domain). By default, set automatically by the [Auto DevOps setting](#enabling-auto-devops). This variable is deprecated and [is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959) in GitLab 12.0. Use `KUBE_INGRESS_BASE_DOMAIN` instead. | | `AUTO_DEVOPS_CHART` | The Helm Chart used to deploy your apps; defaults to the one [provided by GitLab](https://gitlab.com/charts/auto-deploy-app). | | `AUTO_DEVOPS_CHART_REPOSITORY` | The Helm Chart repository used to search for charts; defaults to `https://charts.gitlab.io`. | | `REPLICAS` | The number of replicas to deploy; defaults to 1. | @@ -711,6 +715,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | `DAST_DISABLED` | From GitLab 11.0, this variable can be used to disable the `dast` job. If the variable is present, the job will not be created. | | `PERFORMANCE_DISABLED` | From GitLab 11.0, this variable can be used to disable the `performance` job. If the variable is present, the job will not be created. | | `K8S_SECRET_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) will be made available by Auto DevOps as environment variables to the deployed application. | +| `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/index.md#base-domain) for more information. | TIP: **Tip:** Set up the replica variables using a diff --git a/doc/user/admin_area/broadcast_messages.md b/doc/user/admin_area/broadcast_messages.md index 51949088521..02445abdb37 100644 --- a/doc/user/admin_area/broadcast_messages.md +++ b/doc/user/admin_area/broadcast_messages.md @@ -4,6 +4,8 @@ GitLab can display messages to all users of a GitLab instance in a banner that a  +Broadcast messages can be managed using the [broadcast messages API](../../api/broadcast_messages.md). + NOTE: **Note:** If more than one banner message is active at one time, they are displayed in a stack in order of creation. diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 68a0f1a5837..c1c9b8bf43c 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -46,7 +46,7 @@ Below are the settings for [GitLab Pages]. | Setting | GitLab.com | Default | | ----------------------- | ---------------- | ------------- | | Domain name | `gitlab.io` | - | -| IP address | `52.167.214.135` | - | +| IP address | `35.185.44.232` | - | | Custom domains support | yes | no | | TLS certificates support| yes | no | diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 9f9b2da23e1..9fc50741407 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -59,11 +59,16 @@ Add another cluster similar to the first one and make sure to [set an environment scope](#environment-scopes) that will differentiate the new cluster from the rest. -NOTE: **Note:** -Auto DevOps is not supported for a group with multiple clusters, as it -is not possible to set `AUTO_DEVOPS_DOMAIN` per environment on the group -level. This will be resolved in the future with the [following issue]( -https://gitlab.com/gitlab-org/gitlab-ce/issues/52363). +## Base domain + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24580) in GitLab 11.8. + +Domains at the cluster level permit support for multiple domains +per [multiple Kubernetes clusters](#multiple-kubernetes-clusters-premium). When specifying a domain, +this will be automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during +the [Auto DevOps](../../../topics/autodevops/index.md) stages. + +The domain should have a wildcard DNS configured to the Ingress IP address. ## Environment scopes **[PREMIUM]** diff --git a/doc/user/index.md b/doc/user/index.md index fc68404d0c2..36aba5e01c6 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -12,28 +12,22 @@ includes, except [GitLab administrator](../README.md#administrator-documentation settings, unless you have admin privileges to install, configure, and upgrade your GitLab instance. -For GitLab.com, admin privileges are restricted to the GitLab team. +Admin privileges for [GitLab.com](https://gitlab.com/) are restricted to the GitLab team. -If you run your own GitLab instance and are looking for the administration settings, -please refer to the [administration](../README.md#administrator-documentation) -documentation. +For more information on configuring GitLab self-managed instances, see [Administrator documentation](../README.md#administrator-documentation). ## Overview -GitLab is a fully integrated software development platform that enables you -and your team to work cohesively, faster, transparently, and effectively, -since the discussion of a new idea until taking that idea to production all -the way through, from within the same platform. +GitLab is a fully integrated software development platform that enables your team to be transparent, fast, effective, and cohesive from discussion on a new idea to production, all on the same platform. -Please check this page for an overview on [GitLab's features](https://about.gitlab.com/features/). +For more information, see [All GitLab Features](https://about.gitlab.com/features/). ### Concepts -For an overview on concepts involved when developing code on GitLab, -read the articles on: +To get familiar with the concepts needed to develop code on GitLab, read the following articles: -- [Mastering Code Review With GitLab](https://about.gitlab.com/2017/03/17/demo-mastering-code-review-with-gitlab/). -- [GitLab Workflow, an Overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/#gitlab-workflow-use-case-scenario). +- [Demo: Mastering Code Review With GitLab](https://about.gitlab.com/2017/03/17/demo-mastering-code-review-with-gitlab/). +- [GitLab Workflow: An Overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/#gitlab-workflow-use-case-scenario). - [Tutorial: It's all connected in GitLab](https://about.gitlab.com/2016/03/08/gitlab-tutorial-its-all-connected/): an overview on code collaboration with GitLab. - [Trends in Version Control Land: Microservices](https://about.gitlab.com/2016/08/16/trends-in-version-control-land-microservices/). - [Trends in Version Control Land: Innersourcing](https://about.gitlab.com/2016/07/07/trends-version-control-innersourcing/). @@ -42,16 +36,16 @@ read the articles on: GitLab is a Git-based platform that integrates a great number of essential tools for software development and deployment, and project management: -- Code hosting in repositories with version control -- Track proposals for new implementations, bug reports, and feedback with a +- Hosting code in repositories with version control +- Tracking proposals for new implementations, bug reports, and feedback with a fully featured [Issue Tracker](project/issues/index.md#issue-tracker) -- Organize and prioritize with [Issue Boards](project/issues/index.md#issue-boards) -- Code review in [Merge Requests](project/merge_requests/index.md) with live-preview changes per +- Organizing and prioritizing with [Issue Boards](project/issues/index.md#issue-boards) +- Reviewing code in [Merge Requests](project/merge_requests/index.md) with live-preview changes per branch with [Review Apps](../ci/review_apps/index.md) -- Build, test and deploy with built-in [Continuous Integration](../ci/README.md) -- Deploy your personal and professional static websites with [GitLab Pages](project/pages/index.md) -- Integrate with Docker with [GitLab Container Registry](project/container_registry.md) -- Track the development lifecycle with [GitLab Cycle Analytics](project/cycle_analytics.md) +- Building, testing and deploying with built-in [Continuous Integration](../ci/README.md) +- Deploying personal and professional static websites with [GitLab Pages](project/pages/index.md) +- Integrating with Docker by using [GitLab Container Registry](project/container_registry.md) +- Tracking the development lifecycle by usingn [GitLab Cycle Analytics](project/cycle_analytics.md) With GitLab Enterprise Edition, you can also: @@ -68,15 +62,15 @@ and [Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board. - [Export issues as CSV](https://docs.gitlab.com/ee/user/project/issues/csv_export.html) - View your entire CI/CD pipeline involving more than one project with [Multiple-Project Pipeline Graphs](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html) - [Lock files](https://docs.gitlab.com/ee/user/project/file_lock.html) to prevent conflicts -- View of the current health and status of each CI environment running on Kubernetes with [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) -- Leverage your continuous delivery method with [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) +- View the current health and status of each CI environment running on Kubernetes with [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) +- Leverage continuous delivery method with [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) You can also [integrate](project/integrations/project_services.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, HipChat, Trello, Slack, Bamboo CI, JIRA, and a lot more. ## Projects -In GitLab, you can create [projects](project/index.md) for numerous reasons, such as, host -your code, use it as an issue tracker, collaborate on code, and continuously +In GitLab, you can create [projects](project/index.md) to host +your code, track issues, collaborate on code, and continuously build, test, and deploy your app with built-in GitLab CI/CD. Or, you can do it all at once, from one single project. diff --git a/doc/user/instance_statistics/user_cohorts.md b/doc/user/instance_statistics/user_cohorts.md index f52f24ef5f7..e76363a6d9f 100644 --- a/doc/user/instance_statistics/user_cohorts.md +++ b/doc/user/instance_statistics/user_cohorts.md @@ -25,3 +25,4 @@ How do we measure the activity of users? GitLab considers a user active if: - The user signs in. - The user has Git activity (whether push or pull). +- The user visits pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/54947) in GitLab 11.8). diff --git a/doc/user/markdown.md b/doc/user/markdown.md index f2448f240ca..9a01625f3ff 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -31,8 +31,10 @@ dependency to do so. Please see the [`github-markup` gem readme](https://github. > As of 11.1, GitLab uses the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the -repositories are also processed with CommonMark. Older content in issues/comments -are still processed using the [Redcarpet Ruby library][redcarpet]. +repositories are also processed with CommonMark. As of 11.8, the [Redcarpet +Ruby library][redcarpet] has been removed and all issues/comments, including +those from pre-11.1, are now processed using [CommonMark Ruby +Library][commonmarker]. > > The documentation website had its [markdown engine migrated from Redcarpet to Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108) in October 2018. @@ -41,11 +43,11 @@ in October 2018. ### Transitioning to CommonMark -You may have Markdown documents in your repository that were written using some -of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a -slightly stricter syntax, these documents may now display a little strangely -since we've transitioned to CommonMark. Numbered lists with nested lists in -particular can be displayed incorrectly. +You may have older issues/merge requests or Markdown documents in your +repository that were written using some of the nuances of RedCarpet's version +of Markdown. Since CommonMark uses a slightly stricter syntax, these documents +may now display a little strangely since we've transitioned to CommonMark. +Numbered lists with nested lists in particular can be displayed incorrectly. It is usually quite easy to fix. In the case of a nested list such as this: @@ -65,11 +67,6 @@ simply add a space to each nested item: In the documentation below, we try to highlight some of the differences. -If you have a need to view a document using RedCarpet, you can add the token -`legacy_render=1` to the end of the url, like this: - -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md?legacy_render=1 - If you have a large volume of Markdown files, it can be tedious to determine if they will be displayed correctly or not. You can use the [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) @@ -677,7 +674,7 @@ Becomes: + 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 (_Redcarpet: paragraph should be indented with four spaces._) +each subsequent paragraph should be indented to the same level as the start of the list item text Example: @@ -841,7 +838,7 @@ These details <em>will</em> remain <strong>hidden</strong> until expanded. </details> </p> -**Note:** Markdown inside these tags is supported, as long as you have a blank line after the `</summary>` tag and before the `</details>` tag, as shown in the example. _Redcarpet does not support Markdown inside these tags. You can work around this by using HTML, for example you can use `<pre><code>` tags instead of [code fences](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting)._ +**Note:** Markdown inside these tags is supported, as long as you have a blank line after the `</summary>` tag and before the `</details>` tag, as shown in the example. ```html <details> diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index eb2d731343e..363d3db8db1 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -87,3 +87,11 @@ You can choose between 3 options: - Files and Readme (default) - Readme - Activity + +## Localization + +### First day of the week + +The first day of the week can be customised for calendar views and date pickers. + +You can choose **Sunday** or **Monday** as the first day of the week. If you select **System Default**, the system-wide default setting will be used. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index bb815695cb1..85a4af24dc5 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -172,6 +172,17 @@ functionalities needed to successfully build and deploy a containerized application. Bear in mind that the same credentials are used for all the applications running on the cluster. +## Base domain + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24580) in GitLab 11.8. + +Domains at the cluster level permit support for multiple domains +per [multiple Kubernetes clusters](#multiple-kubernetes-clusters-premium). When specifying a domain, +this will be automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during +the [Auto DevOps](../../../topics/autodevops/index.md) stages. + +The domain should have a wildcard DNS configured to the Ingress IP address. + ## Access controls When creating a cluster in GitLab, you will be asked if you would like to create an @@ -254,6 +265,12 @@ install it manually. ## Installing applications +NOTE: **Note:** +Before starting the installation of applications, make sure that time is synchronized +between your GitLab server and your Kubernetes cluster. Otherwise, installation could fail +and you may get errors like `Error: remote error: tls: bad certificate` +in the `stdout` of pods created by GitLab in your Kubernetes cluster. + GitLab provides a one-click install for various applications which can be added directly to your configured cluster. Those applications are needed for [Review Apps](../../../ci/review_apps/index.md) and @@ -449,6 +466,7 @@ GitLab CI/CD build environment. | `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | | `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | | `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This config also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | +| `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. | NOTE: **NOTE:** Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main diff --git a/doc/user/project/clusters/serverless/img/app-domain.png b/doc/user/project/clusters/serverless/img/app-domain.png Binary files differnew file mode 100644 index 00000000000..d113dfadd2e --- /dev/null +++ b/doc/user/project/clusters/serverless/img/app-domain.png diff --git a/doc/user/project/clusters/serverless/img/serverless-details.png b/doc/user/project/clusters/serverless/img/serverless-details.png Binary files differdeleted file mode 100644 index 61e0735199a..00000000000 --- a/doc/user/project/clusters/serverless/img/serverless-details.png +++ /dev/null diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index bebccf97987..aa1e165e3a2 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -1,7 +1,9 @@ # Serverless > Introduced in GitLab 11.5. -> Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/#alpha). + +CAUTION: **Caution:** +Serverless is currently in [alpha](https://about.gitlab.com/handbook/product/#alpha). Run serverless workloads on Kubernetes using [Knative](https://cloud.google.com/knative/). @@ -82,7 +84,15 @@ Currently the following [runtimes](https://gitlab.com/triggermesh/runtimes) are - node.js - kaniko -In order to deploy functions to your Knative instance, the following files must be present: +You can find all the files referenced in this doc in the [functions example project](https://gitlab.com/knative-examples/functions). + +Follow these steps to deploy a function using the Node.js runtime to your Knative instance: + +1. Create a directory that will house the function. In this example we will create a directory called `echo` at the root of the project. + +1. Create the file that will contain the function code. In this example, our file is called `echo.js` and is located inside the `echo` directory. If your project is: + - Public, continue to the next step. + - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. 1. `.gitlab-ci.yml`: This template allows to define the stage, environment, and image to be used for your functions. It must be included at the root of your repository: @@ -94,10 +104,12 @@ In order to deploy functions to your Knative instance, the following files must functions: stage: deploy environment: test - image: gcr.io/triggermesh/tm:v0.0.7 + image: gcr.io/triggermesh/tm:v0.0.9 script: - - tm -n "$KUBE_NAMESPACE" set registry-auth gitlab-registry --registry "$CI_REGISTRY" --username "$CI_REGISTRY_USER" --password "$CI_JOB_TOKEN" - - tm -n "$KUBE_NAMESPACE" --registry-host "$CI_REGISTRY_IMAGE" deploy --wait + - tm -n "$KUBE_NAMESPACE" set registry-auth gitlab-registry --registry "$CI_REGISTRY" --username "$CI_REGISTRY_USER" --password "$CI_JOB_TOKEN" --push + - tm -n "$KUBE_NAMESPACE" set registry-auth gitlab-registry --registry "$CI_REGISTRY" --username "$CI_DEPLOY_USER" --password "$CI_DEPLOY_PASSWORD" --pull + - tm -n "$KUBE_NAMESPACE" deploy --wait + ``` The `gitlab-ci.yml` template creates a `Deploy` stage with a `functions` job that invokes the `tm` CLI with the required parameters. @@ -127,7 +139,9 @@ In order to deploy functions to your Knative instance, the following files must ``` -The `serverless.yml` file is referencing both an `echo` directory (under `buildargs`) and an `echo` file (under `handler`) which is a reference to `echo.js` in the [repository](https://gitlab.com/knative-examples/functions). Additionally, it contains three sections with distinct parameters: +The `serverless.yml` file references both an `echo` directory (under `buildargs`) and an `echo` file (under `handler`), +which is a reference to `echo.js` in the [repository](https://gitlab.com/knative-examples/functions). Additionally, it +contains three sections with distinct parameters: ### `service` @@ -149,7 +163,6 @@ The `serverless.yml` file is referencing both an `echo` directory (under `builda In the `serverless.yml` example above, the function name is `echo` and the subsequent lines contain the function attributes. - | Parameter | Description | |-----------|-------------| | `handler` | The function's file name. In the example above, both the function name and the handler are the same. | @@ -158,9 +171,8 @@ In the `serverless.yml` example above, the function name is `echo` and the subse | `buildargs` | Pointer to the function file in the repo. In the sample the function is located in the `echo` directory. | | `environment` | Sets an environment variable for the specific function only. | -After the `gitlab-ci.yml` template has been added and the `serverless.yml` file has been -created, each function must be defined as a single file in your repository. Committing a -function to your project will result in a +After the `gitlab-ci.yml` template has been added and the `serverless.yml` file has been +created, pushing a commit to your project will result in a CI pipeline being executed which will deploy each function as a Knative service. Once the deploy stage has finished, additional details for the function will appear under **Operations > Serverless**. @@ -182,14 +194,6 @@ The sample function can now be triggered from any HTTP client using a simple `PO  -Currently, the Serverless page presents all functions available in all clusters registered for the project with Knative installed. - -Clicking on the function name will provide additional details such as the -function's URL as well as runtime statistics such as the number of active pods -available to service the request based on load. - - - ## Deploying Serverless applications > Introduced in GitLab 11.5. @@ -227,14 +231,18 @@ deploy: - tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait ``` -## Deploy the application with Knative +### Deploy the application with Knative With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to **CI/CD > Pipelines** and click the most recent pipeline. -## Obtain the URL for the Knative deployment +### Obtain the URL for the Knative deployment + +Go to the **Operations > Serverless** page to find the URL for your deployment in the **Domain** column. + + -Use the CI/CD deployment job output to obtain the deployment URL. Once all the stages of the pipeline finish, click the **deploy** stage. +Alternatively, use the CI/CD deployment job output to obtain the deployment URL. Once all the stages of the pipeline finish, click the **deploy** stage.  diff --git a/doc/user/project/merge_requests/img/squash_mr_message.png b/doc/user/project/merge_requests/img/squash_mr_message.png Binary files differnew file mode 100644 index 00000000000..8734cab29aa --- /dev/null +++ b/doc/user/project/merge_requests/img/squash_mr_message.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index b4f5a72e148..593eb80e044 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -46,7 +46,7 @@ A. Consider you are a software developer working in a team: 1. You verify your changes with [JUnit test reports](../../../ci/junit_test_reports.md) in GitLab CI/CD 1. You request the approval from your manager 1. Your manager pushes a commit with his final review, [approves the merge request](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html), and set it to [merge when pipeline succeeds](#merge-when-pipeline-succeeds) (Merge Request Approvals are available in GitLab Starter) -1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#manual-actions) for GitLab CI/CD +1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD 1. Your implementations were successfully shipped to your customer B. Consider you're a web developer writing a webpage for your company's: diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 1b57331dbe7..4ff8ec3a7e6 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -18,12 +18,19 @@ Into a single commit on merge: ![A squashed commit followed by a merge commit][squashed-commit] -The squashed commit's commit message is the merge request title. And note that -the squashed commit is still followed by a merge commit, as the merge -method for this example repository uses a merge commit. Squashing also works -with the fast-forward merge strategy, see -[squashing and fast-forward merge](#squash-and-fast-forward-merge) for more -details. +The squashed commit's commit message will be either: + +- Taken from the first multi-line commit message in the merge. +- The merge request's title if no multi-line commit message is found. + +It can be customized before merging a merge request. + + + +NOTE: **Note:** +The squashed commit in this example is followed by a merge commit, as the merge method for this example repository uses a merge commit. + +Squashing also works with the fast-forward merge strategy, see [squashing and fast-forward merge](#squash-and-fast-forward-merge) for more details. ## Use cases @@ -34,7 +41,7 @@ you'd rather not include them in your target branch. With squash and merge, when the merge request is ready to be merged, all you have to do is enable squashing before you press merge to join -the commits include in the merge request into a single commit. +the commits in the merge request into a single commit. This way, the history of your base branch remains clean with meaningful commit messages and is simpler to [revert] if necessary. @@ -56,7 +63,7 @@ This can then be overridden at the time of accepting the merge request: The squashed commit has the following metadata: -- Message: the title of the merge request. +- Message: the message of the squash commit, or a customized message. - Author: the author of the merge request. - Committer: the user who initiated the squash. diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md new file mode 100644 index 00000000000..b0f9936be5c --- /dev/null +++ b/doc/user/project/operations/index.md @@ -0,0 +1,11 @@ +# Project operations + +GitLab provides a variety of tools to help operate and maintain +your applications: + +- Collect [Prometheus metrics](../integrations/prometheus_library/index.md). +- Deploy to different [environments](../../../ci/environments.md). +- Connect your project to a [Kubernetes cluster](../clusters/index.md). +- Discover and view errors generated by your applications with [Error Tracking](error_tracking.md). +- Create, toggle, and remove [Feature Flags](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html). **[PREMIUM]** +- [Trace](https://docs.gitlab.com/ee/user/project/operations/tracing.html) the performance and health of a deployed application. **[ULTIMATE]** diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index cea9628966d..b2da1c85c62 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -79,11 +79,14 @@ running on your instance).  -NOTE: **Note:** -Note that if you use your root domain for your GitLab Pages website **only**, and if -your domain registrar supports this feature, you can add a DNS apex `CNAME` -record instead of an `A` record. The main advantage of doing so is that when GitLab Pages -IP on GitLab.com changes for whatever reason, you don't need to update your `A` record. +CAUTION: **Caution:** +Note that if you use your root domain for your GitLab Pages website +**only**, and if your domain registrar supports this feature, you can +add a DNS apex `CNAME` record instead of an `A` record. The main +advantage of doing so is that when GitLab Pages IP on GitLab.com +changes for whatever reason, you don't need to update your `A` record. +There may be a few exceptions, but **this method is not recommended** +as it most likely won't work if you set an `MX` record for your root domain. #### DNS CNAME record @@ -114,14 +117,16 @@ co-exist, so you need to place the TXT record in a special subdomain of its own. #### TL;DR -If the domain has multiple uses (e.g., you host email on it as well): +For root domains (`domain.com`), set a DNS `A` record and verify your +domain's ownership with a TXT record: | From | DNS Record | To | | ---- | ---------- | -- | | domain.com | A | 35.185.44.232 | | domain.com | TXT | gitlab-pages-verification-code=00112233445566778899aabbccddeeff | -If the domain is dedicated to GitLab Pages use and no other services run on it: +For subdomains (`subdomain.domain.com`), set a DNS `CNAME` record and +verify your domain's ownership with a TXT record: | From | DNS Record | To | | ---- | ---------- | -- | @@ -264,7 +269,7 @@ your Pages project are the same. 1. A PEM certificate 1. An intermediate certificate -1. A public key +1. A private key  @@ -280,7 +285,7 @@ Usually it's combined with the PEM certificate, but there are some cases in which you need to add them manually. [CloudFlare certs](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) are one of these cases. -- A public key is an encrypted key which validates +- A private key is an encrypted key which validates your PEM against your domain. ### Now what? @@ -293,7 +298,7 @@ of this, it's simple: and paste the root certificate (usually available from your CA website) and paste it in the [same field as your PEM certificate](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/), just jumping a line between them. -- Copy your public key and paste it in the last field +- Copy your private key and paste it in the last field >**Note:** **Do not** open certificates or encryption keys in diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index b0560c2f44c..c9081a6d72b 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -31,12 +31,26 @@ The optional settings, custom domain, DNS records, and SSL/TLS certificates, are ## Project Your GitLab Pages project is a regular project created the -same way you do for the other ones. To get started with GitLab Pages, you have two ways: +same way you do for the other ones. To get started with GitLab Pages, you have three ways: +- Use one of the popular templates already in the app, - Fork one of the templates from Page Examples, or - Create a new project from scratch -Let's go over both options. +Let's go over each option. + +### Use one of the popular Pages templates bundled with GitLab + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/47857) +in GitLab 11.8. + +The simplest way to create a GitLab Pages site is to use one of the most +popular templates, which come already bundled and ready to go. To use one +of these templates: + +1. From the top navigation, click the **+** button and select **New project** +1. Select **Create from Template** +1. Choose one of the templates starting with **Pages** ### Fork a project to get started from @@ -57,7 +71,7 @@ created for the steps below. To turn a **project website** forked from the Pages group into a **user/group** website, you'll need to: - Rename it to `namespace.gitlab.io`: navigate to project's **Settings** > expand **Advanced settings** > and scroll down to **Rename repository** -- Adjust your SSG's [base URL](#urls-and-baseurls) to from `"project-name"` to `""`. This setting will be at a different place for each SSG, as each of them have their own structure and file tree. Most likely, it will be in the SSG's config file. +- Adjust your SSG's [base URL](#urls-and-baseurls) from `"project-name"` to `""`. This setting will be at a different place for each SSG, as each of them have their own structure and file tree. Most likely, it will be in the SSG's config file. > **Notes:** > diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index ce4fccdaff3..11f6165fcb4 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -91,8 +91,8 @@ site under the HTTPS protocol. ## Getting started -To get started with GitLab Pages, you can either [create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch) -or quickly start from copying an existing example project, as follows: +To get started with GitLab Pages, you can either [create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch), +use a [bundled template](getting_started_part_two.md#use-one-of-the-popular-pages-templates-bundled-with-gitlab), or copy any of our existing example projects: 1. Choose an [example project](https://gitlab.com/pages) to [fork](../../../gitlab-basics/fork-project.md#how-to-fork-a-project): by forking a project, you create a copy of the codebase you're forking from to start from a template instead of starting from scratch. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index a7846b1ee18..cebff38ba88 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -178,7 +178,7 @@ Supposed your repository contained the following files: ``` ├── index.html ├── css -│ └── main.css +│ └── main.css └── js └── main.js ``` @@ -333,7 +333,7 @@ public/ │ └ index.html.gz │ ├── css/ -│ └─┬ main.css +│ └─┬ main.css │ └ main.css.gz │ └── js/ @@ -356,6 +356,57 @@ By pre-compressing the files and including both versions in the artifact, Pages can serve requests for both compressed and uncompressed content without needing to compress files on-demand. +### Resolving ambiguous URLs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/issues/95) in GitLab 11.8 + +GitLab Pages makes assumptions about which files to serve when receiving a +request for a URL that does not include an extension. + +Consider a Pages site deployed with the following files: + +``` +public/ +├─┬ index.html +│ ├ data.html +│ └ info.html +│ +├── data/ +│ └── index.html +├── info/ +│ └── details.html +└── other/ + └── index.html +``` + +Pages supports reaching each of these files through several different URLs. In +particular, it will always look for an `index.html` file if the URL only +specifies the directory. If the URL references a file that doesn't exist, but +adding `.html` to the URL leads to a file that *does* exist, it will be served +instead. Here are some examples of what will happen given the above Pages site: + +| URL path | HTTP response | File served | +| -------------------- | ------------- | ----------- | +| `/` | `200 OK` | `public/index.html` | +| `/index.html` | `200 OK` | `public/index.html` | +| `/index` | `200 OK` | `public/index.html` | +| `/data` | `200 OK` | `public/data/index.html` | +| `/data/` | `200 OK` | `public/data/index.html` | +| `/data.html` | `200 OK` | `public/data.html` | +| `/info` | `200 OK` | `public/info.html` | +| `/info/` | `200 OK` | `public/info.html` | +| `/info.html` | `200 OK` | `public/info.html` | +| `/info/details` | `200 OK` | `public/info/details.html` | +| `/info/details.html` | `200 OK` | `public/info/details.html` | +| `/other` | `302 Found` | `public/other/index.html` | +| `/other/` | `200 OK` | `public/other/index.html` | +| `/other/index` | `200 OK` | `public/other/index.html` | +| `/other/index.html` | `200 OK` | `public/other/index.html` | + +NOTE: **Note:** +When `public/data/index.html` exists, it takes priority over the `public/data.html` +file for both the `/data` and `/data/` URL paths. + ### Add a custom domain to your Pages website For a complete guide on Pages domains, read through the article diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index a8b47558c99..0d0575b1ab4 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -38,8 +38,9 @@ turn are defined with the `paths` keyword. All paths to files and directories are relative to the repository that was cloned during the build. These uploaded artifacts will be kept in GitLab for 1 week as defined by the `expire_in` definition. You have the option to keep the artifacts from expiring via the -[web interface](#browsing-job-artifacts). If you don't define an expiry date, -the artifacts will be kept forever. +[web interface](#browsing-job-artifacts). If the expiry time is not defined, +it defaults to the [instance wide +setting](../../admin_area/settings/continuous_integration.md#default-artifacts-expiration-core-only). For more examples on artifacts, follow the [artifacts reference in `.gitlab-ci.yml`](../../../ci/yaml/README.md#artifacts). diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 5c9f6ffb163..569bdc9e2d5 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -4,7 +4,12 @@ With GitLab Snippets you can store and share bits of code and text with other us  -There are 2 types of snippets, personal snippets and project snippets. +Snippets can be maintained using [snippets API](../api/snippets.md). + +There are two types of snippets: + +- Personal snippets. +- Project snippets. ## Personal snippets diff --git a/doc/workflow/repository_mirroring.md b/doc/workflow/repository_mirroring.md index ac26aeab137..8a2f4e1b40e 100644 --- a/doc/workflow/repository_mirroring.md +++ b/doc/workflow/repository_mirroring.md @@ -55,7 +55,7 @@ When push mirroring is enabled, only push commits directly to the mirrored repos mirror diverging. All changes will end up in the mirrored repository whenever: - Commits are pushed to GitLab. -- A [forced update](#forcing-an-update) is initiated. +- A [forced update](#forcing-an-update-core) is initiated. Changes pushed to files in the repository are automatically pushed to the remote mirror at least: @@ -88,6 +88,14 @@ The mirrored repository will be listed. For example, `https://*****:*****@github The repository will push soon. To force a push, click the appropriate button. +## Setting up a push mirror to another GitLab instance with 2FA activated + +1. On the destination GitLab instance, create a [personal access token](../user/profile/personal_access_tokens.md) with `API` scope. +1. On the source GitLab instance: + 1. Fill in the **Git repository URL** field using this format: `https://oauth2@<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`. + 1. Fill in **Password** field with the GitLab personal access token created on the destination GitLab instance. + 1. Click the **Mirror repository** button. + ## Pulling from a remote repository **[STARTER]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/51) in GitLab Enterprise Edition 8.2. @@ -122,7 +130,7 @@ directly to the repository on GitLab. Instead, any commits should be pushed to t Changes pushed to the upstream repository will be pulled into the GitLab repository, either: - Automatically within a certain period of time. -- When a [forced update](#forcing-an-update) is initiated. +- When a [forced update](#forcing-an-update-core) is initiated. CAUTION: **Caution:** If you do manually update a branch in the GitLab repository, the branch will become diverged from @@ -259,7 +267,7 @@ failed. This will become visible in either the: - Pull mirror settings page. When a project is hard failed, it will no longer get picked up for mirroring. A user can resume the -project mirroring again by [Forcing an update](#forcing-an-update). +project mirroring again by [Forcing an update](#forcing-an-update-core). ### Trigger update using API **[STARTER]** @@ -292,8 +300,8 @@ them and how they will be resolved. Rewriting any mirrored commit on either remote will cause conflicts and mirroring to fail. This can be prevented by: -- [Pulling only protected branches](#pull-only-protected-branches). -- [Pushing only protected branches](#push-only-protected-branches). +- [Pulling only protected branches](#only-mirror-protected-branches-starter). +- [Pushing only protected branches](#push-only-protected-branches-core). You should [protect the branches](../user/project/protected_branches.md) you wish to mirror on both remotes to prevent conflicts caused by rewriting history. |
