diff options
Diffstat (limited to 'doc')
59 files changed, 850 insertions, 318 deletions
diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 3a394c561db..b2445d1c0e5 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,24 @@ 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, Prometheus will collect metrics from the Nodes in the cluster including performance data on each container. This is particularly helpful if your CI/CD environments run in the same cluster, as you can use the [Prometheus project integration][] to monitor them. + +To disable the monitoring of Kubernetes: + +1. Edit `/etc/gitlab/gitlab.rb` +1. Add or find and uncomment the following line and set it to `false`: + + ```ruby + prometheus['monitor_kubernetes'] = false + ``` + +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 +157,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 +[prometheus-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/branches.md b/doc/api/branches.md index 83705106160..815aabda8e3 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -3,6 +3,8 @@ ## List repository branches Get a list of repository branches from a project, sorted by name alphabetically. +This endpoint can be accessed without authentication if the repository is +publicly accessible. ``` GET /projects/:id/repository/branches @@ -48,7 +50,8 @@ Example response: ## Get single repository branch -Get a single project repository branch. +Get a single project repository branch. This endpoint can be accessed without +authentication if the repository is publicly accessible. ``` GET /projects/:id/repository/branches/:branch diff --git a/doc/api/issues.md b/doc/api/issues.md index cb437ffb174..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` | diff --git a/doc/api/services.md b/doc/api/services.md index 8e7afe41b0c..7d4779f1137 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -139,43 +139,6 @@ Get Buildkite service settings for a project. GET /projects/:id/services/buildkite ``` -## Build-Emails - -Get emails for GitLab CI builds. - -### Create/Edit Build-Emails service - -Set Build-Emails service for a project. - -``` -PUT /projects/:id/services/jobs-email -``` - -Parameters: - -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `recipients` | string | yes | Comma-separated list of recipient email addresses | -| `add_pusher` | boolean | no | Add pusher to recipients list | -| `notify_only_broken_jobs` | boolean | no | Notify only broken jobs | - - -### Delete Job-Emails service - -Delete Build-Emails service for a project. - -``` -DELETE /projects/:id/services/jobs-email -``` - -### Get Job-Emails service settings - -Get Build-Emails service settings for a project. - -``` -GET /projects/:id/services/jobs-email -``` - ## Campfire Simple web-based real-time group chat @@ -580,8 +543,7 @@ Parameters: | --------- | ---- | -------- | ----------- | | `recipients` | string | yes | Comma-separated list of recipient email addresses | | `add_pusher` | boolean | no | Add pusher to recipients list | -| `notify_only_broken_jobs` | boolean | no | Notify only broken pipelines | - +| `notify_only_broken_pipelines` | boolean | no | Notify only broken pipelines | ### Delete Pipeline-Emails service diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 0794156bc39..7f4426ee85d 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -8,16 +8,16 @@ Below are the changes made between V3 and V4. ### 8.17 -- Removed `/projects/:search` (use: `/projects?search=x`) [!8877](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8877) -- `iid` filter has been removed from `projects/:id/issues` [!8967](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8967) -- `projects/:id/merge_requests?iid[]=x&iid[]=y` array filter has been renamed to `iids` [!8793](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8793) -- Endpoints under `projects/merge_request/:id` have been removed (use: `projects/merge_requests/:id`) [!8793](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8793) +- Removed `GET /projects/:search` (use: `GET /projects?search=x`) [!8877](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8877) +- `iid` filter has been removed from `GET /projects/:id/issues` [!8967](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8967) +- `GET /projects/:id/merge_requests?iid[]=x&iid[]=y` array filter has been renamed to `iids` [!8793](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8793) +- Endpoints under `GET /projects/merge_request/:id` have been removed (use: `GET /projects/merge_requests/:id`) [!8793](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8793) - Project snippets do not return deprecated field `expires_at` [!8723](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8723) -- Endpoints under `projects/:id/keys` have been removed (use `projects/:id/deploy_keys`) [!8716](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8716) +- Endpoints under `GET /projects/:id/keys` have been removed (use `GET /projects/:id/deploy_keys`) [!8716](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8716) ### 9.0 -- Status 409 returned for POST `project/:id/members` when a member already exists [!9093](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9093) +- Status 409 returned for `POST /projects/:id/members` when a member already exists [!9093](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9093) - Moved `DELETE /projects/:id/star` to `POST /projects/:id/unstar` [!9328](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9328) - Removed the following deprecated Templates endpoints (these are still accessible with `/templates` prefix) [!8853](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8853) - `/licences` @@ -28,31 +28,31 @@ Below are the changes made between V3 and V4. - `/gitignores/:key` - `/gitlab_ci_ymls/:key` - `/dockerfiles/:key` -- Moved `/projects/fork/:id` to `/projects/:id/fork` [!8940](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8940) +- Moved `POST /projects/fork/:id` to `POST /projects/:id/fork` [!8940](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8940) - Moved `DELETE /todos` to `POST /todos/mark_as_done` and `DELETE /todos/:todo_id` to `POST /todos/:todo_id/mark_as_done` [!9410](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9410) - Project filters are no longer available as `GET /projects/foo`, but as `GET /projects?foo=true` instead [!8962](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8962) - `GET /projects/visible` & `GET /projects/all` are consolidated into `GET /projects` and can be used with or without authorization - `GET /projects/owned` moved to `GET /projects?owned=true` - `GET /projects/starred` moved to `GET /projects?starred=true` - `GET /projects` returns all projects visible to current user, even if the user is not a member [!9674](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9674) - - To get projects the user is a member of, use `/projects?membership=true` + - To get projects the user is a member of, use `GET /projects?membership=true` - Return pagination headers for all endpoints that return an array [!8606](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8606) - Added `POST /environments/:environment_id/stop` to stop an environment [!8808](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8808) -- Removed `DELETE projects/:id/deploy_keys/:key_id/disable`. Use `DELETE projects/:id/deploy_keys/:key_id` instead [!9366](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9366) +- Removed `DELETE /projects/:id/deploy_keys/:key_id/disable`. Use `DELETE /projects/:id/deploy_keys/:key_id` instead [!9366](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9366) - Moved `PUT /users/:id/(block|unblock)` to `POST /users/:id/(block|unblock)` [!9371](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9371) -- Make subscription API more RESTful. Use `post ":project_id/:subscribable_type/:subscribable_id/subscribe"` to subscribe and `post ":project_id/:subscribable_type/:subscribable_id/unsubscribe"` to unsubscribe from a resource. [!9325](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9325) -- Labels filter on `projects/:id/issues` and `/issues` now matches only issues containing all labels (i.e.: Logical AND, not OR) [!8849](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8849) +- Make subscription API more RESTful. Use `POST /projects/:id/:subscribable_type/:subscribable_id/subscribe` to subscribe and `POST /projects/:id/:subscribable_type/:subscribable_id/unsubscribe` to unsubscribe from a resource. [!9325](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9325) +- Labels filter on `GET /projects/:id/issues` and `GET /issues` now matches only issues containing all labels (i.e.: Logical AND, not OR) [!8849](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8849) - Renamed param `branch_name` to `branch` on the following endpoints [!8936](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8936) - - POST `:id/repository/branches` - - POST `:id/repository/commits` - - POST/PUT/DELETE `:id/repository/files` -- Renamed `merge when build succeeds` to merge `when pipeline succeeds parameters` on the following endpoints: [!9335](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/) - - PUT `projects/:id/merge_requests/:merge_request_id/merge` - - POST `projects/:id/merge_requests/:merge_request_id/cancel_merge_when_pipeline_succeeds` - - POST `projects` - - POST `projects/user/:user_id` - - PUT `projects/:id` -- Renamed `branch_name` to `branch` on DELETE `id/repository/branches/:branch` response [!8936](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8936) + - `POST /projects/:id/repository/branches` + - `POST /projects/:id/repository/commits` + - `POST/PUT/DELETE :id/repository/files` +- Renamed the `merge_when_build_succeeds` parameter to `merge_when_pipeline_succeeds` on the following endpoints: [!9335](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/) + - `PUT /projects/:id/merge_requests/:merge_request_id/merge` + - `POST /projects/:id/merge_requests/:merge_request_id/cancel_merge_when_pipeline_succeeds` + - `POST /projects` + - `POST /projects/user/:user_id` + - `PUT /projects/:id` +- Renamed `branch_name` to `branch` on `DELETE /projects/:id/repository/branches/:branch` response [!8936](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8936) - Remove `public` param from create and edit actions of projects [!8736](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8736) - Remove `subscribed` field from responses returning list of issues or merge requests. Fetch individual issues or merge requests to obtain the value @@ -62,21 +62,21 @@ Below are the changes made between V3 and V4. - Notes do not return deprecated field `upvote` and `downvote` [!9384](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9384) - Return HTTP status code `400` for all validation errors when creating or updating a member instead of sometimes `422` error. [!9523](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9523) - Remove `GET /groups/owned`. Use `GET /groups?owned=true` instead [!9505](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9505) -- Return 202 with JSON body on async removals on V4 API (DELETE `/projects/:id/repository/merged_branches` and DELETE `/projects/:id`) [!9449](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9449) -- `projects/:id/milestones?iid[]=x&iid[]=y` array filter has been renamed to `iids` [!9096](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9096) +- Return 202 with JSON body on async removals on V4 API (`DELETE /projects/:id/repository/merged_branches` and `DELETE /projects/:id`) [!9449](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9449) +- `GET /projects/:id/milestones?iid[]=x&iid[]=y` array filter has been renamed to `iids` [!9096](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9096) - Return basic info about pipeline in `GET /projects/:id/pipelines` [!8875](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8875) - Renamed all `build` references to `job` [!9463](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9463) -- Drop GET '/projects/:id/repository/commits/:sha/jobs' [!9463](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9463) +- Drop `GET /projects/:id/repository/commits/:sha/jobs` [!9463](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9463) - Rename Build Triggers to be Pipeline Triggers API [!9713](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9713) - `POST /projects/:id/trigger/builds` to `POST /projects/:id/trigger/pipeline` - Require description when creating a new trigger `POST /projects/:id/triggers` - Simplify project payload exposed on Environment endpoints [!9675](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9675) - API uses merge request `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the merge requests, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530) - API uses issue `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the issues, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530) -- Change initial page from `0` to `1` on `GET projects/:id/repository/commits` (like on the rest of the API) [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) -- Return correct `Link` header data for `GET projects/:id/repository/commits` [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) +- Change initial page from `0` to `1` on `GET /projects/:id/repository/commits` (like on the rest of the API) [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) +- Return correct `Link` header data for `GET /projects/:id/repository/commits` [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679) - Update endpoints for repository files [!9637](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9637) - - Moved `/projects/:id/repository/files?file_path=:file_path` to `/projects/:id/repository/files/:file_path` (`:file_path` should be URL-encoded) - - `/projects/:id/repository/blobs/:sha` now returns JSON attributes for the blob identified by `:sha`, instead of finding the commit identified by `:sha` and returning the raw content of the blob in that commit identified by the required `?filepath=:filepath` - - Moved `/projects/:id/repository/commits/:sha/blob?file_path=:file_path` and `/projects/:id/repository/blobs/:sha?file_path=:file_path` to `/projects/:id/repository/files/:file_path/raw?ref=:sha` - - `/projects/:id/repository/tree` parameter `ref_name` has been renamed to `ref` for consistency + - Moved `GET /projects/:id/repository/files?file_path=:file_path` to `GET /projects/:id/repository/files/:file_path` (`:file_path` should be URL-encoded) + - `GET /projects/:id/repository/blobs/:sha` now returns JSON attributes for the blob identified by `:sha`, instead of finding the commit identified by `:sha` and returning the raw content of the blob in that commit identified by the required `?filepath=:filepath` + - Moved `GET /projects/:id/repository/commits/:sha/blob?file_path=:file_path` and `GET /projects/:id/repository/blobs/:sha?file_path=:file_path` to `GET /projects/:id/repository/files/:file_path/raw?ref=:sha` + - `GET /projects/:id/repository/tree` parameter `ref_name` has been renamed to `ref` for consistency 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/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/quick_start/README.md b/doc/ci/quick_start/README.md index 76e86f3e3c3..30f209f80eb 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -207,15 +207,6 @@ you expected. You are also able to view the status of any commit in the various pages in GitLab, such as **Commits** and **Merge requests**. -## Enabling build emails - -If you want to receive e-mail notifications about the result status of the -jobs, you should explicitly enable the **Builds Emails** service under your -project's settings. - -For more information read the -[Builds emails service documentation](../../user/project/integrations/builds_emails.md). - ## Examples Visit the [examples README][examples] to see a list of examples using GitLab 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 d00faaadc8b..befaa06e918 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -38,6 +38,15 @@ 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 ff9a4fc4fec..ce39a379a0e 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -51,14 +51,34 @@ 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? diff --git a/doc/development/frontend.md b/doc/development/frontend.md index e7add17fe2d..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 diff --git a/doc/development/polling.md b/doc/development/polling.md index a086aca6697..a7f2962acf0 100644 --- a/doc/development/polling.md +++ b/doc/development/polling.md @@ -27,13 +27,13 @@ Instead you should use polling mechanism with ETag caching 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-Modified` header with every subsequent request for the same + the `If-None-Match` header with every subsequent request for the same resource. -1. If the `If-None-Modified` header matches the current value in Redis we know +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-Modified` header does not match the current value in Redis +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: 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/project_services/builds_emails.md b/doc/project_services/builds_emails.md deleted file mode 100644 index ee54d865225..00000000000 --- a/doc/project_services/builds_emails.md +++ /dev/null @@ -1 +0,0 @@ -This document was moved to [user/project/integrations/builds_emails.md](../user/project/integrations/builds_emails.md). diff --git a/doc/ssh/README.md b/doc/ssh/README.md index 678f5199b02..cf28f1a2eca 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -170,12 +170,12 @@ Integration (CI) server. By using deploy keys, you don't have to setup a dummy user account. If you are a project master or owner, you can add a deploy key in the -project settings under the section 'Deploy Keys'. Press the 'New Deploy -Key' button and upload a public SSH key. After this, the machine that uses +project settings under the section 'Repository'. Specify a title for the new +deploy key and paste a public SSH key. After this, the machine that uses the corresponding private SSH key has read-only or read-write (if enabled) access to the project. -You can't add the same deploy key twice with the 'New Deploy Key' option. +You can't add the same deploy key twice using the form. If you want to add the same key to another project, please enable it in the list that says 'Deploy keys from projects available to you'. All the deploy keys of all the projects you have access to are available. This project diff --git a/doc/update/8.12-to-8.13.md b/doc/update/8.12-to-8.13.md index 75956aeb360..ed0e668d854 100644 --- a/doc/update/8.12-to-8.13.md +++ b/doc/update/8.12-to-8.13.md @@ -72,7 +72,7 @@ sudo -u git -H git checkout 8-13-stable-ee ```bash cd /home/git/gitlab-shell sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v3.6.6 +sudo -u git -H git checkout v3.6.7 ``` ### 6. Update gitlab-workhorse diff --git a/doc/update/8.17-to-9.0.md b/doc/update/8.17-to-9.0.md index 626507c0482..b7ba970031c 100644 --- a/doc/update/8.17-to-9.0.md +++ b/doc/update/8.17-to-9.0.md @@ -115,11 +115,11 @@ sudo -u git -H bundle clean # Run database migrations sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -# Install/update frontend asset dependencies -sudo -u git -H npm install --production +# Update node dependencies and recompile assets +sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production -# Clean up assets and cache -sudo -u git -H bundle exec rake gitlab:assets:clean gitlab:assets:compile cache:clear RAILS_ENV=production +# Clean up cache +sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production ``` **MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). 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/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/builds_emails.md b/doc/user/project/integrations/builds_emails.md deleted file mode 100644 index f769dece242..00000000000 --- a/doc/user/project/integrations/builds_emails.md +++ /dev/null @@ -1,15 +0,0 @@ -# Enabling build emails - -By enabling this service, you will be able to receive e-mail notifications about -the result status of your builds. - -Navigate to the [Integrations page](project_services.md#accessing-the-project-services) -and select the **Builds emails** service to configure it. - -In the _Recipients_ area, provide a list of e-mails separated by comma. - -Check the _Add pusher_ checkbox if you want the committer to also receive -e-mail notifications about each build's status. - -If you enable the _Notify only broken builds_ option, e-mail notifications will -be sent only for failed builds. 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/mattermost.md b/doc/user/project/integrations/mattermost.md index cfb0931273d..3e77823a6aa 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -28,7 +28,6 @@ There, you will see a checkbox with the following events that can be triggered: - Merge request - Note - Tag push -- Build - Pipeline - Wiki page @@ -41,7 +40,6 @@ At the end, fill in your Mattermost details: | ----- | ----------- | | **Webhook** | The incoming webhook URL which you have to setup on Mattermost, it will be something like: http://mattermost.example/hooks/5xo… | | **Username** | Optional username which can be on messages sent to Mattermost. Fill this in if you want to change the username of the bot. | -| **Notify only broken builds** | If you choose to enable the **Build** event and you want to be only notified about failed builds. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. |  diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index a3a163a4c6b..25400633de5 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -32,7 +32,6 @@ Click on the service links to see further configuration instructions and details | Assembla | Project Management Software (Source Commits Endpoint) | | [Atlassian Bamboo CI](bamboo.md) | A continuous integration and build server | | Buildkite | Continuous integration and deployments | -| [Builds emails](builds_emails.md) | Email the builds status to a list of recipients | | [Bugzilla](bugzilla.md) | Bugzilla issue tracker | | Campfire | Simple web-based real-time group chat | | Custom Issue Tracker | Custom issue tracker | @@ -48,9 +47,11 @@ Click on the service links to see further configuration instructions and details | [Kubernetes](kubernetes.md) | A containerized deployment service | | [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | | [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | +| Pipelines emails | Email the pipeline status to a list of recipients | | [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/slack.md b/doc/user/project/integrations/slack.md index f27f9a726fc..e8b238351ca 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -25,7 +25,6 @@ There, you will see a checkbox with the following events that can be triggered: - Merge request - Note - Tag push -- Build - Pipeline - Wiki page @@ -38,7 +37,6 @@ At the end, fill in your Slack details: | ----- | ----------- | | **Webhook** | The [incoming webhook URL][slackhook] which you have to setup on Slack. | | **Username** | Optional username which can be on messages sent to Slack. Fill this in if you want to change the username of the bot. | -| **Notify only broken builds** | If you choose to enable the **Build** event and you want to be only notified about failed builds. | | **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | After you are all done, click **Save changes** for the changes to take effect. 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/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/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index be042ddf623..7a4f9f408f1 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -34,7 +34,7 @@ with all their related data and be moved into a new GitLab instance. | 8.10.0 | 0.1.2 | | 8.9.5 | 0.1.1 | | 8.9.0 | 0.1.0 | - + > The table reflects what GitLab version we updated the Import/Export version at. > For instance, 8.10.3 and 8.11 will have the same Import/Export version (0.1.3) > and the exports between them will be compatible. 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. |
