diff options
Diffstat (limited to 'doc')
63 files changed, 1071 insertions, 261 deletions
diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 3a394c561db..69b16b7c483 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -3,10 +3,9 @@ >**Notes:** - Prometheus and the various exporters listed in this page are bundled in the Omnibus GitLab package. Check each exporter's documentation for the timeline - they got added. For installations from source you will have to install - them yourself. Over subsequent releases additional GitLab metrics will be - captured. -- Prometheus services are off by default but will be on starting with GitLab 9.0. + they got added. For installations from source you will have to install them + yourself. Over subsequent releases additional GitLab metrics will be captured. +- Prometheus services are on by default with GitLab 9.0. - Prometheus and its exporters do not authenticate users, and will be available to anyone who can access them. @@ -26,26 +25,25 @@ dashboard tool like [Grafana]. ## Configuring Prometheus >**Note:** -Available since Omnibus GitLab 8.16. For installations from source you'll -have to install and configure it yourself. +For installations from source you'll have to install and configure it yourself. -To enable Prometheus: +Prometheus and it's exporters are on by default, starting with GitLab 9.0. +Prometheus will run as the `gitlab-prometheus` user and listen on +`http://localhost:9090`. Each exporter will be automatically be set up as a +monitoring target for Prometheus, unless individually disabled. + +To disable Prometheus and all of its exporters, as well as any added in the future: 1. Edit `/etc/gitlab/gitlab.rb` -1. Add or find and uncomment the following line, making sure it's set to `true`: +1. Add or find and uncomment the following line, making sure it's set to `false`: ```ruby - prometheus['enable'] = true + prometheus_monitoring['enable'] = false ``` 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to take effect -By default, Prometheus will run as the `gitlab-prometheus` user and listen on -`http://localhost:9090`. If the [node exporter](#node-exporter) service -has been enabled, it will automatically be set up as a monitoring target for -Prometheus. - ## Changing the port Prometheus listens on >**Note:** @@ -71,16 +69,14 @@ To change the address/port that Prometheus listens on: ## Viewing performance metrics -After you have [enabled Prometheus](#configuring-prometheus), you can visit -`http://localhost:9090` for the dashboard that Prometheus offers by default. +You can visit `http://localhost:9090` for the dashboard that Prometheus offers by default. >**Note:** If SSL has been enabled on your GitLab instance, you may not be able to access Prometheus on the same browser as GitLab due to [HSTS][hsts]. We plan to [provide access via GitLab][multi-user-prometheus], but in the interim there are some workarounds: using a separate browser for Prometheus, resetting HSTS, or -having [Nginx proxy it][nginx-custom-config]. Follow issue [#27069] for more -information. +having [Nginx proxy it][nginx-custom-config]. The performance data collected by Prometheus can be viewed directly in the Prometheus console or through a compatible dashboard tool. @@ -96,6 +92,30 @@ Sample Prometheus queries: - **Data transmitted:** `irate(node_network_transmit_bytes[5m])` - **Data received:** `irate(node_network_receive_bytes[5m])` +## Configuring Prometheus to monitor Kubernetes + +> Introduced in GitLab 9.0. + +If your GitLab server is running within Kubernetes, an option is now available +to monitor the health of each node in the cluster. This is particularly helpful +if your CI/CD environments run in the same cluster, and you would like enable +[Prometheus integration][] to monitor them. + +When enabled, the bundled Prometheus server monitors Kubernetes and automatically +[collects metrics][prometheus-cadvisor-metrics] from each Node in the cluster. + +To enable the Kubernetes monitoring: + +1. Edit `/etc/gitlab/gitlab.rb` +1. Add or find and uncomment the following line: + + ```ruby + prometheus['monitor_kubernetes'] = true + ``` + +1. Save the file and [reconfigure GitLab][reconfigure] for the changes to + take effect + ## Prometheus exporters There are a number of libraries and servers which help in exporting existing @@ -143,5 +163,6 @@ The GitLab monitor exporter allows you to measure various GitLab metrics. [prom-grafana]: https://prometheus.io/docs/visualization/grafana/ [scrape-config]: https://prometheus.io/docs/operating/configuration/#%3Cscrape_config%3E [reconfigure]: ../../restart_gitlab.md#omnibus-gitlab-reconfigure -[#27069]: https://gitlab.com/gitlab-org/gitlab-ce/issues/27069 [1261]: https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/1261 +[prometheus integration]: ../../../user/project/integrations/prometheus.md +[rometheus-cadvisor-metrics]: https://github.com/google/cadvisor/blob/master/docs/storage/prometheus.md diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 62b0468da79..0c63b0b59a7 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -26,9 +26,9 @@ it works. --- -In the case of [custom domains](#custom-domains) (but not -[wildcard domains](#wildcard-domains)), the Pages daemon needs to listen on -ports `80` and/or `443`. For that reason, there is some flexibility in the way +In the case of [custom domains](#custom-domains) (but not +[wildcard domains](#wildcard-domains)), the Pages daemon needs to listen on +ports `80` and/or `443`. For that reason, there is some flexibility in the way which you can set it up: 1. Run the Pages daemon in the same server as GitLab, listening on a secondary IP. @@ -65,11 +65,13 @@ you need to add a [wildcard DNS A record][wiki-wildcard-dns] pointing to the host that GitLab runs. For example, an entry would look like this: ``` -*.example.io. 1800 IN A 1.1.1.1 +*.example.io. 1800 IN A 1.1.1.1 +*.example.io. 1800 IN AAAA 2001::1 ``` where `example.io` is the domain under which GitLab Pages will be served -and `1.1.1.1` is the IP address of your GitLab instance. +and `1.1.1.1` is the IPv4 address of your GitLab instance and `2001::1` is the +IPv6 address. If you don't have IPv6, you can omit the AAAA record. > **Note:** You should not use the GitLab domain to serve user pages. For more information @@ -141,7 +143,8 @@ outside world. In addition to the wildcard domains, you can also have the option to configure GitLab Pages to work with custom domains. Again, there are two options here: support custom domains with and without TLS certificates. The easiest setup is -that without TLS certificates. +that without TLS certificates. In either case, you'll need a secondary IP. If +you have IPv6 as well as IPv4 addresses, you can use them both. ### Custom domains @@ -163,11 +166,12 @@ world. Custom domains are supported, but no TLS. pages_external_url "http://example.io" nginx['listen_addresses'] = ['1.1.1.1'] pages_nginx['enable'] = false - gitlab_pages['external_http'] = '1.1.1.2:80' + gitlab_pages['external_http'] = ['1.1.1.2:80', '[2001::2]:80'] ``` where `1.1.1.1` is the primary IP address that GitLab is listening to and - `1.1.1.2` the secondary IP where the GitLab Pages daemon listens to. + `1.1.1.2` and `2001::2` are the secondary IPs the GitLab Pages daemon + listens on. If you don't have IPv6, you can omit the IPv6 address. 1. [Reconfigure GitLab][reconfigure] @@ -194,12 +198,13 @@ world. Custom domains and TLS are supported. pages_nginx['enable'] = false gitlab_pages['cert'] = "/etc/gitlab/ssl/example.io.crt" gitlab_pages['cert_key'] = "/etc/gitlab/ssl/example.io.key" - gitlab_pages['external_http'] = '1.1.1.2:80' - gitlab_pages['external_https'] = '1.1.1.2:443' + gitlab_pages['external_http'] = ['1.1.1.2:80', '[2001::2]:80'] + gitlab_pages['external_https'] = ['1.1.1.2:443', '[2001::2]:443'] ``` where `1.1.1.1` is the primary IP address that GitLab is listening to and - `1.1.1.2` the secondary IP where the GitLab Pages daemon listens to. + `1.1.1.2` and `2001::2` are the secondary IPs where the GitLab Pages daemon + listens on. If you don't have IPv6, you can omit the IPv6 address. 1. [Reconfigure GitLab][reconfigure] diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index f6f50e2c571..a45c3306457 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -1,5 +1,9 @@ # GitLab Pages administration for source installations +>**Note:** +Before attempting to enable GitLab Pages, first make sure you have +[installed GitLab](../../install/installation.md) successfully. + This is the documentation for configuring a GitLab Pages when you have installed GitLab from source and not using the Omnibus packages. @@ -13,7 +17,33 @@ Pages to the latest supported version. ## Overview -[Read the Omnibus overview section.](index.md#overview) +GitLab Pages makes use of the [GitLab Pages daemon], a simple HTTP server +written in Go that can listen on an external IP address and provide support for +custom domains and custom certificates. It supports dynamic certificates through +SNI and exposes pages using HTTP2 by default. +You are encouraged to read its [README][pages-readme] to fully understand how +it works. + +--- + +In the case of [custom domains](#custom-domains) (but not +[wildcard domains](#wildcard-domains)), the Pages daemon needs to listen on +ports `80` and/or `443`. For that reason, there is some flexibility in the way +which you can set it up: + +1. Run the Pages daemon in the same server as GitLab, listening on a secondary IP. +1. Run the Pages daemon in a separate server. In that case, the + [Pages path](#change-storage-path) must also be present in the server that + the Pages daemon is installed, so you will have to share it via network. +1. Run the Pages daemon in the same server as GitLab, listening on the same IP + but on different ports. In that case, you will have to proxy the traffic with + a loadbalancer. If you choose that route note that you should use TCP load + balancing for HTTPS. If you use TLS-termination (HTTPS-load balancing) the + pages will not be able to be served with user provided certificates. For + HTTP it's OK to use HTTP or TCP load balancing. + +In this document, we will proceed assuming the first option. If you are not +supporting custom domains a secondary IP is not needed. ## Prerequisites @@ -75,7 +105,7 @@ The Pages daemon doesn't listen to the outside world. cd /home/git sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git cd gitlab-pages - sudo -u git -H git checkout v0.2.4 + sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` @@ -100,14 +130,21 @@ The Pages daemon doesn't listen to the outside world. https: false ``` -1. Copy the `gitlab-pages-ssl` Nginx configuration file: +1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in + order to enable the pages daemon. In `gitlab_pages_options` the + `-pages-domain` must match the `host` setting that you set above. - ```bash - sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf - sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf ``` + gitlab_pages_enabled=true + gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 + ``` + +1. Copy the `gitlab-pages` Nginx configuration file: - Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL. + ```bash + sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf + sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf + ``` 1. Restart NGINX 1. [Restart GitLab][restart] @@ -131,7 +168,7 @@ outside world. cd /home/git sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git cd gitlab-pages - sudo -u git -H git checkout v0.2.4 + sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` @@ -149,6 +186,17 @@ outside world. https: true ``` +1. Edit `/etc/default/gitlab` and set `gitlab_pages_enabled` to `true` in + order to enable the pages daemon. In `gitlab_pages_options` the + `-pages-domain` must match the `host` setting that you set above. + The `-root-cert` and `-root-key` settings are the wildcard TLS certificates + of the `example.io` domain: + + ``` + gitlab_pages_enabled=true + gitlab_pages_options="-pages-domain example.io -pages-root $app_root/shared/pages -listen-proxy 127.0.0.1:8090 -root-cert /path/to/example.io.crt -root-key /path/to/example.io.key + ``` + 1. Copy the `gitlab-pages-ssl` Nginx configuration file: ```bash @@ -156,12 +204,9 @@ outside world. sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf ``` - Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL. - 1. Restart NGINX 1. [Restart GitLab][restart] - ## Advanced configuration In addition to the wildcard domains, you can also have the option to configure @@ -189,7 +234,7 @@ world. Custom domains are supported, but no TLS. cd /home/git sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git cd gitlab-pages - sudo -u git -H git checkout v0.2.4 + sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` @@ -224,12 +269,10 @@ world. Custom domains are supported, but no TLS. 1. Copy the `gitlab-pages-ssl` Nginx configuration file: ```bash - sudo cp lib/support/nginx/gitlab-pages-ssl /etc/nginx/sites-available/gitlab-pages-ssl.conf - sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf + sudo cp lib/support/nginx/gitlab-pages /etc/nginx/sites-available/gitlab-pages.conf + sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages.conf ``` - Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL. - 1. Edit all GitLab related configs in `/etc/nginx/site-available/` and replace `0.0.0.0` with `1.1.1.1`, where `1.1.1.1` the primary IP where GitLab listens to. @@ -257,7 +300,7 @@ world. Custom domains and TLS are supported. cd /home/git sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-pages.git cd gitlab-pages - sudo -u git -H git checkout v0.2.4 + sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` @@ -300,8 +343,6 @@ world. Custom domains and TLS are supported. sudo ln -sf /etc/nginx/sites-{available,enabled}/gitlab-pages-ssl.conf ``` - Replace `gitlab-pages-ssl` with `gitlab-pages` if you are not using SSL. - 1. Edit all GitLab related configs in `/etc/nginx/site-available/` and replace `0.0.0.0` with `1.1.1.1`, where `1.1.1.1` the primary IP where GitLab listens to. @@ -392,5 +433,6 @@ than GitLab to prevent XSS attacks. [pages-userguide]: ../../user/project/pages/index.md [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure [restart]: ../restart_gitlab.md#installations-from-source -[gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.2.4 +[gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.4.0 +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab.default.example [shared runners]: ../../ci/runners/README.md diff --git a/doc/api/issues.md b/doc/api/issues.md index e25841926f8..a19c965a8c3 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -23,7 +23,6 @@ GET /issues?state=closed GET /issues?labels=foo GET /issues?labels=foo,bar GET /issues?labels=foo,bar&state=opened -GET /projects/:id/issues?labels_name=No+Label GET /issues?milestone=1.0.0 GET /issues?milestone=1.0.0&state=opened GET /issues?iids[]=42&iids[]=43 @@ -32,8 +31,7 @@ GET /issues?iids[]=42&iids[]=43 | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `state` | string | no | Return all issues or just those that are `opened` or `closed`| -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned | -| `labels_name` | string | no | Return all issues with the mentioned label. `No+Label` lists all issues with no labels | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | | `milestone` | string| no | The milestone title | | `iids` | Array[integer] | no | Return only the issues having the given `iid` | | `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | @@ -103,7 +101,6 @@ GET /groups/:id/issues?state=closed GET /groups/:id/issues?labels=foo GET /groups/:id/issues?labels=foo,bar GET /groups/:id/issues?labels=foo,bar&state=opened -GET /projects/:id/issues?labels_name=No+Label GET /groups/:id/issues?milestone=1.0.0 GET /groups/:id/issues?milestone=1.0.0&state=opened GET /groups/:id/issues?iids[]=42&iids[]=43 @@ -113,8 +110,7 @@ GET /groups/:id/issues?iids[]=42&iids[]=43 | --------- | ---- | -------- | ----------- | | `id` | integer | yes | The ID of a group | | `state` | string | no | Return all issues or just those that are `opened` or `closed`| -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned | -| `labels_name` | string | no | Return all issues with the mentioned label. `No+Label` lists all issues with no labels | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | | `iids` | Array[integer] | no | Return only the issues having the given `iid` | | `milestone` | string| no | The milestone title | | `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | @@ -185,7 +181,6 @@ GET /projects/:id/issues?state=closed GET /projects/:id/issues?labels=foo GET /projects/:id/issues?labels=foo,bar GET /projects/:id/issues?labels=foo,bar&state=opened -GET /projects/:id/issues?labels_name=No+Label GET /projects/:id/issues?milestone=1.0.0 GET /projects/:id/issues?milestone=1.0.0&state=opened GET /projects/:id/issues?iids[]=42&iids[]=43 @@ -196,8 +191,7 @@ GET /projects/:id/issues?iids[]=42&iids[]=43 | `id` | integer | yes | The ID of a project | | `iids` | Array[integer] | no | Return only the milestone having the given `iid` | | `state` | string | no | Return all issues or just those that are `opened` or `closed`| -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned | -| `labels_name` | string | no | Return all issues with the mentioned label. `No+Label` lists all issues with no labels | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | | `milestone` | string| no | The milestone title | | `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | @@ -329,18 +323,19 @@ Creates a new project issue. POST /projects/:id/issues ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | -| `title` | string | yes | The title of an issue | -| `description` | string | no | The description of an issue | -| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | -| `assignee_id` | integer | no | The ID of a user to assign issue | -| `milestone_id` | integer | no | The ID of a milestone to assign issue | -| `labels` | string | no | Comma-separated label names for an issue | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | -| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | -| `merge_request_for_resolving_discussions` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values. | +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `title` | string | yes | The title of an issue | +| `description` | string | no | The description of an issue | +| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | +| `assignee_id` | integer | no | The ID of a user to assign issue | +| `milestone_id` | integer | no | The ID of a milestone to assign issue | +| `labels` | string | no | Comma-separated label names for an issue | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | +| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | +| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values. | +| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 8620984d40d..b3c9fe275c4 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -298,14 +298,14 @@ could look like: - docker:dind stage: build script: - - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.example.com + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.example.com - docker build -t registry.example.com/group/project:latest . - docker push registry.example.com/group/project:latest ``` You have to use the special `gitlab-ci-token` user created for you in order to push to the Registry connected to your project. Its password is provided in the -`$CI_BUILD_TOKEN` variable. This allows you to automate building and deployment +`$CI_JOB_TOKEN` variable. This allows you to automate building and deployment of your Docker images. You can also make use of [other variables](../variables/README.md) to avoid hardcoding: @@ -315,10 +315,10 @@ services: - docker:dind variables: - IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_BUILD_REF_NAME + IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_NAME before_script: - - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN $CI_REGISTRY + - docker login -u gitlab-ci-token -p $CI_COMMIT_TOKEN $CI_REGISTRY build: stage: build @@ -328,7 +328,7 @@ build: ``` Here, `$CI_REGISTRY_IMAGE` would be resolved to the address of the registry tied -to this project, and `$CI_BUILD_REF_NAME` would be resolved to the branch or +to this project, and `$CI_COMMIT_REF_NAME` would be resolved to the branch or tag name for this particular job. We also declare our own variable, `$IMAGE_TAG`, combining the two to save us some typing in the `script` section. @@ -350,11 +350,11 @@ stages: - deploy variables: - CONTAINER_TEST_IMAGE: registry.example.com/my-group/my-project:$CI_BUILD_REF_NAME + CONTAINER_TEST_IMAGE: registry.example.com/my-group/my-project:$CI_COMMIT_REF_NAME CONTAINER_RELEASE_IMAGE: registry.example.com/my-group/my-project:latest before_script: - - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.example.com + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.example.com build: stage: build diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 00787323b6b..f025a7e3496 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -170,13 +170,17 @@ services: ``` When the job is run, `tutum/wordpress` will be started and you will have -access to it from your build container under the hostname `tutum__wordpress`. +access to it from your build container under the hostnames `tutum-wordpress` +(requires GitLab Runner v1.1.0 or newer) and `tutum__wordpress`. -The alias hostname for the service is made from the image name following these +*Note: hostname with underscores is not RFC valid and may cause problems in 3rd party applications.* + +The alias hostnames for the service are made from the image name following these rules: 1. Everything after `:` is stripped -2. Slash (`/`) is replaced with double underscores (`__`) +2. Slash (`/`) is replaced with double underscores (`__`) - primary alias +3. Slash (`/`) is replaced with dash (`-`) - secondary alias, requires GitLab Runner v1.1.0 or newer ## Configuring services diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 3c31ba45d3d..b28f3e13eae 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -263,7 +263,7 @@ This works just like any other terminal - you'll be in the container created by your deployment, so you can run shell commands and get responses in real time, check the logs, try out configuration or code tweaks, etc. You can open multiple terminals to the same environment - they each get their own shell -session - and even a multiplexer like `screen` or `tmux`! +session - and even a multiplexer like `screen` or `tmux`! >**Note:** Container-based deployments often lack basic tools (like an editor), and may @@ -295,7 +295,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com only: - branches @@ -306,22 +306,22 @@ deploy_review: Let's break it down in pieces. The job's name is `deploy_review` and it runs on the `deploy` stage. The `script` at this point is fictional, you'd have to use your own based on your deployment. Then, we set the `environment` with the -`environment:name` being `review/$CI_BUILD_REF_NAME`. Now that's an interesting +`environment:name` being `review/$CI_COMMIT_REF_NAME`. Now that's an interesting one. Since the [environment name][env-name] can contain slashes (`/`), we can use this pattern to distinguish between dynamic environments and the regular ones. -So, the first part is `review`, followed by a `/` and then `$CI_BUILD_REF_NAME` -which takes the value of the branch name. Since `$CI_BUILD_REF_NAME` itself may +So, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME` +which takes the value of the branch name. Since `$CI_COMMIT_REF_NAME` itself may also contain `/`, or other characters that would be invalid in a domain name or URL, we use `$CI_ENVIRONMENT_SLUG` in the `environment:url` so that the environment can get a specific and distinct URL for each branch. In this case, -given a `$CI_BUILD_REF_NAME` of `100-Do-The-Thing`, the URL will be something +given a `$CI_COMMIT_REF_NAME` of `100-Do-The-Thing`, the URL will be something like `https://100-do-the-4f99a2.example.com`. Again, the way you set up the web server to serve these requests is based on your setup. -You could also use `$CI_BUILD_REF_SLUG` in `environment:url`, e.g.: -`https://$CI_BUILD_REF_SLUG.example.com`. We use `$CI_ENVIRONMENT_SLUG` +You could also use `$CI_COMMIT_REF_SLUG` in `environment:url`, e.g.: +`https://$CI_COMMIT_REF_SLUG.example.com`. We use `$CI_ENVIRONMENT_SLUG` here because it is guaranteed to be unique, but if you're using a workflow like [GitLab Flow][gitlab-flow], collisions are very unlikely, and you may prefer environment names to be more closely based on the branch name - the example @@ -356,7 +356,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com only: - branches @@ -387,16 +387,16 @@ deploy_prod: A more realistic example would include copying files to a location where a webserver (NGINX) could then read and serve. The example below will copy the -`public` directory to `/srv/nginx/$CI_BUILD_REF_SLUG/public`: +`public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public`: ```yaml review_app: stage: deploy script: - - rsync -av --delete public /srv/nginx/$CI_BUILD_REF_SLUG + - rsync -av --delete public /srv/nginx/$CI_COMMIT_REF_SLUG environment: - name: review/$CI_BUILD_REF_NAME - url: https://$CI_BUILD_REF_SLUG.example.com + name: review/$CI_COMMIT_REF_NAME + url: https://$CI_COMMIT_REF_SLUG.example.com ``` It is assumed that the user has already setup NGINX and GitLab Runner in the @@ -526,7 +526,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review only: @@ -542,7 +542,7 @@ stop_review: - echo "Remove review app" when: manual environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME action: stop ``` @@ -568,13 +568,13 @@ You can read more in the [`.gitlab-ci.yml` reference][onstop]. As we've seen in the [dynamic environments](#dynamic-environments), you can prepend their name with a word, then followed by a `/` and finally the branch -name which is automatically defined by the `CI_BUILD_REF_NAME` variable. +name which is automatically defined by the `CI_COMMIT_REF_NAME` variable. In short, environments that are named like `type/foo` are presented under a group named `type`. -In our minimal example, we name the environments `review/$CI_BUILD_REF_NAME` -where `$CI_BUILD_REF_NAME` is the branch name: +In our minimal example, we name the environments `review/$CI_COMMIT_REF_NAME` +where `$CI_COMMIT_REF_NAME` is the branch name: ```yaml deploy_review: @@ -582,7 +582,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME ``` In that case, if you visit the Environments page, and provided the branches diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index c679ea4e298..28c484ddbe6 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -80,7 +80,7 @@ The process of adding Review Apps in your workflow would look like: 1. [Install][install-runner] and [configure][conf-runner] a Runner that does the deployment. 1. Set up a job in `.gitlab-ci.yml` that uses the predefined - [predefined CI environment variable][variables] `${CI_BUILD_REF_NAME}` to + [predefined CI environment variable][variables] `${CI_COMMIT_REF_NAME}` to create dynamic environments and restrict it to run only on branches. 1. Optionally set a job that [manually stops][manual-env] the Review Apps. diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index 49e7ac38b26..befaa06e918 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -30,14 +30,23 @@ This is the universal solution which works with any type of executor ## SSH keys when using the Docker executor You will first need to create an SSH key pair. For more information, follow the -instructions to [generate an SSH key](../../ssh/README.md). Do not add a comment -to the SSH key, or the `before_script` will prompt for a passphrase. +instructions to [generate an SSH key](../../ssh/README.md). Do not add a +passphrase to the SSH key, or the `before_script` will prompt for it. Then, create a new **Secret Variable** in your project settings on GitLab following **Settings > Variables**. As **Key** add the name `SSH_PRIVATE_KEY` and in the **Value** field paste the content of your _private_ key that you created earlier. +It is also good practice to check the server's own public key to make sure you +are not being targeted by a man-in-the-middle attack. To do this, add another +variable named `SSH_SERVER_HOSTKEYS`. To find out the hostkeys of your server, run +the `ssh-keyscan YOUR_SERVER` command from a trusted network (ideally, from the +server itself), and paste its output into the `SSH_SERVER_HOSTKEY` variable. If +you need to connect to multiple servers, concatenate all the server public keys +that you collected into the **Value** of the variable. There must be one key per +line. + Next you need to modify your `.gitlab-ci.yml` with a `before_script` action. Add it to the top: @@ -59,6 +68,11 @@ before_script: # you will overwrite your user's SSH config. - mkdir -p ~/.ssh - '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config' + # In order to properly check the server's host key, assuming you created the + # SSH_SERVER_HOSTKEYS variable previously, uncomment the following two lines + # instead. + # - mkdir -p ~/.ssh + # - '[[ -f /.dockerenv ]] && echo "$SSH_SERVER_HOSTKEYS" > ~/.ssh/known_hosts' ``` As a final step, add the _public_ key from the one you created earlier to the diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 03e6b5303c5..4e9094cb0f1 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -236,18 +236,18 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ CI=true ++ export CI_DEBUG_TRACE=false ++ CI_DEBUG_TRACE=false -++ export CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ export CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ export CI_BUILD_REF_NAME=master -++ CI_BUILD_REF_NAME=master -++ export CI_BUILD_ID=7046507 -++ CI_BUILD_ID=7046507 -++ export CI_BUILD_REPO=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git -++ CI_BUILD_REPO=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git -++ export CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx -++ CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ export CI_COMMIT_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_COMMIT_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_COMMIT_REF_NAME=master +++ CI_COMMIT_REF_NAME=master +++ export CI_JOB_ID=7046507 +++ CI_JOB_ID=7046507 +++ export CI_REPOSITORY_URL=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git +++ CI_REPOSITORY_URL=https://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@example.com/gitlab-examples/ci-debug-trace.git +++ export CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx ++ export CI_PROJECT_ID=1796893 ++ CI_PROJECT_ID=1796893 ++ export CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace @@ -266,20 +266,20 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ CI=true ++ export GITLAB_CI=true ++ GITLAB_CI=true -++ export CI_BUILD_ID=7046507 -++ CI_BUILD_ID=7046507 -++ export CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx -++ CI_BUILD_TOKEN=xxxxxxxxxxxxxxxxxxxx -++ export CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ CI_BUILD_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ export CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ CI_BUILD_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 -++ export CI_BUILD_REF_NAME=master -++ CI_BUILD_REF_NAME=master -++ export CI_BUILD_NAME=debug_trace -++ CI_BUILD_NAME=debug_trace -++ export CI_BUILD_STAGE=test -++ CI_BUILD_STAGE=test +++ export CI_JOB_ID=7046507 +++ CI_JOB_ID=7046507 +++ export CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ CI_JOB_TOKEN=xxxxxxxxxxxxxxxxxxxx +++ export CI_COMMIT_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_COMMIT_REF=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ CI_COMMIT_BEFORE_SHA=dd648b2e48ce6518303b0bb580b2ee32fadaf045 +++ export CI_COMMIT_REF_NAME=master +++ CI_COMMIT_REF_NAME=master +++ export CI_COMMIT_NAME=debug_trace +++ CI_JOB_NAME=debug_trace +++ export CI_JOB_STAGE=test +++ CI_JOB_STAGE=test ++ export CI_SERVER_NAME=GitLab ++ CI_SERVER_NAME=GitLab ++ export CI_SERVER_VERSION=8.14.3-ee diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 49fa8761e5e..ad3ebd144df 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -153,7 +153,7 @@ thus allowing to fine tune them. Variables can be also defined on a [job level](#job-variables). Except for the user defined variables, there are also the ones set up by the -Runner itself. One example would be `CI_BUILD_REF_NAME` which has the value of +Runner itself. One example would be `CI_COMMIT_REF_NAME` which has the value of the branch or tag name for which project is built. Apart from the variables you can set in `.gitlab-ci.yml`, there are also the so called secret variables which can be set in GitLab's UI. @@ -252,7 +252,7 @@ To enable per-job caching: ```yaml cache: - key: "$CI_BUILD_NAME" + key: "$CI_JOB_NAME" untracked: true ``` @@ -260,7 +260,7 @@ To enable per-branch caching: ```yaml cache: - key: "$CI_BUILD_REF_NAME" + key: "$CI_COMMIT_REF_NAME" untracked: true ``` @@ -268,7 +268,7 @@ To enable per-job and per-branch caching: ```yaml cache: - key: "$CI_BUILD_NAME/$CI_BUILD_REF_NAME" + key: "$CI_JOB_NAME/$CI_COMMIT_REF_NAME" untracked: true ``` @@ -276,7 +276,7 @@ To enable per-branch and per-stage caching: ```yaml cache: - key: "$CI_BUILD_STAGE/$CI_BUILD_REF_NAME" + key: "$CI_JOB_STAGE/$CI_COMMIT_REF_NAME" untracked: true ``` @@ -285,7 +285,7 @@ If you use **Windows Batch** to run your shell scripts you need to replace ```yaml cache: - key: "%CI_BUILD_STAGE%/%CI_BUILD_REF_NAME%" + key: "%CI_JOB_STAGE%/%CI_COMMIT_REF_NAME%" untracked: true ``` @@ -739,12 +739,12 @@ deploy as review app: stage: deploy script: make deploy environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com/ ``` The `deploy as review app` job will be marked as deployment to dynamically -create the `review/$CI_BUILD_REF_NAME` environment, where `$CI_BUILD_REF_NAME` +create the `review/$CI_COMMIT_REF_NAME` environment, where `$CI_COMMIT_REF_NAME` is an [environment variable][variables] set by the Runner. The `$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable for inclusion in URLs. In this case, if the `deploy as review app` job was run @@ -850,7 +850,7 @@ To create an archive with a name of the current job: ```yaml job: artifacts: - name: "$CI_BUILD_NAME" + name: "$CI_JOB_NAME" ``` To create an archive with a name of the current branch or tag including only @@ -859,7 +859,7 @@ the files that are untracked by Git: ```yaml job: artifacts: - name: "$CI_BUILD_REF_NAME" + name: "$CI_COMMIT_REF_NAME" untracked: true ``` @@ -869,7 +869,7 @@ tag including only the files that are untracked by Git: ```yaml job: artifacts: - name: "${CI_BUILD_NAME}_${CI_BUILD_REF_NAME}" + name: "${CI_JOB_NAME}_${CI_COMMIT_REF_NAME}" untracked: true ``` @@ -878,7 +878,7 @@ To create an archive with a name of the current [stage](#stages) and branch name ```yaml job: artifacts: - name: "${CI_BUILD_STAGE}_${CI_BUILD_REF_NAME}" + name: "${CI_JOB_STAGE}_${CI_COMMIT_REF_NAME}" untracked: true ``` @@ -890,7 +890,7 @@ If you use **Windows Batch** to run your shell scripts you need to replace ```yaml job: artifacts: - name: "%CI_BUILD_STAGE%_%CI_BUILD_REF_NAME%" + name: "%CI_JOB_STAGE%_%CI_COMMIT_REF_NAME%" untracked: true ``` diff --git a/doc/development/changelog.md b/doc/development/changelog.md index c71858c6a24..ce39a379a0e 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -1,7 +1,7 @@ -# Generate a changelog entry +# Changelog entries -This guide contains instructions for generating a changelog entry data file, as -well as information and history about our changelog process. +This guide contains instructions for when and how to generate a changelog entry +file, as well as information and history about our changelog process. ## Overview @@ -19,19 +19,71 @@ author: Ozzy Osbourne The `merge_request` value is a reference to a merge request that adds this entry, and the `author` key is used to give attribution to community -contributors. Both are optional. +contributors. **Both are optional**. Community contributors and core team members are encouraged to add their name to -the `author` field. GitLab team members should not. - -If you're working on the GitLab EE repository, the entry will be added to -`changelogs/unreleased-ee/` instead. +the `author` field. GitLab team members **should not**. [changelog.md]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CHANGELOG.md [unreleased]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/changelogs/ [YAML]: https://en.wikipedia.org/wiki/YAML -## Instructions +## What warrants a changelog entry? + +- Any user-facing change **should** have a changelog entry. Example: "GitLab now + uses system fonts for all text." +- A fix for a regression introduced and then fixed in the same release (i.e., + fixing a bug introduced during a monthly release candidate) **should not** + have a changelog entry. +- Any developer-facing change (e.g., refactoring, technical debt remediation, + test suite changes) **should not** have a changelog entry. Example: "Reduce + database records created during Cycle Analytics model spec." +- _Any_ contribution from a community member, no matter how small, **may** have + a changelog entry regardless of these guidelines if the contributor wants one. + Example: "Fixed a typo on the search results page. (Jane Smith)" + +## Writing good changelog entries + +A good changelog entry should be descriptive and concise. It should explain the +change to a reader who has _zero context_ about the change. If you have trouble +making it both concise and descriptive, err on the side of descriptive. + +- **Bad:** Go to a project order. +- **Good:** Show a user's starred projects at the top of the "Go to project" + dropdown. + +The first example provides no context of where the change was made, or why, or +how it benefits the user. + +- **Bad:** Copy [some text] to clipboard. +- **Good:** Update the "Copy to clipboard" tooltip to indicate what's being + copied. + +Again, the first example is too vague and provides no context. + +- **Bad:** Fixes and Improves CSS and HTML problems in mini pipeline graph and + builds dropdown. +- **Good:** Fix tooltips and hover states in mini pipeline graph and builds + dropdown. + +The first example is too focused on implementation details. The user doesn't +care that we changed CSS and HTML, they care about the _end result_ of those +changes. + +- **Bad:** Strip out `nil`s in the Array of Commit objects returned from + `find_commits_by_message_with_elastic` +- **Good:** Fix 500 errors caused by elasticsearch results referencing + garbage-collected commits + +The first example focuses on _how_ we fixed something, not on _what_ it fixes. +The rewritten version clearly describes the _end benefit_ to the user (fewer 500 +errors), and _when_ (searching commits with ElasticSearch). + +Use your best judgement and try to put yourself in the mindset of someone +reading the compiled changelog. Does this entry add value? Does it offer context +about _where_ and _why_ the change was made? + +## How to generate a changelog entry A `bin/changelog` script is available to generate the changelog entry file automatically. @@ -55,19 +107,28 @@ title: Hey DZ, I added a feature to GitLab! merge_request: author: ``` +If you're working on the GitLab EE repository, the entry will be added to +`changelogs/unreleased-ee/` instead. + +#### Arguments -### Arguments +| Argument | Shorthand | Purpose | +| ----------------- | --------- | --------------------------------------------- | +| [`--amend`] | | Amend the previous commit | +| [`--force`] | `-f` | Overwrite an existing entry | +| [`--merge-request`] | `-m` | Set merge request ID | +| [`--dry-run`] | `-n` | Don't actually write anything, just print | +| [`--git-username`] | `-u` | Use Git user.name configuration as the author | +| [`--help`] | `-h` | Print help message | -| Argument | Shorthand | Purpose | -| ----------------- | --------- | --------------------------------------------- | -| `--amend` | | Amend the previous commit | -| `--force` | `-f` | Overwrite an existing entry | -| `--merge-request` | `-m` | Merge Request ID | -| `--dry-run` | `-n` | Don't actually write anything, just print | -| `--git-username` | `-u` | Use Git user.name configuration as the author | -| `--help` | `-h` | Print help message | +[`--amend`]: #-amend +[`--force`]: #-force-or-f +[`--merge-request`]: #-merge-request-or-m +[`--dry-run`]: #-dry-run-or-n +[`--git-username`]: #-git-username-or-u +[`--help`]: #-help -#### `--amend` +##### `--amend` You can pass the **`--amend`** argument to automatically stage the generated file and amend it to the previous commit. @@ -88,7 +149,7 @@ merge_request: author: ``` -#### `--force` or `-f` +##### `--force` or `-f` Use **`--force`** or **`-f`** to overwrite an existing changelog entry if it already exists. @@ -105,7 +166,7 @@ merge_request: 1983 author: ``` -#### `--merge-request` or `-m` +##### `--merge-request` or `-m` Use the **`--merge-request`** or **`-m`** argument to provide the `merge_request` value: @@ -119,7 +180,7 @@ merge_request: 1983 author: ``` -#### `--dry-run` or `-n` +##### `--dry-run` or `-n` Use the **`--dry-run`** or **`-n`** argument to prevent actually writing or committing anything: @@ -135,7 +196,7 @@ author: $ ls changelogs/unreleased/ ``` -#### `--git-username` or `-u` +##### `--git-username` or `-u` Use the **`--git-username`** or **`-u`** argument to automatically fill in the `author` value with your configured Git `user.name` value: @@ -152,7 +213,7 @@ merge_request: author: Jane Doe ``` -## History and Reasoning +### History and Reasoning Our `CHANGELOG` file was previously updated manually by each contributor that felt their change warranted an entry. When two merge requests added their own diff --git a/doc/development/frontend.md b/doc/development/frontend.md index d646de7c54a..50105a486d0 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -32,6 +32,28 @@ You can find the Frontend Architecture experts on the [team page][team-page]. You can find documentation about the desired architecture for a new feature built with Vue.js in [here][vue-section]. +### Realtime + +When writing code for realtime features we have to keep a couple of things in mind: +1. Do not overload the server with requests. +1. It should feel realtime. + +Thus, we must strike a balance between sending requests and the feeling of realtime. +Use the following rules when creating realtime solutions. + +1. The server will tell you how much to poll by sending `Poll-Interval` in the header. +Use that as your polling interval. This way it is easy for system administrators to change the +polling rate. +A `Poll-Interval: -1` means you should disable polling, and this must be implemented. +1. A response with HTTP status `4XX` or `5XX` should disable polling as well. +1. Use a common library for polling. +1. Poll on active tabs only. Use a common library to find out which tab currently has eyes on it. +Please use [Focus](https://gitlab.com/andrewn/focus). Specifically [Eyeballs Detector](https://gitlab.com/andrewn/focus/blob/master/lib/eyeballs-detector.js). +1. Use regular polling intervals, do not use backoff polling, or jitter, as the interval will be +controlled by the server. +1. The backend code will most likely be using etags. You do not and should not check for status +`304 Not Modified`. The browser will transform it for you. + ### Vue For more complex frontend features, we recommend using Vue.js. It shares @@ -66,6 +88,8 @@ Let's look into each of them: This is the index file of your new feature. This is where the root Vue instance of the new feature should be. +The Store and the Service should be imported and initialized in this file and provided as a prop to the main component. + Don't forget to follow [these steps.][page_specific_javascript] **A folder for Components** @@ -86,7 +110,7 @@ You can read more about components in Vue.js site, [Component System][component- **A folder for the Store** -The Store is a simple object that allows us to manage the state in a single +The Store is a class that allows us to manage the state in a single source of truth. The concept we are trying to follow is better explained by Vue documentation @@ -289,7 +313,7 @@ When exactly one object is needed for a given task, prefer to define it as a `class` rather than as an object literal. Prefer also to explicitly restrict instantiation, unless flexibility is important (e.g. for testing). -``` +```javascript // bad gl.MyThing = { @@ -332,6 +356,33 @@ gl.MyThing = MyThing; ``` +### Manipulating the DOM in a JS Class + +When writing a class that needs to manipulate the DOM guarantee a container option is provided. +This is useful when we need that class to be instantiated more than once in the same page. + +Bad: +```javascript +class Foo { + constructor() { + document.querySelector('.bar'); + } +} +new Foo(); +``` + +Good: +```javascript +class Foo { + constructor(opts) { + document.querySelector(`${opts.container} .bar`); + } +} + +new Foo({ container: '.my-element' }); +``` +You can find an example of the above in this [class][container-class-example]; + ## Supported browsers For our currently-supported browsers, see our [requirements][requirements]. @@ -457,3 +508,4 @@ Scenario: Developer can approve merge request [eslintrc]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.eslintrc [team-page]: https://about.gitlab.com/team [vue-section]: https://docs.gitlab.com/ce/development/frontend.html#how-to-build-a-new-feature-with-vue-js +[container-class-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/mini_pipeline_graph_dropdown.js diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index 8232a0a113c..2b4126b43ef 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -68,7 +68,7 @@ end This will end up running one query for every object to update. This code can easily overload a database given enough rows to update or many instances of this code running in parallel. This particular problem is known as the -["N+1 query problem"](http://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations). +["N+1 query problem"](http://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations). You can write a test with [QueryRecoder](query_recorder.md) to detect this and prevent regressions. In this particular case the workaround is fairly easy: @@ -117,6 +117,8 @@ Post.all.includes(:author).each do |post| end ``` +Also consider using [QueryRecoder tests](query_recorder.md) to prevent a regression when eager loading. + ## Memory Usage **Summary:** merge requests **must not** increase memory usage unless absolutely diff --git a/doc/development/performance.md b/doc/development/performance.md index c1f129e576c..04419650b12 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -39,6 +39,7 @@ GitLab provides built-in tools to aid the process of improving performance: * [Sherlock](profiling.md#sherlock) * [GitLab Performance Monitoring](../administration/monitoring/performance/introduction.md) * [Request Profiling](../administration/monitoring/performance/request_profiling.md) +* [QueryRecoder](query_recorder.md) for preventing `N+1` regressions GitLab employees can use GitLab.com's performance monitoring systems located at <http://performance.gitlab.net>, this requires you to log in using your diff --git a/doc/development/polling.md b/doc/development/polling.md new file mode 100644 index 00000000000..a7f2962acf0 --- /dev/null +++ b/doc/development/polling.md @@ -0,0 +1,41 @@ +# Polling with ETag caching + +Polling for changes (repeatedly asking server if there are any new changes) +introduces high load on a GitLab instance, because it usually requires +executing at least a few SQL queries. This makes scaling large GitLab +instances (like GitLab.com) very difficult so we do not allow adding new +features that require polling and hit the database. + +Instead you should use polling mechanism with ETag caching in Redis. + +## How to use it + +1. Add the path of the endpoint which you want to poll to + `Gitlab::EtagCaching::Middleware`. +1. Implement cache invalidation for the path of your endpoint using + `Gitlab::EtagCaching::Store`. Whenever a resource changes you + have to invalidate the ETag for the path that depends on this + resource. +1. Check that the mechanism works: + - requests should return status code 304 + - there should be no SQL queries logged in `log/development.log` + +## How it works + +1. Whenever a resource changes we generate a random value and store it in + Redis. +1. When a client makes a request we set the `ETag` response header to the value + from Redis. +1. The client caches the response (client-side caching) and sends the ETag as + the `If-None-Match` header with every subsequent request for the same + resource. +1. If the `If-None-Match` header matches the current value in Redis we know + that the resource did not change so we can send 304 response immediately, + without querying the database at all. The client's browser will use the + cached response. +1. If the `If-None-Match` header does not match the current value in Redis + we have to generate a new response, because the resource changed. + +For more information see: +- [RFC 7232](https://tools.ietf.org/html/rfc7232) +- [ETag proposal](https://gitlab.com/gitlab-org/gitlab-ce/issues/26926) diff --git a/doc/development/profiling.md b/doc/development/profiling.md index e244ad4e881..933033a09e0 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -25,3 +25,5 @@ starting GitLab. For example: Bullet will log query problems to both the Rails log as well as the Chrome console. + +As a follow up to finding `N+1` queries with Bullet, consider writing a [QueryRecoder test](query_recorder.md) to prevent a regression. diff --git a/doc/development/query_recorder.md b/doc/development/query_recorder.md new file mode 100644 index 00000000000..e0127aaed4c --- /dev/null +++ b/doc/development/query_recorder.md @@ -0,0 +1,29 @@ +# QueryRecorder + +QueryRecorder is a tool for detecting the [N+1 queries problem](http://guides.rubyonrails.org/active_record_querying.html#eager-loading-associations) from tests. + +> Implemented in [spec/support/query_recorder.rb](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/support/query_recorder.rb) via [9c623e3e](https://gitlab.com/gitlab-org/gitlab-ce/commit/9c623e3e5d7434f2e30f7c389d13e5af4ede770a) + +As a rule, merge requests [should not increase query counts](merge_request_performance_guidelines.md#query-counts). If you find yourself adding something like `.includes(:author, :assignee)` to avoid having `N+1` queries, consider using QueryRecorder to enforce this with a test. Without this, a new feature which causes an additional model to be accessed will silently reintroduce the problem. + +## How it works + +This style of test works by counting the number of SQL queries executed by ActiveRecord. First a control count is taken, then you add new records to the database and rerun the count. If the number of queries has significantly increased then an `N+1` queries problem exists. + +```ruby +it "avoids N+1 database queries" do + control_count = ActiveRecord::QueryRecorder.new { visit_some_page }.count + create_list(:issue, 5) + expect { visit_some_page }.not_to exceed_query_limit(control_count) +end +``` + +As an example you might create 5 issues in between counts, which would cause the query count to increase by 5 if an N+1 problem exists. + +> **Note:** In some cases the query count might change slightly between runs for unrelated reasons. In this case you might need to test `exceed_query_limit(control_count + acceptable_change)`, but this should be avoided if possible. + +## See also + +- [Bullet](profiling.md#Bullet) For finding `N+1` query problems +- [Performance guidelines](performance.md) +- [Merge request performance guidelines](merge_request_performance_guidelines.md#query-counts)
\ No newline at end of file diff --git a/doc/development/testing.md b/doc/development/testing.md index 9b545d7f0f1..5ac7b8dadeb 100644 --- a/doc/development/testing.md +++ b/doc/development/testing.md @@ -35,8 +35,8 @@ GitLab uses [Karma] to run its [Jasmine] JavaScript specs. They can be run on the command line via `bundle exec karma`. - JavaScript tests live in `spec/javascripts/`, matching the folder structure of - `app/assets/javascripts/`: `app/assets/javascripts/behaviors/autosize.js.es6` has a corresponding - `spec/javascripts/behaviors/autosize_spec.js.es6` file. + `app/assets/javascripts/`: `app/assets/javascripts/behaviors/autosize.js` has a corresponding + `spec/javascripts/behaviors/autosize_spec.js` file. - Haml fixtures required for JavaScript tests live in `spec/javascripts/fixtures`. They should contain the bare minimum amount of markup necessary for the test. diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 3f90597ec80..7b586138f42 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -108,7 +108,7 @@ use the CI features. ## Unicorn Workers -It's possible to increase the amount of unicorn workers and this will usually help for to reduce the response time of the applications and increase the ability to handle parallel requests. +It's possible to increase the amount of unicorn workers and this will usually help to reduce the response time of the applications and increase the ability to handle parallel requests. For most instances we recommend using: CPU cores + 1 = unicorn workers. So for a machine with 2 cores, 3 unicorn workers is ideal. @@ -148,8 +148,18 @@ Sidekiq processes the background jobs with a multithreaded process. This process starts with the entire Rails stack (200MB+) but it can grow over time due to memory leaks. On a very active server (10,000 active users) the Sidekiq process can use 1GB+ of memory. +## Prometheus and its exporters + +As of Omnibus GitLab 9.0, [Prometheus](https://prometheus.io) and its related +exporters are enabled by default, to enable easy and in depth monitoring of +GitLab. Approximately 200MB of memory will be consumed by these processes, with +default settings. + +If you would like to disable Prometheus and it's exporters or read more information +about it, check the [Prometheus documentation](../administration/monitoring/prometheus/index.md). + ## Supported web browsers We support the current and the previous major release of Firefox, Chrome/Chromium, Safari and Microsoft browsers (Microsoft Edge and Internet Explorer 11). -Each time a new browser version is released, we begin supporting that version and stop supporting the third most recent version. +Each time a new browser version is released, we begin supporting that version and stop supporting the third most recent version.
\ No newline at end of file diff --git a/doc/integration/github.md b/doc/integration/github.md index cea85f073cc..4b0d33334bd 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -19,7 +19,7 @@ GitHub will generate an application ID and secret key for you to use. - 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. 'https://gitlab.company.com' - Application description: Fill this in if you wish. - - Authorization callback URL is 'http(s)://${YOUR_DOMAIN}' + - Authorization callback URL is 'http(s)://${YOUR_DOMAIN}'. Please make sure the port is included if your Gitlab instance is not configured on default port. 1. Select "Register application". 1. You should now see a Client ID and Client Secret near the top right of the page (see screenshot). diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index ec13c2446ef..ad5ffc84473 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -313,8 +313,19 @@ X-Gitlab-Event: System Hook "git_ssh_url":"git@example.com:mike/diaspora.git", "visibility_level":0 }, - "commits": [], - "total_commits_count": 0 + "commits": [ + { + "id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", + "message": "Add simple search to projects in public area", + "timestamp": "2013-05-13T18:18:08+00:00", + "url": "https://dev.gitlab.org/gitlab/gitlabhq/commit/c5feabde2d8cd023215af4d2ceeb7a64839fc428", + "author": { + "name": "Dmitriy Zaporozhets", + "email": "dmitriy.zaporozhets@gmail.com" + } + } + ], + "total_commits_count": 1 } ``` diff --git a/doc/update/8.16-to-8.17.md b/doc/update/8.16-to-8.17.md index 954109ba18f..74ffe0bc846 100644 --- a/doc/update/8.16-to-8.17.md +++ b/doc/update/8.16-to-8.17.md @@ -139,7 +139,7 @@ sudo -u git -H git checkout v4.1.1 #### New configuration options for `gitlab.yml` -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: +There might be new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: ```sh cd /home/git/gitlab @@ -195,6 +195,16 @@ See [smtp_settings.rb.sample] as an example. #### Init script +There might be new configuration options available for [`gitlab.default.example`][gl-example]. +You need to update this file if you want to [enable GitLab Pages][pages-admin]. +View them with the command below and apply them manually to your current `/etc/default/gitlab`: + +```sh +cd /home/git/gitlab + +git diff origin/8-16-stable:lib/support/init.d/gitlab.default.example origin/8-17-stable:lib/support/init.d/gitlab.default.example +``` + Ensure you're still up-to-date with the latest init script changes: ```bash @@ -254,3 +264,5 @@ sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. [yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-17-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-17-stable/lib/support/init.d/gitlab.default.example +[pages-admin]: ../administration/pages/source.md diff --git a/doc/update/8.17-to-9.0.md b/doc/update/8.17-to-9.0.md index 1fe38cf8d2a..626507c0482 100644 --- a/doc/update/8.17-to-9.0.md +++ b/doc/update/8.17-to-9.0.md @@ -149,7 +149,7 @@ sudo -u git -H git checkout v5.0.0 #### New configuration options for `gitlab.yml` -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: +There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: ```sh cd /home/git/gitlab @@ -189,7 +189,7 @@ Update your current configuration as follows, replacing with your storages names **For Omnibus installations** -1. Upate your `/etc/gitlab/gitlab.rb`, from +1. Update your `/etc/gitlab/gitlab.rb`, from ```ruby git_data_dirs({ @@ -260,6 +260,14 @@ See [smtp_settings.rb.sample] as an example. #### Init script +There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: + +```sh +cd /home/git/gitlab + +git diff origin/8-17-stable:lib/support/init.d/gitlab.default.example origin/9-0-stable:lib/support/init.d/gitlab.default.example +``` + Ensure you're still up-to-date with the latest init script changes: ```bash @@ -319,3 +327,4 @@ sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. [yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-0-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-0-stable/lib/support/init.d/gitlab.default.example diff --git a/doc/user/award_emojis.md b/doc/user/award_emojis.md new file mode 100644 index 00000000000..acbd2a66d37 --- /dev/null +++ b/doc/user/award_emojis.md @@ -0,0 +1,51 @@ +# Award emoji + +>**Notes:** +- First [introduced][1825] in GitLab 8.2. +- GitLab 9.0 [introduced][ce-9570] the usage of native emojis if the platform + supports them and falls back to images or CSS sprites. This change greatly + improved the award emoji performance overall. + +When you're collaborating online, you get fewer opportunities for high-fives +and thumbs-ups. Emoji can be awarded to issues, merge requests, snippets, and +virtually everywhere where you can have a discussion. + + + +Award emoji make it much easier to give and receive feedback without a long +comment thread. Comments that are only emoji will automatically become +award emoji. + +## Sort issues and merge requests on vote count + +> [Introduced][2871] in GitLab 8.5. + +You can quickly sort issues and merge requests by the number of votes they +have received. The sort options can be found in the dropdown menu as "Most +popular" and "Least popular". + + + +The total number of votes is not summed up. An issue with 18 upvotes and 5 +downvotes is considered more popular than an issue with 17 upvotes and no +downvotes. + +## Award emoji for comments + +> [Introduced][4291] in GitLab 8.9. + +Award emoji can also be applied to individual comments when you want to +celebrate an accomplishment or agree with an opinion. + +To add an award emoji, click the smile in the top right of the comment and pick +an emoji from the dropdown. If you want to remove an award emoji, just click +the emoji again and the vote will be removed. + + + + + +[2871]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781 +[1825]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825 +[4291]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4291 +[ce-9570]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9570 diff --git a/doc/user/group/subgroups/img/create_new_group.png b/doc/user/group/subgroups/img/create_new_group.png Binary files differnew file mode 100644 index 00000000000..9d011ec709a --- /dev/null +++ b/doc/user/group/subgroups/img/create_new_group.png diff --git a/doc/user/group/subgroups/img/create_subgroup_button.png b/doc/user/group/subgroups/img/create_subgroup_button.png Binary files differnew file mode 100644 index 00000000000..000b54c2855 --- /dev/null +++ b/doc/user/group/subgroups/img/create_subgroup_button.png diff --git a/doc/user/group/subgroups/img/group_members.png b/doc/user/group/subgroups/img/group_members.png Binary files differnew file mode 100644 index 00000000000..b95fe6263bf --- /dev/null +++ b/doc/user/group/subgroups/img/group_members.png diff --git a/doc/user/group/subgroups/img/mention_subgroups.png b/doc/user/group/subgroups/img/mention_subgroups.png Binary files differnew file mode 100644 index 00000000000..8e6bed0111b --- /dev/null +++ b/doc/user/group/subgroups/img/mention_subgroups.png diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md new file mode 100644 index 00000000000..ce5da07c61a --- /dev/null +++ b/doc/user/group/subgroups/index.md @@ -0,0 +1,164 @@ +# Subgroups + +> [Introduced][ce-2772] in GitLab 9.0. + +With subgroups (aka nested groups or hierarchical groups) you can have +up to 20 levels of nested groups, which among other things can help you to: + +- **Separate internal / external organizations.** Since every group + can have its own visibility level, you are able to host groups for different + purposes under the same umbrella. +- **Organize large projects.** For large projects, subgroups makes it + potentially easier to separate permissions on parts of the source code. +- **Make it easier to manage people and control visibility.** Give people + different [permissions][] depending on their group [membership](#membership). + +## Overview + +A group can have many subgroups inside it, and at the same time a group can have +only 1 parent group. It resembles a directory behavior or a nested items list: + +- Group 1 + - Group 1.1 + - Group 1.2 + - Group 1.2.1 + - Group 1.2.2 + - Group 1.2.2.1 + +In a real world example, imagine maintaining a GNU/Linux distribution with the +first group being the name of the distro and subsequent groups split like: + +- Organization Group - GNU/Linux distro + - Category Subgroup - Packages + - (project) Package01 + - (project) Package02 + - Category Subgroup - Software + - (project) Core + - (project) CLI + - (project) Android app + - (project) iOS app + - Category Subgroup - Infra tools + - (project) Ansible playbooks + +Another example of GitLab as a company would be the following: + +- Organization Group - GitLab + - Category Subroup - Marketing + - (project) Design + - (project) General + - Category Subgroup - Software + - (project) GitLab CE + - (project) GitLab EE + - (project) Omnibus GitLab + - (project) GitLab Runner + - (project) GitLab Pages daemon + - Category Subgroup - Infra tools + - (project) Chef cookbooks + - Category Subgroup - Executive team + +--- + +The maximum nested groups a group can have, including the first one in the +hierarchy, is 21. + +Things like transferring or importing a project inside nested groups, work like +when performing these actions the traditional way with the `group/project` +structure. + +## Creating a subgroup + +>**Notes:** +- You need to be an Owner of a group in order to be able to create + a subgroup. For more information check the [permissions table][permissions]. +- For a list of words that are not allowed to be used as group names see the + [`namespace_validator.rb` file][reserved] under the `RESERVED` and + `WILDCARD_ROUTES` lists. + +To create a subgroup: + +1. In the group's dashboard go to the **Subgroups** page and click **Create subgroup**. + +  + +1. Create a new group like you would normally do. Notice that the parent group + namespace is fixed under **Group path**. The visibility level can differ from + the parent group. + +  + +1. Click the **Create group** button and you will be taken to the new group's + dashboard page. + +--- + +You can follow the same process to create any subsequent groups. + +## Membership + +When you add a member to a subgroup, they inherit the membership and permission +level from the parent group. This model allows access to nested groups if you +have membership in one of its parents. + +The group permissions for a member can be changed only by Owners and only on +the **Members** page of the group the member was added. + +You can tell if a member has inherited the permissions from a parent group by +looking at the group's **Members** page. + + + +From the image above, we can deduct the following things: + +- There are 5 members that have access to the group `four` +- User0 is a Reporter and has inherited their permissions from group `one` + which is above the hierarchy of group `four` +- User1 is a Developer and has inherited their permissions from group + `one/two` which is above the hierarchy of group `four` +- User2 is a Developer and has inherited their permissions from group + `one/two/three` which is above the hierarchy of group `four` +- For User3 there is no indication of a parent group, therefore they belong to + group `four`, the one we're inspecting +- Administrator is the Owner and member of **all** subgroups and for that reason, + same as User3, there is no indication of an ancestor group + +### Overriding the ancestor group membership + +>**Note:** +You need to be an Owner of a group in order to be able to add members to it. + +To override a user's membership of an ancestor group (the first group they were +added to), simply add the user in the new subgroup again, but with different +permissions. + +For example, if User0 was first added to group `group-1/group-1-1` with Developer +permissions, then they will inherit those permissions in every other subgroup +of `group-1/group-1-1`. To give them Master access to `group-1/group-1-1/group1-1-1`, +you would add them again in that group as Master. Removing them from that group, +the permissions will fallback to those of the ancestor group. + +## Mentioning subgroups + +Mentioning groups (`@group`) in issues, commits and merge requests, would +notify all members of that group. Now with subgroups, there is a more granular +support if you want to split your group's structure. Mentioning works as before +and you can choose the group of people to be notified. + + + +## Limitations + +Here's a list of what you can't do with subgroups: + +- [GitLab Pages](../../project/pages/index.md) are not currently working for + projects hosted under a subgroup. That means that only projects hosted under + the first parent group will work. +- Group level labels don't work in subgroups / sub projects +- It is not possible to share a project with a group that's an ancestor of + the group the project is in. That means you can only share as you walk down + the hierarchy. For example, `group/subgroup01/project` **cannot** be shared + with `group`, but can be shared with `group/subgroup02` or + `group/subgroup01/subgroup03`. + +[ce-2772]: https://gitlab.com/gitlab-org/gitlab-ce/issues/2772 +[permissions]: ../../permissions.md#group +[reserved]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/validators/namespace_validator.rb diff --git a/doc/workflow/img/award_emoji_comment_awarded.png b/doc/user/img/award_emoji_comment_awarded.png Binary files differindex 111793ebf8a..111793ebf8a 100644 --- a/doc/workflow/img/award_emoji_comment_awarded.png +++ b/doc/user/img/award_emoji_comment_awarded.png diff --git a/doc/workflow/img/award_emoji_comment_picker.png b/doc/user/img/award_emoji_comment_picker.png Binary files differindex 3ad1bab3119..3ad1bab3119 100644 --- a/doc/workflow/img/award_emoji_comment_picker.png +++ b/doc/user/img/award_emoji_comment_picker.png diff --git a/doc/user/img/award_emoji_select.png b/doc/user/img/award_emoji_select.png Binary files differnew file mode 100644 index 00000000000..496acb29eec --- /dev/null +++ b/doc/user/img/award_emoji_select.png diff --git a/doc/user/img/award_emoji_votes_sort_options.png b/doc/user/img/award_emoji_votes_sort_options.png Binary files differnew file mode 100644 index 00000000000..dd84b7f4f64 --- /dev/null +++ b/doc/user/img/award_emoji_votes_sort_options.png diff --git a/doc/user/markdown.md b/doc/user/markdown.md index db06224bac2..97de428d11d 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -431,7 +431,7 @@ Emphasis, aka italics, with *asterisks* or _underscores_. Strong emphasis, aka bold, with **asterisks** or __underscores__. -Combined emphasis with **asterisks and _underscores_**. +Combined emphasis with **_asterisks and underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` diff --git a/doc/user/permissions.md b/doc/user/permissions.md index b49a244160a..0ea6d01411f 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -81,6 +81,7 @@ group. |-------------------------|-------|----------|-----------|--------|-------| | Browse group | ✓ | ✓ | ✓ | ✓ | ✓ | | Edit group | | | | | ✓ | +| Create subgroup | | | | | ✓ | | Create project in group | | | | ✓ | ✓ | | Manage group members | | | | | ✓ | | Remove group | | | | | ✓ | diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index eaa39a0c4ea..63a3d3c472e 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -215,3 +215,14 @@ you may have cases where authorization always fails because of time differences. [Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en [FreeOTP]: https://freeotp.github.io/ [YubiKey]: https://www.yubico.com/products/yubikey-hardware/ + +- The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from +multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at +the time of registration, and cannot be used for other hostnames/FQDNs. + + For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`: + + - The user logs in via `first.host.xyz` and registers their U2F key. + - The user logs out and attempts to log in via `first.host.xyz` - U2F authentication suceeds. + - The user logs out and attempts to log in via `second.host.xyz` - U2F authentication fails, because + the U2F key has only been registered on `first.host.xyz`. diff --git a/doc/user/project/integrations/img/prometheus_environment_detail_with_metrics.png b/doc/user/project/integrations/img/prometheus_environment_detail_with_metrics.png Binary files differnew file mode 100644 index 00000000000..1f5a44f8820 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_environment_detail_with_metrics.png diff --git a/doc/user/project/integrations/img/prometheus_gcp_firewall_rule.png b/doc/user/project/integrations/img/prometheus_gcp_firewall_rule.png Binary files differnew file mode 100644 index 00000000000..e30cba211e6 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_gcp_firewall_rule.png diff --git a/doc/user/project/integrations/img/prometheus_gcp_node_name.png b/doc/user/project/integrations/img/prometheus_gcp_node_name.png Binary files differnew file mode 100644 index 00000000000..ea289431454 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_gcp_node_name.png diff --git a/doc/user/project/integrations/img/prometheus_service_configuration.png b/doc/user/project/integrations/img/prometheus_service_configuration.png Binary files differnew file mode 100644 index 00000000000..c7dfe874817 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_service_configuration.png diff --git a/doc/user/project/integrations/img/prometheus_yaml_deploy.png b/doc/user/project/integrations/img/prometheus_yaml_deploy.png Binary files differnew file mode 100644 index 00000000000..978cd7eaa50 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_yaml_deploy.png diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index a3a163a4c6b..3cf1cc704a2 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -51,6 +51,7 @@ Click on the service links to see further configuration instructions and details | [Slack Notifications](slack.md) | Receive event notifications in Slack | | [Slack slash commands](slack_slash_commands.md) | Slack chat and ChatOps slash commands | | PivotalTracker | Project Management Software (Source Commits Endpoint) | +| [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | | [Redmine](redmine.md) | Redmine issue tracker | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md new file mode 100644 index 00000000000..676a21e85c4 --- /dev/null +++ b/doc/user/project/integrations/prometheus.md @@ -0,0 +1,196 @@ +# Prometheus integration + +> [Introduced][ce-8935] in GitLab 9.0. + +GitLab offers powerful integration with [Prometheus] for monitoring your apps. +Metrics are retrieved from the configured Prometheus server, and then displayed +within the GitLab interface. + +Each project can be configured with its own specific Prometheus server, see the +[configuration](#configuration) section for more details. If you have a single +Prometheus server which monitors all of your infrastructure, you can pre-fill +the settings page with a default template. To configure the template, see the +[Services templates](services_templates.md) document. + +## Requirements + +Integration with Prometheus requires the following: + +1. GitLab 9.0 or higher +1. Your app must be deployed on [Kubernetes][] +1. Prometheus must be configured to collect Kubernetes metrics +1. Each metric must be have a label to indicate the environment +1. GitLab must have network connectivity to the Prometheus sever + +There are a few steps necessary to set up integration between Prometheus and +GitLab. + +## Configuring Prometheus to collect Kubernetes metrics + +In order for Prometheus to collect Kubernetes metrics, you first must have a +Prometheus server up and running. You have two options here: + +- If you installed Omnibus GitLab inside of Kubernetes, you can simply use the + [bundled version of Prometheus][promgldocs]. In that case, follow the info in the + [Omnibus GitLab section](#configuring-omnibus-gitlab-prometheus-to-monitor-kubernetes) + below. +- If you are using GitLab.com or installed GitLab outside of Kubernetes, you + will likely need to run a Prometheus server within the Kubernetes cluster. + Once installed, the easiest way to monitor Kubernetes is to simply use + Prometheus' support for [Kubernetes Service Discovery][prometheus-k8s-sd]. + In that case, follow the instructions on + [configuring your own Prometheus server within Kubernetes](#configuring-your-own-prometheus-server-within-kubernetes). + +### Configuring Omnibus GitLab Prometheus to monitor Kubernetes + +With Omnibus GitLab running inside of Kubernetes, you can leverage the bundled +version of Prometheus to collect the required metrics. + +1. Read how to configure the bundled Prometheus server in the + [Administration guide][gitlab-prometheus-k8s-monitor]. +1. Now that Prometheus is configured, proceed on + [configuring the Prometheus project service in GitLab](#configuration-in-gitlab). + +### Configuring your own Prometheus server within Kubernetes + +Setting up and configuring Prometheus within Kubernetes is quick and painless. +The Prometheus project provides an [official Docker image][prometheus-docker-image] +which we can use as a starting point. + +To get started quickly, we have provided a [sample YML file][prometheus-yml] +that can be used as a template. This file will create a `prometheus` **Namespace**, +**Service**, **Deployment**, and **ConfigMap** in Kubernetes. You can upload +this file to the Kubernetes dashboard using **+ Create** at the top right. + + + +Or use `kubectl`: + +```bash +kubectl apply -f path/to/prometheus.yml +``` + +Once deployed, you should see the Prometheus service, deployment, and +pod start within the `prometheus` namespace. The server will begin to collect +metrics from each Kubernetes Node in the cluster, based on the configuration +provided in the template. + +Since GitLab is not running within Kubernetes, the template provides external +network access via a `NodePort` running on `30090`. This method allows access +to be controlled using provider firewall rules, like within Google Compute Engine. + +Since a `NodePort` does not automatically have firewall rules created for it, +one will need to be created manually to allow access. In GCP/GKE, you will want +to confirm the Node that the Prometheus pod is running on. This can be done +either by looking at the Pod in the Kubernetes dashboard, or by running: + +```bash +kubectl describe pods -n prometheus +``` + +Next on GKE, we need to get the `tag` of the Node or VM Instance, so we can +create an accurate firewall rule. The easiest way to do this is to go into the +Google Cloud Platform Compute console and select the VM instance that matches +the name of the Node gathered from the step above. In this case, the node tag +needed is `gke-prometheus-demo-5d5ada10-node`. Also make a note of the +**External IP**, which will be the IP address the Prometheus server is reachable +on. + + + +Armed with the proper Node tag, the firewall rule can now be created +specifically for this node. To create the firewall rule, open the Google Cloud +Platform Networking console, and select **Firewall Rules**. + +Create a new rule: + +- Specify the source IP range to match your desired access list, which should + include your GitLab server. A sample of GitLab.com's IP address range is + available [in this issue][gitlab.com-ip-range], but note that GitLab.com's IPs + are subject to change without prior notification. +- Allowed protocol and port should be `tcp:30090`. +- The target tags should match the Node tag identified earlier in this step. + + + +--- + +Now that Prometheus is configured, proceed to +[configure the Prometheus project service in GitLab](##configuration-in-gitlab). + +## Configuration in GitLab + +The actual configuration of Prometheus integration within GitLab is very simple. +All you will need is the DNS or IP address of the Prometheus server you'd like +to integrate with. + +1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) +1. Click the **Prometheus** service +1. Provide the base URL of the your server, for example `http://prometheus.example.com/`. + The **Test Settings** button can be used to confirm connectivity from GitLab + to the Prometheus server. + + + +## Metrics and Labels + +GitLab retrieves performance data from two metrics, `container_cpu_usage_seconds_total` +and `container_memory_usage_bytes`. These metrics are collected from the +Kubernetes pods via Prometheus, and report CPU and Memory utilization of each +container or Pod running in the cluster. + +In order to isolate and only display relevant metrics for a given environment +however, GitLab needs a method to detect which pods are associated. To do that, +GitLab will specifically request metrics that have an `environment` tag that +matches the [$CI_ENVIRONMENT_SLUG][ci-environment-slug]. + +If you are using [GitLab Auto-Deploy][autodeploy] and one of the methods of +configuring Prometheus above, the `environment` will be automatically added. + +### GitLab Prometheus queries + +The queries utilized by GitLab are shown in the following table. + +| Metric | Query | +| ------ | ----- | +| Average Memory (MB) | `(sum(container_memory_usage_bytes{container_name="app",environment="$CI_ENVIRONMENT_SLUG"}) / count(container_memory_usage_bytes{container_name="app",environment="$CI_ENVIRONMENT_SLUG"})) /1024/1024` | +| Average CPU Utilization (%) | `sum(rate(container_cpu_usage_seconds_total{container_name="app",environment="$CI_ENVIRONMENT_SLUG"}[2m])) / count(container_cpu_usage_seconds_total{container_name="app",environment="$CI_ENVIRONMENT_SLUG"}) * 100` | + +## Monitoring CI/CD Environments + +Once configured, GitLab will attempt to retrieve performance metrics for any +environment which has had a successful deployment. If monitoring data was +successfully retrieved, a metrics button will appear on the environment's +detail page. + + + +Clicking on the metrics button will display a new page, showing up to the last +8 hours of performance data. It may take a minute or two for data to appear +after initial deployment. + +## Troubleshooting + +If the metrics button is not appearing, then one of a few issues may be +occurring: + +- GitLab is not able to reach the Prometheus server. A test request can be sent + to the Prometheus server from the [Prometheus Service](#configuration-in-gitlab) + configuration screen. +- No successful deployments have occurred to this environment. +- Prometheus does not have performance data for this environment, or the metrics + are not labeled correctly. To test this, connect to the Prometheus server and + [run a query](#gitlab-prometheus-queries), replacing `$CI_ENVIRONMENT_SLUG` + with the name of your environment. + +[autodeploy]: ../../../ci/autodeploy/index.md +[kubernetes]: https://kubernetes.io +[prometheus-k8s-sd]: https://prometheus.io/docs/operating/configuration/#<kubernetes_sd_config> +[prometheus]: https://prometheus.io +[gitlab-prometheus-k8s-monitor]: ../../../administration/monitoring/prometheus/index.md#configuring-prometheus-to-monitor-kubernetes +[prometheus-docker-image]: https://hub.docker.com/r/prom/prometheus/ +[prometheus-yml]:samples/prometheus.yml +[gitlab.com-ip-range]: https://gitlab.com/gitlab-com/infrastructure/issues/434 +[ci-environment-slug]: https://docs.gitlab.com/ce/ci/variables/#predefined-variables-environment-variables +[ce-8935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935 +[promgldocs]: ../../../administration/monitoring/prometheus/index.md diff --git a/doc/user/project/integrations/samples/prometheus.yml b/doc/user/project/integrations/samples/prometheus.yml new file mode 100644 index 00000000000..01bbcaffe1e --- /dev/null +++ b/doc/user/project/integrations/samples/prometheus.yml @@ -0,0 +1,69 @@ +apiVersion: v1 +kind: Namespace +metadata: + name: prometheus +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: prometheus + namespace: prometheus +data: + prometheus.yml: |- + scrape_configs: + - job_name: 'kubernetes-nodes' + scheme: https + tls_config: + ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt + insecure_skip_verify: true + bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token + kubernetes_sd_configs: + - role: node + metric_relabel_configs: + - source_labels: [pod_name] + target_label: environment + regex: (.+)-.+-.+ + replacement: $1 +--- +apiVersion: v1 +kind: Service +metadata: + name: prometheus + namespace: prometheus +spec: + selector: + app: prometheus + ports: + - name: prometheus + protocol: TCP + port: 9090 + nodePort: 30090 + type: NodePort +--- +apiVersion: extensions/v1beta1 +kind: Deployment +metadata: + name: prometheus + namespace: prometheus +spec: + replicas: 1 + template: + metadata: + labels: + app: prometheus + spec: + containers: + - name: prometheus + image: prom/prometheus:latest + args: + - '-config.file=/prometheus-data/prometheus.yml' + ports: + - name: prometheus + containerPort: 9090 + volumeMounts: + - name: data-volume + mountPath: /prometheus-data + volumes: + - name: data-volume + configMap: + name: prometheus diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index ed1e867f5fb..dbdc93a77a8 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -250,7 +250,19 @@ X-Gitlab-Event: Issue Hook "name": "User1", "username": "user1", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" - } + }, + "labels": [{ + "id": 206, + "title": "API", + "color": "#ffffff", + "project_id": 14, + "created_at": "2013-12-03T17:15:43Z", + "updated_at": "2013-12-03T17:15:43Z", + "template": false, + "description": "API related issues", + "type": "ProjectLabel", + "group_id": 41 + }] } ``` ### Comment events diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 3199d370a58..5aa8337b75d 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -28,7 +28,7 @@ Below is a table of the definitions used for GitLab's Issue Board. | -------------- | ------------- | | **Issue Board** | It represents a different view for your issues. It can have multiple lists with each list consisting of issues represented by cards. | | **List** | Each label that exists in the issue tracker can have its own dedicated list. Every list is named after the label it is based on and is represented by a column which contains all the issues associated with that label. You can think of a list like the results you get when you filter the issues by a label in your issue tracker. | -| **Card** | Every card represents an issue and it is shown under the list for which it has a label. The information you can see on a card consists of the issue number, the issue title, the assignee and the labels associated with it. You can drag cards around from one list to another. Issues inside lists are [ordered by priority](labels.md#prioritize-labels). | +| **Card** | Every card represents an issue and it is shown under the list for which it has a label. The information you can see on a card consists of the issue number, the issue title, the assignee and the labels associated with it. You can drag cards around from one list to another. You can re-order cards within a list. | There are two types of lists, the ones you create based on your labels, and one default: @@ -45,6 +45,7 @@ In short, here's a list of actions you can take in an Issue Board: - [Create a new list](#creating-a-new-list). - [Delete an existing list](#deleting-a-list). - Drag issues between lists. +- Re-order issues in lists. - Drag and reorder the lists themselves. - Change issue labels on-the-fly while dragging issues between lists. - Close an issue if you drag it to the **Done** list. @@ -114,6 +115,13 @@ board itself.  +## Re-ordering an issue in a list + +> Introduced in GitLab 9.0. + +Issues can be re-ordered inside of lists. This is as simple as dragging and dropping +an issue into the order you want. + ## Filtering issues You should be able to use the filters on top of your Issue Board to show only @@ -176,7 +184,6 @@ A few things to remember: - Clicking on the issue title inside a card will take you to that issue. - Clicking on a label inside a card will quickly filter the entire Issue Board and show only the issues from all lists that have that label. -- Issues inside lists are [ordered by priority][label-priority]. - For performance and visibility reasons, each list shows the first 20 issues by default. If you have more than 20 issues start scrolling down and the next 20 will appear. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index cf1d9cbe69c..8ec7adad172 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -65,7 +65,7 @@ issues and merge requests assigned to each label. > https://gitlab.com/gitlab-org/gitlab-ce/issues/18554. Prioritized labels are like any other label, but sorted by priority. This allows -you to sort issues and merge requests by priority. +you to sort issues and merge requests by label priority. To prioritize labels, navigate to your project's **Issues > Labels** and click on the star icon next to them to put them in the priority list. Click on the @@ -77,9 +77,13 @@ having their priority set to null.  -Now that you have labels prioritized, you can use the 'Priority' filter in the -issues or merge requests tracker. Those with the highest priority label, will -appear on top. +Now that you have labels prioritized, you can use the 'Priority' and 'Label +priority' filters in the issues or merge requests tracker. + +The 'Label priority' filter puts issues with the highest priority label on top. + +The 'Priority' filter sorts issues by their soonest milestone due date, then by +label priority.  @@ -156,4 +160,3 @@ mouse over the label in the issue tracker or wherever else the label is rendered.  - diff --git a/doc/user/project/merge_requests/img/btn_new_issue_for_all_discussions.png b/doc/user/project/merge_requests/img/btn_new_issue_for_all_discussions.png Binary files differnew file mode 100644 index 00000000000..b15447ec290 --- /dev/null +++ b/doc/user/project/merge_requests/img/btn_new_issue_for_all_discussions.png diff --git a/doc/user/project/merge_requests/img/new_issue_for_discussion.png b/doc/user/project/merge_requests/img/new_issue_for_discussion.png Binary files differnew file mode 100644 index 00000000000..93c9dad8921 --- /dev/null +++ b/doc/user/project/merge_requests/img/new_issue_for_discussion.png diff --git a/doc/user/project/merge_requests/img/preview_issue_for_discussion.png b/doc/user/project/merge_requests/img/preview_issue_for_discussion.png Binary files differnew file mode 100644 index 00000000000..2ee0653b2ba --- /dev/null +++ b/doc/user/project/merge_requests/img/preview_issue_for_discussion.png diff --git a/doc/user/project/merge_requests/img/preview_issue_for_discussions.png b/doc/user/project/merge_requests/img/preview_issue_for_discussions.png Binary files differindex 9fdd387676c..3fe0a666678 100644 --- a/doc/user/project/merge_requests/img/preview_issue_for_discussions.png +++ b/doc/user/project/merge_requests/img/preview_issue_for_discussions.png diff --git a/doc/user/project/merge_requests/img/resolve_discussion_issue_notice.png b/doc/user/project/merge_requests/img/resolve_discussion_issue_notice.png Binary files differindex 8c7ce215ae0..e0ee6a39ffd 100644 --- a/doc/user/project/merge_requests/img/resolve_discussion_issue_notice.png +++ b/doc/user/project/merge_requests/img/resolve_discussion_issue_notice.png diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md index d4b85676d19..230e957f045 100644 --- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md +++ b/doc/user/project/merge_requests/merge_request_discussion_resolution.md @@ -53,12 +53,18 @@ are resolved. ## Move all unresolved discussions in a merge request to an issue -> [Introduced][ce-7180] in GitLab 8.15. +> [Introduced][ce-8266] -To delegate unresolved discussions to a new issue you can click the link **open -an issue to resolve them later**. +To continue all open discussions in a merge request, click the button **Resolve +all discussions in new issue** - + + +Alternatively, when your project only accepts merge requests when all discussions +are resolved, there will be an **open an issue to resolve them later** link in +the merge request-widget. + + This will prepare an issue with content referring to the merge request and discussions. @@ -72,9 +78,28 @@ add a note referring to the newly created issue. You can now proceed to merge the merge request from the UI. +## Moving a single discussion to a new issue + +> [Introduced][ce-8266] + +To create a new issue for a single discussion, you can use the **Resolve this +discussion in a new issue** button. + + + +This will direct you to a new issue prefilled with the content of the +discussion, similar to the issues created for delegating multiple +discussions at once. + + + +Saving the issue will mark the discussion as resolved and add a note +to the discussion referencing the new issue. + [ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022 [ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125 [ce-7180]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7180 +[ce-8266]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8266 [resolve-discussion-button]: img/resolve_discussion_button.png [resolve-comment-button]: img/resolve_comment_button.png [discussion-view]: img/discussion_view.png diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 5f631f63050..b559d132590 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -119,7 +119,7 @@ And then the users could also use it in their CI jobs all Docker related commands to interact with GitLab Container Registry. For example: ``` -docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN registry.gitlab.com +docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.gitlab.com ``` Using single token had multiple security implications: @@ -208,7 +208,7 @@ This is how an example usage can look like: ``` test: script: - - docker login -u gitlab-ci-token -p $CI_BUILD_TOKEN $CI_REGISTRY + - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY - docker pull $CI_REGISTRY/group/other-project:latest - docker run $CI_REGISTRY/group/other-project:latest ``` diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index c415d566a7c..d47a3acdbe9 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -109,12 +109,19 @@ the title of the issue and as suffix it will have its ID. Thus, the example screenshot above will yield a branch named `2-et-cum-et-sed-expedita-repellat-consequatur-ut-assumenda-numquam-rerum`. +Since GitLab 9.0, when you click the `New branch` in an empty repository project, GitLab automatically creates the master branch, commits a blank `README.md` file to it and creates and redirects you to a new branch based on the issue title. +If your [project is already configured with a deployment service][project-services-doc] (e.g. Kubernetes), GitLab takes one step further and prompts you to set up [auto deploy][auto-deploy-doc] by helping you create a `.gitlab-ci.yml` file. + + After the branch is created, you can edit files in the repository to fix the issue. When a merge request is created based on the newly created branch, the description field will automatically display the [issue closing pattern] `Closes #ID`, where `ID` the ID of the issue. This will close the issue once the merge request is merged. +[project-services-doc]: ../integrations/project_services.md +[auto-deploy-doc]: ../../../ci/autodeploy/index.md + ### Create a new branch from a project's dashboard If you want to make changes to several files before creating a new merge diff --git a/doc/workflow/README.md b/doc/workflow/README.md index 9e7ee47387c..6a8de51a199 100644 --- a/doc/workflow/README.md +++ b/doc/workflow/README.md @@ -40,3 +40,4 @@ - [Importing from SVN, GitHub, Bitbucket, etc](importing/README.md) - [Todos](todos.md) - [Snippets](../user/snippets.md) +- [Subgroups](../user/group/subgroups/index.md) diff --git a/doc/workflow/award_emoji.md b/doc/workflow/award_emoji.md index 1df0698afd0..d74378cc564 100644 --- a/doc/workflow/award_emoji.md +++ b/doc/workflow/award_emoji.md @@ -1,65 +1 @@ -# Award emoji - ->**Note:** -[Introduced][1825] in GitLab 8.2. - -When you're collaborating online, you get fewer opportunities for high-fives -and thumbs-ups. Emoji can be awarded to issues and merge requests, making -virtual celebrations easier. - - - -Award emoji make it much easier to give and receive feedback without a long -comment thread. Comments that are only emoji will automatically become -award emoji. - -## Sort issues and merge requests on vote count - ->**Note:** -[Introduced][2871] in GitLab 8.5. - -You can quickly sort issues and merge requests by the number of votes they -have received. The sort options can be found in the dropdown menu as "Most -popular" and "Least popular". - - - ---- - -Sort by most popular issues/merge requests. - - - ---- - -Sort by least popular issues/merge requests. - - - ---- - -The total number of votes is not summed up. An issue with 18 upvotes and 5 -downvotes is considered more popular than an issue with 17 upvotes and no -downvotes. - -## Award emoji for comments - ->**Note:** -[Introduced][4291] in GitLab 8.9. - -Award emoji can also be applied to individual comments when you want to -celebrate an accomplishment or agree with an opinion. - -To add an award emoji, click the smile in the top right of the comment and pick -an emoji from the dropdown. - - - - - -If you want to remove an award emoji, just click the emoji again and the vote -will be removed. - -[2871]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781 -[1825]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825 -[4291]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4291 +This document was moved to [another location](../user/award_emojis.md). diff --git a/doc/workflow/img/award_emoji_select.png b/doc/workflow/img/award_emoji_select.png Binary files differdeleted file mode 100644 index e1b37beaf62..00000000000 --- a/doc/workflow/img/award_emoji_select.png +++ /dev/null diff --git a/doc/workflow/img/award_emoji_votes_least_popular.png b/doc/workflow/img/award_emoji_votes_least_popular.png Binary files differdeleted file mode 100644 index 86ede4b0c10..00000000000 --- a/doc/workflow/img/award_emoji_votes_least_popular.png +++ /dev/null diff --git a/doc/workflow/img/award_emoji_votes_most_popular.png b/doc/workflow/img/award_emoji_votes_most_popular.png Binary files differdeleted file mode 100644 index 1d3e2e57aa0..00000000000 --- a/doc/workflow/img/award_emoji_votes_most_popular.png +++ /dev/null diff --git a/doc/workflow/img/award_emoji_votes_sort_options.png b/doc/workflow/img/award_emoji_votes_sort_options.png Binary files differdeleted file mode 100644 index c6dc1b939c1..00000000000 --- a/doc/workflow/img/award_emoji_votes_sort_options.png +++ /dev/null diff --git a/doc/workflow/milestones.md b/doc/workflow/milestones.md index dff36899aec..37afe553e55 100644 --- a/doc/workflow/milestones.md +++ b/doc/workflow/milestones.md @@ -1,13 +1,28 @@ # Milestones -Milestones allow you to organize issues and merge requests into a cohesive group, optionally setting a due date. +Milestones allow you to organize issues and merge requests into a cohesive group, optionally setting a due date. A common use is keeping track of an upcoming software version. Milestones are created per-project.  ## Groups and milestones -You can create a milestone for several projects in the same group simultaneously. +You can create a milestone for several projects in the same group simultaneously. On the group's milestones page, you will be able to see the status of that milestone across all of the selected projects.  + +## Special milestone filters + +In addition to the milestones that exist in the project or group, there are some +special options available when filtering by milestone: + +* **No Milestone** - only show issues or merge requests without a milestone. +* **Upcoming** - show issues or merge request that belong to the next open + milestone with a due date, by project. (For example: if project A has + milestone v1 due in three days, and project B has milestone v2 due in a week, + then this will show issues or merge requests from milestone v1 in project A + and milestone v2 in project B.) +* **Started** - show issues or merge requests from any milestone with a start + date less than today. Note that this can return results from several + milestones in the same project. |
