diff options
Diffstat (limited to 'doc')
47 files changed, 1579 insertions, 575 deletions
diff --git a/doc/README.md b/doc/README.md index 03371226041..20fcd2e1724 100644 --- a/doc/README.md +++ b/doc/README.md @@ -165,6 +165,7 @@ configuration. Then customize everything from buildpacks to CI/CD. - [Deployment of Helm, Ingress, and Prometheus on Kubernetes](user/project/clusters/index.md#installing-applications) - [Protected variables](ci/variables/README.md#protected-variables) - [Easy creation of Kubernetes clusters on GKE](user/project/clusters/index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) +- [Executable Runbooks](user/project/clusters/runbooks/index.md) ### Monitor diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md index 96803746637..481eb692674 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -61,7 +61,7 @@ on an Linux NFS server, do the following: 2. Restart the NFS server process. For example, on CentOS run `service nfs restart`. -## AWS Elastic File System +## Avoid using AWS's Elastic File System (EFS) GitLab strongly recommends against using AWS Elastic File System (EFS). Our support team will not be able to assist on performance issues related to @@ -78,6 +78,23 @@ stored on a local volume. For more details on another person's experience with EFS, see [Amazon's Elastic File System: Burst Credits](https://rawkode.com/2017/04/16/amazons-elastic-file-system-burst-credits/) +## Avoid using PostgreSQL with NFS + +GitLab strongly recommends against running your PostgreSQL database +across NFS. The GitLab support team will not be able to assist on performance issues related to +this configuration. + +Additionally, this configuration is specifically warned against in the +[Postgres Documentation](https://www.postgresql.org/docs/current/static/creating-cluster.html#CREATING-CLUSTER-NFS): + +>PostgreSQL does nothing special for NFS file systems, meaning it assumes NFS behaves exactly like +>locally-connected drives. If the client or server NFS implementation does not provide standard file +>system semantics, this can cause reliability problems. Specifically, delayed (asynchronous) writes +>to the NFS server can cause data corruption problems. + +For supported database architecture, please see our documentation on +[Configuring a Database for GitLab HA](https://docs.gitlab.com/ee/administration/high_availability/database.html). + ## NFS Client mount options Below is an example of an NFS mount point defined in `/etc/fstab` we use on diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index b5d1ff698c6..dcee57def74 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -15,7 +15,7 @@ Omnibus GitLab packages. > **Notes:** > - Redis requires authentication for High Availability. See -> [Redis Security](http://redis.io/topics/security) documentation for more +> [Redis Security](https://redis.io/topics/security) documentation for more > information. We recommend using a combination of a Redis password and tight > firewall rules to secure your Redis service. > - You are highly encouraged to read the [Redis Sentinel][sentinel] documentation @@ -82,7 +82,7 @@ When a **Master** fails to respond, it's the application's responsibility for a new **Master**). To get a better understanding on how to correctly set up Sentinel, please read -the [Redis Sentinel documentation](http://redis.io/topics/sentinel) first, as +the [Redis Sentinel documentation](https://redis.io/topics/sentinel) first, as failing to configure it correctly can lead to data loss or can bring your whole cluster down, invalidating the failover effort. @@ -885,8 +885,8 @@ Read more on High Availability: [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure [gh-531]: https://github.com/redis/redis-rb/issues/531 [gh-534]: https://github.com/redis/redis-rb/issues/534 -[redis]: http://redis.io/ -[sentinel]: http://redis.io/topics/sentinel +[redis]: https://redis.io/ +[sentinel]: https://redis.io/topics/sentinel [omnifile]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb [source]: ../../install/installation.md [ce]: https://about.gitlab.com/downloads diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md index 5823c575251..2101d36d2b6 100644 --- a/doc/administration/high_availability/redis_source.md +++ b/doc/administration/high_availability/redis_source.md @@ -107,7 +107,7 @@ starting with `sentinel` prefix. Assuming that the Redis Sentinel is installed on the same instance as Redis master with IP `10.0.0.1` (some settings might overlap with the master): -1. [Install Redis Sentinel](http://redis.io/topics/sentinel) +1. [Install Redis Sentinel](https://redis.io/topics/sentinel) 1. Edit `/etc/redis/sentinel.conf`: ```conf @@ -363,7 +363,7 @@ production: port: 26379 # point to sentinel, not to redis port ``` -When in doubt, please read [Redis Sentinel documentation](http://redis.io/topics/sentinel). +When in doubt, please read [Redis Sentinel documentation](https://redis.io/topics/sentinel). [gh-531]: https://github.com/redis/redis-rb/issues/531 [downloads]: https://about.gitlab.com/downloads diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 0e41a38b7e2..038e043281c 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -84,7 +84,7 @@ Introduced in GitLab 10.0, this file lives in It helps you see requests made directly to the API. For example: ```json -{"time":"2017-10-10T12:30:11.579Z","severity":"INFO","duration":16.84,"db":1.57,"view":15.27,"status":200,"method":"POST","path":"/api/v4/internal/allowed","params":{"action":"git-upload-pack","changes":"_any","gl_repository":null,"project":"root/foobar.git","protocol":"ssh","env":"{}","key_id":"[FILTERED]","secret_token":"[FILTERED]"},"host":"127.0.0.1","ip":"127.0.0.1","ua":"Ruby"} +{"time":"2018-10-29T12:49:42.123Z","severity":"INFO","duration":709.08,"db":14.59,"view":694.49,"status":200,"method":"GET","path":"/api/v4/projects","params":[{"key":"action","value":"git-upload-pack"},{"key":"changes","value":"_any"},{"key":"key_id","value":"secret"},{"key":"secret_token","value":"[FILTERED]"}],"host":"localhost","ip":"::1","ua":"Ruby","route":"/api/:version/projects","user_id":1,"username":"root","queue_duration":100.31,"gitaly_calls":30} ``` This entry above shows an access to an internal endpoint to check whether an diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 2952a98626a..d8345f2d6bd 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -242,6 +242,33 @@ verification requirement. Navigate to `Admin area ➔ Settings` and uncheck **Require users to prove ownership of custom domains** in the Pages section. This setting is enabled by default. +### Access control + +Access control was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) +in GitLab 11.5. It can be configured per-project, and allows access to a Pages +site to be controlled based on a user's membership to that project. + +Access control works by registering the Pages daemon as an OAuth application +with GitLab. Whenever a request to access a private Pages site is made by an +unauthenticated user, the Pages daemon redirects the user to GitLab. If +authentication is successful, the user is redirected back to Pages with a token, +which is persisted in a cookie. The cookies are signed with a secret key, so +tampering can be detected. + +Each request to view a resource in a private site is authenticated by Pages +using that token. For each request it receives, it makes a request to the GitLab +API to check that the user is authorized to read that site. + +Pages access control is currently disabled by default. To enable it, you must: + +1. Enable it in `/etc/gitlab/gitlab.rb` + + ```ruby + gitlab_pages['access_control'] = true + ``` + +1. [Reconfigure GitLab][reconfigure] + ## Activate verbose logging for daemon Verbose logging was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/2533) in diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 295905a7625..ddff54be575 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -391,6 +391,44 @@ the first one with a backslash (\). For example `pages.example.io` would be: server_name ~^.*\.pages\.example\.io$; ``` +## Access control + +Access control was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) +in GitLab 11.5. It can be configured per-project, and allows access to a Pages +site to be controlled based on a user's membership to that project. + +Access control works by registering the Pages daemon as an OAuth application +with GitLab. Whenever a request to access a private Pages site is made by an +unauthenticated user, the Pages daemon redirects the user to GitLab. If +authentication is successful, the user is redirected back to Pages with a token, +which is persisted in a cookie. The cookies are signed with a secret key, so +tampering can be detected. + +Each request to view a resource in a private site is authenticated by Pages +using that token. For each request it receives, it makes a request to the GitLab +API to check that the user is authorized to read that site. + +Pages access control is currently disabled by default. To enable it, you must: + +1. Modify your `config/gitlab.yml` file: + ```yaml + pages: + access_control: true + ``` +1. [Restart GitLab][restart] +1. Create a new [system OAuth application](../../integration/oauth_provider.md#adding-an-application-through-the-profile) + This should be called `GitLab Pages` and have a `Redirect URL` of + `https://projects.example.io/auth`. It does not need to be a "trusted" + application, but it does need the "api" scope. +1. Start the Pages daemon with the following additional arguments: + + ```shell + -auth-client-secret <OAuth code generated by GitLab> \ + -auth-redirect-uri http://projects.example.io/auth \ + -auth-secret <40 random hex characters> \ + -auth-server <URL of the GitLab instance> + ``` + ## Change storage path Follow the steps below to change the default path where GitLab Pages' contents diff --git a/doc/api/issues.md b/doc/api/issues.md index cc1d6834a20..0dc9d706120 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -37,11 +37,11 @@ GET /issues?my_reaction_emoji=star | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. `No+Label` lists all issues with no labels | -| `milestone` | string | no | The milestone title. `No+Milestone` lists all issues with no milestone. `Any+Milestone` lists all issues that have an assigned milestone | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced][ce-13004] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | @@ -151,11 +151,11 @@ GET /groups/:id/issues?my_reaction_emoji=star | `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. `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. `No+Milestone` lists all issues with no milestone | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search group issues against their `title` and `description` | @@ -265,11 +265,11 @@ GET /projects/:id/issues?my_reaction_emoji=star | `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. `No+Label` lists all issues with no labels | -| `milestone` | string | no | The milestone title. `No+Milestone` lists all issues with no milestone | +| `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `assignee_id` | integer | no | Return issues assigned to the given user `id`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search project issues against their `title` and `description` | @@ -1113,6 +1113,93 @@ Example response: } ``` +## List merge requests related to issue + +Get all the merge requests that are related to the issue. + +``` +GET /projects/:id/issues/:issue_id/related_merge_requests +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|--------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `issue_iid` | integer | yes | The internal ID of a project's issue | + +```sh +curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/11/related_merge_requests +``` + +Example response: + +```json +[ + { + "id": 29, + "iid": 11, + "project_id": 1, + "title": "Provident eius eos blanditiis consequatur neque odit.", + "description": "Ut consequatur ipsa aspernatur quisquam voluptatum fugit. Qui harum corporis quo fuga ut incidunt veritatis. Autem necessitatibus et harum occaecati nihil ea.\r\n\r\ntwitter/flight#8", + "state": "opened", + "created_at": "2018-09-18T14:36:15.510Z", + "updated_at": "2018-09-19T07:45:13.089Z", + "target_branch": "v2.x", + "source_branch": "so_long_jquery", + "upvotes": 0, + "downvotes": 0, + "author": { + "id": 14, + "name": "Verna Hills", + "username": "lawanda_reinger", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/de68a91aeab1cff563795fb98a0c2cc0?s=80&d=identicon", + "web_url": "https://gitlab.example.com/lawanda_reinger" + }, + "assignee": { + "id": 19, + "name": "Jody Baumbach", + "username": "felipa.kuvalis", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/6541fc75fc4e87e203529bd275fafd07?s=80&d=identicon", + "web_url": "https://gitlab.example.com/felipa.kuvalis" + }, + "source_project_id": 1, + "target_project_id": 1, + "labels": [], + "work_in_progress": false, + "milestone": { + "id": 27, + "iid": 2, + "project_id": 1, + "title": "v1.0", + "description": "Et tenetur voluptatem minima doloribus vero dignissimos vitae.", + "state": "active", + "created_at": "2018-09-18T14:35:44.353Z", + "updated_at": "2018-09-18T14:35:44.353Z", + "due_date": null, + "start_date": null, + "web_url": "https://gitlab.example.com/twitter/flight/milestones/2" + }, + "merge_when_pipeline_succeeds": false, + "merge_status": "cannot_be_merged", + "sha": "3b7b528e9353295c1c125dad281ac5b5deae5f12", + "merge_commit_sha": null, + "user_notes_count": 9, + "discussion_locked": null, + "should_remove_source_branch": null, + "force_remove_source_branch": false, + "web_url": "https://gitlab.example.com/twitter/flight/merge_requests/4", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, + "squash": false + } +] +``` + ## List merge requests that will close issue on merge Get all the merge requests that will close issue when merged. diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 862ee398a84..f3cfe0ad218 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -30,10 +30,10 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | | `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` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | | `labels` | string | no | Return merge requests matching a comma separated list of labels | | `created_after` | datetime | no | Return merge requests created on or after the given time | @@ -42,12 +42,12 @@ Parameters: | `updated_before` | datetime | no | Return merge requests updated on or before the given time | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. | | `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me` | -| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `source_branch` | string | no | Return merge requests with the given source branch | | `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | -| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | +| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | ```json [ @@ -154,10 +154,10 @@ Parameters: | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `id` | integer | yes | The ID of a project | | `iids[]` | Array[integer] | no | Return the request having the given `iid` | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | | `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` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | | `labels` | string | no | Return merge requests matching a comma separated list of labels | | `created_after` | datetime | no | Return merge requests created on or after the given time | @@ -166,10 +166,10 @@ Parameters: | `updated_before` | datetime | no | Return merge requests updated on or before the given time | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13060] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | -| `source_branch` | string | no | Return merge requests with the given source branch | -| `target_branch` | string | no | Return merge requests with the given target branch | +| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `source_branch` | string | no | Return merge requests with the given source branch | +| `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | ```json @@ -266,11 +266,11 @@ Parameters: | Attribute | Type | Required | Description | | ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `id` | integer | yes | The ID of a group | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | -| `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc` | -| `milestone` | string | no | Return merge requests for a specific milestone | +| `id` | integer | yes | The ID of a group | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc` | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | | `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | | `labels` | string | no | Return merge requests matching a comma separated list of labels | | `created_after` | datetime | no | Return merge requests created on or after the given time | @@ -279,10 +279,10 @@ Parameters: | `updated_before` | datetime | no | Return merge requests updated on or before the given time | | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> | | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | -| `source_branch` | string | no | Return merge requests with the given source branch | -| `target_branch` | string | no | Return merge requests with the given target branch | +| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `source_branch` | string | no | Return merge requests with the given source branch | +| `target_branch` | string | no | Return merge requests with the given target branch | | `search` | string | no | Search merge requests against their `title` and `description` | ```json diff --git a/doc/api/projects.md b/doc/api/projects.md index 947e7db9c52..961241f31e1 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -451,6 +451,7 @@ GET /projects/:id | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `statistics` | boolean | no | Include project statistics | +| `license` | boolean | no | Include project license data | | `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | ```json @@ -508,6 +509,14 @@ GET /projects/:id }, "archived": false, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE", + "license": { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0", + "nickname": "GNU LGPLv3", + "html_url": "http://choosealicense.com/licenses/lgpl-3.0/", + "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" + }, "shared_runners_enabled": true, "forks_count": 0, "star_count": 0, @@ -572,6 +581,14 @@ If the project is a fork, and you provide a valid token to authenticate, the "http_url_to_repo":"https://gitlab.com/gitlab-org/gitlab-ce.git", "web_url":"https://gitlab.com/gitlab-org/gitlab-ce", "avatar_url":"https://assets.gitlab-static.net/uploads/-/system/project/avatar/13083/logo-extra-whitespace.png", + "license_url": "https://gitlab.com/gitlab-org/gitlab-ce/blob/master/LICENSE", + "license": { + "key": "mit", + "name": "MIT License", + "nickname": null, + "html_url": "http://choosealicense.com/licenses/mit/", + "source_url": "https://opensource.org/licenses/MIT", + }, "star_count":3812, "forks_count":3561, "last_activity_at":"2018-01-02T11:40:26.570Z", @@ -905,6 +922,14 @@ Example response: "import_status": "none", "archived": true, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE", + "license": { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0", + "nickname": "GNU LGPLv3", + "html_url": "http://choosealicense.com/licenses/lgpl-3.0/", + "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" + }, "shared_runners_enabled": true, "forks_count": 0, "star_count": 1, @@ -983,6 +1008,14 @@ Example response: "import_status": "none", "archived": true, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE", + "license": { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0", + "nickname": "GNU LGPLv3", + "html_url": "http://choosealicense.com/licenses/lgpl-3.0/", + "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" + }, "shared_runners_enabled": true, "forks_count": 0, "star_count": 0, @@ -1101,6 +1134,14 @@ Example response: }, "archived": true, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE", + "license": { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0", + "nickname": "GNU LGPLv3", + "html_url": "http://choosealicense.com/licenses/lgpl-3.0/", + "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" + }, "shared_runners_enabled": true, "forks_count": 0, "star_count": 0, @@ -1197,6 +1238,14 @@ Example response: }, "archived": false, "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "license_url": "http://example.com/diaspora/diaspora-client/blob/master/LICENSE", + "license": { + "key": "lgpl-3.0", + "name": "GNU Lesser General Public License v3.0", + "nickname": "GNU LGPLv3", + "html_url": "http://choosealicense.com/licenses/lgpl-3.0/", + "source_url": "http://www.gnu.org/licenses/lgpl-3.0.txt" + }, "shared_runners_enabled": true, "forks_count": 0, "star_count": 0, diff --git a/doc/api/tags.md b/doc/api/tags.md index f2a3f9f28d2..826900ca518 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -134,7 +134,7 @@ Parameters: "description": "Amazing release. Wow" }, "name": "v1.0.0", - "target: "2695effb5807a22ff3d138d593fd856244e155e7", + "target": "2695effb5807a22ff3d138d593fd856244e155e7", "message": null } ``` diff --git a/doc/ci/examples/artifactory_and_gitlab/index.md b/doc/ci/examples/artifactory_and_gitlab/index.md index 9657f52159e..6aa0edd87b4 100644 --- a/doc/ci/examples/artifactory_and_gitlab/index.md +++ b/doc/ci/examples/artifactory_and_gitlab/index.md @@ -16,8 +16,8 @@ to build a [Maven](https://maven.apache.org/) project, deploy it to [Artifactory You'll create two different projects: -- `simple-maven-dep`: the app built and deployed to Artifactory (available at https://gitlab.com/gitlab-examples/maven/simple-maven-dep) -- `simple-maven-app`: the app using the previous one as a dependency (available at https://gitlab.com/gitlab-examples/maven/simple-maven-app) +- `simple-maven-dep`: the app built and deployed to Artifactory (available at https://gitlab.com/gitlab-examples/maven/simple-maven-dep ) +- `simple-maven-app`: the app using the previous one as a dependency (available at https://gitlab.com/gitlab-examples/maven/simple-maven-app ) We assume that you already have a GitLab account on [GitLab.com](https://gitlab.com/), and that you know the basic usage of Git and [GitLab CI/CD](https://about.gitlab.com/features/gitlab-ci-cd/). We also assume that an Artifactory instance is available and reachable from the internet, and that you have valid credentials to deploy on it. diff --git a/doc/ci/examples/container_scanning.md b/doc/ci/examples/container_scanning.md index 0f79f7d1b17..bc948dc6ea9 100644 --- a/doc/ci/examples/container_scanning.md +++ b/doc/ci/examples/container_scanning.md @@ -63,4 +63,10 @@ are still maintained, they have been deprecated with GitLab 11.0 and may be remo in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` configuration to reflect that change. +CAUTION: **Caution:** +Starting with GitLab 11.5, Container Scanning feature is licensed under the name `container_scanning`. +While the old name `sast_container` is still maintained, it has been deprecated with GitLab 11.5 and +may be removed in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` +configuration to reflect that change if you are using the `$GITLAB_FEATURES` environment variable. + [ee]: https://about.gitlab.com/pricing/ diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index b2c73caae2e..c0346d78141 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -398,10 +398,10 @@ other reasons][ci-reasons] to keep using GitLab CI/CD. The benefits to our teams - [Using Docker images documentation][using-docker] - [Example project: Hello GitLab CI/CD on GitLab][hello-gitlab] -[phoenix-site]: http://phoenixframework.org/ "Phoenix Framework" +[phoenix-site]: https://phoenixframework.org/ "Phoenix Framework" [phoenix-learning-guide]: https://hexdocs.pm/phoenix/learning.html "Phoenix Learning Guide" -[phoenix-install]: http://www.phoenixframework.org/docs/installation "Phoenix Installation" -[phoenix-mysql]: http://www.phoenixframework.org/docs/using-mysql "Phoenix with MySQL" +[phoenix-install]: https://hexdocs.pm/phoenix/installation.html "Phoenix Installation" +[phoenix-mysql]: https://hexdocs.pm/phoenix/ecto.html#using-mysql "Phoenix with MySQL" [elixir-site]: http://elixir-lang.org/ "Elixir" [elixir-mix]: http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html "Introduction to mix" [elixir-docs]: http://elixir-lang.org/getting-started/introduction.html "Elixir Documentation" diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 83e0fa34ad6..2a179bfbbf0 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -312,7 +312,7 @@ We're always looking for contributions that can mitigate these If you think that registration token for a Project was revealed, you should reset them. It's recommended because such token can be used to register another -Runner to thi Project. It may be next used to obtain the values of secret +Runner to the Project. It may be next used to obtain the values of secret variables or clone the project code, that normally may be unavailable for the attacker. diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 424e1af7ba3..981aa101dd3 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -474,6 +474,7 @@ docker build: changes: - Dockerfile - docker/scripts/* + - dockerfiles/**/* ``` In the scenario above, if you are pushing multiple commits to GitLab to an @@ -482,6 +483,7 @@ one of the commits contains changes to either: - The `Dockerfile` file. - Any of the files inside `docker/scripts/` directory. +- Any of the files and subfolders inside `dockerfiles` directory. CAUTION: **Warning:** There are some caveats when using this feature with new branches and tags. See @@ -2031,3 +2033,5 @@ CI with various languages. [ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909 [schedules]: ../../user/project/pipelines/schedules.md [variables-expressions]: ../variables/README.md#variables-expressions +[ee]: https://about.gitlab.com/gitlab-ee/ +[gitlab-versions]: https://about.gitlab.com/products/
\ No newline at end of file diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 6c6e198a7c3..95722c027ba 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -379,7 +379,7 @@ let(:mutation) do ) end -it 'returns a successfull response' do +it 'returns a successful response' do post_graphql_mutation(mutation, current_user: user) expect(response).to have_gitlab_http_status(:success) diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index f9e6efa2c30..b6f053ff0e9 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -171,7 +171,7 @@ There are a few gotchas with it: class Base def execute return unless enabled? - + # ... # ... end @@ -185,12 +185,12 @@ There are a few gotchas with it: class Base def execute return unless enabled? - + do_something end - + private - + def do_something # ... # ... @@ -204,14 +204,14 @@ There are a few gotchas with it: ```ruby module EE::Base extend ::Gitlab::Utils::Override - + override :do_something def do_something # Follow the above pattern to call super and extend it end end ``` - + This would require updating CE first, or make sure this is back ported to CE. When prepending, place them in the `ee/` specific sub-directory, and @@ -332,6 +332,21 @@ full implementation details. [ce-mr-full-private]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12373 [ee-mr-full-private]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2199 +### Code in `config/routes` + +When we add `draw :admin` in `config/routes.rb`, the application will try to +load the file located in `config/routes/admin.rb`, and also try to load the +file located in `ee/config/routes/admin.rb`. + +In EE, it should at least load one file, at most two files. If it cannot find +any files, an error will be raised. In CE, since we don't know if there will +be an EE route, it will not raise any errors even if it cannot find anything. + +This means if we want to extend a particular CE route file, just add the same +file located in `ee/config/routes`. If we want to add an EE only route, we +could still put `draw :ee_only` in both CE and EE, and add +`ee/config/routes/ee_only.rb` in EE, similar to `render_if_exists`. + ### Code in `app/controllers/` In controllers, the most common type of conflict is with `before_action` that diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index 3d8da6accc1..533e2001300 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -3,7 +3,7 @@ We manage our own Icon and Illustration library in the [gitlab-svgs][gitlab-svgs] repository. This repository is published on [npm][npm] and managed as a dependency via yarn. You can browse all available Icons and Illustrations [here][svg-preview]. -To upgrade to a new version run `yarn upgrade @gitlab-org/gitlab-svgs`. +To upgrade to a new version run `yarn upgrade @gitlab/svgs`. ## Icons @@ -111,6 +111,6 @@ export default { </template> ``` -[npm]: https://www.npmjs.com/package/@gitlab-org/gitlab-svgs +[npm]: https://www.npmjs.com/package/@gitlab/svgs [gitlab-svgs]: https://gitlab.com/gitlab-org/gitlab-svgs [svg-preview]: https://gitlab-org.gitlab.io/gitlab-svgs diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index 0f1f079bdb4..350593cc813 100644 --- a/doc/development/feature_flags.md +++ b/doc/development/feature_flags.md @@ -112,3 +112,8 @@ feature flag. You can stub a feature flag as follows: ```ruby stub_feature_flags(my_feature_flag: false) ``` + +## Enabling a feature flag + +Check how to [roll out changes using feature flags](rolling_out_changes_using_feature_flags.md). + diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index 6a67aa7f610..f58d79fccf1 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -20,6 +20,7 @@ are very appreciative of the work done by translators and proofreaders! - French - Davy Defaud - [GitLab](https://gitlab.com/DevDef), [Crowdin](https://crowdin.com/profile/DevDef) - German + - Michael Hahnle - [GitLab](https://gitlab.com/mhah), [Crowdin](https://crowdin.com/profile/mhah) - Indonesian - Ahmad Naufal Mukhtar - [GitLab](https://gitlab.com/anaufalm), [Crowdin](https://crowdin.com/profile/anaufalm) - Italian diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md index dada59ce242..b65fbc9d958 100644 --- a/doc/development/rolling_out_changes_using_feature_flags.md +++ b/doc/development/rolling_out_changes_using_feature_flags.md @@ -152,14 +152,31 @@ in RC1, followed by the feature flag being removed in RC2. This in turn means the feature will be stable by the time we publish a stable package around the 22nd of the month. -## Undefined feature flags default to "on" +## Implicit feature flags -By default, the [`Project#feature_available?`][project-fa], +The [`Project#feature_available?`][project-fa], [`Namespace#feature_available?`][namespace-fa] (EE), and -[`License.feature_available?`][license-fa] (EE) methods will check if the -specified feature is behind a feature flag. Unless the feature is explicitly -disabled or limited to a percentage of users, the feature flag check will -default to `true`. +[`License.feature_available?`][license-fa] (EE) methods all implicitly check for +a feature flag by the same name as the provided argument. + +For example if a feature is license-gated, there's no need to add an additional +explicit feature flag check since the flag will be checked as part of the +`License.feature_available?` call. Similarly, there's no need to "clean up" a +feature flag once the feature has reached general availability. + +You'd still want to use an explicit `Feature.enabled?` check if your new feature +isn't gated by a License or Plan. + +[project-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/app/models/project_feature.rb#L63-68 +[namespace-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/ee/namespace.rb#L71-85 +[license-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/license.rb#L293-300 + +### Undefined feature flags default to "on" + +An important side-effect of the [implicit feature +flags][#implicit-feature-flags] mentioned above is that unless the feature is +explicitly disabled or limited to a percentage of users, the feature flag check +will default to `true`. As an example, if you were to ship the backend half of a feature behind a flag, you'd want to explicitly disable that flag until the frontend half is also ready @@ -171,7 +188,3 @@ to be shipped. You can do this via ChatOps: Note that you can do this at any time, even before the merge request using the flag has been merged! - -[project-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/app/models/project_feature.rb#L63-68 -[namespace-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/ee/namespace.rb#L71-85 -[license-fa]: https://gitlab.com/gitlab-org/gitlab-ee/blob/4cc1c62918aa4c31750cb21dfb1a6c3492d71080/ee/app/models/license.rb#L293-300 diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 25c6371f3d7..4f4ff85fe1d 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -1,15 +1,13 @@ # Review apps -We currently have review apps available as a manual job in EE pipelines. Here is -[the first implementation](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6259). - -That said, [the Quality team is working](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6665) -on making Review Apps automatically deployed by each pipeline, both in CE and EE. +Review Apps are automatically deployed by each pipeline, both in +[CE](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22010) and +[EE](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6665). ## How does it work? -1. On every EE [pipeline][gitlab-pipeline] during the `test` stage, you can - start the [`review` job][review-job] +1. On every [pipeline][gitlab-pipeline] during the `test` stage, the + [`review` job][review-job] is automatically started. 1. The `review` job [triggers a pipeline][cng-pipeline] in the [`CNG-mirror`][cng-mirror] [^1] project 1. The `CNG-mirror` pipeline creates the Docker images of each component (e.g. `gitlab-rails-ee`, @@ -39,6 +37,9 @@ on making Review Apps automatically deployed by each pipeline, both in CE and EE review app manually, and is also started by GitLab once a branch is deleted - [TBD] Review apps are cleaned up regularly using a pipeline schedule that runs the [`scripts/review_apps/automated_cleanup.rb`][automated_cleanup.rb] script +- If you're unable to log in using the `root` username and password, the + deployment may have failed. Stop the Review App via the `stop_review` + manual job and then retry the `review` job to redeploy the Review App. [^1]: We use the `CNG-mirror` project so that the `CNG`, (**C**loud **N**ative **G**itLab), project's registry is not overloaded with a lot of transient Docker images. diff --git a/doc/development/ux_guide/tips.md b/doc/development/ux_guide/tips.md index 8348de4f8a2..ceb9ed56ac4 100644 --- a/doc/development/ux_guide/tips.md +++ b/doc/development/ux_guide/tips.md @@ -1,20 +1,16 @@ # Tips -## Contents -* [SVGs](#svgs) - ---- - ## SVGs When exporting SVGs, be sure to follow the following guidelines: 1. Convert all strokes to outlines. -2. Use pathfinder tools to combine overlapping paths and create compound paths. -3. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS. -4. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes. +1. Use pathfinder tools to combine overlapping paths and create compound paths. +1. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS. +1. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes. + +You can open your SVG in a text editor to ensure that it is clean. -You can open your svg in a text editor to ensure that it is clean. Incorrect files will look like this: ```xml @@ -35,10 +31,10 @@ Incorrect files will look like this: </svg> ``` -Correct file will look like this: +Correct files will look like this: ```xml <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 17" enable-background="new 0 0 16 17"><path d="m15.1 1h-2.1v-1h-2v1h-6v-1h-2v1h-2.1c-.5 0-.9.5-.9 1v14c0 .6.4 1 .9 1h14.2c.5 0 .9-.4.9-1v-14c0-.5-.4-1-.9-1m-1.1 14h-12v-9h12v9m0-11h-12v-1h12v1"/><path d="m5.4 11.6l1.5 1.2c.4.3 1.1.3 1.4-.1l2.5-3c.3-.4.3-1.1-.1-1.4-.5-.4-1.1-.3-1.5.1l-1.8 2.2-.8-.6c-.4-.3-1.1-.3-1.4.2-.3.4-.3 1 .2 1.4"/></svg> ``` -> TODO: Checkout [https://github.com/svg/svgo](https://github.com/svg/svgo) +> TODO: Checkout <https://github.com/svg/svgo>. diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md index 676392eacf2..d67695d75b4 100644 --- a/doc/install/digitaloceandocker.md +++ b/doc/install/digitaloceandocker.md @@ -1,7 +1,8 @@ # Digital Ocean and Docker Machine test environment -## Warning. This guide is for quickly testing different versions of GitLab and -## not recommended for ease of future upgrades or keeping the data you create. +CAUTION: **Caution:** +This guide is for quickly testing different versions of GitLab and not recommended for ease of +future upgrades or keeping the data you create. ## Initial setup @@ -12,92 +13,88 @@ locally on either macOS or Linux. #### Install Docker Toolbox -1. [https://www.docker.com/products/docker-toolbox](https://www.docker.com/products/docker-toolbox) +- <https://www.docker.com/products/docker-toolbox> ### On Linux #### Install Docker Engine -1. [https://docs.docker.com/engine/installation/linux](https://docs.docker.com/engine/installation/linux/) +- <https://docs.docker.com/engine/installation/linux/> #### Install Docker Machine -1. [https://docs.docker.com/machine/install-machine](https://docs.docker.com/machine/install-machine/) +- <https://docs.docker.com/machine/install-machine/> -_The rest of the steps are identical for macOS and Linux_ +NOTE: **Note:** +The rest of the steps are identical for macOS and Linux. ### Create new docker host -1. Login to Digital Ocean -1. Generate a new API token at https://cloud.digitalocean.com/settings/api/tokens +1. Login to Digital Ocean. +1. Generate a new API token at <https://cloud.digitalocean.com/settings/api/tokens>. + This command will create a new DO droplet called `gitlab-test-env-do` that will act as a docker host. -This command will create a new DO droplet called `gitlab-test-env-do` that will act as a docker host. + NOTE: **Note:** + 4GB is the minimum requirement for a Docker host that will run more than one GitLab instance. -**Note: 4GB is the minimum requirement for a Docker host that will run more then one GitLab instance** + - RAM: 4GB + - Name: `gitlab-test-env-do` + - Driver: `digitalocean` -+ RAM: 4GB -+ Name: `gitlab-test-env-do` -+ Driver: `digitalocean` +1. Set the DO token: + ```sh + export DOTOKEN=<your generated token> + ``` -**Set the DO token** - Replace the string below with your generated token +1. Create the machine: -``` -export DOTOKEN=cf3dfd0662933203005c4a73396214b7879d70aabc6352573fe178d340a80248 -``` - -**Create the machine** - -``` -docker-machine create \ - --driver digitalocean \ - --digitalocean-access-token=$DOTOKEN \ - --digitalocean-size "4gb" \ - gitlab-test-env-do -``` - -+ Resource: https://docs.docker.com/machine/drivers/digital-ocean/ + ```sh + docker-machine create \ + --driver digitalocean \ + --digitalocean-access-token=$DOTOKEN \ + --digitalocean-size "4gb" \ + gitlab-test-env-do + ``` +Resource: <https://docs.docker.com/machine/drivers/digital-ocean/>. ### Creating GitLab test instance - #### Connect your shell to the new machine - In this example we'll create a GitLab EE 8.10.8 instance. - First connect the docker client to the docker host you created previously. -``` +```sh eval "$(docker-machine env gitlab-test-env-do)" ``` You can add this to your `~/.bash_profile` file to ensure the `docker` client uses the `gitlab-test-env-do` docker host - #### Create new GitLab container -+ HTTP port: `8888` -+ SSH port: `2222` - + Set `gitlab_shell_ssh_port` using `--env GITLAB_OMNIBUS_CONFIG ` -+ Hostname: IP of docker host -+ Container name: `gitlab-test-8.10` -+ GitLab version: **EE** `8.10.8-ee.0` +- HTTP port: `8888` +- SSH port: `2222` + - Set `gitlab_shell_ssh_port` using `--env GITLAB_OMNIBUS_CONFIG` +- Hostname: IP of docker host +- Container name: `gitlab-test-8.10` +- GitLab version: **EE** `8.10.8-ee.0` -##### Set up container settings +##### Set up container settings -``` +```sh export SSH_PORT=2222 export HTTP_PORT=8888 export VERSION=8.10.8-ee.0 export NAME=gitlab-test-8.10 ``` -##### Create container -``` +##### Create container + +```sh docker run --detach \ --env GITLAB_OMNIBUS_CONFIG="external_url 'http://$(docker-machine ip gitlab-test-env-do):$HTTP_PORT'; gitlab_rails['gitlab_shell_ssh_port'] = $SSH_PORT;" \ --hostname $(docker-machine ip gitlab-test-env-do) \ @@ -110,23 +107,20 @@ gitlab/gitlab-ee:$VERSION ##### Retrieve the docker host IP -``` +```sh docker-machine ip gitlab-test-env-do # example output: 192.168.151.134 ``` - -+ Browse to: http://192.168.151.134:8888/ - +Browse to: <http://192.168.151.134:8888/>. ##### Execute interactive shell/edit configuration - -``` +```sh docker exec -it $NAME /bin/bash ``` -``` +```sh # example commands root@192:/# vi /etc/gitlab/gitlab.rb root@192:/# gitlab-ctl reconfigure @@ -134,6 +128,6 @@ root@192:/# gitlab-ctl reconfigure #### Resources -+ [https://docs.gitlab.com/omnibus/docker/](https://docs.gitlab.com/omnibus/docker/) -+ [https://docs.docker.com/machine/get-started/](https://docs.docker.com/machine/get-started/) -+ [https://docs.docker.com/machine/reference/ip/](https://docs.docker.com/machine/reference/ip/)+ +- <https://docs.gitlab.com/omnibus/docker/>. +- <https://docs.docker.com/machine/get-started/>. +- <https://docs.docker.com/machine/reference/ip/>. diff --git a/doc/install/installation.md b/doc/install/installation.md index 1210ac58499..37c826ce9e0 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -132,9 +132,9 @@ Remove the old Ruby 1.8 if present: Download Ruby and compile it: mkdir /tmp/ruby && cd /tmp/ruby - curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.4.tar.gz - echo 'ec82b0d53bd0adad9b19e6b45e44d54e9ec3f10c ruby-2.4.4.tar.gz' | shasum -c - && tar xzf ruby-2.4.4.tar.gz - cd ruby-2.4.4 + curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.5.tar.gz + echo '4d650f302f1ec00256450b112bb023644b6ab6dd ruby-2.4.5.tar.gz' | shasum -c - && tar xzf ruby-2.4.5.tar.gz + cd ruby-2.4.5 ./configure --disable-install-rdoc make diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 2b9cce6539f..76f5495ff78 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -9,37 +9,39 @@ You can only restore a backup to **exactly the same version and type (CE/EE)** of GitLab on which it was created. The best way to migrate your repositories from one server to another is through backup restore. -## Backup +## Requirements -GitLab provides a simple command line interface to backup your whole installation, -and is flexible enough to fit your needs. +In order to be able to backup and restore, you need two essential tools +installed on your system. -### Requirements +### Rsync -* rsync +If you installed GitLab: -If you're using GitLab with the Omnibus package, you're all set. If you -installed GitLab from source, make sure you have rsync installed. +- Using the Omnibus package, you're all set. +- From source, make sure `rsync` is installed: -If you're using Ubuntu, you could run: + ```sh + # Debian/Ubuntu + sudo apt-get install rsync -``` -sudo apt-get install -y rsync -``` + # RHEL/CentOS + sudo yum install rsync + ``` -* tar +### Tar Backup and restore tasks use `tar` under the hood to create and extract archives. Ensure you have version 1.30 or above of `tar` available in your system. To check the version, run: -``` +```sh tar --version ``` -### Backup timestamp +## Backup timestamp ->**Note:** +NOTE: **Note:** In GitLab 9.2 the timestamp format was changed from `EPOCH_YYYY_MM_DD` to `EPOCH_YYYY_MM_DD_GitLab_version`, for example `1493107454_2018_04_25` would become `1493107454_2018_04_25_10.6.4-ce`. @@ -54,30 +56,46 @@ available. For example, if the backup name is `1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar`, then the timestamp is `1493107454_2018_04_25_10.6.4-ce`. -### Creating a backup of the GitLab system +## Creating a backup of the GitLab system + +GitLab provides a simple command line interface to backup your whole instance. +It backs up your: + +- Database +- Attachments +- Git repositories data +- CI/CD job output logs +- CI/CD job artifacts +- LFS objects +- Container Registry images +- GitLab Pages content + +CAUTION: **Warning:** +GitLab does not back up any configuration files, SSL certificates, or system files. +You are highly advised to [read about storing configuration files](#storing-configuration-files). Use this command if you've installed GitLab with the Omnibus package: -``` +```sh sudo gitlab-rake gitlab:backup:create ``` Use this if you've installed GitLab from source: -``` +```sh sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production ``` If you are running GitLab within a Docker container, you can run the backup from the host: -``` +```sh docker exec -t <container name> gitlab-rake gitlab:backup:create ``` If you are using the gitlab-omnibus helm chart on a Kubernetes cluster, you can -run the backup task on the gitlab application pod using kubectl +run the backup task on the gitlab application pod using kubectl: -``` +```sh kubectl exec -it <gitlab-gitlab pod> gitlab-rake gitlab:backup:create ``` @@ -110,9 +128,50 @@ Deleting tmp directories...[DONE] Deleting old backups... [SKIPPING] ``` +## Storing configuration files + +A backup performed by the [raketask GitLab provides](#creating-a-backup-of-the-gitlab-system) +does **not** store your configuration files. The primary reason for this is that your +database contains encrypted information for two-factor authentication, the CI/CD +'secure variables', etc. Storing encrypted information along with its key in the +same place defeats the purpose of using encryption in the first place. + +CAUTION: **Warning:** +The secrets file is essential to preserve your database encryption key. + +At the very **minimum**, you must backup: + +For Omnibus: + +- `/etc/gitlab/gitlab-secrets.json` +- `/etc/gitlab/gitlab.rb` + +For installation from source: + +- `/home/git/gitlab/config/secrets.yml` +- `/home/git/gitlab/config/gitlab.yml` + +For [Docker installations](https://docs.gitlab.com/omnibus/docker/), you must +back up the volume where the configuration files are stored. If you have created +the GitLab container according to the documentation, it should be under +`/srv/gitlab/config`. + +You may also want to back up any TLS keys and certificates, and your +[SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). + +If you use Omnibus GitLab, see some additional information +[to backup your configuration](https://docs.gitlab.com/omnibus/settings/backups.html). + +In the unlikely event that the secrets file is lost, see the +[troubleshooting section](#when-the-secrets-file-is-lost). + +## Backup options + +The command line tool GitLab provides to backup your instance can take more options. + ### Backup strategy option -> **Note:** Introduced as an option in GitLab 8.17. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8728) in GitLab 8.17. The default backup strategy is to essentially stream data from the respective data locations to the backup using the Linux command `tar` and `gzip`. This works @@ -129,8 +188,11 @@ so the problem doesn't compound, but it could be a considerable change for large installations. This is why the `copy` strategy is not the default in 8.17. To use the `copy` strategy instead of the default streaming strategy, specify -`STRATEGY=copy` in the Rake task command. For example, -`sudo gitlab-rake gitlab:backup:create STRATEGY=copy`. +`STRATEGY=copy` in the Rake task command. For example: + +```sh +sudo gitlab-rake gitlab:backup:create STRATEGY=copy +``` ### Excluding specific directories from the backup @@ -151,11 +213,15 @@ Use a comma to specify several options at the same time: All wikis will be backed up as part of the `repositories` group. Non-existent wikis will be skipped during a backup. -``` -# use this command if you've installed GitLab with the Omnibus package +For Omnibus GitLab packages: + +```sh sudo gitlab-rake gitlab:backup:create SKIP=db,uploads +``` + +For installations from source: -# if you've installed GitLab from source +```sh sudo -u git -H bundle exec rake gitlab:backup:create SKIP=db,uploads RAILS_ENV=production ``` @@ -208,7 +274,7 @@ This example can be used for a bucket in Amsterdam (AMS3). 1. [Reconfigure GitLab] for the changes to take effect -CAUTION: **Warning:** +NOTE: **Note:** If you see `400 Bad Request` by using Digital Ocean Spaces, the cause may be the usage of backup encryption. Remove or comment the line that contains `gitlab_rails['backup_encryption']` since Digital Ocean Spaces @@ -370,33 +436,43 @@ backups will be copied to, and will be created if it does not exist. If the directory that you want to copy the tarballs to is the root of your mounted directory, just use `.` instead. -For omnibus packages: -```ruby -gitlab_rails['backup_upload_connection'] = { - :provider => 'Local', - :local_root => '/mnt/backups' -} +For Omnibus GitLab packages: -# The directory inside the mounted folder to copy backups to -# Use '.' to store them in the root directory -gitlab_rails['backup_upload_remote_directory'] = 'gitlab_backups' -``` +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_rails['backup_upload_connection'] = { + :provider => 'Local', + :local_root => '/mnt/backups' + } + + # The directory inside the mounted folder to copy backups to + # Use '.' to store them in the root directory + gitlab_rails['backup_upload_remote_directory'] = 'gitlab_backups' + ``` + +1. [Reconfigure GitLab] for the changes to take effect. + +--- For installations from source: -```yaml - backup: - # snip - upload: - # Fog storage connection settings, see http://fog.io/storage/ . - connection: - provider: Local - local_root: '/mnt/backups' - # The directory inside the mounted folder to copy backups to - # Use '.' to store them in the root directory - remote_directory: 'gitlab_backups' -``` +1. Edit `home/git/gitlab/config/gitlab.yml`: + + ```yaml + backup: + upload: + # Fog storage connection settings, see http://fog.io/storage/ . + connection: + provider: Local + local_root: '/mnt/backups' + # The directory inside the mounted folder to copy backups to + # Use '.' to store them in the root directory + remote_directory: 'gitlab_backups' + ``` + +1. [Restart GitLab] for the changes to take effect. ### Backup archive permissions @@ -405,45 +481,56 @@ will have owner/group git:git and 0600 permissions by default. This is meant to avoid other system users reading GitLab's data. If you need the backup archives to have different permissions you can use the 'archive_permissions' setting. -``` -# In /etc/gitlab/gitlab.rb, for omnibus packages -gitlab_rails['backup_archive_permissions'] = 0644 # Makes the backup archives world-readable -``` +For Omnibus GitLab packages: -``` -# In gitlab.yml, for installations from source: - backup: - archive_permissions: 0644 # Makes the backup archives world-readable -``` +1. Edit `/etc/gitlab/gitlab.rb`: -### Storing configuration files + ```ruby + gitlab_rails['backup_archive_permissions'] = 0644 # Makes the backup archives world-readable + ``` + +1. [Reconfigure GitLab] for the changes to take effect. + +--- + +For installations from source: -Please be informed that a backup does not store your configuration -files. One reason for this is that your database contains encrypted -information for two-factor authentication. Storing encrypted -information along with its key in the same place defeats the purpose -of using encryption in the first place! +1. Edit `/home/git/gitlab/config/gitlab.yml`: -If you use an Omnibus package please see the [instructions in the readme to backup your configuration](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#backup-and-restore-omnibus-gitlab-configuration). -If you have a cookbook installation there should be a copy of your configuration in Chef. -If you installed from source, please consider backing up your `config/secrets.yml` file, `gitlab.yml` file, any SSL keys and certificates, and your [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). + ```yaml + backup: + archive_permissions: 0644 # Makes the backup archives world-readable + ``` -At the very **minimum** you should backup `/etc/gitlab/gitlab.rb` and -`/etc/gitlab/gitlab-secrets.json` (Omnibus), or -`/home/git/gitlab/config/secrets.yml` (source) to preserve your database -encryption key. +1. [Restart GitLab] for the changes to take effect. ### Configuring cron to make daily backups ->**Note:** +NOTE: **Note:** The following cron jobs do not [backup your GitLab configuration files](#storing-configuration-files) or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). -**For Omnibus installations** +For Omnibus GitLab packages: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + ## Limit backup lifetime to 7 days - 604800 seconds + gitlab_rails['backup_keep_time'] = 604800 + ``` + +1. [Reconfigure GitLab] for the changes to take effect. + +Note that the `backup_keep_time` configuration option only manages local +files. GitLab does not automatically prune old files stored in a third-party +object storage (e.g., AWS S3) because the user may not have permission to list +and delete files. We recommend that you configure the appropriate retention +policy for your object storage. For example, you can configure [the S3 backup +policy as described here](http://stackoverflow.com/questions/37553070/gitlab-omnibus-delete-backup-from-amazon-s3). To schedule a cron job that backs up your repositories and GitLab metadata, use the root user: -``` +```sh sudo su - crontab -e ``` @@ -455,26 +542,24 @@ There, add the following line to schedule the backup for everyday at 2 AM: ``` You may also want to set a limited lifetime for backups to prevent regular -backups using all your disk space. To do this add the following lines to -`/etc/gitlab/gitlab.rb` and reconfigure: +backups using all your disk space. -``` -# limit backup lifetime to 7 days - 604800 seconds -gitlab_rails['backup_keep_time'] = 604800 -``` +--- -Note that the `backup_keep_time` configuration option only manages local -files. GitLab does not automatically prune old files stored in a third-party -object storage (e.g., AWS S3) because the user may not have permission to list -and delete files. We recommend that you configure the appropriate retention -policy for your object storage. For example, you can configure [the S3 backup -policy as described here](http://stackoverflow.com/questions/37553070/gitlab-omnibus-delete-backup-from-amazon-s3). +For installations from source: + +1. Edit `home/git/gitlab/config/gitlab.yml`: -**For installation from source** + ```yaml + backup: + ## Limit backup lifetime to 7 days - 604800 seconds + keep_time: 604800 + ``` -``` -cd /home/git/gitlab -sudo -u git -H editor config/gitlab.yml # Enable keep_time in the backup section to automatically delete old backups +1. [Restart GitLab] for the changes to take effect. + + +```sh sudo -u git crontab -e # Edit the crontab for the git user ``` @@ -711,5 +796,53 @@ Those objects have no influence on the database backup/restore but they give thi For more information see similar questions on postgresql issue tracker[here](http://www.postgresql.org/message-id/201110220712.30886.adrian.klaver@gmail.com) and [here](http://www.postgresql.org/message-id/2039.1177339749@sss.pgh.pa.us) as well as [stack overflow](http://stackoverflow.com/questions/4368789/error-must-be-owner-of-language-plpgsql). +### When the secrets file is lost + +If you have failed to [back up the secrets file](#storing-configuration-files), +then users with 2FA enabled will not be able to log into GitLab. In that case, +you need to [disable 2FA for everyone](../security/two_factor_authentication.md#disabling-2fa-for-everyone). + +In the case of CI/CD, if your project has secure variables set, you might experience +some weird behavior, like stuck jobs or 500 errors. In that case, you can try +deleting the `ci_variables` table from the database. + +CAUTION: **Warning:** +Use the following commands at your own risk, and make sure you've taken a +backup beforehand. + +1. Enter the Rails console: + + For Omnibus GitLab packages: + + ```sh + sudo gitlab-rails dbconsole + ``` + + For installations from source: + + ```sh + sudo -u git -H bundle exec rails dbconsole RAILS_ENV=production + ``` + +1. Check the `ci_variables` table: + + ```sql + SELECT * FROM public."ci_variables"; + ``` + + Those are the variables that you need to delete. + +1. Drop the table: + + ```sql + DELETE FROM ci_variables; + ``` + +1. You may need to reconfigure or restart GitLab for the changes to take + effect. + +You should now be able to visit your project, and the jobs will start +running again. + [reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure [restart GitLab]: ../administration/restart_gitlab.md#installations-from-source diff --git a/doc/ssh/README.md b/doc/ssh/README.md index 5db042326f3..c5b7813b285 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -8,163 +8,224 @@ you need a secure communication channel for sharing information. The SSH protocol provides this security and allows you to authenticate to the GitLab remote server without supplying your username or password each time. -For a more detailed explanation of how the SSH protocol works, we advise you to -read [this nice tutorial by DigitalOcean](https://www.digitalocean.com/community/tutorials/understanding-the-ssh-encryption-and-connection-process). +For a more detailed explanation of how the SSH protocol works, read +[this nice tutorial by DigitalOcean](https://www.digitalocean.com/community/tutorials/understanding-the-ssh-encryption-and-connection-process). -## Locating an existing SSH key pair +## Requirements -Before generating a new SSH key pair check if your system already has one -at the default location by opening a shell, or Command Prompt on Windows, -and running the following command: +The only requirement is to have the OpenSSH client installed on your system. This +comes pre-installed on GNU/Linux and macOS, but not on Windows. -**Windows Command Prompt:** +Depending on your Windows version, there are different methods to work with +SSH keys. -```bash -type %userprofile%\.ssh\id_rsa.pub -``` +### Installing the SSH client for Windows 10 -**Git Bash on Windows / GNU/Linux / macOS / PowerShell:** +Starting with Windows 10, you can +[install the Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10) +where you can run Linux distributions directly on Windows, without the overhead +of a virtual machine. Once installed and set up, you'll have the Git and SSH +clients at your disposal. -```bash -cat ~/.ssh/id_rsa.pub -``` +### Installing the SSH client for Windows 8.1 and Windows 7 + +The easiest way to install Git and the SSH client on Windows 8.1 and Windows 7 +is [Git for Windows](https://gitforwindows.com). It provides a BASH +emulation (Git Bash) used for running Git from the command line and the +`ssh-keygen` command that is useful to create SSH keys as you'll learn below. + +NOTE: **Alternative tools:** +Although not explored in this page, you can use some alternative tools. +[Cygwin](https://www.cygwin.com) is a large collection of GNU and open source +tools which provide functionality similar to a Unix distribution. +[PuttyGen](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) +provides a graphical user interface to [create SSH keys](https://tartarus.org/~simon/putty-snapshots/htmldoc/Chapter8.html#pubkey-puttygen). + +## Types of SSH keys and which to choose + +GitLab supports RSA, DSA, ECDSA, and ED25519 keys. Their difference lies on +the signing algorithm, and some of them have advantages over the others. For +more information, you can read this +[nice article on ArchWiki](https://wiki.archlinux.org/index.php/SSH_keys#Choosing_the_authentication_key_type). +We'll focus on ED25519 and RSA and here. + +NOTE: **Note:** +As an admin, you can restrict +[which keys should be permitted and their minimum length](../security/ssh_keys_restrictions.md). +By default, all keys are permitted, which is also the case for +[GitLab.com](../user/gitlab_com/index.md#ssh-host-keys-fingerprints). -If you see a string starting with `ssh-rsa` you already have an SSH key pair -and you can skip the generate portion of the next section and skip to the copy -to clipboard step. -If you don't see the string or would like to generate a SSH key pair with a -custom name continue onto the next step. +## ED25519 SSH keys -Note that Public SSH key may also be named as follows: +Following [best practices](https://linux-audit.com/using-ed25519-openssh-keys-instead-of-dsa-rsa-ecdsa/), +you should always favor [ED25519](https://ed25519.cr.yp.to/) SSH keys, since they +are more secure and have better performance over the other types. -- `id_dsa.pub` -- `id_ecdsa.pub` -- `id_ed25519.pub` +They were introduced in OpenSSH 6.5, so any modern OS should include the +option to create them. If for any reason your OS or the GitLab instance you +interact with doesn't support this, you can fallback to RSA. + +## RSA SSH keys + +RSA keys are the most common ones and therefore the most compatible with +servers that may have an old OpenSSH version. Use them if the GitLab server +doesn't work with ED25519 keys. + +The minimum key size is 1024 bits, defaulting to 2048. If you wish to generate a +stronger RSA key pair, specify the `-b` flag with a higher bit value than the +default. + +The old, default password encoding for SSH private keys keys is +[insecure](https://latacora.singles/2018/08/03/the-default-openssh.html); +it's only a single round of an MD5 hash. Since OpenSSH version 6.5, you should +use the `-o` option to `ssh-keygen` to encode your private key in a new, more +secure format. + +If you already have an RSA SSH key pair to use with GitLab, consider upgrading it +to use the more secure password encryption format by using the following command +on the private key: + +```bash +ssh-keygen -o -f ~/.ssh/id_rsa +``` ## Generating a new SSH key pair -1. To generate a new SSH key pair, use the following command: +Before creating an SSH key pair, make sure to read about the +[different types of keys](#types-of-ssh-keys-and-which-to-choose) to understand +their differences. + +To create a new SSH key pair: - **Git Bash on Windows / GNU/Linux / macOS:** +1. Open a terminal on Linux or macOS, or Git Bash / WSL on Windows. +1. Generate a new ED25519 SSH key pair: ```bash - ssh-keygen -o -t rsa -C "your.email@example.com" -b 4096 + ssh-keygen -t ed25519 -C "email@example.com" ``` - (Note: the `-o` option was introduced in 2014; if this command does not work for you, simply remove the `-o` option and try again) + Or, if you want to use RSA: - **Windows:** + ```bash + ssh-keygen -o -t rsa -b 4096 -C "email@example.com" + ``` - Alternatively on Windows you can download - [PuttyGen](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) - and follow [this documentation article][winputty] to generate a SSH key pair. + The `-C` flag adds a comment in the key in case you have multiple of them + and want to tell which is which. It is optional. 1. Next, you will be prompted to input a file path to save your SSH key pair to. + If you don't already have an SSH key pair, use the suggested path by pressing + <kbd>Enter</kbd>. Using the suggested path will normally allow your SSH client + to automatically use the SSH key pair with no additional configuration. - If you don't already have an SSH key pair use the suggested path by pressing - enter. Using the suggested path will normally allow your SSH client - to automatically use the SSH key pair with no additional configuration. + If you already have an SSH key pair with the suggested file path, you will need + to input a new file path and [declare what host](#working-with-non-default-ssh-key-pair-paths) + this SSH key pair will be used for in your `~/.ssh/config` file. - If you already have a SSH key pair with the suggested file path, you will need - to input a new file path and declare what host this SSH key pair will be used - for in your `.ssh/config` file, see [**Working with non-default SSH key pair paths**](#working-with-non-default-ssh-key-pair-paths) - for more information. +1. Once the path is decided, you will be prompted to input a password to + secure your new SSH key pair. It's a best practice to use a password, + but it's not required and you can skip creating it by pressing + <kbd>Enter</kbd> twice. -1. Once you have input a file path you will be prompted to input a password to - secure your SSH key pair. It is a best practice to use a password for an SSH - key pair, but it is not required and you can skip creating a password by - pressing enter. + If, in any case, you want to add or change the password of your SSH key pair, + you can use the `-p`flag: - NOTE: **Note:** - If you want to change the password of your SSH key pair, you can use - `ssh-keygen -p -o -f <keyname>`. - The `-o` option was added in 2014, so if this command does not work for you, - simply remove the `-o` option and try again. + ``` + ssh-keygen -p -o -f <keyname> + ``` -## Adding a SSH key to your GitLab account +Now, it's time to add the newly created public key to your GitLab account. -1. The next step is to copy the public SSH key as we will need it afterwards. +## Adding an SSH key to your GitLab account - To copy your public SSH key to the clipboard, use the appropriate code below: +1. Copy your **public** SSH key to the clipboard by using one of the commands below + depending on your Operating System: **macOS:** ```bash - pbcopy < ~/.ssh/id_rsa.pub + pbcopy < ~/.ssh/id_ed25519.pub ``` - **GNU/Linux (requires the xclip package):** + **WSL / GNU/Linux (requires the xclip package):** ```bash - xclip -sel clip < ~/.ssh/id_rsa.pub + xclip -sel clip < ~/.ssh/id_ed25519.pub ``` - **Windows Command Line:** + **Git Bash on Windows:** ```bash - type %userprofile%\.ssh\id_rsa.pub | clip + cat ~/.ssh/id_ed25519.pub | clip ``` - **Git Bash on Windows / Windows PowerShell:** + You can also open the key in a graphical editor and copy it from there, + but be careful not to accidentally change anything. - ```bash - cat ~/.ssh/id_rsa.pub | clip - ``` - -1. The final step is to add your public SSH key to GitLab. + NOTE: **Note:** + If you opted to create an RSA key, the name might differ. - Navigate to the 'SSH Keys' tab in your 'Profile Settings'. - Paste your key in the 'Key' section and give it a relevant 'Title'. - Use an identifiable title like 'Work Laptop - Windows 7' or - 'Home MacBook Pro 15'. +1. Add your public SSH key to your GitLab account by clicking your avatar + in the upper right corner and selecting **Settings**. From there on, + navigate to **SSH Keys** and paste your public key in the "Key" section. + If you created the key with a comment, this will appear under "Title". + If not, give your key an identifiable title like _Work Laptop_ or + _Home Workstation_, and click **Add key**. + NOTE: **Note:** If you manually copied your public SSH key make sure you copied the entire - key starting with `ssh-rsa` and ending with your email. + key starting with `ssh-ed25519` (or `ssh-rsa`) and ending with your email. + +## Testing that everything is set up correctly + +To test whether your SSH key was added correctly, run the following command in +your terminal (replacing `gitlab.com` with your GitLab's instance domain): -1. Optionally you can test your setup by running `ssh -T git@example.com` - (replacing `example.com` with your GitLab domain) and verifying that you - receive a `Welcome to GitLab` message. +```bash +ssh -T git@gitlab.com +``` + +You should receive a _Welcome to GitLab, `@username`!_ message. + +If the welcome message doesn't appear, run SSH's verbose mode by replacing `-T` +with `-vvvT` to understand where the error is. ## Working with non-default SSH key pair paths If you used a non-default file path for your GitLab SSH key pair, you must configure your SSH client to find your GitLab private SSH key -for connections to your GitLab server (perhaps `gitlab.com`). +for connections to GitLab. -For your current terminal session you can do so using the following commands +Open a terminal and use the following commands (replacing `other_id_rsa` with your private SSH key): -**Git Bash on Windows / GNU/Linux / macOS:** - ```bash eval $(ssh-agent -s) ssh-add ~/.ssh/other_id_rsa ``` -To retain these settings you'll need to save them to a configuration file. -For OpenSSH clients this is configured in the `~/.ssh/config` file for some -operating systems. +To retain these settings, you'll need to save them to a configuration file. +For OpenSSH clients this is configured in the `~/.ssh/config` file. In this +file you can set up configurations for multiple hosts, like GitLab.com, your +own GitLab instance, GitHub, Bitbucket, etc. + Below are two example host configurations using their own SSH key: -``` -# GitLab.com server +```conf +# GitLab.com Host gitlab.com -RSAAuthentication yes -IdentityFile ~/.ssh/config/private-key-filename-01 + Preferredauthentications publickey + IdentityFile ~/.ssh/gitlab_com_rsa -# Private GitLab server +# Private GitLab instance Host gitlab.company.com -RSAAuthentication yes -IdentityFile ~/.ssh/config/private-key-filename + Preferredauthentications publickey + IdentityFile ~/.ssh/example_com_rsa ``` -Due to the wide variety of SSH clients and their very large number of -configuration options, further explanation of these topics is beyond the scope -of this document. - -Public SSH keys need to be unique, as they will bind to your account. -Your SSH key is the only identifier you'll have when pushing code via SSH. -That's why it needs to uniquely map to a single user. +Public SSH keys need to be unique to GitLab, as they will bind to your account. +Your SSH key is the only identifier you'll have when pushing code via SSH, +that's why it needs to uniquely map to a single user. ## Deploy keys @@ -240,8 +301,6 @@ not implicitly give any access just by setting them up. How to add your SSH key to Eclipse: https://wiki.eclipse.org/EGit/User_Guide#Eclipse_SSH_Configuration -[winputty]: https://the.earth.li/~sgtatham/putty/0.67/htmldoc/Chapter8.html#pubkey-puttygen - ## SSH on the GitLab server GitLab integrates with the system-installed SSH daemon, designating a user diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index 9546f43eea8..73301394e9f 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -43,7 +43,7 @@ This page gathers all the resources for the topic **Authentication** within GitL ## Third-party resources - [Kanboard Plugin GitLab Authentication](https://github.com/kanboard/plugin-gitlab-auth) -- [Jenkins GitLab OAuth Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+OAuth+Plugin) +- [Jenkins GitLab OAuth Plugin](https://wiki.jenkins.io/display/JENKINS/GitLab+OAuth+Plugin) - [Set up Gitlab CE with Active Directory authentication](https://www.caseylabs.com/setup-gitlab-ce-with-active-directory-authentication/) - [How to customize GitLab to support OpenID authentication](http://eric.van-der-vlist.com/blog/2013/11/23/how-to-customize-gitlab-to-support-openid-authentication/) - [Openshift - Configuring Authentication and User Agent](https://docs.openshift.org/latest/install_config/configuring_authentication.html#GitLab) diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index c60d25eda1b..96e788666a1 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -2,14 +2,15 @@ > [Introduced][ce-37115] in GitLab 10.0. Generally available on GitLab 11.0. -Auto DevOps automatically detects, builds, tests, deploys, and monitors your -applications. +Auto DevOps provides pre-defined CI/CD configuration which allows you to automatically detect, build, test, +deploy, and monitor your applications. Leveraging CI/CD best practices and tools, Auto DevOps aims +to simplify the setup and execution of a mature & modern software development lifecycle. ## Overview NOTE: **Enabled by default:** -Starting with GitLab 11.3, the Auto DevOps pipeline will be enabled by default for all -projects. If it's not explicitly enabled for the project, Auto DevOps will be automatically +Starting with GitLab 11.3, the Auto DevOps pipeline is enabled by default for all +projects. If it has not been explicitly enabled for the project, Auto DevOps will be automatically disabled on the first pipeline failure. Your project will continue to use an alternative [CI/CD configuration file](../../ci/yaml/README.md) if one is found. A GitLab administrator can [change this setting](../../user/admin_area/settings/continuous_integration.html#auto-devops) @@ -17,33 +18,38 @@ in the admin area. With Auto DevOps, the software development process becomes easier to set up as every project can have a complete workflow from verification to monitoring -without needing to configure anything. Just push your code and GitLab takes +with minimal configuration. Just push your code and GitLab takes care of everything else. This makes it easier to start new projects and brings consistency to how applications are set up throughout a company. ## Quick start If you are using GitLab.com, see the [quick start guide](quick_start_guide.md) -for using Auto DevOps with GitLab.com and a Kubernetes cluster on Google Kubernetes -Engine. +for how to use Auto DevOps with GitLab.com and a Kubernetes cluster on Google Kubernetes +Engine (GKE). + +If you are using a self-hosted instance of GitLab, you will need to configure the +[Google OAuth2 OmniAuth Provider](../../integration/google.md) before +you can configure a cluster on GKE. Once this is set up, you can follow the steps on the +[quick start guide](quick_start_guide.md) to get started. ## Comparison to application platforms and PaaS -Auto DevOps provides functionality described by others as an application -platform or as a Platform as a Service (PaaS). It takes inspiration from the +Auto DevOps provides functionality that is often included in an application +platform or a Platform as a Service (PaaS). It takes inspiration from the innovative work done by [Heroku](https://www.heroku.com/) and goes beyond it -in a couple of ways: +in multiple ways: -1. Auto DevOps works with any Kubernetes cluster, you're not limited to running - on GitLab's infrastructure (note that many features also work without Kubernetes). +1. Auto DevOps works with any Kubernetes cluster; you're not limited to running + on GitLab's infrastructure. (Note that many features also work without Kubernetes.) 1. There is no additional cost (no markup on the infrastructure costs), and you can use a self-hosted Kubernetes cluster or Containers as a Service on any - public cloud (for example [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)). + public cloud (for example, [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)). 1. Auto DevOps has more features including security testing, performance testing, and code quality testing. -1. It offers an incremental graduation path. If you need advanced customizations +1. Auto DevOps offers an incremental graduation path. If you need advanced customizations, you can start modifying the templates without having to start over on a - completely different platform. + completely different platform. Review the [customizing](#customizing) section for more information. ## Features @@ -197,23 +203,38 @@ and verifying that your app is deployed as a review app in the Kubernetes cluster with the `review/*` environment scope. Similarly, you can check the other environments. -## Enabling Auto DevOps +## Enabling/Disabling Auto DevOps -If you haven't done already, read the [requirements](#requirements) to make -full use of Auto DevOps. If this is your fist time, we recommend you follow the +When first using Auto Devops, review the [requirements](#requirements) to ensure all necessary components to make +full use of Auto DevOps are available. If this is your fist time, we recommend you follow the [quick start guide](quick_start_guide.md). -To enable Auto DevOps to your project: +GitLab.com users can enable/disable Auto DevOps at the project-level only. Self-managed users +can enable/disable Auto DevOps at either the project-level or instance-level. + +### Enabling/disabling Auto DevOps at the instance-level (Administrators only) + +1. Go to **Admin area > Settings > Continuous Integration and Deployment**. +1. Toggle the checkbox labeled **Default to Auto DevOps pipeline for all projects**. +1. If enabling, optionally set up the Auto DevOps [base domain](#auto-devops-base-domain) which will be used for Auto Deploy and Auto Review Apps. +1. Click **Save changes** for the changes to take effect. + +NOTE: **Note:** +Even when disabled at the instance level, project maintainers are still able to enable +Auto DevOps at the project level. + +### Enabling/disabling Auto DevOps at the project-level -1. Check that your project doesn't have a `.gitlab-ci.yml`, or remove it otherwise -1. Go to your project's **Settings > CI/CD > Auto DevOps** -1. Select "Enable Auto DevOps" -1. Optionally, but recommended, add in the [base domain](#auto-devops-base-domain) - that will be used by Kubernetes to [deploy your application](#auto-deploy) - and choose the [deployment strategy](#deployment-strategy) -1. Hit **Save changes** for the changes to take effect +If enabling, check that your project doesn't have a `.gitlab-ci.yml`, or if one exists, remove it. -Once saved, an Auto DevOps pipeline will be triggered on the default branch. +1. Go to your project's **Settings > CI/CD > Auto DevOps**. +1. Toggle the **Default to Auto DevOps pipeline** checkbox (checked to enable, unchecked to disable) +1. When enabling, it's optional but recommended to add in the [base domain](#auto-devops-base-domain) + that will be used by Auto DevOps to [deploy your application](#auto-deploy) + and choose the [deployment strategy](#deployment-strategy). +1. Click **Save changes** for the changes to take effect. + +When the feature has been enabled, an Auto DevOps pipeline is triggered on the default branch. NOTE: **Note:** For GitLab versions 10.0 - 10.2, when enabling Auto DevOps, a pipeline needs to be @@ -222,12 +243,6 @@ manually triggered either by pushing a new commit to the repository or by visiti a new pipeline for your default branch, generally `master`. NOTE: **Note:** -If you are a GitLab Administrator, you can -[enable/disable Auto DevOps instance-wide](../../user/admin_area/settings/continuous_integration.md#auto-devops), -and all projects that haven't explicitly set an option will have Auto DevOps -enabled/disabled by default. - -NOTE: **Note:** There is also a feature flag to enable Auto DevOps to a percentage of projects which can be enabled from the console with `Feature.get(:force_autodevops_on_by_default).enable_percentage_of_actors(10)`. @@ -299,8 +314,7 @@ static analysis and other code checks on the current code. The report is created, and is uploaded as an artifact which you can later download and check out. -In GitLab Starter, differences between the source and -target branches are also +Any differences between the source and target branches are also [shown in the merge request widget](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html). ### Auto SAST **[ULTIMATE]** @@ -313,9 +327,12 @@ analysis on the current code and checks for potential security issues. Once the report is created, it's uploaded as an artifact which you can later download and check out. -In GitLab Ultimate, any security warnings are also +Any security warnings are also [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/sast.html). +NOTE: **Note:** +The Auto SAST stage will be skipped on licenses other than Ultimate. + ### Auto Dependency Scanning **[ULTIMATE]** > Introduced in [GitLab Ultimate][ee] 10.7. @@ -329,6 +346,9 @@ check out. Any security warnings are also [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/dependency_scanning.html). +NOTE: **Note:** +The Auto Dependency Scanning stage will be skipped on licenses other than Ultimate. + ### Auto License Management **[ULTIMATE]** > Introduced in [GitLab Ultimate][ee] 11.0. @@ -342,6 +362,9 @@ check out. Any licenses are also [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/license_management.html). +NOTE: **Note:** +The Auto License Management stage will be skipped on licenses other than Ultimate. + ### Auto Container Scanning > Introduced in GitLab 10.4. @@ -352,9 +375,12 @@ Docker image and checks for potential security issues. Once the report is created, it's uploaded as an artifact which you can later download and check out. -In GitLab Ultimate, any security warnings are also +Any security warnings are also [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/container_scanning.html). +NOTE: **Note:** +The Auto Container Scanning stage will be skipped on licenses other than Ultimate. + ### Auto Review Apps NOTE: **Note:** @@ -374,6 +400,9 @@ branch's code so developers, designers, QA, product managers, and other reviewers can actually see and interact with code changes as part of the review process. Auto Review Apps create a Review App for each branch. +Auto Review Apps will deploy your app to your Kubernetes cluster only. When no cluster +is available, no deployment will occur. + The Review App will have a unique URL based on the project name, the branch name, and a unique number, combined with the Auto DevOps base domain. For example, `user-project-branch-1234.example.com`. A link to the Review App shows @@ -391,9 +420,12 @@ to perform an analysis on the current code and checks for potential security issues. Once the report is created, it's uploaded as an artifact which you can later download and check out. -In GitLab Ultimate, any security warnings are also +Any security warnings are also [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/dast.html). +NOTE: **Note:** +The Auto DAST stage will be skipped on licenses other than Ultimate. + ### Auto Browser Performance Testing **[PREMIUM]** > Introduced in [GitLab Premium][ee] 10.4. @@ -406,8 +438,8 @@ Auto Browser Performance Testing utilizes the [Sitespeed.io container](https://h /direction ``` -In GitLab Premium, performance differences between the source -and target branches are [shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/browser_performance_testing.html). +Any performance differences between the source and target branches are also +[shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/browser_performance_testing.html). ### Auto Deploy diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index b12e86cb0a9..6326aadcdf2 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -83,6 +83,9 @@ under which this application will be deployed.  1. Once ready, click **Create Kubernetes cluster**. + +NOTE: **Note:** +Do not select `f1-micro` from the **Machine type** dropdown. `f1-micro` machines cannot support a full GitLab installation. After a couple of minutes, the cluster will be created. You can also see its status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). diff --git a/doc/university/README.md b/doc/university/README.md index 5edf92b3b09..f19b1ffd3d9 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -205,7 +205,7 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project ### 4. External Articles -1. [2011 WSJ article by Marc Andreessen - Software is Eating the World](http://www.wsj.com/articles/SB10001424053111903480904576512250915629460) +1. [2011 WSJ article by Marc Andreessen - Software is Eating the World](https://www.wsj.com/articles/SB10001424053111903480904576512250915629460) 1. [2014 Blog post by Chris Dixon - Software eats software development](http://cdixon.org/2014/04/13/software-eats-software-development/) 1. [2015 Venture Beat article - Actually, Open Source is Eating the World](http://venturebeat.com/2015/12/06/its-actually-open-source-software-thats-eating-the-world/) diff --git a/doc/university/glossary/README.md b/doc/university/glossary/README.md index 6ff27e495fb..6e0f71017c6 100644 --- a/doc/university/glossary/README.md +++ b/doc/university/glossary/README.md @@ -303,7 +303,7 @@ A [tool](https://docs.gitlab.com/ee/integration/external-issue-tracker.html) use ### Jenkins -An Open Source CI tool written using the Java programming language. [Jenkins](https://jenkins-ci.org/) does the same job as GitLab CI, Bamboo, and Travis CI. It is extremely popular. Related [documentation](https://docs.gitlab.com/ee/integration/jenkins.html). +An Open Source CI tool written using the Java programming language. [Jenkins](https://jenkins.io/) does the same job as GitLab CI, Bamboo, and Travis CI. It is extremely popular. Related [documentation](https://docs.gitlab.com/ee/integration/jenkins.html). ### Jira diff --git a/doc/university/training/user_training.md b/doc/university/training/user_training.md index dccb6cbf071..f3a4d766522 100644 --- a/doc/university/training/user_training.md +++ b/doc/university/training/user_training.md @@ -6,91 +6,90 @@ comments: false --- -# Agenda +## Agenda -1. Brief history of Git -1. GitLab walkthrough -1. Configure your environment -1. Workshop +1. Brief history of Git. +1. GitLab walkthrough. +1. Configure your environment. +1. Workshop. --- -# Git introduction +## Git introduction -https://git-scm.com/about +<https://git-scm.com/about> -- Distributed version control - - Does not rely on connection to a central server - - Many copies of the complete history -- Powerful branching and merging -- Adapts to nearly any workflow -- Fast, reliable and stable file format +- Distributed version control. + - Does not rely on connection to a central server. + - Many copies of the complete history. +- Powerful branching and merging. +- Adapts to nearly any workflow. +- Fast, reliable and stable file format. --- -# Help! +## Help! Use the tools at your disposal when you get stuck. -- Use '`git help <command>`' command -- Use Google -- Read documentation at https://git-scm.com +- Use '`git help <command>`' command. +- Use Google. +- Read documentation at <https://git-scm.com>. --- -# GitLab Walkthrough +## GitLab Walkthrough  --- -# Configure your environment +## Configure your environment - Windows: Install 'Git for Windows' -> https://git-for-windows.github.io +> <https://git-for-windows.github.io> - Mac: Type '`git`' in the Terminal application. > If it's not installed, it will prompt you to install it. -- Debian: '`sudo apt-get install git-all`' -or Red Hat '`sudo yum install git-all`' +- Debian: '`sudo apt-get install git-all`' or Red Hat '`sudo yum install git-all`' --- -# Git Workshop +## Git Workshop -## Overview +### Overview -1. Configure Git -1. Configure SSH Key -1. Create a project -1. Committing -1. Feature branching -1. Merge requests -1. Feedback and Collaboration +1. Configure Git. +1. Configure SSH Key. +1. Create a project. +1. Committing. +1. Feature branching. +1. Merge requests. +1. Feedback and Collaboration. --- -# Configure Git +## Configure Git -One-time configuration of the Git client +One-time configuration of the Git client: -```bash +```sh git config --global user.name "Your Name" git config --global user.email you@example.com ``` --- -# Configure SSH Key +## Configure SSH Key -```bash +```sh ssh-keygen -t rsa -b 4096 -C "you@computer-name" ``` -```bash +```sh # You will be prompted for the following information. Press enter to accept the defaults. Defaults appear in parentheses. Generating public/private rsa key pair. Enter file in which to save the key (/Users/you/.ssh/id_rsa): @@ -102,31 +101,30 @@ The key fingerprint is: 39:fc:ce:94:f4:09:13:95:64:9a:65:c1:de:05:4d:01 you@computer-name ``` -Copy your public key and add it to your GitLab profile +Copy your public key and add it to your GitLab profile: -```bash +```sh cat ~/.ssh/id_rsa.pub ``` -```bash +```sh ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example.com ``` --- -# Create a project +## Create a project -- Create a project in your user namespace - - Choose to import from 'Any Repo by URL' and use - https://gitlab.com/gitlab-org/training-examples.git +- Create a project in your user namespace. + - Choose to import from 'Any Repo by URL' and use <https://gitlab.com/gitlab-org/training-examples.git>. - Create a '`development`' or '`workspace`' directory in your home directory. -- Clone the '`training-examples`' project +- Clone the '`training-examples`' project. --- -# Commands +## Commands (project) -``` +```sh mkdir ~/development cd ~/development @@ -141,37 +139,37 @@ cd training-examples --- -# Git concepts +## Git concepts -**Untracked files** +### Untracked files New files that Git has not been told to track previously. -**Working area** +### Working area Files that have been modified but are not committed. -**Staging area** +### Staging area Modified files that have been marked to go in the next commit. --- -# Committing +## Committing -1. Edit '`edit_this_file.rb`' in '`training-examples`' -1. See it listed as a changed file (working area) -1. View the differences -1. Stage the file -1. Commit -1. Push the commit to the remote -1. View the git log +1. Edit '`edit_this_file.rb`' in '`training-examples`'. +1. See it listed as a changed file (working area). +1. View the differences. +1. Stage the file. +1. Commit. +1. Push the commit to the remote. +1. View the git log. --- -# Commands +## Commands (committing) -``` +```sh # Edit `edit_this_file.rb` git status git diff @@ -183,29 +181,29 @@ git log --- -# Feature branching +## Feature branching -- Efficient parallel workflow for teams -- Develop each feature in a branch -- Keeps changes isolated -- Consider a 1-to-1 link to issues -- Push branches to the server frequently - - Hint: This is a cheap backup for your work-in-progress code +- Efficient parallel workflow for teams. +- Develop each feature in a branch. +- Keeps changes isolated. +- Consider a 1-to-1 link to issues. +- Push branches to the server frequently. + - Hint: This is a cheap backup for your work-in-progress code. --- -# Feature branching +## Feature branching steps -1. Create a new feature branch called 'squash_some_bugs' +1. Create a new feature branch called 'squash_some_bugs'. 1. Edit '`bugs.rb`' and remove all the bugs. -1. Commit -1. Push +1. Commit. +1. Push. --- -# Commands +## Commands (feature branching) -``` +```sh git checkout -b squash_some_bugs # Edit `bugs.rb` git status @@ -216,51 +214,50 @@ git push origin squash_some_bugs --- -# Merge requests +## Merge requests -- When you want feedback create a merge request -- Target is the ‘default’ branch (usually master) -- Assign or mention the person you would like to review -- Add 'WIP' to the title if it's a work in progress -- When accepting, always delete the branch -- Anyone can comment, not just the assignee -- Push corrections to the same branch +- When you want feedback create a merge request. +- Target is the ‘default’ branch (usually master). +- Assign or mention the person you would like to review. +- Add 'WIP' to the title if it's a work in progress. +- When accepting, always delete the branch. +- Anyone can comment, not just the assignee. +- Push corrections to the same branch. --- -# Merge requests +## Merge requests steps -**Create your first merge request** +Create your first merge request: -1. Use the blue button in the activity feed -1. View the diff (changes) and leave a comment -1. Push a new commit to the same branch -1. Review the changes again and notice the update +1. Use the blue button in the activity feed. +1. View the diff (changes) and leave a comment. +1. Push a new commit to the same branch. +1. Review the changes again and notice the update. --- -# Feedback and Collaboration +## Feedback and Collaboration -- Merge requests are a time for feedback and collaboration -- Giving feedback is hard -- Be as kind as possible -- Receiving feedback is hard -- Be as receptive as possible -- Feedback is about the best code, not the person. You are not your code +- Merge requests are a time for feedback and collaboration. +- Giving feedback is hard. +- Be as kind as possible. +- Receiving feedback is hard. +- Be as receptive as possible. +- Feedback is about the best code, not the person. You are not your code. --- -# Feedback and Collaboration +## Feedback and Collaboration resources Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests: -[https://github.com/thoughtbot/guides/tree/master/code-review](https://github.com/thoughtbot/guides/tree/master/code-review) +<https://github.com/thoughtbot/guides/tree/master/code-review>. -See GitLab merge requests for examples: -[https://gitlab.com/gitlab-org/gitlab-ce/merge_requests](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests) +See GitLab merge requests for examples: <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests>. --- -# Explore GitLab projects +## Explore GitLab projects  @@ -274,31 +271,29 @@ See GitLab merge requests for examples: --- -# Tags +## Tags -- Useful for marking deployments and releases -- Annotated tags are an unchangeable part of Git history -- Soft/lightweight tags can be set and removed at will -- Many projects combine an annotated release tag with a stable branch -- Consider setting deployment/release tags automatically +- Useful for marking deployments and releases. +- Annotated tags are an unchangeable part of Git history. +- Soft/lightweight tags can be set and removed at will. +- Many projects combine an annotated release tag with a stable branch. +- Consider setting deployment/release tags automatically. --- -# Tags - -- Create a lightweight tag -- Create an annotated tag -- Push the tags to the remote repository +## Tags steps -**Additional resources** +1. Create a lightweight tag. +1. Create an annotated tag. +1. Push the tags to the remote repository. -[http://git-scm.com/book/en/Git-Basics-Tagging](http://git-scm.com/book/en/Git-Basics-Tagging) +Additional resources: <http://git-scm.com/book/en/Git-Basics-Tagging>. --- -# Commands +## Commands (tags) -``` +```sh git checkout master # Lightweight tag @@ -313,31 +308,31 @@ git push origin --tags --- -# Merge conflicts +## Merge conflicts -- Happen often -- Learning to fix conflicts is hard -- Practice makes perfect +- Happen often. +- Learning to fix conflicts is hard. +- Practice makes perfect. - Force push after fixing conflicts. Be careful! --- -# Merge conflicts +## Merge conflicts steps 1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'. -1. Commit and push +1. Commit and push. 1. Checkout master and edit `conflicts.rb`. Add 'Line6' and 'Line7' below 'Line3'. -1. Commit and push to master -1. Create a merge request +1. Commit and push to master. +1. Create a merge request. --- -# Merge conflicts +## Merge conflicts commands After creating a merge request you should notice that conflicts exist. Resolve the conflicts locally by rebasing. -``` +```sh git rebase master # Fix conflicts by editing the files. @@ -350,7 +345,7 @@ git push origin <branch> -f --- -# Rebase with squash +## Rebase with squash You may end up with a commit log that looks like this: @@ -368,11 +363,11 @@ Squash these in to meaningful commits using an interactive rebase. --- -# Rebase with squash +## Rebase with squash commands Squash the commits on the same branch we used for the merge conflicts step. -``` +```sh git rebase -i master ``` @@ -380,17 +375,17 @@ In the editor, leave the first commit as 'pick' and set others to 'fixup'. --- -# Questions? +## Questions?  Thank you for your hard work! -**Additional Resources** +## Additional Resources -GitLab Documentation [http://docs.gitlab.com](http://docs.gitlab.com/) -GUI Clients [http://git-scm.com/downloads/guis](http://git-scm.com/downloads/guis) -Pro git book [http://git-scm.com/book](http://git-scm.com/book) -Platzi Course [https://courses.platzi.com/courses/git-gitlab/](https://courses.platzi.com/courses/git-gitlab/) -Code School tutorial [http://try.github.io/](http://try.github.io/) -Contact Us at `subscribers@gitlab.com` +- GitLab Documentation: <http://docs.gitlab.com/>. +- GUI Clients: <http://git-scm.com/downloads/guis>. +- Pro git book: <http://git-scm.com/book>. +- Platzi Course: <https://courses.platzi.com/courses/git-gitlab/>. +- Code School tutorial: <http://try.github.io/>. +- Contact us at `subscribers@gitlab.com`. diff --git a/doc/update/11.3-to-11.4.md b/doc/update/11.3-to-11.4.md index b50e21f27dd..00dfb19b4b4 100644 --- a/doc/update/11.3-to-11.4.md +++ b/doc/update/11.3-to-11.4.md @@ -39,9 +39,9 @@ Download Ruby and compile it: ```bash mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.4.tar.gz -echo 'ec82b0d53bd0adad9b19e6b45e44d54e9ec3f10c ruby-2.4.4.tar.gz' | shasum -c - && tar xzf ruby-2.4.4.tar.gz -cd ruby-2.4.4 +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.5.tar.gz +echo '4d650f302f1ec00256450b112bb023644b6ab6dd ruby-2.4.5.tar.gz' | shasum -c - && tar xzf ruby-2.4.5.tar.gz +cd ruby-2.4.5 ./configure --disable-install-rdoc make diff --git a/doc/update/11.4-to-11.5.md b/doc/update/11.4-to-11.5.md new file mode 100644 index 00000000000..e64ab2acae2 --- /dev/null +++ b/doc/update/11.4-to-11.5.md @@ -0,0 +1,404 @@ +--- +comments: false +--- + +# From 11.4 to 11.5 + +Make sure you view this update guide from the branch (version) of GitLab you would +like to install (e.g., `11-5-stable`. You can select the branch in the version +dropdown at the top left corner of GitLab (below the menu bar). + +If the highest number stable branch is unclear please check the +[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation +guide links by version. + +### 1. Stop server + +```bash +sudo service gitlab stop +``` + +### 2. Backup + +NOTE: If you installed GitLab from source, make sure `rsync` is installed. + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Update Ruby + +NOTE: GitLab 11.0 and higher only support Ruby 2.4.x and dropped support for Ruby 2.3.x. Be +sure to upgrade your interpreter if necessary. + +You can check which version you are running with `ruby -v`. + +Download Ruby and compile it: + +```bash +mkdir /tmp/ruby && cd /tmp/ruby +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.5.tar.gz +echo '4d650f302f1ec00256450b112bb023644b6ab6dd ruby-2.4.5.tar.gz' | shasum -c - && tar xzf ruby-2.4.5.tar.gz +cd ruby-2.4.5 + +./configure --disable-install-rdoc +make +sudo make install +``` + +Install Bundler: + +```bash +sudo gem install bundler --no-ri --no-rdoc +``` + +### 4. Update Node + +GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. +This requires a minimum version of node v6.0.0. + +You can check which version you are running with `node -v`. If you are running +a version older than `v6.0.0` you will need to update to a newer version. You +can find instructions to install from community maintained packages or compile +from source at the nodejs.org website. + +<https://nodejs.org/en/download/> + +GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript +dependencies. + +```bash +curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list +sudo apt-get update +sudo apt-get install yarn +``` + +More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). + +### 5. Update Go + +NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go +1.9.x. Be sure to upgrade your installation if necessary. + +You can check which version you are running with `go version`. + +Download and install Go: + +```bash +# Remove former Go installation folder +sudo rm -rf /usr/local/go + +curl --remote-name --progress https://dl.google.com/go/go1.10.3.linux-amd64.tar.gz +echo 'fa1b0e45d3b647c252f51f5e1204aba049cde4af177ef9f2181f43004f901035 go1.10.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ + sudo tar -C /usr/local -xzf go1.10.3.linux-amd64.tar.gz +sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ +rm go1.10.3.linux-amd64.tar.gz +``` + +### 6. Get latest code + +```bash +cd /home/git/gitlab + +sudo -u git -H git fetch --all --prune +sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically +sudo -u git -H git checkout -- locale +``` + +For GitLab Community Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 11-5-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 11-5-stable-ee +``` + +### 7. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) +sudo -u git -H bin/compile +``` + +### 8. Update gitlab-workhorse + +Install and compile gitlab-workhorse. GitLab-Workhorse uses +[GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-workhorse + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) +sudo -u git -H make +``` + +### 9. Update Gitaly + +#### New Gitaly configuration options required + +In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. + +```shell +echo ' +[gitaly-ruby] +dir = "/home/git/gitaly/ruby" + +[gitlab-shell] +dir = "/home/git/gitlab-shell" +' | sudo -u git tee -a /home/git/gitaly/config.toml +``` + +#### Check Gitaly configuration + +Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly +configuration file may contain syntax errors. The block name +`[[storages]]`, which may occur more than once in your `config.toml` +file, should be `[[storage]]` instead. + +```shell +sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml +``` + +#### Compile Gitaly + +```shell +cd /home/git/gitaly +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) +sudo -u git -H make +``` + +### 10. Update gitlab-pages + +#### Only needed if you use GitLab Pages. + +Install and compile gitlab-pages. GitLab-Pages uses +[GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-pages + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) +sudo -u git -H make +``` + +### 11. Update MySQL permissions + +If you are using MySQL you need to grant the GitLab user the necessary +permissions on the database: + +```bash +mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" +``` + +If you use MySQL with replication, or just have MySQL configured with binary logging, +you will need to also run the following on all of your MySQL servers: + +```bash +mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" +``` + +You can make this setting permanent by adding it to your `my.cnf`: + +``` +log_bin_trust_function_creators=1 +``` + +### 12. Update configuration files + +#### New `unicorn.rb` configuration + +Note: we have made [changes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22372) to `unicorn.rb` to allow GitLab run with both Unicorn and Puma in future. + +- Make `/home/git/gitlab/config/unicorn.rb` the same as https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/config/unicorn.rb.example but with your settings. + - In particular, make sure that `require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events"` line exists and the `before_exec`, `before_fork`, and `after_fork` handlers are configured as shown below: + +```ruby +require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events" + +before_exec do |server| + # Signal application hooks that we're about to restart + Gitlab::Cluster::LifecycleEvents.do_master_restart +end + +before_fork do |server, worker| + # Signal application hooks that we're about to fork + Gitlab::Cluster::LifecycleEvents.do_before_fork +end + +after_fork do |server, worker| + # Signal application hooks of worker start + Gitlab::Cluster::LifecycleEvents.do_worker_start +end +``` + +#### New configuration options for `gitlab.yml` + +There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: + +```sh +cd /home/git/gitlab + +git diff origin/11-4-stable:config/gitlab.yml.example origin/11-5-stable:config/gitlab.yml.example +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +cd /home/git/gitlab + +# For HTTPS configurations +git diff origin/11-1-stable:lib/support/nginx/gitlab-ssl origin/11-5-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/11-1-stable:lib/support/nginx/gitlab origin/11-5-stable:lib/support/nginx/gitlab +``` + +If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx +configuration as GitLab application no longer handles setting it. + +If you are using Apache instead of NGINX please see the updated [Apache templates]. +Also note that because Apache does not support upstreams behind Unix sockets you +will need to let gitlab-workhorse listen on a TCP port. You can do this +via [/etc/default/gitlab]. + +[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/lib/support/init.d/gitlab.default.example#L38 + +#### SMTP configuration + +If you're installing from source and use SMTP to deliver mail, you will need to add the following line +to config/initializers/smtp_settings.rb: + +```ruby +ActionMailer::Base.delivery_method = :smtp +``` + +See [smtp_settings.rb.sample] as an example. + +[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/config/initializers/smtp_settings.rb.sample#L13 + +#### Init script + +There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: + +```sh +cd /home/git/gitlab + +git diff origin/11-1-stable:lib/support/init.d/gitlab.default.example origin/11-5-stable:lib/support/init.d/gitlab.default.example +``` + +Ensure you're still up-to-date with the latest init script changes: + +```bash +cd /home/git/gitlab + +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +``` + +For Ubuntu 16.04.1 LTS: + +```bash +sudo systemctl daemon-reload +``` + +### 13. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Compile GetText PO files + +sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=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 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). + +### 14. Start application + +```bash +sudo service gitlab start +sudo service nginx restart +``` + +### 15. Check application status + +Check if GitLab and its environment are configured correctly: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production +``` + +To make sure you didn't miss anything run a more thorough check: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production +``` + +If all items are green, then congratulations, the upgrade is complete! + +## Things went south? Revert to previous version (11.4) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 11.3 to 11.4](11.3-to-11.4.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. + +[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/lib/support/init.d/gitlab.default.example diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 35a9d7adb28..bd0155dc712 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -42,7 +42,11 @@ not send any project names, usernames, or any other specific data. The information from the usage ping is not anonymous, it is linked to the hostname of the instance. -You can view the exact JSON payload in the administration panel. +You can view the exact JSON payload in the administration panel. To view the payload: + +1. Go to the **Admin area** (spanner symbol on the top bar). +1. Expand **Settings** in the left sidebar and click on **Metrics and profiling**. +1. Expand **Usage statistics** and click on the **Preview payload** button. ### Deactivate the usage ping diff --git a/doc/user/markdown.md b/doc/user/markdown.md index f9bdaea185b..96a509c4b21 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,17 +1,8 @@ # Markdown -## GitLab Flavored Markdown (GFM) - -> **Note:** -> Not all of the GitLab-specific extensions to Markdown that are described in -> this document currently work on our documentation website. -> -> For the best result, we encourage you to check this document out as rendered -> by GitLab: [markdown.md] - -_GitLab uses (as of 11.1) the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the repositories are also processed with CommonMark. Older content in issues/comments are still processed using the [Redcarpet Ruby library][redcarpet]._ +This markdown guide is valid for GitLab's system markdown entries and files. -_Where there are significant differences, we will try to call them out in this document._ +## GitLab Flavored Markdown (GFM) GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification][commonmark-spec] (which is based on standard Markdown) in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). @@ -26,11 +17,28 @@ You can use GFM in the following areas: - markdown documents inside the repository You can also use other rich text files in GitLab. You might have to install a -dependency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information. +dependency to do so. Please see the [`github-markup` gem readme](https://github.com/gitlabhq/markup#markups) for more information. + +> **Notes:** +> +> For the best result, we encourage you to check this document out as rendered +> by GitLab itself: [markdown.md] +> +> As of 11.1, GitLab uses the [CommonMark Ruby Library][commonmarker] for Markdown +processing of all new issues, merge requests, comments, and other Markdown content +in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the +repositories are also processed with CommonMark. Older content in issues/comments +are still processed using the [Redcarpet Ruby library][redcarpet]. +> +> _Where there are significant differences, we will try to call them out in this document._ ### Transitioning to CommonMark -You may have Markdown documents in your repository that were written using some of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a slightly stricter syntax, these documents may now display a little strangely since we've transitioned to CommonMark. Numbered lists with nested lists in particular can be displayed incorrectly. +You may have Markdown documents in your repository that were written using some +of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a +slightly stricter syntax, these documents may now display a little strangely +since we've transitioned to CommonMark. Numbered lists with nested lists in +particular can be displayed incorrectly. It is usually quite easy to fix. In the case of a nested list such as this: @@ -50,11 +58,18 @@ simply add a space to each nested item: In the documentation below, we try to highlight some of the differences. -If you have a need to view a document using RedCarpet, you can add the token `legacy_render=1` to the end of the url, like this: +If you have a need to view a document using RedCarpet, you can add the token +`legacy_render=1` to the end of the url, like this: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md?legacy_render=1 -If you have a large volume of Markdown files, it can be tedious to determine if they will be displayed correctly or not. You can use the [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) tool (not an officially supported product) to generate a list of files and differences between how RedCarpet and CommonMark render the files. It can give you a great idea if anything needs to be changed - many times nothing will need to changed. +If you have a large volume of Markdown files, it can be tedious to determine +if they will be displayed correctly or not. You can use the +[diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) +tool (not an officially supported product) to generate a list of files and +differences between how RedCarpet and CommonMark render the files. It can give +you a great idea if anything needs to be changed - many times nothing will need +to changed. ### Newlines @@ -63,7 +78,8 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newline GFM honors the markdown specification in how [paragraphs and line breaks are handled][commonmark-spec]. -A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. +A paragraph is simply one or more consecutive lines of text, separated by one or +more blank lines. Line-breaks, or soft returns, are rendered if you end a line with two or more spaces: <!-- (Do *NOT* remove the two ending whitespaces in the following line.) --> @@ -85,7 +101,9 @@ Sugar is sweet > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words -It is not reasonable to italicize just _part_ of a word, especially when you're dealing with code and names that often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words: +It is not reasonable to italicize just _part_ of a word, especially when you're +dealing with code and names that often appear with multiple underscores. +Therefore, GFM ignores multiple underscores in words: perform_complicated_task @@ -124,7 +142,7 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multili On top of standard Markdown [blockquotes](#blockquotes), which require prepending `>` to quoted lines, GFM supports multiline blockquotes fenced by <code>>>></code>: -```no-highlight +``` >>> If you paste a message from somewhere else @@ -158,7 +176,7 @@ Blocks of code are either fenced by lines with three back-ticks <code>```</code> or are indented with four spaces. Only the fenced code blocks support syntax highlighting: -```no-highlight +``` Inline `code` has `back-ticks around` it. ``` @@ -248,21 +266,23 @@ However the wrapping tags cannot be mixed as such: > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji - Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: +``` +Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: - :zap: You can use emoji anywhere GFM is supported. :v: +:zap: You can use emoji anywhere GFM is supported. :v: - You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. +You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that. - If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes. +If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes. - Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: +Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup: - Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. +Most emoji are natively supported on macOS, Windows, iOS, Android and will fallback to image-based emoji where there is lack of support. - On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. +On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/help/emoji/) to get full native emoji support. - Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. +``` Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px"> to your <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px">. Well we have a gift for you: @@ -281,7 +301,6 @@ On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/he Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. - ### Special GitLab References GFM recognizes special references. @@ -343,7 +362,7 @@ https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-li You can add task lists to issues, merge requests and comments. To create a task list, add a specially-formatted Markdown list, like so: -```no-highlight +``` - [x] Completed task - [ ] Incomplete task - [ ] Sub-task 1 @@ -355,7 +374,7 @@ You can add task lists to issues, merge requests and comments. To create a task Tasks formatted as ordered lists are supported as well: -```no-highlight +``` 1. [x] Completed task 1. [ ] Incomplete task 1. [ ] Sub-task 1 @@ -412,7 +431,7 @@ This math is inline . This is on a separate line -<div align="center"><img src="./img/math_inline_sup_render_gfm.png" ></div> +<img src="./img/math_inline_sup_render_gfm.png" > _Be advised that KaTeX only supports a [subset][katex-subset] of LaTeX._ @@ -440,7 +459,7 @@ Examples: `HSL(540,70%,50%)` `HSLA(540,70%,50%,0.7)` -Become: +Becomes:  @@ -482,7 +501,7 @@ For details see the [Mermaid official page][mermaid]. ### Headers -```no-highlight +``` # H1 ## H2 ### H3 @@ -540,7 +559,7 @@ Note that the Emoji processing happens before the header IDs are generated, so t Examples: -```no-highlight +``` Emphasis, aka italics, with *asterisks* or _underscores_. Strong emphasis, aka bold, with **asterisks** or __underscores__. @@ -550,7 +569,7 @@ Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` -Become: +Becomes: Emphasis, aka italics, with *asterisks* or _underscores_. @@ -564,7 +583,7 @@ Strikethrough uses two tildes. ~~Scratch this.~~ Examples: -```no-highlight +``` 1. First ordered list item 2. Another item * Unordered sub-list. @@ -577,7 +596,7 @@ Examples: + Or pluses ``` -Become: +Becomes: 1. First ordered list item 2. Another item @@ -595,7 +614,7 @@ each subsequent paragraph should be indented to the same level as the start of t Example: -```no-highlight +``` 1. First ordered list item Second paragraph of first item. @@ -616,7 +635,7 @@ the paragraph will appear outside the list, instead of properly indented under t Example: -```no-highlight +``` 1. First ordered list item Paragraph of first item. @@ -676,7 +695,7 @@ Examples: [logo]: img/markdown_logo.png -Become: +Becomes: Here's our logo: @@ -694,7 +713,7 @@ Reference-style: Examples: -```no-highlight +``` > Blockquotes are very handy in email to emulate reply text. > This line is part of the same quote. @@ -703,7 +722,7 @@ Quote break. > This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. ``` -Become: +Becomes: > Blockquotes are very handy in email to emulate reply text. > This line is part of the same quote. @@ -720,7 +739,7 @@ See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubyd Examples: -```no-highlight +``` <dl> <dt>Definition list</dt> <dd>Is something people use sometimes.</dd> @@ -730,7 +749,7 @@ Examples: </dl> ``` -Become: +Becomes: <dl> <dt>Definition list</dt> @@ -788,7 +807,7 @@ ___ Underscores ``` -Become: +Becomes: Three or more... @@ -826,7 +845,7 @@ This line is *on its own line*, because the previous line ends with two spaces. spaces. ``` -Become: +Becomes: Here's a line for us to start with. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index caf175b5be9..94744cf8500 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -113,6 +113,14 @@ To add an existing Kubernetes cluster to your project: After a couple of minutes, your cluster will be ready to go. You can now proceed to install some [pre-defined applications](#installing-applications). +To determine the: + +- API URL, run `kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}'`. +- Token: + 1. List the secrets by running: `kubectl get secrets`. Note the name of the secret you need the token for. + 1. Get the token for the appropriate secret by running: `kubectl get secret <SECRET_NAME> -o jsonpath="{['data']['token']}" | base64 -D`. +- CA certificate, run `kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 -D`. + ## Security implications CAUTION: **Important:** diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md new file mode 100644 index 00000000000..3b81e439119 --- /dev/null +++ b/doc/user/project/clusters/runbooks/index.md @@ -0,0 +1,49 @@ +# Runbooks + +Runbooks are a collection of documented procedures that explain how to +carry out a particular process, be it starting, stopping, debugging, +or troubleshooting a particular system. + +## Overview + +Historically, runbooks took the form of a decision tree or a detailed +step-by-step guide depending on the condition or system. + +Modern implementations have introduced the concept of an "executable +runbooks", where along with a well define process, operators can execute +code blocks or database queries against a given environment. + +## Nurtch Executable Runbooks + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45912) in GitLab 11.4. + +The JupyterHub app offered via GitLab’s Kubernetes integration now ships +with Nurtch’s Rubix library, providing a simple way to create DevOps +runbooks. A sample runbook is provided, showcasing common operations. + +**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +Watch this [video](https://www.youtube.com/watch?v=Q_OqHIIUPjE) +for an overview of how this is acomplished in GitLab!** + +## Requirements + +To create an executable runbook, you will need: + +1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. + The simplest way to get started is to add a cluster using [GitLab's GKE integration](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab). +1. **Helm Tiller** - Helm is a package manager for Kubernetes and is required to install + all the other applications. It is installed in its own pod inside the cluster which + can run the helm CLI in a safe environment. +1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based + virtual hosting. It acts as a web proxy for your applications. +1. **JupyterHub** - JupyterHub is a multi-user service for managing notebooks across + a team. Jupyter Notebooks provide a web-based interactive programming environment + used for data analysis, visualization, and machine learning. + +## Nurtch + +Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). Rubix is +an open-source python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks. +Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified +down to a couple of lines of code. Check the [Nurtch Documentation](http://docs.nurtch.com/en/latest) +for more information. diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 464fa5987c1..9e2434c02ec 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -176,6 +176,9 @@ Clicking on the current board name in the upper left corner will reveal a menu from where you can create another Issue Board and rename or delete the existing one. +When you're revisiting an issue board in a project or group with multiple boards, +GitLab will automatically load the last board you visited. + NOTE: **Note:** The Multiple Issue Boards feature is available for **projects in GitLab Starter Edition** and for **groups in GitLab Premium Edition**. diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index f9ebf277125..0a7f7d37384 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -236,6 +236,35 @@ all your changes will be available to preview by anyone with the Review Apps lin Find out about [bulk editing merge requests](../../project/bulk_editing.md). +## Troubleshooting + +Sometimes things don't go as expected in a merge request, here are some +troubleshooting steps. + +### Merge request cannot retrieve the pipeline status + +This can occur for one of two reasons: + +* Sidekiq doesn't pick up the changes fast enough +* Because of the bug described in [#41545](https://gitlab.com/gitlab-org/gitlab-ce/issues/41545) + +#### Sidekiq + +Sidekiq didn't process the CI state change fast enough. Please wait a few +seconds and the status will update automatically. + +#### Bug + +Merge Request pipeline statuses can't be retrieved when the following occurs: + +1. A Merge Requst is created +1. The Merge Request is closed +1. Changes are made in the project +1. The Merge Request is reopened + +To enable the pipeline status to be properly retrieved, close and reopen the +Merge Request again. + ## Tips Here are some tips that will help you be more efficient with merge requests in diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index e1eede8bbed..89b9621b8b9 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -212,7 +212,7 @@ security measure, necessary just for big companies, like banks and shoppings sit with financial transactions. Now we have a different picture. [According to Josh Aas](https://letsencrypt.org/2015/10/29/phishing-and-malware.html), Executive Director at [ISRG](https://en.wikipedia.org/wiki/Internet_Security_Research_Group): -> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](http://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ +> _We’ve since come to realize that HTTPS is important for almost all websites. It’s important for any website that allows people to log in with a password, any website that [tracks its users](https://www.washingtonpost.com/news/the-switch/wp/2013/12/10/nsa-uses-google-cookies-to-pinpoint-targets-for-hacking/) in any way, any website that [doesn’t want its content altered](http://arstechnica.com/tech-policy/2014/09/why-comcasts-javascript-ad-injections-threaten-security-net-neutrality/), and for any site that offers content people might not want others to know they are consuming. We’ve also learned that any site not secured by HTTPS [can be used to attack other sites](https://krebsonsecurity.com/2015/04/dont-be-fodder-for-chinas-great-cannon/)._ Therefore, the reason why certificates are so important is that they encrypt the connection between the **client** (you, me, your visitors) diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index e1d8345f415..783081cec26 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -30,12 +30,12 @@ to learn more. ## Delete merged branches -> [Introduced][ce-6449] in GitLab 8.14. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6449) in GitLab 8.14.  This feature allows merged branches to be deleted in bulk. Only branches that -have been merged and [are not protected][protected] will be deleted as part of +have been merged and [are not protected](../../protected_branches.md) will be deleted as part of this operation. It's particularly useful to clean up old branches that were not deleted @@ -44,7 +44,7 @@ automatically when a merge request was merged. ## Branch filter search box -> [Introduced][https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22166] in GitLab 11.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22166) in GitLab 11.5.  @@ -57,6 +57,3 @@ Sometimes when you have hundreds of branches you may want a more flexible matchi - `^feature` will only match branch names that begin with 'feature'. - `feature$` will only match branch names that end with 'feature'. - -[ce-6449]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6449 "Add button to delete all merged branches" -[protected]: ../../protected_branches.md diff --git a/doc/user/search/img/issues_filter_none_any.png b/doc/user/search/img/issues_filter_none_any.png Binary files differnew file mode 100644 index 00000000000..9682fc55315 --- /dev/null +++ b/doc/user/search/img/issues_filter_none_any.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 4f1b96b775c..3f9d07dacaa 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -40,6 +40,16 @@ The same process is valid for merge requests. Navigate to your project's **Merge and click **Search or filter results...**. Merge requests can be filtered by author, assignee, milestone, and label. +### Filtering by **None** / **Any** + +Some filter fields like milestone and assignee, allow you to filter by **None** or **Any**. + + + +Selecting **None** returns results that have an empty value for that field. E.g.: no milestone, no assignee. + +Selecting **Any** does the opposite. It returns results that have a non-empty value for that field. + ### Searching for specific terms You can filter issues and merge requests by specific terms included in titles or descriptions. diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md index 731c9209224..9e41038e02e 100644 --- a/doc/workflow/notifications.md +++ b/doc/workflow/notifications.md @@ -10,31 +10,32 @@ You can find notification settings under the user profile. Notification settings are divided into three groups: -* Global Settings -* Group Settings -* Project Settings +- Global settings +- Group settings +- Project settings Each of these settings have levels of notification: -* Disabled - turns off notifications -* Participating - receive notifications from related resources -* Watch - receive notifications from projects or groups user is a member of -* Global - notifications as set at the global settings -* Custom - user will receive notifications when mentioned, is participant and custom selected events. +- Watch: Receive notifications for any activity. +- On Mention: Receive notifications when `@mentioned` in comments. +- Participate: Receive notifications for threads you have participated in. +- Disabled: Turns off notifications. +- Custom: Receive notifications for custom selected events. +- Global: For groups and projects, notifications as per global settings. -#### Global Settings +### Global Settings -Global Settings are at the bottom of the hierarchy. +Global settings are at the bottom of the hierarchy. Any setting set here will be overridden by a setting at the group or a project level. Group or Project settings can use `global` notification setting which will then use anything that is set at Global Settings. -#### Group Settings +### Group Settings  -Group Settings are taking precedence over Global Settings but are on a level below Project or Subgroup Settings: +Group settings are taking precedence over Global Settings but are on a level below Project or Subgroup settings: ``` Group < Subgroup < Project @@ -46,11 +47,11 @@ Organization like this is suitable for users that belong to different groups but same need for being notified for every group they are member of. These settings can be configured on group page under the name of the group. It will be the dropdown with the bell icon. They can also be configured on the user profile notifications dropdown. -#### Project Settings +### Project Settings  -Project Settings are at the top level and any setting placed at this level will take precedence of any +Project settings are at the top level and any setting placed at this level will take precedence of any other setting. This is suitable for users that have different needs for notifications per project basis. These settings can be configured on project page under the name of the project. It will be the dropdown with the bell icon. They can also be configured on the user profile notifications dropdown. @@ -73,11 +74,12 @@ Below is the table of events users can be notified of: ### Issue / Merge request events In most of the below cases, the notification will be sent to: + - Participants: - the author and assignee of the issue/merge request - authors of comments on the issue/merge request - anyone mentioned by `@username` in the issue/merge request title or description - - anyone mentioned by `@username` in any of the comments on the issue/merge request + - anyone mentioned by `@username` in any of the comments on the issue/merge request ...with notification level "Participating" or higher - Watchers: users with notification level "Watch" - Subscribers: anyone who manually subscribed to the issue/merge request @@ -129,16 +131,19 @@ Notification emails include headers that provide extra content about the notific | X-GitLab-NotificationReason | The reason for being notified. "mentioned", "assigned", etc | #### X-GitLab-NotificationReason + This header holds the reason for the notification to have been sent out, where reason can be `mentioned`, `assigned`, `own_activity`, etc. Only one reason is sent out according to its priority: + - `own_activity` - `assigned` - `mentioned` -The reason in this header will also be shown in the footer of the notification email. For example an email with the +The reason in this header will also be shown in the footer of the notification email. For example an email with the reason `assigned` will have this sentence in the footer: `"You are receiving this email because you have been assigned an item on {configured GitLab hostname}"` -**Note: Only reasons listed above have been implemented so far** -Further implementation is [being discussed here](https://gitlab.com/gitlab-org/gitlab-ce/issues/42062) +NOTE: **Note:** +Only reasons listed above have been implemented so far. +Further implementation is [being discussed](https://gitlab.com/gitlab-org/gitlab-ce/issues/42062). |
